@tangle-network/agent-profile-materialize 0.15.1 → 0.16.0

package/dist/execution-controls.js

@@ -0,0 +1,186 @@
+export function materializeExecutionControls(h, tools, permissions, modes, plan, add, unsupported) {
+    const toolEntries = Object.entries(tools ?? {}).sort(([left], [right]) => compareStrings(left, right));
+    const permissionEntries = Object.entries(permissions ?? {}).sort(([left], [right]) => compareStrings(left, right));
+    switch (h) {
+        case "claude-code": {
+            if (toolEntries.length > 0 || permissionEntries.length > 0) {
+                const nativeTools = mapSupportedBooleanEntries(toolEntries, claudeToolName, (name) => unsupported("tools", `claude-code: no verified native tool mapping for "${name}"`), "claude-code tool");
+                const nativePermissions = mapSupportedPermissionEntries(permissionEntries, claudeToolName, (name) => unsupported("permissions", `claude-code: no verified native permission mapping for "${name}"`), "claude-code permission");
+                const rules = claudePermissionRules(nativePermissions);
+                for (const [tool, enabled] of nativeTools) {
+                    rules[enabled ? "allow" : "deny"].push(tool);
+                }
+                add(CLAUDE_SETTINGS_PATH, serializeWorkspacePlanJson({
+                    permissions: sealClaudePermissionRules(rules),
+                }));
+                registerClaudeSettings(plan);
+            }
+            break;
+        }
+        case "opencode": {
+            const enforceableTools = toolEntries.filter(([name, enabled]) => {
+                if (normalizedControlName(name) !== "lsp" || !enabled)
+                    return true;
+                unsupported("tools", "opencode: the LSP tool is disabled by the runtime and cannot be enabled exactly");
+                return false;
+            });
+            const enforceablePermissions = permissionEntries.filter(([name, policy]) => {
+                if (normalizedControlName(name) !== "read")
+                    return true;
+                if (!permissionAllowsEverything(policy)) {
+                    unsupported("permissions", "opencode: read access cannot be denied or approval-gated");
+                }
+                return false;
+            });
+            const nativeTools = mapSupportedBooleanEntries(enforceableTools, openCodeToolName, (name) => unsupported("tools", `opencode: no verified native tool mapping for "${name}"`), "opencode tool");
+            const nativePermissions = mapSupportedPermissionEntries(enforceablePermissions, openCodePermissionName, (name) => unsupported("permissions", `opencode: no verified native permission mapping for "${name}"`), "opencode permission");
+            if (enforceableTools.length > 0 || permissionEntries.length > 0) {
+                add("opencode.json", serializeWorkspacePlanJson({
+                    $schema: "https://opencode.ai/config.json",
+                    ...(nativeTools.length > 0
+                        ? { tools: Object.fromEntries(nativeTools) }
+                        : {}),
+                    ...(nativePermissions.length > 0
+                        ? { permission: Object.fromEntries(nativePermissions) }
+                        : {}),
+                }));
+            }
+            break;
+        }
+        case "codex": {
+            const searchEntries = [];
+            for (const [name, enabled] of toolEntries) {
+                const posture = resolveNativeWebTools({ [name]: enabled });
+                if (posture.search === enabled && posture.fetch === undefined) {
+                    searchEntries.push([name, enabled]);
+                    continue;
+                }
+                if (posture.fetch === enabled && posture.search === undefined) {
+                    if (enabled) {
+                        unsupported("tools", `codex: native web fetch is unavailable for "${name}"`);
+                    }
+                    continue;
+                }
+                unsupported("tools", `codex: no verified primary-process tool mapping for "${name}"`);
+            }
+            const nativeSearch = mapSupportedBooleanEntries(searchEntries, () => "web_search", () => undefined, "codex tool");
+            if (nativeSearch[0]) {
+                plan.flags.push("-c", `tools.web_search=${nativeSearch[0][1]}`);
+            }
+            if (permissionEntries.length > 0) {
+                unsupported("permissions", "codex: no verified primary-process permission policy mapping");
+            }
+            break;
+        }
+        case "pi": {
+            const nativeTools = mapSupportedBooleanEntries(toolEntries, piToolId, (name) => unsupported("tools", `pi: tool name "${name}" is empty after trimming`), "pi tool");
+            const nativePermissions = mapSupportedPermissionEntries(permissionEntries, piToolId, (name) => unsupported("permissions", `pi: permission name "${name}" is empty after trimming`), "pi permission");
+            const enabled = new Set(nativeTools
+                .filter(([, value]) => value)
+                .map(([name]) => name)
+                .sort(compareStrings));
+            const excluded = new Set(nativeTools
+                .filter(([, value]) => !value)
+                .map(([name]) => name)
+                .sort(compareStrings));
+            for (const [name, policy] of nativePermissions) {
+                if (typeof policy !== "string") {
+                    unsupported("permissions", `pi: conditional permission policy for "${name}" has no verified headless mapping`);
+                    continue;
+                }
+                if (policy === "ask") {
+                    unsupported("permissions", `pi: permission policy "ask" for "${name}" requires an interactive decision surface`);
+                    continue;
+                }
+                if (policy === "allow") {
+                    if (excluded.has(name)) {
+                        throw new Error(`pi execution control "${name}" conflicts between disabled and allow`);
+                    }
+                    continue;
+                }
+                if (enabled.has(name)) {
+                    throw new Error(`pi execution control "${name}" conflicts between enabled and deny`);
+                }
+                excluded.add(name);
+            }
+            if (enabled.size > 0 || excluded.size > 0) {
+                add(PI_EXECUTION_CONTROL_EXTENSION_PATH, piExecutionControlExtensionSource([...enabled], [...excluded]));
+                plan.flags.push("--extension", PI_EXECUTION_CONTROL_EXTENSION_PATH);
+            }
+            if (excluded.size > 0) {
+                plan.flags.push("--exclude-tools", [...excluded].sort(compareStrings).join(","));
+            }
+            break;
+        }
+        default:
+            if (toolEntries.length > 0) {
+                unsupported("tools", `${h}: no verified primary-process tool availability mapping`);
+            }
+            if (permissionEntries.length > 0) {
+                unsupported("permissions", `${h}: no verified primary-process permission policy mapping`);
+            }
+    }
+    if (modes && Object.keys(modes).length > 0) {
+        unsupported("modes", `${h}: resolve one named AgentProfile mode before materialization`);
+    }
+}
+function piExecutionControlExtensionSource(enabledTools, excludedTools) {
+    return [
+        'import { writeSync } from "node:fs";',
+        `const enabledTools = Object.freeze(${JSON.stringify(enabledTools)});`,
+        `const excludedTools = Object.freeze(${JSON.stringify(excludedTools)});`,
+        "",
+        "function failProfile(message) {",
+        "  try {",
+        '    writeSync(2, "Pi profile execution controls failed: " + message + "\\n");',
+        "  } finally {",
+        "    process.exit(78);",
+        "  }",
+        "}",
+        "",
+        "function resolveTool(reference, available, required) {",
+        "  if (available.includes(reference)) return reference;",
+        "  const folded = reference.toLowerCase();",
+        "  const matches = available.filter((name) => name.toLowerCase() === folded);",
+        "  if (matches.length === 1) return matches[0];",
+        "  if (matches.length > 1) {",
+        "    failProfile('tool \"' + reference + '\" is ambiguous: ' + matches.join(\", \"));",
+        "  }",
+        "  if (required) {",
+        "    failProfile('requested tool \"' + reference + '\" is unavailable');",
+        "  }",
+        "  return undefined;",
+        "}",
+        "",
+        "function applyControls(pi) {",
+        "  const available = pi.getAllTools().map((tool) => tool.name);",
+        "  for (const reference of excludedTools) {",
+        "    const remaining = resolveTool(reference, available, false);",
+        "    if (remaining !== undefined) {",
+        "      failProfile(",
+        "        'excluded tool \"' + reference + '\" remains available as \"' + remaining +",
+        "        '\"; pass its exact registered Pi name',",
+        "      );",
+        "    }",
+        "  }",
+        "  const enabled = enabledTools.map((name) =>",
+        "    resolveTool(name, available, true),",
+        "  );",
+        "  const active = new Set(pi.getActiveTools());",
+        "  for (const name of enabled) active.add(name);",
+        "  pi.setActiveTools([...active]);",
+        "}",
+        "",
+        "export default function applyProfileExecutionControls(pi) {",
+        '  pi.on("before_agent_start", () => applyControls(pi));',
+        '  pi.on("turn_start", () => applyControls(pi));',
+        "}",
+        "",
+    ].join("\n");
+}
+import { resolveNativeWebTools } from "@tangle-network/agent-interface";
+import { claudePermissionRules, claudeToolName, mapSupportedBooleanEntries, mapSupportedPermissionEntries, normalizedControlName, openCodePermissionName, openCodeToolName, PI_EXECUTION_CONTROL_EXTENSION_PATH, permissionAllowsEverything, piToolId, sealClaudePermissionRules, } from "./control-maps.js";
+import { CLAUDE_SETTINGS_PATH } from "./harness.js";
+import { registerClaudeSettings } from "./hooks.js";
+import { serializeWorkspacePlanJson } from "./plan-json.js";
+import { compareStrings } from "./workspace-files.js";

package/dist/harness.d.ts

@@ -0,0 +1,81 @@
+export declare const MATERIALIZER_HARNESSES: readonly ["claude-code", "nanoclaw", "codex", "opencode", "kimi-code", "pi", "prime", "gemini", "hermes", "openclaw"];
+export type HarnessId = (typeof MATERIALIZER_HARNESSES)[number];
+export declare function isMaterializerHarness(harness: string): harness is HarnessId;
+export declare function assertMaterializerHarness(harness: string): asserts harness is HarnessId;
+export declare const CODEX_SYSTEM_PROMPT_FILE = ".codex/system-prompt.md";
+export declare const OPENCODE_APPEND_SYSTEM_PROMPT_FILE = ".opencode/agent-system-prompt.md";
+export declare const OPENCODE_PRIMARY_AGENT_PREFIX = "tangle-profile-";
+export declare const CLAUDE_SETTINGS_PATH = ".tangle/claude-settings.json";
+export declare function harnessAutoLoadsContextFile(harness: HarnessId): boolean;
+/**
+ * The project context file this harness reads from cwd — its stable, documented
+ * ALWAYS-LOADED surface. Exported so a caller lowering additive context (e.g. a
+ * bare TUI's persona, which has no per-message system channel) targets the same
+ * file the materializer writes instructions to, instead of keeping its own copy
+ * of this per-harness map.
+ */
+export declare function harnessContextFile(harness: HarnessId): string;
+/**
+ * Why a harness refuses a system-prompt REPLACEMENT.
+ *
+ * The reason names the control that does exist, so the refusal is actionable
+ * without a capability-matrix lookup — a bare "unsupported" sends the caller
+ * looking for a flag that was never there.
+ */
+export declare function systemPromptRefusal(harness: HarnessId): string;
+/**
+ * Why a harness refuses an ADDITION to the system prompt.
+ *
+ * gemini puts its context file in the system-prompt position, so the temptation
+ * is to lower an addition there. That is refused because GEMINI.md is the ONE
+ * file it auto-loads: an addition written there is byte-identical to the same
+ * text under `prompt.instructions`, and no consumer could tell which intent the
+ * caller expressed. opencode is not refused for the same situation, because it
+ * loads exactly the files its config names and can therefore carry the two
+ * intents in separate, separately-ordered files.
+ */
+export declare function appendSystemPromptRefusal(harness: HarnessId): string;
+/** Project context file each harness actually reads from cwd. NEVER a constant. */
+export declare const CONTEXT_FILE: Record<HarnessId, string>;
+/**
+ * The paths whose only possible author is this package, per
+ * {@link PlanFile.ownership}.
+ *
+ * Codex names no system-prompt file of its own — `model_instructions_file`
+ * takes whatever path it is given — and opencode names none either, since it
+ * reads exactly the files its config lists. All three names below were chosen
+ * here, so a file already at one of them is this materializer's own output from
+ * an earlier application into the same workspace.
+ *
+ * That is an inference from the path name, not verified provenance: nothing
+ * checks the existing bytes are prior materializer output, so a workspace that
+ * carried a foreign file at one of these invented names is overwritten on the
+ * first application. Accepted cost of stateless multi-turn re-application,
+ * bounded by the names being ones no harness or user convention uses.
+ *
+ * Deliberately absent: `.gemini/system.md` (gemini's own documented name),
+ * `GEMINI.md`, `CLAUDE.md`, `AGENTS.md`, `opencode.json`. A user's repository
+ * can carry any of those, and clobbering one is worse than refusing the turn.
+ * For `opencode.json` this means a profile change that alters the
+ * `instructions[]` membership between turns of one workspace refuses loudly
+ * (the consolidated config no longer matches byte-for-byte) rather than
+ * replacing a possibly user-authored config.
+ */
+export declare const MATERIALIZER_OWNED_PATHS: ReadonlySet<string>;
+/**
+ * cwd-relative native skill dir per harness, or null if the harness has no
+ * cwd skill primitive (skills live in a user/global dir the workspace plan
+ * cannot reach). Public so consumers composing a profile can (a) render the
+ * exact path the platform will mount a skill at into their prompts instead
+ * of hardcoding `~/.claude/skills/...`, and (b) branch on skill support
+ * ahead of materialization instead of catching the materialize-time throw.
+ */
+export declare const HARNESS_SKILL_DIRS: Readonly<Record<HarnessId, string | null>>;
+/**
+ * Resolve the cwd-relative directory `resources.skills` refs materialize
+ * into on `harness`. `null` means the harness cannot receive cwd skills, the
+ * same condition that surfaces as an `unsupported`
+ * "skills" entry (and an {@link assertWorkspacePlanSupported} throw) at
+ * materialize time, exposed here as branchable data.
+ */
+export declare function skillDirForHarness(harness: HarnessId): string | null;

package/dist/harness.js

@@ -0,0 +1,167 @@
+export const MATERIALIZER_HARNESSES = [
+    "claude-code",
+    "nanoclaw",
+    "codex",
+    "opencode",
+    "kimi-code",
+    "pi",
+    "prime",
+    "gemini",
+    "hermes",
+    "openclaw",
+];
+const MATERIALIZER_HARNESS_SET = new Set(MATERIALIZER_HARNESSES);
+export function isMaterializerHarness(harness) {
+    return MATERIALIZER_HARNESS_SET.has(harness);
+}
+export function assertMaterializerHarness(harness) {
+    if (!isMaterializerHarness(harness)) {
+        throw new Error(`Unsupported profile materialization harness "${harness}"`);
+    }
+}
+export const CODEX_SYSTEM_PROMPT_FILE = ".codex/system-prompt.md";
+export const OPENCODE_APPEND_SYSTEM_PROMPT_FILE = ".opencode/agent-system-prompt.md";
+export const OPENCODE_PRIMARY_AGENT_PREFIX = "tangle-profile-";
+export const CLAUDE_SETTINGS_PATH = ".tangle/claude-settings.json";
+export function harnessAutoLoadsContextFile(harness) {
+    assertMaterializerHarness(harness);
+    return harness !== "opencode";
+}
+/**
+ * The project context file this harness reads from cwd — its stable, documented
+ * ALWAYS-LOADED surface. Exported so a caller lowering additive context (e.g. a
+ * bare TUI's persona, which has no per-message system channel) targets the same
+ * file the materializer writes instructions to, instead of keeping its own copy
+ * of this per-harness map.
+ */
+export function harnessContextFile(harness) {
+    assertMaterializerHarness(harness);
+    // The map is keyed by HarnessId, but callers reach this from runtime strings
+    // (a registry spec name, a request field). A miss would otherwise return
+    // undefined behind a `string` return type and surface as an undefined write
+    // path much later.
+    const path = CONTEXT_FILE[harness];
+    if (!path) {
+        throw new Error(`No project context file is known for harness "${harness}"`);
+    }
+    return path;
+}
+/**
+ * Why a harness refuses a system-prompt REPLACEMENT.
+ *
+ * The reason names the control that does exist, so the refusal is actionable
+ * without a capability-matrix lookup — a bare "unsupported" sends the caller
+ * looking for a flag that was never there.
+ */
+export function systemPromptRefusal(harness) {
+    switch (harness) {
+        case "opencode":
+            // The control exists, so the reason names the two declarations that reach
+            // it rather than claiming opencode has none.
+            return 'opencode: the only system-prompt replacement is per-agent (`agent.<name>.prompt`), which binds to the agent selected at launch and a workspace plan cannot guarantee; an executor that applies the plan\'s "--agent" flag to its own spawn declares binds: ["systemPrompt"], and one that composes opencode\'s config itself declares binds: ["opencode.agent-prompt"]';
+        default:
+            return `${harness}: no verified exact system-prompt replacement control`;
+    }
+}
+/**
+ * Why a harness refuses an ADDITION to the system prompt.
+ *
+ * gemini puts its context file in the system-prompt position, so the temptation
+ * is to lower an addition there. That is refused because GEMINI.md is the ONE
+ * file it auto-loads: an addition written there is byte-identical to the same
+ * text under `prompt.instructions`, and no consumer could tell which intent the
+ * caller expressed. opencode is not refused for the same situation, because it
+ * loads exactly the files its config names and can therefore carry the two
+ * intents in separate, separately-ordered files.
+ */
+export function appendSystemPromptRefusal(harness) {
+    switch (harness) {
+        case "gemini":
+            return "gemini: the only additive system-prompt channel is GEMINI.md memory, the single context file it auto-loads, which `prompt.instructions` already materializes — use it instead";
+        case "codex":
+            return "codex: no verified additive system-prompt control — its AGENTS.md lands in a developer/user message, not the system channel";
+        default:
+            return `${harness}: no verified additive system-prompt control`;
+    }
+}
+/** Project context file each harness actually reads from cwd. NEVER a constant. */
+export const CONTEXT_FILE = {
+    "claude-code": "CLAUDE.md",
+    nanoclaw: "CLAUDE.md",
+    codex: "AGENTS.md",
+    opencode: ".opencode/profile-instructions.md",
+    "kimi-code": "AGENTS.md",
+    pi: "AGENTS.md",
+    // prime (PrimeIntellect-ai/prime-agent v0.7.0, be9e2fa0) walks cwd and its
+    // ancestors for AGENTS.md/CLAUDE.md, cwd first (fork resource-loader.ts:59
+    // candidates, :94-109 walk from cwd inside loadProjectContextFiles).
+    prime: "AGENTS.md",
+    gemini: "GEMINI.md", // current default; AGENTS.md only via .gemini/settings.json context.fileName
+    hermes: "HERMES.md", // highest-priority native name; only ONE context loads (first match)
+    openclaw: "AGENTS.md",
+};
+/**
+ * The paths whose only possible author is this package, per
+ * {@link PlanFile.ownership}.
+ *
+ * Codex names no system-prompt file of its own — `model_instructions_file`
+ * takes whatever path it is given — and opencode names none either, since it
+ * reads exactly the files its config lists. All three names below were chosen
+ * here, so a file already at one of them is this materializer's own output from
+ * an earlier application into the same workspace.
+ *
+ * That is an inference from the path name, not verified provenance: nothing
+ * checks the existing bytes are prior materializer output, so a workspace that
+ * carried a foreign file at one of these invented names is overwritten on the
+ * first application. Accepted cost of stateless multi-turn re-application,
+ * bounded by the names being ones no harness or user convention uses.
+ *
+ * Deliberately absent: `.gemini/system.md` (gemini's own documented name),
+ * `GEMINI.md`, `CLAUDE.md`, `AGENTS.md`, `opencode.json`. A user's repository
+ * can carry any of those, and clobbering one is worse than refusing the turn.
+ * For `opencode.json` this means a profile change that alters the
+ * `instructions[]` membership between turns of one workspace refuses loudly
+ * (the consolidated config no longer matches byte-for-byte) rather than
+ * replacing a possibly user-authored config.
+ */
+export const MATERIALIZER_OWNED_PATHS = new Set([
+    CODEX_SYSTEM_PROMPT_FILE,
+    OPENCODE_APPEND_SYSTEM_PROMPT_FILE,
+    CONTEXT_FILE.opencode,
+]);
+/**
+ * cwd-relative native skill dir per harness, or null if the harness has no
+ * cwd skill primitive (skills live in a user/global dir the workspace plan
+ * cannot reach). Public so consumers composing a profile can (a) render the
+ * exact path the platform will mount a skill at into their prompts instead
+ * of hardcoding `~/.claude/skills/...`, and (b) branch on skill support
+ * ahead of materialization instead of catching the materialize-time throw.
+ */
+export const HARNESS_SKILL_DIRS = {
+    "claude-code": ".claude/skills",
+    nanoclaw: ".claude/skills",
+    codex: ".codex/skills",
+    opencode: ".opencode/skills",
+    "kimi-code": ".kimi/skills",
+    pi: ".pi/skills",
+    // prime auto-discovers project skills from <cwd>/<configDir>/skills where the
+    // fork ships configDir ".prime/agent" (fork package.json piConfig, config.ts:494;
+    // package-manager.ts:885 projectBaseDir, :2175-2180 projectDirs.skills,
+    // :2209-2213 collectAutoSkillEntries). The loader recurses into
+    // <name>/SKILL.md subdirs (skills.ts:328-372).
+    prime: ".prime/agent/skills",
+    gemini: ".gemini/skills",
+    hermes: null, // skills are ~/.hermes/skills (user) only — no cwd discovery
+    openclaw: "skills", // <workspace>/skills/<name>/SKILL.md
+};
+/**
+ * Resolve the cwd-relative directory `resources.skills` refs materialize
+ * into on `harness`. `null` means the harness cannot receive cwd skills, the
+ * same condition that surfaces as an `unsupported`
+ * "skills" entry (and an {@link assertWorkspacePlanSupported} throw) at
+ * materialize time, exposed here as branchable data.
+ */
+export function skillDirForHarness(harness) {
+    assertMaterializerHarness(harness);
+    return HARNESS_SKILL_DIRS[harness];
+}

package/dist/hooks.d.ts

@@ -0,0 +1,6 @@
+export declare function materializeHooks(h: HarnessId, hooks: Record<string, AgentProfileHookCommand[]>, add: AddPlanFile, unsupported: (d: Unsupported["dimension"], r: string) => void, plan: WorkspacePlan): void;
+export declare function registerClaudeSettings(plan: WorkspacePlan): void;
+export declare function hookWrapperSource(executable: string, args: string[], env: Record<string, string>): string;
+import type { AgentProfileHookCommand } from "@tangle-network/agent-interface";
+import type { AddPlanFile } from "./plan-json.js";
+import type { HarnessId, Unsupported, WorkspacePlan } from "./plan-types.js";