agent-trellis 0.1.0

package/dist/pi-bridge/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * pi extension entry point (trellis-pi-mcp-bridge-p4). Delivered by
+ * symlinking this exact file into `~/.pi/agent/extensions/`
+ * (src/adapters/pi.ts) — pi's own directory-based auto-discovery loads
+ * it with zero settings.json involvement (design.md D1).
+ *
+ * Deliberately duck-typed against pi's extension API (no dependency on
+ * `@earendil-works/pi-coding-agent` itself — this file must work
+ * regardless of which pi version is installed on a given machine, and a
+ * type-only import would still require that package to be resolvable
+ * from Trellis's own install tree). Only the handful of fields/methods
+ * this bridge actually uses are declared here.
+ */
+import type { TSchema } from "typebox";
+import { toPiContent } from "./schemaTranslate.js";
+interface PiToolResult {
+    content: ReturnType<typeof toPiContent>;
+    details: unknown;
+}
+interface PiToolDefinition {
+    name: string;
+    label: string;
+    description: string;
+    parameters: TSchema;
+    execute(toolCallId: string, params: Record<string, unknown>): Promise<PiToolResult>;
+}
+interface PiExtensionAPI {
+    registerTool(tool: PiToolDefinition): void;
+    on?(event: "session_shutdown", handler: () => Promise<void> | void): void;
+}
+/**
+ * A hanging server (process alive, protocol response never sent) leaves
+ * `promise` permanently unsettled — indistinguishable from "still
+ * starting up" without a bound. Racing against a timeout converts that
+ * into an ordinary rejection, which every caller here already knows how
+ * to isolate (design.md D1, trellis-mcp-connect-timeout).
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T>;
+/**
+ * `homeDir`/`connectTimeoutMs` default to the real `~` / 10s — only
+ * overridable for tests, same seam every other Trellis entry point
+ * uses. Neither is something pi itself ever passes; this factory's own
+ * signature matches pi's `ExtensionFactory = (pi) => void | Promise<void>`
+ * exactly (both trailing params have defaults, so calling it as
+ * `factory(pi)` — what pi actually does — works unchanged).
+ */
+export default function trellisMcpBridge(pi: PiExtensionAPI, homeDir?: string, connectTimeoutMs?: number): Promise<void>;
+export {};

package/dist/pi-bridge/index.js

@@ -0,0 +1,188 @@
+/**
+ * pi extension entry point (trellis-pi-mcp-bridge-p4). Delivered by
+ * symlinking this exact file into `~/.pi/agent/extensions/`
+ * (src/adapters/pi.ts) — pi's own directory-based auto-discovery loads
+ * it with zero settings.json involvement (design.md D1).
+ *
+ * Deliberately duck-typed against pi's extension API (no dependency on
+ * `@earendil-works/pi-coding-agent` itself — this file must work
+ * regardless of which pi version is installed on a given machine, and a
+ * type-only import would still require that package to be resolvable
+ * from Trellis's own install tree). Only the handful of fields/methods
+ * this bridge actually uses are declared here.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { homedir } from "node:os";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { resolveMcpPlan } from "../adapters/mcpPlan.js";
+import { resolveSecretEnv } from "../lib/secretEnv.js";
+import { extractTemplateVarNames } from "../lib/envVarNames.js";
+import { bridgedToolName, toParametersSchema, toPiContent } from "./schemaTranslate.js";
+const CLIENT_INFO = { name: "trellis-mcp-bridge", version: "0.0.0" };
+const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
+/**
+ * A hanging server (process alive, protocol response never sent) leaves
+ * `promise` permanently unsettled — indistinguishable from "still
+ * starting up" without a bound. Racing against a timeout converts that
+ * into an ordinary rejection, which every caller here already knows how
+ * to isolate (design.md D1, trellis-mcp-connect-timeout).
+ */
+export function withTimeout(promise, timeoutMs, message) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+/**
+ * A timed-out (or otherwise failed) connect attempt must not leak the
+ * transport's own resources — for `StdioClientTransport` specifically,
+ * an unclosed transport means an orphaned child process that outlives
+ * this failed attempt indefinitely (confirmed by a real leaked
+ * subprocess during this change's own test run). `transport.close()` is
+ * best-effort: a transport that never fully connected may itself error
+ * on close, but the original connect failure is what the caller needs
+ * to see, not a secondary cleanup error.
+ */
+async function connectWithCleanup(client, transport, timeoutMs, message) {
+    try {
+        await withTimeout(client.connect(transport), timeoutMs, message);
+        return client;
+    }
+    catch (err) {
+        try {
+            await transport.close();
+        }
+        catch {
+            // best-effort; the original connect failure is what matters
+        }
+        throw err;
+    }
+}
+async function connectStdio(def, secretsPolicy, timeoutMs) {
+    const client = new Client(CLIENT_INFO, { capabilities: {} });
+    const resolved = resolveSecretEnv(def.env ?? [], secretsPolicy);
+    const namedEnv = Object.fromEntries((def.env ?? []).map((name) => [name, resolved[name] ?? ""]));
+    const transport = new StdioClientTransport({
+        command: def.command,
+        args: def.args,
+        env: { ...getDefaultEnvironment(), ...namedEnv },
+    });
+    return connectWithCleanup(client, transport, timeoutMs, `connect timed out after ${timeoutMs}ms`);
+}
+function resolveHeaders(def, secretsPolicy) {
+    if (!def.headers || Object.keys(def.headers).length === 0)
+        return undefined;
+    const names = Object.keys(def.headers).flatMap((key) => extractTemplateVarNames(def.headers[key]));
+    const resolved = resolveSecretEnv(names, secretsPolicy);
+    const result = {};
+    for (const [key, template] of Object.entries(def.headers)) {
+        result[key] = template.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => resolved[name] ?? "");
+    }
+    return result;
+}
+async function connectHttp(def, secretsPolicy, timeoutMs) {
+    const client = new Client(CLIENT_INFO, { capabilities: {} });
+    const headers = resolveHeaders(def, secretsPolicy);
+    const opts = headers ? { requestInit: { headers } } : undefined;
+    return connectWithCleanup(client, new StreamableHTTPClientTransport(new URL(def.url), opts), timeoutMs, `connect timed out after ${timeoutMs}ms`);
+}
+async function connectSse(def, secretsPolicy, timeoutMs) {
+    const client = new Client(CLIENT_INFO, { capabilities: {} });
+    const headers = resolveHeaders(def, secretsPolicy);
+    const opts = headers ? { requestInit: { headers } } : undefined;
+    return connectWithCleanup(client, new SSEClientTransport(new URL(def.url), opts), timeoutMs, `connect timed out after ${timeoutMs}ms`);
+}
+function registerServerTools(pi, serverName, client, timeoutMs) {
+    return withTimeout(client.listTools(), timeoutMs, `listTools timed out after ${timeoutMs}ms`).then((result) => {
+        for (const tool of result.tools) {
+            pi.registerTool({
+                name: bridgedToolName(serverName, tool.name),
+                label: tool.name,
+                description: tool.description ?? `MCP tool "${tool.name}" from server "${serverName}"`,
+                parameters: toParametersSchema(tool.inputSchema),
+                async execute(_toolCallId, params) {
+                    const result = await client.callTool({ name: tool.name, arguments: params });
+                    const content = Array.isArray(result.content) ? result.content : [];
+                    return { content: toPiContent(content), details: result };
+                },
+            });
+        }
+    });
+}
+/**
+ * `homeDir`/`connectTimeoutMs` default to the real `~` / 10s — only
+ * overridable for tests, same seam every other Trellis entry point
+ * uses. Neither is something pi itself ever passes; this factory's own
+ * signature matches pi's `ExtensionFactory = (pi) => void | Promise<void>`
+ * exactly (both trailing params have defaults, so calling it as
+ * `factory(pi)` — what pi actually does — works unchanged).
+ */
+export default async function trellisMcpBridge(pi, homeDir = homedir(), connectTimeoutMs = DEFAULT_CONNECT_TIMEOUT_MS) {
+    const canonical = loadCanonicalSource(homeDir);
+    const { desired } = resolveMcpPlan("pi", canonical.mcp);
+    const clients = new Set();
+    const closeClient = async (client) => {
+        if (!clients.delete(client))
+            return;
+        try {
+            await client.close();
+        }
+        catch (err) {
+            // Cleanup is best-effort; one transport must not block other servers.
+            console.error(`trellis-mcp-bridge: failed to close MCP client: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const closeAllClients = async () => {
+        const pending = [...clients];
+        clients.clear();
+        await Promise.all(pending.map(async (client) => {
+            try {
+                await client.close();
+            }
+            catch (err) {
+                console.error(`trellis-mcp-bridge: failed to close MCP client: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }));
+    };
+    // pi 0.85.x emits this before tearing down an extension runtime. Keep the
+    // hook optional so the bridge remains loadable in older compatible hosts.
+    pi.on?.("session_shutdown", closeAllClients);
+    await Promise.all(desired.map(async ({ name, def }) => {
+        let client;
+        try {
+            if (def.transport === "http") {
+                client = await connectHttp(def, canonical.secretsPolicy, connectTimeoutMs);
+            }
+            else if (def.transport === "sse") {
+                client = await connectSse(def, canonical.secretsPolicy, connectTimeoutMs);
+            }
+            else {
+                client = await connectStdio(def, canonical.secretsPolicy, connectTimeoutMs);
+            }
+        }
+        catch (err) {
+            // One unreachable/misconfigured (including permanently hanging —
+            // trellis-mcp-connect-timeout) server must never prevent every
+            // other server's tools from registering (tasks.md 3.2).
+            console.error(`trellis-mcp-bridge: failed to connect to MCP server "${name}": ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        clients.add(client);
+        try {
+            await registerServerTools(pi, name, client, connectTimeoutMs);
+        }
+        catch (err) {
+            console.error(`trellis-mcp-bridge: failed to list tools for MCP server "${name}": ${err instanceof Error ? err.message : String(err)}`);
+            await closeClient(client);
+        }
+    }));
+}

package/dist/pi-bridge/schemaTranslate.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Pure translation between MCP's protocol shapes and pi's own extension
+ * API shapes (trellis-pi-mcp-bridge-p4 design.md D3/D4/D5). No I/O, no
+ * MCP client, no pi runtime — everything here is unit-testable in
+ * isolation from both.
+ */
+import { type TSchema } from "typebox";
+/** MCP's `tools/call` result content item, narrowed to the fields this
+ * bridge actually reads — not the full protocol union. */
+export type McpContentItem = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+} | {
+    type: "audio";
+    data: string;
+    mimeType: string;
+} | {
+    type: "resource";
+    resource: {
+        uri: string;
+        mimeType?: string;
+    };
+} | {
+    type: "resource_link";
+    uri: string;
+    name: string;
+};
+export interface PiTextContent {
+    type: "text";
+    text: string;
+}
+export interface PiImageContent {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+export type PiContent = PiTextContent | PiImageContent;
+/** Wraps a raw MCP JSON Schema as a TypeBox `TSchema` via `Type.Unsafe` —
+ * the schema was already authored as valid JSON Schema by the MCP server,
+ * so it needs no TypeBox builder semantics applied to it, only a type
+ * that satisfies `ToolDefinition.parameters`'s `TSchema` bound
+ * (design.md D4). */
+export declare function toParametersSchema(inputSchema: unknown): TSchema;
+/** Text/image pass through unchanged; audio/resource/resource_link
+ * degrade to a text summary rather than being dropped silently — pi's
+ * own `AgentToolResult.content` has no representation for them
+ * (design.md D3). */
+export declare function toPiContent(items: McpContentItem[]): PiContent[];
+/** `${serverName}__${toolName}` — deterministic, collision-free across
+ * servers sharing pi.registerTool()'s single flat namespace (design.md D5). */
+export declare function bridgedToolName(serverName: string, toolName: string): string;

package/dist/pi-bridge/schemaTranslate.js

@@ -0,0 +1,40 @@
+/**
+ * Pure translation between MCP's protocol shapes and pi's own extension
+ * API shapes (trellis-pi-mcp-bridge-p4 design.md D3/D4/D5). No I/O, no
+ * MCP client, no pi runtime — everything here is unit-testable in
+ * isolation from both.
+ */
+import { Type } from "typebox";
+/** Wraps a raw MCP JSON Schema as a TypeBox `TSchema` via `Type.Unsafe` —
+ * the schema was already authored as valid JSON Schema by the MCP server,
+ * so it needs no TypeBox builder semantics applied to it, only a type
+ * that satisfies `ToolDefinition.parameters`'s `TSchema` bound
+ * (design.md D4). */
+export function toParametersSchema(inputSchema) {
+    return Type.Unsafe(inputSchema);
+}
+/** Text/image pass through unchanged; audio/resource/resource_link
+ * degrade to a text summary rather than being dropped silently — pi's
+ * own `AgentToolResult.content` has no representation for them
+ * (design.md D3). */
+export function toPiContent(items) {
+    return items.map((item) => {
+        switch (item.type) {
+            case "text":
+                return { type: "text", text: item.text };
+            case "image":
+                return { type: "image", data: item.data, mimeType: item.mimeType };
+            case "audio":
+                return { type: "text", text: `[audio content omitted, mimeType=${item.mimeType} — pi has no native audio tool-result type]` };
+            case "resource":
+                return { type: "text", text: `[resource content omitted, uri=${item.resource.uri} — pi has no native resource tool-result type]` };
+            case "resource_link":
+                return { type: "text", text: `[resource link omitted: ${item.name} (${item.uri}) — pi has no native resource tool-result type]` };
+        }
+    });
+}
+/** `${serverName}__${toolName}` — deterministic, collision-free across
+ * servers sharing pi.registerTool()'s single flat namespace (design.md D5). */
+export function bridgedToolName(serverName, toolName) {
+    return `${serverName}__${toolName}`;
+}

package/dist/probes/claude-code.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Claude Code probe: `~/.claude.json` (`mcpServers`), `~/.claude/skills`,
+ * `~/.claude/agents`, `~/.claude/CLAUDE.md`. Built first (tasks.md 4.1) to
+ * validate the shared `AgentSnapshot` shape before the other three probes
+ * commit to it.
+ */
+import type { AgentSnapshot } from "../core/types.js";
+export interface ProbeOptions {
+    /** Spawn each configured stdio server for a live handshake. Off by
+     * default — see docs/architecture.md "MCP handshake probing is opt-in". */
+    probeMcp?: boolean;
+}
+export declare function probe(homeDir?: string, opts?: ProbeOptions): Promise<AgentSnapshot>;

package/dist/probes/claude-code.js

@@ -0,0 +1,48 @@
+/**
+ * Claude Code probe: `~/.claude.json` (`mcpServers`), `~/.claude/skills`,
+ * `~/.claude/agents`, `~/.claude/CLAUDE.md`. Built first (tasks.md 4.1) to
+ * validate the shared `AgentSnapshot` shape before the other three probes
+ * commit to it.
+ */
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { probeMcpServer } from "../lib/mcpProbe.js";
+import { countDirEntries, pathRef, readJsonFile, resolveEnvRefs, scanSkillRoot } from "../lib/probeCommon.js";
+export async function probe(homeDir = homedir(), opts = {}) {
+    const claudeJson = readJsonFile(join(homeDir, ".claude.json"));
+    if (claudeJson === undefined) {
+        return { agent: "claude-code", present: false, skillRoots: [], mcpServers: [], diagnostics: [] };
+    }
+    let version;
+    try {
+        version = execFileSync("claude", ["--version"], { encoding: "utf-8", timeout: 5_000 }).trim();
+    }
+    catch {
+        // Config exists without the CLI on PATH — still probeable, just unversioned.
+    }
+    const mcpServers = Object.entries(claudeJson.mcpServers ?? {}).map(([name, def]) => ({
+        name,
+        transport: def.url ? "http" : "stdio",
+    }));
+    if (opts.probeMcp) {
+        await Promise.all(Object.entries(claudeJson.mcpServers ?? {}).map(async ([name, def], index) => {
+            if (def.url || !def.command)
+                return;
+            mcpServers[index].probe = await probeMcpServer({ transport: "stdio", command: def.command, args: def.args }, resolveEnvRefs(def.env, process.env));
+        }));
+    }
+    const skillRoot = scanSkillRoot(join(homeDir, ".claude", "skills"));
+    const agentsDir = join(homeDir, ".claude", "agents");
+    const agentsRef = pathRef(agentsDir);
+    return {
+        agent: "claude-code",
+        present: true,
+        version,
+        skillRoots: skillRoot ? [skillRoot] : [],
+        mcpServers,
+        instructionsFile: pathRef(join(homeDir, ".claude", "CLAUDE.md")),
+        subagentsDir: agentsRef ? { ...agentsRef, count: countDirEntries(agentsDir) } : undefined,
+        diagnostics: [],
+    };
+}

package/dist/probes/codex.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Codex probe: MCP inventory via `codex mcp list --json` (design.md D2),
+ * not TOML parsing — Codex already exposes this, so a read-only phase has
+ * no reason to hand-roll a parser P2 will need to get right for writes
+ * anyway. Skill root is `~/.agents/skills` (Codex's own convention,
+ * confirmed in docs/research.md); `~/.codex/skills` is reported as a
+ * second skill root so `doctor`'s within-agent duplication check
+ * (src/commands/doctor.ts) can catch a physical copy living there —
+ * exactly the regression already found and fixed once in this project.
+ */
+import type { AgentSnapshot } from "../core/types.js";
+/**
+ * P0-only heuristic extraction of the single top-level `instructions = "..."`
+ * key — not a TOML parser, and never feeds a write path. P2's writer uses a
+ * real TOML library (docs/research.md "Codex — three hard constraints" #3);
+ * this exists purely to display where Codex's instructions file lives.
+ */
+export declare function readInstructionsPath(configTomlPath: string): string | undefined;
+export interface ProbeOptions {
+    /** Spawn each configured stdio server for a live handshake. Off by
+     * default — see docs/architecture.md "MCP handshake probing is opt-in". */
+    probeMcp?: boolean;
+}
+export declare function probe(homeDir?: string, opts?: ProbeOptions): Promise<AgentSnapshot>;

package/dist/probes/codex.js

@@ -0,0 +1,78 @@
+/**
+ * Codex probe: MCP inventory via `codex mcp list --json` (design.md D2),
+ * not TOML parsing — Codex already exposes this, so a read-only phase has
+ * no reason to hand-roll a parser P2 will need to get right for writes
+ * anyway. Skill root is `~/.agents/skills` (Codex's own convention,
+ * confirmed in docs/research.md); `~/.codex/skills` is reported as a
+ * second skill root so `doctor`'s within-agent duplication check
+ * (src/commands/doctor.ts) can catch a physical copy living there —
+ * exactly the regression already found and fixed once in this project.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { probeMcpServer } from "../lib/mcpProbe.js";
+import { pathRef, resolveEnvRefs, scanSkillRoot } from "../lib/probeCommon.js";
+/**
+ * P0-only heuristic extraction of the single top-level `instructions = "..."`
+ * key — not a TOML parser, and never feeds a write path. P2's writer uses a
+ * real TOML library (docs/research.md "Codex — three hard constraints" #3);
+ * this exists purely to display where Codex's instructions file lives.
+ */
+export function readInstructionsPath(configTomlPath) {
+    let content;
+    try {
+        content = readFileSync(configTomlPath, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+    return /^\s*instructions\s*=\s*"([^"]*)"/m.exec(content)?.[1];
+}
+export async function probe(homeDir = homedir(), opts = {}) {
+    const configTomlPath = join(homeDir, ".codex", "config.toml");
+    if (!existsSync(configTomlPath)) {
+        return { agent: "codex", present: false, skillRoots: [], mcpServers: [], diagnostics: [] };
+    }
+    const diagnostics = [];
+    let version;
+    try {
+        version = execFileSync("codex", ["--version"], { encoding: "utf-8", timeout: 5_000 }).trim();
+    }
+    catch {
+        // config exists without the binary on PATH — unusual, still probeable
+    }
+    let mcpEntries = [];
+    try {
+        const raw = execFileSync("codex", ["mcp", "list", "--json"], { encoding: "utf-8", timeout: 5_000 });
+        mcpEntries = JSON.parse(raw);
+    }
+    catch (err) {
+        diagnostics.push(`codex mcp list --json failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const mcpServers = mcpEntries.map((entry) => ({
+        name: entry.name,
+        transport: entry.transport.type === "stdio" ? "stdio" : "http",
+    }));
+    if (opts.probeMcp) {
+        await Promise.all(mcpEntries.map(async (entry, index) => {
+            if (!entry.enabled || entry.transport.type !== "stdio" || !entry.transport.command)
+                return;
+            mcpServers[index].probe = await probeMcpServer({ transport: "stdio", command: entry.transport.command, args: entry.transport.args }, resolveEnvRefs(entry.transport.env_vars, process.env));
+        }));
+    }
+    const primaryRoot = scanSkillRoot(join(homeDir, ".agents", "skills"));
+    const codexOwnRoot = scanSkillRoot(join(homeDir, ".codex", "skills"));
+    const skillRoots = [primaryRoot, codexOwnRoot].filter((r) => r !== undefined);
+    const instructionsPath = readInstructionsPath(configTomlPath);
+    return {
+        agent: "codex",
+        present: true,
+        version,
+        skillRoots,
+        mcpServers,
+        instructionsFile: instructionsPath ? pathRef(instructionsPath) : undefined,
+        diagnostics,
+    };
+}

package/dist/probes/kiro.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Kiro probe: same shape as Claude Code — `~/.kiro/settings/mcp.json`,
+ * `~/.kiro/skills`, `~/.kiro/steering/CLAUDE.md`. No subagent concept
+ * confirmed for Kiro (docs/research.md), so `subagentsDir` is never set.
+ */
+import type { AgentSnapshot } from "../core/types.js";
+export interface ProbeOptions {
+    /** Spawn each configured stdio server for a live handshake. Off by
+     * default — see docs/architecture.md "MCP handshake probing is opt-in". */
+    probeMcp?: boolean;
+}
+export declare function probe(homeDir?: string, opts?: ProbeOptions): Promise<AgentSnapshot>;

package/dist/probes/kiro.js

@@ -0,0 +1,48 @@
+/**
+ * Kiro probe: same shape as Claude Code — `~/.kiro/settings/mcp.json`,
+ * `~/.kiro/skills`, `~/.kiro/steering/CLAUDE.md`. No subagent concept
+ * confirmed for Kiro (docs/research.md), so `subagentsDir` is never set.
+ */
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { probeMcpServer } from "../lib/mcpProbe.js";
+import { pathRef, readJsonFile, resolveEnvRefs, scanSkillRoot } from "../lib/probeCommon.js";
+export async function probe(homeDir = homedir(), opts = {}) {
+    const mcpJsonPath = join(homeDir, ".kiro", "settings", "mcp.json");
+    const skillsPath = join(homeDir, ".kiro", "skills");
+    const steeringPath = join(homeDir, ".kiro", "steering", "CLAUDE.md");
+    const mcpJson = readJsonFile(mcpJsonPath);
+    const present = mcpJson !== undefined || pathRef(skillsPath) !== undefined || pathRef(steeringPath) !== undefined;
+    if (!present) {
+        return { agent: "kiro", present: false, skillRoots: [], mcpServers: [], diagnostics: [] };
+    }
+    let version;
+    try {
+        version = execFileSync("kiro-cli", ["--version"], { encoding: "utf-8", timeout: 5_000 }).trim();
+    }
+    catch {
+        // binary not on PATH — config existing without it is still probeable
+    }
+    const mcpServers = Object.entries(mcpJson?.mcpServers ?? {}).map(([name, def]) => ({
+        name,
+        transport: def.url ? "http" : "stdio",
+    }));
+    if (opts.probeMcp) {
+        await Promise.all(Object.entries(mcpJson?.mcpServers ?? {}).map(async ([name, def], index) => {
+            if (def.url || !def.command)
+                return;
+            mcpServers[index].probe = await probeMcpServer({ transport: "stdio", command: def.command, args: def.args }, resolveEnvRefs(def.env, process.env));
+        }));
+    }
+    const skillRoot = scanSkillRoot(skillsPath);
+    return {
+        agent: "kiro",
+        present: true,
+        version,
+        skillRoots: skillRoot ? [skillRoot] : [],
+        mcpServers,
+        instructionsFile: pathRef(steeringPath),
+        diagnostics: [],
+    };
+}

package/dist/probes/pi.d.ts

@@ -0,0 +1,14 @@
+/**
+ * pi probe. Skill root and global instructions file are both under
+ * `~/.pi/agent` — confirmed by direct source read of
+ * `@earendil-works/pi-coding-agent`'s `dist/core/skills.js` (`loadSkills`)
+ * and `dist/core/resource-loader.js` (`loadContextFileFromDir(resolvedAgentDir)`),
+ * not by assumption. See design.md D5 (openspec/changes/trellis-doctor-p0).
+ *
+ * pi has no native MCP client (docs/research.md) — nothing to read or
+ * probe, so `mcpServers` is always empty here. That's real information
+ * (this is why P4 has to write a runtime bridge extension instead of
+ * generating config), not an omission.
+ */
+import type { AgentSnapshot } from "../core/types.js";
+export declare function probe(homeDir?: string): Promise<AgentSnapshot>;

package/dist/probes/pi.js

@@ -0,0 +1,53 @@
+/**
+ * pi probe. Skill root and global instructions file are both under
+ * `~/.pi/agent` — confirmed by direct source read of
+ * `@earendil-works/pi-coding-agent`'s `dist/core/skills.js` (`loadSkills`)
+ * and `dist/core/resource-loader.js` (`loadContextFileFromDir(resolvedAgentDir)`),
+ * not by assumption. See design.md D5 (openspec/changes/trellis-doctor-p0).
+ *
+ * pi has no native MCP client (docs/research.md) — nothing to read or
+ * probe, so `mcpServers` is always empty here. That's real information
+ * (this is why P4 has to write a runtime bridge extension instead of
+ * generating config), not an omission.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pathRef, scanSkillRoot } from "../lib/probeCommon.js";
+/** Priority order pi itself checks (`loadContextFileFromDir`), first match wins. */
+const INSTRUCTIONS_CANDIDATES = ["AGENTS.override.md", "AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"];
+export async function probe(homeDir = homedir()) {
+    const agentDir = join(homeDir, ".pi", "agent");
+    const settingsPath = join(agentDir, "settings.json");
+    const skillsPath = join(agentDir, "skills");
+    const present = existsSync(settingsPath) || existsSync(skillsPath);
+    if (!present) {
+        return { agent: "pi", present: false, skillRoots: [], mcpServers: [], diagnostics: [] };
+    }
+    let version;
+    try {
+        version = execFileSync("pi", ["--version"], { encoding: "utf-8", timeout: 5_000 }).trim();
+    }
+    catch {
+        // config exists without the binary on PATH — unusual, still probeable
+    }
+    const skillRoot = scanSkillRoot(skillsPath);
+    let instructionsFile;
+    for (const candidate of INSTRUCTIONS_CANDIDATES) {
+        const ref = pathRef(join(agentDir, candidate));
+        if (ref) {
+            instructionsFile = ref;
+            break;
+        }
+    }
+    return {
+        agent: "pi",
+        present: true,
+        version,
+        skillRoots: skillRoot ? [skillRoot] : [],
+        mcpServers: [],
+        instructionsFile,
+        diagnostics: [],
+    };
+}

package/dist/sdk.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `agent-trellis`'s public, read-only API surface (trellis-sdk-p5) — a
+ * stable contract for reading `~/.trellis/`'s canonical state without
+ * depending on the CLI. Deliberately narrow (design.md D1): everything
+ * here is canonical-source loading and its type surface, nothing from
+ * `src/adapters/*` or `src/commands/*` — those are how the four
+ * built-in integrations work, not something a third-party integration
+ * should reach into. A third party wanting Trellis-style sync for its
+ * own agent writes its own adapter against these types, the same way
+ * `src/adapters/pi.ts` does today.
+ */
+export { loadCanonicalSource } from "./core/canonical.js";
+export { ALL_AGENTS, resolveScope } from "./core/types.js";
+export type { AgentId, AgentProfile, CanonicalSource, HubConfig, McpConfig, McpServerDef, MemoryEntry, Scope, SecretsPolicy, SkillRef, Transport, } from "./core/types.js";

package/dist/sdk.js

@@ -0,0 +1,13 @@
+/**
+ * `agent-trellis`'s public, read-only API surface (trellis-sdk-p5) — a
+ * stable contract for reading `~/.trellis/`'s canonical state without
+ * depending on the CLI. Deliberately narrow (design.md D1): everything
+ * here is canonical-source loading and its type surface, nothing from
+ * `src/adapters/*` or `src/commands/*` — those are how the four
+ * built-in integrations work, not something a third-party integration
+ * should reach into. A third party wanting Trellis-style sync for its
+ * own agent writes its own adapter against these types, the same way
+ * `src/adapters/pi.ts` does today.
+ */
+export { loadCanonicalSource } from "./core/canonical.js";
+export { ALL_AGENTS, resolveScope } from "./core/types.js";