@tangle-network/agent-profile-materialize 0.9.4 → 0.10.1

package/dist/index.d.ts

@@ -23,6 +23,11 @@
  */
 import type { AgentCandidateConfigValue, AgentCandidateProfile, AgentCandidateProfileActivation, AgentCandidateProfileApplication, AgentCandidateProfilePlanEvidence, AgentCandidateProfilePlanMaterial, AgentProfile, AgentProfileConfigValue, AgentProfileMcpServer, AgentProfileSecretProvider, AgentProfileSecretRef, Sha256Digest } from "@tangle-network/agent-interface";
 export declare const UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER: AgentProfileSecretProvider;
+/**
+ * The harnesses this materializer can lower an AgentProfile into. `satisfies` binds every id to
+ * the canonical harness enum, so a rename upstream is a compile error here rather than an
+ * `isMaterializerHarness` that silently returns false for a harness that still exists.
+ */
 export declare const MATERIALIZER_HARNESSES: readonly ["claude-code", "nanoclaw", "codex", "opencode", "kimi-code", "pi", "gemini", "hermes", "openclaw"];
 export type HarnessId = (typeof MATERIALIZER_HARNESSES)[number];
 export declare function isMaterializerHarness(harness: string): harness is HarnessId;
@@ -80,6 +85,16 @@ export interface Unsupported {
     dimension: "files" | "skills" | "mcp" | "hooks" | "subagents" | "commands" | "instructions" | "systemPrompt" | "connections" | "confidential" | "permissions" | "tools" | "modes" | "extensions";
     reason: string;
 }
+/**
+ * The dimensions `materializeProfile`'s `skip` option honors.
+ *
+ * Every other dimension is materialized unconditionally: generated plan files are pushed through
+ * a single site that carries no dimension tag, so there is nothing to gate them on. Naming the
+ * honored set keeps `skip: ["hooks"]` a loud rejection instead of a silent no-op.
+ */
+export declare const SKIPPABLE_DIMENSIONS: readonly ["mcp", "extensions"];
+export type SkippableDimension = (typeof SKIPPABLE_DIMENSIONS)[number];
+export declare function isSkippableDimension(value: string): value is SkippableDimension;
 /** The plan a caller writes into the run cwd, then applies to the spawn. */
 export interface WorkspacePlan {
     harness: HarnessId;
@@ -93,6 +108,42 @@ export interface WorkspacePlan {
     systemPrompt?: string;
     /** Dimensions requested but with NO cwd path on this harness — fail-closed record. */
     unsupported: Unsupported[];
+    /**
+     * Prerequisites the workspace files CANNOT establish on their own.
+     *
+     * A plan is a set of files, an env map, and flags. Some harness capabilities need more than
+     * that to actually function: pi's MCP support is not built in, it arrives from an extension
+     * that must be installed into the harness's own package directory and permitted to load. No
+     * file written into a run workspace can make either true.
+     *
+     * Writing the config anyway and hoping is the failure this field exists to prevent: the
+     * harness starts, silently has no MCP, and the agent runs without the tools it was configured
+     * with while nothing reports a problem. So the plan states the requirement and the executor —
+     * which knows where its harness is installed and how it spawns — verifies or refuses it.
+     *
+     * Optional because this is an additive field on a published type: a plan built before it
+     * existed, or by a caller that does not construct one, is still a valid plan with no
+     * prerequisites. Every plan this package builds sets it.
+     */
+    requires?: PlanRequirement[];
+}
+/**
+ * One prerequisite a {@link WorkspacePlan} depends on but cannot create.
+ *
+ * Declarative on purpose: this package builds plans and never probes a filesystem, spawns a
+ * process, or reaches the network. The executor holds that context and does the checking.
+ */
+export interface PlanRequirement {
+    /** The only kind so far: a harness extension/plugin that must be loaded for a dimension to work. */
+    kind: "harness-extension";
+    /** Dimension that produced the requirement, so a refusal can name what will not work. */
+    dimension: Unsupported["dimension"];
+    /** Package spec in the harness's own vocabulary, e.g. `npm:pi-mcp-adapter`. */
+    id: string;
+    /** Why the plan needs it — goes verbatim into the executor's refusal message. */
+    reason: string;
+    /** The exact command that satisfies it, so a failure is actionable without a doc lookup. */
+    remedy: string;
 }
 /**
  * Proof of the profile workspace inputs applied before a harness is spawned.
@@ -225,7 +276,7 @@ export declare function normalizeSkillMd(name: string, raw: string): string;
  * The explicit target harness takes precedence over the profile's default.
  */
 export declare function materializeProfile(inputProfile: AgentProfile, harness: HarnessId, opts?: {
-    skip?: Unsupported["dimension"][];
+    skip?: SkippableDimension[];
 }): WorkspacePlan;
 /**
  * Materialize a sealed candidate profile without weakening its process values.

package/dist/index.js

@@ -59,6 +59,11 @@ function resolveInlineRef(ref) {
     }
     return null; // github / unresolved
 }
+/**
+ * The harnesses this materializer can lower an AgentProfile into. `satisfies` binds every id to
+ * the canonical harness enum, so a rename upstream is a compile error here rather than an
+ * `isMaterializerHarness` that silently returns false for a harness that still exists.
+ */
 export const MATERIALIZER_HARNESSES = [
     "claude-code",
     "nanoclaw",
@@ -79,6 +84,32 @@ function assertMaterializerHarness(harness) {
         throw new Error(`Unsupported profile materialization harness "${harness}"`);
     }
 }
+/**
+ * The dimensions `materializeProfile`'s `skip` option honors.
+ *
+ * Every other dimension is materialized unconditionally: generated plan files are pushed through
+ * a single site that carries no dimension tag, so there is nothing to gate them on. Naming the
+ * honored set keeps `skip: ["hooks"]` a loud rejection instead of a silent no-op.
+ */
+export const SKIPPABLE_DIMENSIONS = [
+    "mcp",
+    "extensions",
+];
+const SKIPPABLE_DIMENSION_SET = new Set(SKIPPABLE_DIMENSIONS);
+export function isSkippableDimension(value) {
+    return SKIPPABLE_DIMENSION_SET.has(value);
+}
+/** Reject a dimension `materializeProfile` would not actually skip, rather than ignoring it. */
+function assertSkippableDimensions(skip) {
+    if (!skip)
+        return [];
+    const unsupportedSkips = skip.filter((dimension) => !isSkippableDimension(dimension));
+    if (unsupportedSkips.length > 0) {
+        throw new Error(`materializeProfile: cannot skip ${unsupportedSkips.join(", ")}. ` +
+            `Skippable dimensions are: ${SKIPPABLE_DIMENSIONS.join(", ")}.`);
+    }
+    return skip;
+}
 /** The plan was applied, but one or more private staging files remain. */
 export class WorkspacePlanCleanupError extends AggregateError {
     receipt;
@@ -543,13 +574,14 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
     assertMaterializerHarness(harness);
     const profile = agentProfileSchema.parse(inputProfile);
     const h = harness;
-    const skip = new Set(opts.skip ?? []);
+    const skip = new Set(assertSkippableDimensions(opts.skip));
     const plan = {
         harness: h,
         files: [],
         env: {},
         flags: [],
         unsupported: [],
+        requires: [],
     };
     // Every plan file is tagged by provenance at the single push site: `add`
     // (harness-generated native config) vs `addExplicitResource` (a profile
@@ -1186,6 +1218,9 @@ export function hashWorkspacePlan(plan) {
             : agentProfileSecretRefSchema.parse(value),
     ]));
     const unsupported = [...plan.unsupported].sort((a, b) => compareStrings(`${a.dimension}\0${a.reason}`, `${b.dimension}\0${b.reason}`));
+    // A plan that needs an extension is not the same plan as one that does not, even when every
+    // byte it writes is identical — the digest is what a receipt proves, so it must say so.
+    const requires = [...(plan.requires ?? [])].sort((a, b) => compareStrings(`${a.kind}\0${a.id}`, `${b.kind}\0${b.id}`));
     const canonical = JSON.stringify({
         harness: plan.harness,
         files,
@@ -1195,6 +1230,7 @@ export function hashWorkspacePlan(plan) {
             ? {}
             : { systemPrompt: plan.systemPrompt }),
         unsupported,
+        ...(requires.length === 0 ? {} : { requires }),
     });
     return `sha256:${sha256(canonical)}`;
 }
@@ -2141,9 +2177,39 @@ function materializeMcp(h, mcp, plan, add, unsupported) {
             plan.flags.push("--mcp-config-file", rel);
             break;
         }
-        case "pi":
-            unsupported("mcp", "pi MCP requires a loaded MCP extension; the base Pi runtime has no MCP control");
+        case "pi": {
+            // pi ships NO MCP. It arrives from the `pi-mcp-adapter` extension, which discovers
+            // `<cwd>/.pi/mcp.json` (adapter 2.17.0 config.ts:17) and also registers a `--mcp-config`
+            // flag (index.ts:252). The flag is registered BY the extension, so passing it when the
+            // extension is absent is not a fallback — it is an unknown flag.
+            //
+            // This was previously marked unsupported because a workspace file cannot install an
+            // extension. That reasoning was right about the constraint and wrong about the conclusion:
+            // the file half is perfectly materializable, and the half that is not becomes a declared
+            // requirement the executor enforces. Marking the whole dimension unsupported pushed both
+            // halves onto every consumer, and two of them independently rebuilt it.
+            const rel = ".pi/mcp.json";
+            const servers = Object.fromEntries(Object.entries(mcp).map(([name, server]) => [
+                name,
+                // `directTools` promotes this server's verbs to first-class pi tools. Without it the
+                // agent gets one generic `mcp` tool and must connect, then describe, then call — three
+                // round trips of discovery before it can do anything. Per-server, because the adapter
+                // lets a per-server value override the global `settings.directTools` (direct-tools.ts:135).
+                { ...piMcpServer(server), directTools: true },
+            ]));
+            // serializeWorkspacePlanJson, NOT JSON.stringify: it unwraps public config values to their
+            // bytes and lifts any secret-ref into a tracked slot the applier resolves. Stringifying
+            // straight would write `{"kind":"public","value":"..."}` into the file as an argv entry.
+            add(rel, serializeWorkspacePlanJson({ mcpServers: servers }));
+            plan.requires?.push({
+                kind: "harness-extension",
+                dimension: "mcp",
+                id: "npm:pi-mcp-adapter",
+                reason: "pi has no built-in MCP; without this extension the servers in .pi/mcp.json are never read and the agent starts with none of their tools",
+                remedy: "pi install npm:pi-mcp-adapter",
+            });
             break;
+        }
         case "hermes":
             unsupported("mcp", "hermes MCP is global config.yaml (mcp_servers), no cwd discovery — write to the hermes global config or pass a config flag");
             break;
@@ -2203,6 +2269,17 @@ function setPlanEnvironment(plan, name, value) {
     }
     plan.env[name] = normalized;
 }
+/**
+ * Lower one canonical MCP server to the shape `pi-mcp-adapter` reads from `.pi/mcp.json`.
+ *
+ * The adapter consumes the same `{mcpServers: {...}}` document Claude and Kimi use, so this
+ * mirrors {@link kimiMcpServer} rather than inventing a pi dialect. `directTools` is added by the
+ * caller, not here, because it is a policy about tool surfacing rather than a property of the
+ * server definition.
+ */
+function piMcpServer(server) {
+    return kimiMcpServer(server);
+}
 function kimiMcpServer(server) {
     if (server.url) {
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.9.4",
+  "version": "0.10.1",
   "description": "Materialize an AgentProfile into the native per-harness workspace files (the one shared materializer for cli-bridge, agent-dev-container, and VB).",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,7 +26,7 @@
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "@tangle-network/agent-interface": ">=0.38.0 <0.41.0"
+    "@tangle-network/agent-interface": ">=0.38.0 <0.43.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",