@pulsemcp/air-adapter-pi 0.7.0

package/README.md

@@ -0,0 +1,70 @@
+# @pulsemcp/air-adapter-pi
+
+AIR adapter extension for the [Pi coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (`pi`). Injects AIR skills into Pi's native skills location and prepares working directories for agent sessions.
+
+> **Scope: skills only.** Pi does not ship with pre-baked MCP servers, hooks, references, or plugins, so this adapter translates *only* skills. MCP servers, hooks, and standalone references are intentionally not translated (see [Known gaps](#known-gaps)).
+
+## Installation
+
+```bash
+npm install @pulsemcp/air-adapter-pi
+```
+
+## Usage
+
+### With the AIR CLI
+
+```bash
+# Install the adapter globally alongside the CLI
+npm install -g @pulsemcp/air-cli @pulsemcp/air-adapter-pi
+
+# Start a Pi session
+air start pi --root web-app
+```
+
+### Programmatic
+
+```typescript
+import { resolveArtifacts } from "@pulsemcp/air-core";
+import { PiAdapter } from "@pulsemcp/air-adapter-pi";
+
+const artifacts = await resolveArtifacts("./air.json");
+const adapter = new PiAdapter();
+
+// Prepare a working directory for a Pi session
+const session = await adapter.prepareSession(artifacts, "./my-project", {
+  root: artifacts.roots["web-app"],
+});
+
+// session.configFiles  — [] (Pi discovers skills from the filesystem)
+// session.skillPaths   — skill dirs created in .pi/skills/
+// session.hookPaths    — [] (Pi is skills-only)
+// session.startCommand — { command: "pi", args: [], cwd: "..." }
+```
+
+## What `prepareSession()` does
+
+1. **Injects skills** — copies `SKILL.md` files and associated content into `.pi/skills/{name}/`, where Pi auto-discovers them. Any directory containing a `SKILL.md` is treated by Pi as a skill root.
+2. **Copies references** — attaches a skill's referenced documents into `<skill>/references/`, so they travel with the self-contained skill directory.
+3. **Reconciles via the manifest** — re-runs remove skills that are no longer activated before injecting the current set, keeping `air clean` and re-`prepare` idempotent.
+4. **Respects local priority** — if a skill directory already exists in the target, it is not overwritten.
+
+No config file is written: Pi loads `.pi/skills/` directly from the filesystem, so `prepareSession()` returns an **empty `configFiles` array**.
+
+## Translation Details
+
+| AIR Format | Pi Format |
+|------------|-----------|
+| Skills (`SKILL.md` + content) | `.pi/skills/{name}/` (auto-discovered as a project skill) |
+| Skill-owned references | `.pi/skills/{name}/references/` |
+| Plugin-declared skills | merged into the skill activation set (composition sugar) |
+
+## Known gaps
+
+These AIR features are intentionally **not** translated, because Pi is a skills-only target for AIR:
+
+- **MCP servers** — Pi does not ship with an AIR-translatable MCP server registry. MCP server entries are ignored; the manifest records `mcpServers: []`.
+- **Hooks** — Pi has no AIR-translatable hook lifecycle. Hook entries are ignored; the manifest records `hooks: []` and `prepareSession()` returns an empty `hookPaths` array.
+- **Standalone references** — only skill-*owned* references are copied (alongside the skill). There is no standalone reference materialization.
+- **Plugins** — honored only as composition sugar: a plugin's declared *skills* are merged into the activation set; its MCP servers and hooks are ignored.
+- **Subagent context** — this adapter does not wire an AIR-driven system-prompt flag, so subagent-root context is returned to the caller via `PreparedSession.subagentContext` rather than passed to the CLI.

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import type { AirExtension } from "@pulsemcp/air-core";
+export { PiAdapter } from "./pi-adapter.js";
+declare const extension: AirExtension;
+export default extension;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,QAAA,MAAM,SAAS,EAAE,YAGhB,CAAC;AAEF,eAAe,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+import { PiAdapter } from "./pi-adapter.js";
+export { PiAdapter } from "./pi-adapter.js";
+const extension = {
+    name: "pi",
+    adapter: new PiAdapter(),
+};
+export default extension;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,MAAM,SAAS,GAAiB;IAC9B,IAAI,EAAE,IAAI;IACV,OAAO,EAAE,IAAI,SAAS,EAAE;CACzB,CAAC;AAEF,eAAe,SAAS,CAAC"}

package/dist/pi-adapter.d.ts

@@ -0,0 +1,114 @@
+import type { AgentAdapter, AgentSessionConfig, StartCommand, ResolvedArtifacts, RootEntry, PrepareSessionOptions, PreparedSession, CleanSessionOptions, CleanSessionResult, LocalArtifacts } from "@pulsemcp/air-core";
+/**
+ * AIR adapter for the Pi coding agent (`pi`, https://www.npmjs.com/package/@earendil-works/pi-coding-agent).
+ *
+ * Scope: SKILLS ONLY. Pi does not ship with pre-baked MCP servers, hooks,
+ * references, or plugins the way a fuller agent runtime might, so this adapter
+ * translates only skills. MCP servers, hooks, and standalone references are
+ * intentionally not translated — see `generateConfig` and `prepareSession`.
+ *
+ * Pi auto-discovers project skills from `<cwd>/.pi/skills/`: any directory
+ * containing a `SKILL.md` is treated as a skill root (Pi stops recursing into
+ * it, so bundled reference files are safe). This adapter materializes activated
+ * skills into `.pi/skills/<name>/` — purely filesystem placement, no config
+ * file is written or required for Pi to load them.
+ */
+export declare class PiAdapter implements AgentAdapter {
+    name: string;
+    displayName: string;
+    isAvailable(): Promise<boolean>;
+    /**
+     * Translate resolved AIR artifacts into a Pi session config.
+     *
+     * Skills only: plugin-declared skills are merged into the root's default
+     * skills (additive), since AIR plugins are composition sugar. A plugin's
+     * MCP servers and hooks are intentionally ignored — Pi is skills-only.
+     */
+    generateConfig(artifacts: ResolvedArtifacts, root?: RootEntry, _workDir?: string): AgentSessionConfig;
+    buildStartCommand(config: AgentSessionConfig): StartCommand;
+    /**
+     * Prepare a working directory for a Pi session.
+     *
+     * Injects activated skills + their references into `.pi/skills/<name>/`,
+     * reconciling against the per-target manifest so re-runs and `air clean`
+     * are idempotent. No config file is written: Pi auto-discovers `.pi/skills/`
+     * by walking the filesystem, so there is nothing for AIR's JSON transform
+     * pipeline to post-process — `configFiles` is returned empty.
+     *
+     * Inputs to the skill activation list (root defaults, overrides, subagent
+     * roots, plugin-declared skills) are accepted as either qualified (`@scope/id`)
+     * or short form; ambiguous short forms are rejected. Filesystem
+     * materialization uses shortnames — `.pi/skills/` and the manifest are
+     * scope-naive. Two activated qualified IDs that share a shortname hard-fail
+     * with a clear "add one to exclude" message.
+     *
+     * MCP servers, hooks, and standalone references are intentionally NOT
+     * translated: Pi is skills-only. The manifest records skills only
+     * (`hooks: []`, `mcpServers: []`).
+     */
+    prepareSession(artifacts: ResolvedArtifacts, targetDir: string, options?: PrepareSessionOptions): Promise<PreparedSession>;
+    /**
+     * Enumerate skills checked into `<targetDir>/.pi/skills/`. Pi loads these
+     * directly from the filesystem regardless of AIR's involvement, so they're
+     * always active and must not be overwritten or removed. The TUI uses this
+     * list to surface them as read-only entries.
+     */
+    listLocalArtifacts(targetDir: string): Promise<LocalArtifacts>;
+    /**
+     * Remove every skill AIR has previously written into `targetDir`.
+     *
+     * Reads the per-target manifest and deletes each tracked skill directory
+     * under `.pi/skills/`. Pi is skills-only, so there are no hooks, MCP servers,
+     * or settings files to prune. When skills are cleaned (the only category that
+     * can hold entries), the manifest itself is deleted; a partial clean
+     * (`keepSkills`) updates the manifest with the kept entries instead.
+     *
+     * Items in the manifest that no longer exist on disk are silently skipped —
+     * the manifest can drift if a user removed files manually between runs.
+     */
+    cleanSession(targetDir: string, options?: CleanSessionOptions): Promise<CleanSessionResult>;
+    /**
+     * Resolve subagent roots from the root's default_subagent_roots.
+     * IDs are already qualified after composition-time canonicalization.
+     */
+    private resolveSubagentRoots;
+    /**
+     * Merge subagent roots' default_skills into the parent's activated skills
+     * (union, preserving order with parent first). MCP servers are not merged —
+     * Pi is skills-only.
+     */
+    private mergeSubagentSkills;
+    /**
+     * Build a system prompt section describing the subagent root dependencies.
+     * Skills-scoped: MCP servers are not surfaced because Pi is skills-only.
+     */
+    private buildSubagentContext;
+    /**
+     * Resolve a list of activation IDs (each qualified or short) into qualified
+     * IDs paired with shortnames suitable for filesystem materialization.
+     *
+     * Throws on:
+     *   - unknown IDs (after attempting both qualified and short-form lookup)
+     *   - ambiguous short references (multiple scopes contribute the shortname)
+     *   - shortname collisions in the activation set itself (two qualified IDs
+     *     with the same shortname can't share a single materialization dir)
+     */
+    private resolveActivations;
+    /**
+     * Build the warning emitted when a registered skill's `path` does not exist
+     * on disk at materialization time. The qualified ID encodes the declaring
+     * catalog's scope, so a reviewer can trace the offending entry back to its
+     * index file. Materialization is skipped for this skill and the rest of the
+     * session proceeds.
+     */
+    private missingSourceDirMessage;
+    private formatPoolKeys;
+    /**
+     * Copy referenced documents into a references/ subdirectory of the skill.
+     * `refIds` are qualified IDs (post-canonicalization). Pi treats the skill
+     * directory as a self-contained root, so bundled references travel with it.
+     */
+    private copyReferences;
+    private copyDirRecursive;
+}
+//# sourceMappingURL=pi-adapter.d.ts.map

package/dist/pi-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-adapter.d.ts","sourceRoot":"","sources":["../src/pi-adapter.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,SAAS,EAET,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EAEf,MAAM,oBAAoB,CAAC;AAsB5B;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAU,YAAW,YAAY;IAC5C,IAAI,SAAQ;IACZ,WAAW,SAAQ;IAEb,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IASrC;;;;;;OAMG;IACH,cAAc,CACZ,SAAS,EAAE,iBAAiB,EAC5B,IAAI,CAAC,EAAE,SAAS,EAChB,QAAQ,CAAC,EAAE,MAAM,GAChB,kBAAkB;IA+BrB,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY;IAY3D;;;;;;;;;;;;;;;;;;;OAmBG;IACG,cAAc,CAClB,SAAS,EAAE,iBAAiB,EAC5B,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,eAAe,CAAC;IAyH3B;;;;;OAKG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAIpE;;;;;;;;;;;OAWG;IACG,YAAY,CAChB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC;IAsE9B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAa3B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAyB5B;;;;;;;;;OASG;IACH,OAAO,CAAC,kBAAkB;IAgD1B;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IAY/B,OAAO,CAAC,cAAc;IAStB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,gBAAgB;CAYzB"}

package/dist/pi-adapter.js

@@ -0,0 +1,444 @@
+import { execSync } from "child_process";
+import { existsSync, mkdirSync, readdirSync, copyFileSync, rmSync, statSync, } from "fs";
+import { join, dirname } from "path";
+import { buildManifest, deleteManifest, diffManifest, getManifestPath, loadManifest, writeManifest, parseQualifiedId, resolveReference, } from "@pulsemcp/air-core";
+import { scanLocalSkills } from "./scan-local-skills.js";
+/**
+ * AIR adapter for the Pi coding agent (`pi`, https://www.npmjs.com/package/@earendil-works/pi-coding-agent).
+ *
+ * Scope: SKILLS ONLY. Pi does not ship with pre-baked MCP servers, hooks,
+ * references, or plugins the way a fuller agent runtime might, so this adapter
+ * translates only skills. MCP servers, hooks, and standalone references are
+ * intentionally not translated — see `generateConfig` and `prepareSession`.
+ *
+ * Pi auto-discovers project skills from `<cwd>/.pi/skills/`: any directory
+ * containing a `SKILL.md` is treated as a skill root (Pi stops recursing into
+ * it, so bundled reference files are safe). This adapter materializes activated
+ * skills into `.pi/skills/<name>/` — purely filesystem placement, no config
+ * file is written or required for Pi to load them.
+ */
+export class PiAdapter {
+    name = "pi";
+    displayName = "Pi";
+    async isAvailable() {
+        try {
+            execSync("which pi", { stdio: "pipe" });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Translate resolved AIR artifacts into a Pi session config.
+     *
+     * Skills only: plugin-declared skills are merged into the root's default
+     * skills (additive), since AIR plugins are composition sugar. A plugin's
+     * MCP servers and hooks are intentionally ignored — Pi is skills-only.
+     */
+    generateConfig(artifacts, root, _workDir) {
+        const pluginActivations = root?.default_plugins
+            ? this.resolveActivations(artifacts.plugins, root.default_plugins, "plugin")
+            : [];
+        const plugins = {};
+        for (const a of pluginActivations)
+            plugins[a.qualified] = artifacts.plugins[a.qualified];
+        // Merge plugin-declared skills into root defaults (additive). All incoming
+        // IDs are qualified (post-canonicalization at composition time), so we
+        // deduplicate on qualified IDs.
+        const skillQualSet = new Set(root?.default_skills ?? []);
+        for (const plugin of Object.values(plugins)) {
+            if (plugin.skills) {
+                for (const id of plugin.skills)
+                    skillQualSet.add(id);
+            }
+        }
+        const skillActivations = this.resolveActivations(artifacts.skills, [...skillQualSet], "skill");
+        const skillPaths = skillActivations.map((a) => artifacts.skills[a.qualified].path);
+        return {
+            agent: "pi",
+            skillPaths,
+            env: {},
+        };
+    }
+    buildStartCommand(config) {
+        // Pi auto-discovers `.pi/skills/` relative to its working directory.
+        // Pointing the working directory at the prepared directory loads the
+        // injected skills; no extra flags are required.
+        return {
+            command: "pi",
+            args: [],
+            env: config.env,
+            cwd: config.workDir,
+        };
+    }
+    /**
+     * Prepare a working directory for a Pi session.
+     *
+     * Injects activated skills + their references into `.pi/skills/<name>/`,
+     * reconciling against the per-target manifest so re-runs and `air clean`
+     * are idempotent. No config file is written: Pi auto-discovers `.pi/skills/`
+     * by walking the filesystem, so there is nothing for AIR's JSON transform
+     * pipeline to post-process — `configFiles` is returned empty.
+     *
+     * Inputs to the skill activation list (root defaults, overrides, subagent
+     * roots, plugin-declared skills) are accepted as either qualified (`@scope/id`)
+     * or short form; ambiguous short forms are rejected. Filesystem
+     * materialization uses shortnames — `.pi/skills/` and the manifest are
+     * scope-naive. Two activated qualified IDs that share a shortname hard-fail
+     * with a clear "add one to exclude" message.
+     *
+     * MCP servers, hooks, and standalone references are intentionally NOT
+     * translated: Pi is skills-only. The manifest records skills only
+     * (`hooks: []`, `mcpServers: []`).
+     */
+    async prepareSession(artifacts, targetDir, options) {
+        const root = options?.root;
+        const skillPaths = [];
+        const prevManifest = loadManifest(targetDir);
+        // 1. Resolve which skills to activate (overrides take precedence over root defaults).
+        let skillIds = options?.skillOverrides ?? root?.default_skills ?? [];
+        // 1b. Merge subagent roots' skills if applicable.
+        const subagentRoots = this.resolveSubagentRoots(root, artifacts, options);
+        if (subagentRoots.length > 0 && !options?.skillOverrides) {
+            skillIds = this.mergeSubagentSkills(subagentRoots, skillIds);
+        }
+        // 1c. Resolve plugins and merge their declared skills (additive). A plugin's
+        //     MCP servers and hooks are intentionally ignored — Pi is skills-only.
+        const pluginIds = options?.pluginOverrides ?? root?.default_plugins ?? undefined;
+        const pluginActivations = pluginIds?.length
+            ? this.resolveActivations(artifacts.plugins, pluginIds, "plugin")
+            : [];
+        const skillSet = new Set(skillIds);
+        for (const a of pluginActivations) {
+            const plugin = artifacts.plugins[a.qualified];
+            if (plugin.skills)
+                for (const id of plugin.skills)
+                    skillSet.add(id);
+        }
+        skillIds = [...skillSet];
+        // 2. Resolve activations: qualified ID + shortname per skill.
+        //    Throws on unknown IDs, ambiguous shortnames, and shortname collisions.
+        const skillActs = this.resolveActivations(artifacts.skills, skillIds, "skill");
+        const skillShortIds = skillActs.map((a) => a.short);
+        // 3. Reconcile against prior manifest using shortnames — those are the keys
+        //    used for filesystem materialization and stored in the manifest.
+        const diff = diffManifest(prevManifest, {
+            skills: skillShortIds,
+            hooks: [],
+            mcpServers: [],
+        });
+        for (const staleSkillId of diff.staleSkills) {
+            const staleDir = join(targetDir, ".pi", "skills", staleSkillId);
+            if (existsSync(staleDir)) {
+                rmSync(staleDir, { recursive: true, force: true });
+            }
+        }
+        // 4. Inject skills + references into .pi/skills/<short>/.
+        const materializedSkillShortIds = [];
+        for (const a of skillActs) {
+            const skill = artifacts.skills[a.qualified];
+            const skillTargetDir = join(targetDir, ".pi", "skills", a.short);
+            if (existsSync(skillTargetDir)) {
+                materializedSkillShortIds.push(a.short);
+                continue;
+            }
+            const skillSourceDir = skill.path;
+            if (!existsSync(skillSourceDir)) {
+                console.warn(this.missingSourceDirMessage("skill", a.qualified, skillSourceDir));
+                continue;
+            }
+            this.copyDirRecursive(skillSourceDir, skillTargetDir);
+            skillPaths.push(skillTargetDir);
+            materializedSkillShortIds.push(a.short);
+            if (skill.references && skill.references.length > 0) {
+                this.copyReferences(skill.references, skillTargetDir, artifacts);
+            }
+        }
+        // 5. Persist the updated manifest (shortnames — keyed by filesystem dir).
+        //    Only record skills that were actually materialized so the manifest
+        //    does not claim ownership of artifacts AIR skipped (e.g. a missing
+        //    source dir). Hooks and MCP servers are always empty for Pi.
+        writeManifest(buildManifest(targetDir, {
+            adapter: this.name,
+            skills: materializedSkillShortIds,
+            hooks: [],
+            mcpServers: [],
+        }));
+        // 6. Generate ephemeral subagent context for the session. Pi loads skills
+        //    from the filesystem and has no AIR-driven system-prompt flag wired by
+        //    this adapter, so subagent context is surfaced to the caller via
+        //    `subagentContext` rather than the start command.
+        let subagentContext;
+        if (subagentRoots.length > 0) {
+            subagentContext = this.buildSubagentContext(subagentRoots);
+        }
+        // 7. Build start command (working directory = prepared directory).
+        //    `root` is passed as `undefined` here on purpose: skill activation
+        //    (root defaults + overrides + subagent + plugin skills) was already
+        //    resolved and materialized above, so we only need `generateConfig` for
+        //    the agent name + env that `buildStartCommand` consumes. Passing `root`
+        //    would redundantly re-resolve skill paths from defaults alone, ignoring
+        //    the overrides applied in this call.
+        const config = this.generateConfig(artifacts, undefined, targetDir);
+        const startCommand = this.buildStartCommand({
+            ...config,
+            workDir: targetDir,
+        });
+        return {
+            // Empty by design — Pi discovers `.pi/skills/` from the filesystem, so
+            // there is no JSON config file for AIR's transform pipeline to process.
+            configFiles: [],
+            skillPaths,
+            // Pi is skills-only: no hooks are ever materialized.
+            hookPaths: [],
+            startCommand,
+            subagentContext,
+        };
+    }
+    /**
+     * Enumerate skills checked into `<targetDir>/.pi/skills/`. Pi loads these
+     * directly from the filesystem regardless of AIR's involvement, so they're
+     * always active and must not be overwritten or removed. The TUI uses this
+     * list to surface them as read-only entries.
+     */
+    async listLocalArtifacts(targetDir) {
+        return { skills: scanLocalSkills(targetDir) };
+    }
+    /**
+     * Remove every skill AIR has previously written into `targetDir`.
+     *
+     * Reads the per-target manifest and deletes each tracked skill directory
+     * under `.pi/skills/`. Pi is skills-only, so there are no hooks, MCP servers,
+     * or settings files to prune. When skills are cleaned (the only category that
+     * can hold entries), the manifest itself is deleted; a partial clean
+     * (`keepSkills`) updates the manifest with the kept entries instead.
+     *
+     * Items in the manifest that no longer exist on disk are silently skipped —
+     * the manifest can drift if a user removed files manually between runs.
+     */
+    async cleanSession(targetDir, options) {
+        const dryRun = options?.dryRun ?? false;
+        const cleanSkills = !(options?.keepSkills ?? false);
+        const cleanHooks = !(options?.keepHooks ?? false);
+        const cleanMcpServers = !(options?.keepMcpServers ?? false);
+        // Pi only ever tracks skills, but honor the same "full clean" predicate as
+        // other adapters so a caller that keeps any category preserves the manifest.
+        const fullClean = cleanSkills && cleanHooks && cleanMcpServers;
+        const manifestPath = getManifestPath(targetDir);
+        const manifestFileExists = existsSync(manifestPath);
+        const manifest = loadManifest(targetDir);
+        if (!manifest) {
+            let corruptManifestRemoved = false;
+            if (manifestFileExists && fullClean && !dryRun) {
+                corruptManifestRemoved = deleteManifest(targetDir);
+            }
+            return {
+                removedSkills: [],
+                removedHooks: [],
+                removedMcpServers: [],
+                mcpConfigPath: null,
+                settingsPath: null,
+                manifestPath,
+                manifestExisted: manifestFileExists,
+                manifestRemoved: corruptManifestRemoved,
+            };
+        }
+        const removedSkills = [];
+        if (cleanSkills) {
+            for (const id of manifest.skills) {
+                const dir = join(targetDir, ".pi", "skills", id);
+                if (!existsSync(dir))
+                    continue;
+                if (!dryRun)
+                    rmSync(dir, { recursive: true, force: true });
+                removedSkills.push(id);
+            }
+        }
+        let manifestRemoved = false;
+        if (fullClean) {
+            if (!dryRun) {
+                manifestRemoved = deleteManifest(targetDir);
+            }
+            else {
+                manifestRemoved = manifestFileExists;
+            }
+        }
+        else if (!dryRun) {
+            writeManifest(buildManifest(targetDir, {
+                adapter: manifest.adapter ?? this.name,
+                skills: cleanSkills ? [] : manifest.skills,
+                hooks: [],
+                mcpServers: [],
+            }));
+        }
+        return {
+            removedSkills,
+            // Pi is skills-only: hooks and MCP servers are never materialized.
+            removedHooks: [],
+            removedMcpServers: [],
+            mcpConfigPath: null,
+            settingsPath: null,
+            manifestPath,
+            manifestExisted: true,
+            manifestRemoved,
+        };
+    }
+    /**
+     * Resolve subagent roots from the root's default_subagent_roots.
+     * IDs are already qualified after composition-time canonicalization.
+     */
+    resolveSubagentRoots(root, artifacts, options) {
+        if (options?.skipSubagentMerge)
+            return [];
+        if (!root?.default_subagent_roots?.length)
+            return [];
+        const resolved = [];
+        for (const id of root.default_subagent_roots) {
+            const res = resolveReference(artifacts.roots, id, undefined);
+            if (res.status === "ok") {
+                resolved.push(artifacts.roots[res.qualified]);
+            }
+        }
+        return resolved;
+    }
+    /**
+     * Merge subagent roots' default_skills into the parent's activated skills
+     * (union, preserving order with parent first). MCP servers are not merged —
+     * Pi is skills-only.
+     */
+    mergeSubagentSkills(subagentRoots, parentSkillIds) {
+        const skillSet = new Set(parentSkillIds);
+        for (const sub of subagentRoots) {
+            if (sub.default_skills) {
+                for (const id of sub.default_skills)
+                    skillSet.add(id);
+            }
+        }
+        return [...skillSet];
+    }
+    /**
+     * Build a system prompt section describing the subagent root dependencies.
+     * Skills-scoped: MCP servers are not surfaced because Pi is skills-only.
+     */
+    buildSubagentContext(subagentRoots) {
+        const lines = [
+            "## Subagent Root Dependencies",
+            "",
+            "This session includes capabilities from the following subagent roots.",
+            "Their skills have been merged into your session.",
+            "",
+        ];
+        for (const sub of subagentRoots) {
+            lines.push(`### ${sub.display_name || "Subagent"}`);
+            lines.push("");
+            lines.push(`**Description**: ${sub.description}`);
+            if (sub.default_skills?.length) {
+                lines.push(`**Skills**: ${sub.default_skills.join(", ")}`);
+            }
+            if (sub.subdirectory) {
+                lines.push(`**Subdirectory**: ${sub.subdirectory}`);
+            }
+            lines.push("");
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Resolve a list of activation IDs (each qualified or short) into qualified
+     * IDs paired with shortnames suitable for filesystem materialization.
+     *
+     * Throws on:
+     *   - unknown IDs (after attempting both qualified and short-form lookup)
+     *   - ambiguous short references (multiple scopes contribute the shortname)
+     *   - shortname collisions in the activation set itself (two qualified IDs
+     *     with the same shortname can't share a single materialization dir)
+     */
+    resolveActivations(pool, ids, artifactType) {
+        const acts = [];
+        const errors = [];
+        const shortToQualified = new Map();
+        for (const id of ids) {
+            const res = resolveReference(pool, id, undefined);
+            if (res.status === "missing") {
+                errors.push(`Unknown ${artifactType} ID "${id}". Available: ${this.formatPoolKeys(pool)}.`);
+                continue;
+            }
+            if (res.status === "ambiguous") {
+                errors.push(`${artifactType} reference "${id}" is ambiguous — candidates: ` +
+                    `${res.candidates.join(", ")}. Use the qualified form to disambiguate.`);
+                continue;
+            }
+            const qualified = res.qualified;
+            const { id: short } = parseQualifiedId(qualified);
+            const prior = shortToQualified.get(short);
+            if (prior !== undefined && prior !== qualified) {
+                errors.push(`${artifactType} shortname collision: both "${prior}" and "${qualified}" ` +
+                    `are activated and would write to the same target name "${short}". ` +
+                    `Add one to air.json#exclude or activate only one of them.`);
+                continue;
+            }
+            if (prior === qualified)
+                continue; // dedup
+            shortToQualified.set(short, qualified);
+            acts.push({ qualified, short });
+        }
+        if (errors.length > 0) {
+            throw new Error(errors.length === 1 ? errors[0] : `Activation errors:\n  - ${errors.join("\n  - ")}`);
+        }
+        return acts;
+    }
+    /**
+     * Build the warning emitted when a registered skill's `path` does not exist
+     * on disk at materialization time. The qualified ID encodes the declaring
+     * catalog's scope, so a reviewer can trace the offending entry back to its
+     * index file. Materialization is skipped for this skill and the rest of the
+     * session proceeds.
+     */
+    missingSourceDirMessage(artifactType, qualified, resolvedPath) {
+        return (`warning: ${artifactType} "${qualified}" declares path "${resolvedPath}" but that directory does not exist — skipping. ` +
+            `The catalog that contributed "${qualified}" registered a path AIR cannot materialize. ` +
+            `Fix the \`path\` field in the catalog's index file (or exclude the artifact in air.json) to restore the ${artifactType}.`);
+    }
+    formatPoolKeys(pool) {
+        const keys = Object.keys(pool);
+        if (keys.length === 0)
+            return "(none)";
+        if (keys.length > 8) {
+            return `${keys.slice(0, 8).join(", ")}, … (${keys.length} total)`;
+        }
+        return keys.join(", ");
+    }
+    /**
+     * Copy referenced documents into a references/ subdirectory of the skill.
+     * `refIds` are qualified IDs (post-canonicalization). Pi treats the skill
+     * directory as a self-contained root, so bundled references travel with it.
+     */
+    copyReferences(refIds, targetDir, artifacts) {
+        const refsTargetDir = join(targetDir, "references");
+        for (const refId of refIds) {
+            const ref = artifacts.references[refId];
+            if (!ref)
+                continue;
+            const refSourcePath = ref.path;
+            if (existsSync(refSourcePath)) {
+                const refTargetPath = join(refsTargetDir, ref.path.split("/").pop() || ref.path);
+                mkdirSync(dirname(refTargetPath), { recursive: true });
+                copyFileSync(refSourcePath, refTargetPath);
+            }
+        }
+    }
+    copyDirRecursive(src, dest) {
+        mkdirSync(dest, { recursive: true });
+        for (const entry of readdirSync(src)) {
+            const srcPath = join(src, entry);
+            const destPath = join(dest, entry);
+            if (statSync(srcPath).isDirectory()) {
+                this.copyDirRecursive(srcPath, destPath);
+            }
+            else {
+                copyFileSync(srcPath, destPath);
+            }
+        }
+    }
+}
+//# sourceMappingURL=pi-adapter.js.map

package/dist/pi-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-adapter.js","sourceRoot":"","sources":["../src/pi-adapter.ts"],"names":[],"mappings":"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"}

package/dist/scan-local-skills.d.ts

@@ -0,0 +1,11 @@
+import type { LocalSkillEntry } from "@pulsemcp/air-core";
+/**
+ * Scan `<targetDir>/.pi/skills/` for user-managed skills and return one entry
+ * per directory containing a `SKILL.md`. Pi auto-discovers project skills from
+ * `.pi/skills/` (a directory containing `SKILL.md` is treated as a skill root),
+ * so these are always active regardless of AIR's involvement — the TUI surfaces
+ * them as read-only entries. Missing or unreadable directories yield an empty
+ * list — this is a best-effort informational scan, not validation.
+ */
+export declare function scanLocalSkills(targetDir: string): LocalSkillEntry[];
+//# sourceMappingURL=scan-local-skills.d.ts.map

package/dist/scan-local-skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-local-skills.d.ts","sourceRoot":"","sources":["../src/scan-local-skills.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CA2CpE"}

package/dist/scan-local-skills.js

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+/**
+ * Scan `<targetDir>/.pi/skills/` for user-managed skills and return one entry
+ * per directory containing a `SKILL.md`. Pi auto-discovers project skills from
+ * `.pi/skills/` (a directory containing `SKILL.md` is treated as a skill root),
+ * so these are always active regardless of AIR's involvement — the TUI surfaces
+ * them as read-only entries. Missing or unreadable directories yield an empty
+ * list — this is a best-effort informational scan, not validation.
+ */
+export function scanLocalSkills(targetDir) {
+    const skillsDir = join(targetDir, ".pi", "skills");
+    if (!existsSync(skillsDir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(skillsDir);
+    }
+    catch {
+        return [];
+    }
+    const skills = [];
+    for (const name of entries) {
+        if (name.startsWith("."))
+            continue;
+        const skillDir = join(skillsDir, name);
+        let isDir = false;
+        try {
+            isDir = statSync(skillDir).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (!isDir)
+            continue;
+        const skillMdPath = join(skillDir, "SKILL.md");
+        if (!existsSync(skillMdPath))
+            continue;
+        const frontmatter = readFrontmatter(skillMdPath);
+        const description = pickString(frontmatter, "description") ?? "(local skill — no description)";
+        const title = pickString(frontmatter, "title") ?? pickString(frontmatter, "name");
+        skills.push({
+            id: name,
+            description,
+            title,
+            path: skillDir,
+        });
+    }
+    skills.sort((a, b) => a.id.localeCompare(b.id));
+    return skills;
+}
+/**
+ * Minimal YAML frontmatter reader — parses a leading block delimited by
+ * `---` lines into a flat key/value map. Only handles top-level
+ * `key: value` scalars, which is all SKILL.md frontmatter needs in
+ * practice. Unquoted values have surrounding whitespace trimmed and
+ * matching single/double quotes stripped.
+ */
+function readFrontmatter(path) {
+    let content;
+    try {
+        content = readFileSync(path, "utf-8");
+    }
+    catch {
+        return {};
+    }
+    const lines = content.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---")
+        return {};
+    const result = {};
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === "---")
+            return result;
+        const match = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
+        if (!match)
+            continue;
+        const key = match[1];
+        let value = match[2].trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        result[key] = value;
+    }
+    return result;
+}
+function pickString(obj, key) {
+    const v = obj[key];
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+//# sourceMappingURL=scan-local-skills.js.map

package/dist/scan-local-skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-local-skills.js","sourceRoot":"","sources":["../src/scan-local-skills.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@pulsemcp/air-adapter-pi",
+  "version": "0.7.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pulsemcp/air.git",
+    "directory": "packages/extensions/adapter-pi"
+  },
+  "description": "AIR adapter for the Pi coding agent — injects AIR skills into Pi's native skills location",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@pulsemcp/air-core": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}