@tangle-network/agent-profile-materialize 0.15.2 → 0.17.0

package/dist/candidate-types.d.ts

@@ -0,0 +1,32 @@
+export interface AgentCandidateWorkspacePlan {
+    sourceProfileDigest: Sha256Digest;
+    harness: HarnessId;
+    files: PlanFile[];
+    env: Record<string, AgentCandidateConfigValue>;
+    flags: AgentCandidateConfigValue[];
+    systemPrompt?: AgentCandidateConfigValue;
+    appendSystemPrompt?: AgentCandidateConfigValue;
+    unsupported: Unsupported[];
+}
+export interface AgentCandidateWorkspacePlanReceipt {
+    profileActivation: AgentCandidateProfileActivation;
+    application: AgentCandidateProfileApplication;
+    env: Record<string, AgentCandidateConfigValue>;
+    flags: AgentCandidateConfigValue[];
+    systemPrompt?: AgentCandidateConfigValue;
+    appendSystemPrompt?: AgentCandidateConfigValue;
+    unsupported: Unsupported[];
+}
+export interface MaterializeCandidateProfileOptions {
+    /** Exact text fetched from pinned resource refs, keyed by declared SHA-256. */
+    resolvedResources?: ReadonlyMap<Sha256Digest, string>;
+    /**
+     * Launcher controls this caller owns and will bind itself. The declaration
+     * is forwarded to the classic materializer so candidate execution uses the
+     * same lowering as ordinary profile execution.
+     */
+    binds?: readonly BindableLaunchControl[];
+}
+import type { AgentCandidateConfigValue, AgentCandidateProfileActivation, AgentCandidateProfileApplication, Sha256Digest } from "@tangle-network/agent-interface";
+import type { HarnessId } from "./harness.js";
+import type { BindableLaunchControl, PlanFile, Unsupported } from "./plan-types.js";

package/dist/candidate-types.js

@@ -0,0 +1 @@
+export {};

package/dist/candidate.d.ts

@@ -0,0 +1,9 @@
+import type { AgentCandidateProfile, AgentCandidateProfileApplication } from "@tangle-network/agent-interface";
+import type { AgentCandidateWorkspacePlan, AgentCandidateWorkspacePlanReceipt, MaterializeCandidateProfileOptions } from "./candidate-types.js";
+import type { HarnessId } from "./harness.js";
+export declare function materializeCandidateProfile(profile: AgentCandidateProfile, harness: HarnessId, opts?: MaterializeCandidateProfileOptions): AgentCandidateWorkspacePlan;
+/**
+ * Apply a candidate plan and return its spawn values together with captured
+ * canonical evidence. No caller needs to re-serialize or reinterpret the plan.
+ */
+export declare function applyAgentCandidateWorkspacePlan(plan: AgentCandidateWorkspacePlan, workspaceDir: string, targetWorkspace: AgentCandidateProfileApplication["targetWorkspace"]): AgentCandidateWorkspacePlanReceipt;

package/dist/candidate.js

@@ -0,0 +1,279 @@
+import { createHash } from "node:crypto";
+import { agentCandidateProfileActivationSchema, agentCandidateProfileSchema, canonicalCandidateDigest, } from "@tangle-network/agent-interface";
+import { assertMaterializerHarness } from "./harness.js";
+import { hookWrapperSource } from "./hooks.js";
+import { applyWorkspacePlan } from "./plan-application.js";
+import { captureAgentCandidateProfilePlan } from "./plan-digest.js";
+import { normalizePlanFiles } from "./plan-normalize.js";
+import { promptIntentFields, samePromptIntentValue } from "./plan-prompt.js";
+import { assertWorkspacePlanSupported } from "./plan-support.js";
+import { materializeProfile } from "./profile-materializer.js";
+import { compareStrings } from "./workspace-files.js";
+export function materializeCandidateProfile(profile, harness, opts = {}) {
+    assertMaterializerHarness(harness);
+    const candidate = agentCandidateProfileSchema.parse(profile);
+    verifyCandidateInlineResources(candidate);
+    const hookLowering = lowerCandidateHooks(candidate.hooks, harness);
+    const candidateResources = candidate.resources
+        ? candidateResourcesForClassicMaterializer(candidate.resources, opts.resolvedResources)
+        : {};
+    candidateResources.files = [
+        ...(candidateResources.files ?? []),
+        ...hookLowering.wrapperFiles,
+    ];
+    const classicProfile = {
+        ...candidate,
+        resources: candidateResources,
+        mcp: candidateMcpRecordForClassicMaterializer(candidate.mcp),
+        hooks: hookLowering.hooks,
+    };
+    const classicPlan = materializeProfile(classicProfile, harness, {
+        binds: opts.binds,
+    });
+    // Canonical candidate evidence has no field for a launcher-addressed binding.
+    // Refuse that shape instead of returning a candidate plan whose receipt would
+    // omit the exact control still owed by the launcher.
+    if (classicPlan.systemPromptBinding !== undefined) {
+        throw new Error(`Sealed candidate evidence cannot represent a system-prompt binding to ${classicPlan.systemPromptBinding.control}`);
+    }
+    if (hookLowering.unsupportedReason) {
+        classicPlan.unsupported.push({
+            dimension: "hooks",
+            reason: hookLowering.unsupportedReason,
+        });
+    }
+    classicPlan.unsupported.sort((left, right) => compareStrings(`${left.dimension}\0${left.reason}`, `${right.dimension}\0${right.reason}`));
+    assertWorkspacePlanSupported(classicPlan);
+    return {
+        sourceProfileDigest: canonicalCandidateDigest(candidate),
+        harness: classicPlan.harness,
+        files: classicPlan.files,
+        env: candidatePublicRecord(classicPlan.env),
+        flags: classicPlan.flags.map(candidatePublicArgument),
+        ...promptIntentFields(classicPlan, candidatePublicValue),
+        unsupported: classicPlan.unsupported,
+    };
+}
+/**
+ * Apply a candidate plan and return its spawn values together with captured
+ * canonical evidence. No caller needs to re-serialize or reinterpret the plan.
+ */
+export function applyAgentCandidateWorkspacePlan(plan, workspaceDir, targetWorkspace) {
+    assertWorkspacePlanSupported(plan);
+    const profilePlan = captureAgentCandidateProfilePlan(plan);
+    const activationFiles = normalizePlanFiles(plan.files).map((file) => ({
+        path: file.relPath,
+        mode: file.mode,
+        content: file.content,
+    }));
+    const activationMaterial = {
+        kind: "agent-candidate-profile-activation",
+        profilePlan,
+        files: activationFiles,
+    };
+    const profileActivation = agentCandidateProfileActivationSchema.parse({
+        ...activationMaterial,
+        digest: canonicalCandidateDigest(activationMaterial),
+    });
+    const applied = applyWorkspacePlan({
+        harness: plan.harness,
+        files: plan.files,
+        env: Object.fromEntries(Object.entries(plan.env).map(([name, value]) => [
+            name,
+            candidatePublicString(value),
+        ])),
+        flags: plan.flags.map(candidatePublicString),
+        ...promptIntentFields(plan, candidatePublicString),
+        unsupported: plan.unsupported,
+    }, workspaceDir);
+    return {
+        profileActivation,
+        application: {
+            planDigest: profilePlan.digest,
+            targetWorkspace,
+            mountPaths: applied.written,
+        },
+        env: { ...plan.env },
+        flags: [...plan.flags],
+        ...promptIntentFields(plan, samePromptIntentValue),
+        unsupported: [...plan.unsupported],
+    };
+}
+function lowerCandidateHooks(hooks, harness) {
+    if (!hooks || Object.keys(hooks).length === 0)
+        return { wrapperFiles: [] };
+    const nativeHarness = harness;
+    if (nativeHarness !== "codex" && nativeHarness !== "claude-code") {
+        return {
+            wrapperFiles: [],
+            unsupportedReason: `${nativeHarness} hook configuration requires an unverified command-string mapping; ` +
+                "sealed candidate hooks preserve executable, argv, and env separately",
+        };
+    }
+    const wrapperFiles = [];
+    const lowered = {};
+    for (const [event, commands] of Object.entries(hooks)) {
+        lowered[event] = commands.map((command, index) => {
+            const wrapper = candidateHookWrapper(event, index, command);
+            wrapperFiles.push({
+                path: wrapper.path,
+                resource: {
+                    kind: "inline",
+                    name: wrapper.path,
+                    content: wrapper.content,
+                },
+            });
+            return {
+                command: `node ${wrapper.path}`,
+                timeoutMs: command.timeoutMs,
+                blocking: command.blocking,
+                matcher: command.matcher,
+            };
+        });
+    }
+    return { hooks: lowered, wrapperFiles };
+}
+function candidateHookWrapper(event, index, command) {
+    const args = (command.args ?? []).map(candidatePublicString);
+    const env = Object.fromEntries(Object.entries(command.env ?? {})
+        .sort(([left], [right]) => compareStrings(left, right))
+        .map(([name, value]) => [name, candidatePublicString(value)]));
+    const wrapperId = canonicalCandidateDigest({
+        event,
+        index,
+        executable: command.executable,
+        args,
+        env,
+        timeoutMs: command.timeoutMs ?? null,
+        blocking: command.blocking ?? null,
+        matcher: command.matcher ?? null,
+    }).slice("sha256:".length);
+    const path = `.tangle/profile-hooks/${wrapperId}.mjs`;
+    const content = hookWrapperSource(command.executable, args, env);
+    return { path, content };
+}
+function candidateMcpRecordForClassicMaterializer(servers) {
+    if (!servers)
+        return undefined;
+    return Object.fromEntries(Object.entries(servers)
+        .filter((entry) => entry[1].enabled !== false)
+        .map(([name, server]) => [
+        name,
+        candidateMcpForClassicMaterializer(server),
+    ]));
+}
+function candidateMcpForClassicMaterializer(server) {
+    return {
+        command: server.command,
+        ...(server.transport === undefined ? {} : { transport: server.transport }),
+        ...(server.args === undefined
+            ? {}
+            : {
+                args: server.args.map((value) => profilePublicValue(candidatePublicString(value))),
+            }),
+        ...(server.env === undefined
+            ? {}
+            : {
+                env: Object.fromEntries(Object.entries(server.env).map(([name, value]) => [
+                    name,
+                    profilePublicValue(candidatePublicString(value)),
+                ])),
+            }),
+        ...(server.cwd === undefined ? {} : { cwd: server.cwd }),
+    };
+}
+function candidateResourcesForClassicMaterializer(resources, resolvedResources) {
+    const convert = (ref) => {
+        if (ref.kind === "inline") {
+            return { kind: "inline", name: ref.name, content: ref.content };
+        }
+        const content = resolvedResources?.get(ref.sha256);
+        if (content !== undefined) {
+            verifyCandidateResourceBytes(ref, content, ref.name ?? ref.path);
+            return {
+                kind: "inline",
+                name: ref.name ?? ref.path.split("/").at(-1) ?? "resource",
+                content,
+            };
+        }
+        return {
+            kind: "github",
+            repository: `${ref.repository.owner}/${ref.repository.repo}`,
+            path: ref.path,
+            ref: ref.commit,
+            name: ref.name,
+        };
+    };
+    return {
+        files: resources.files?.map((mount) => ({
+            path: mount.path,
+            resource: convert(mount.resource),
+            executable: mount.executable,
+        })),
+        tools: resources.tools?.map(convert),
+        skills: resources.skills?.map(convert),
+        agents: resources.agents?.map(convert),
+        commands: resources.commands?.map(convert),
+        instructions: typeof resources.instructions === "string"
+            ? resources.instructions
+            : resources.instructions
+                ? convert(resources.instructions)
+                : undefined,
+        // The candidate wrapper owns the complete unsupported check after it adds
+        // dimensions that the classic materializer cannot represent.
+        failOnError: false,
+    };
+}
+function candidatePublicString(value) {
+    if (value.kind !== "public") {
+        throw new Error("Candidate materialization accepts public config values only");
+    }
+    return value.value;
+}
+function candidatePublicValue(value) {
+    return { kind: "public", value };
+}
+function profilePublicValue(value) {
+    return { kind: "public", value };
+}
+function candidatePublicArgument(value) {
+    if (typeof value !== "string") {
+        throw new Error("Candidate materialization cannot emit private launch arguments");
+    }
+    return candidatePublicValue(value);
+}
+function candidatePublicRecord(values) {
+    return Object.fromEntries(Object.entries(values).map(([name, value]) => {
+        if (typeof value !== "string") {
+            throw new Error("Candidate materialization cannot emit private environment values");
+        }
+        return [name, candidatePublicValue(value)];
+    }));
+}
+function verifyCandidateInlineResources(profile) {
+    const resources = profile.resources;
+    if (!resources)
+        return;
+    const refs = [
+        ...(resources.files?.map((mount) => mount.resource) ?? []),
+        ...(resources.tools ?? []),
+        ...(resources.skills ?? []),
+        ...(resources.agents ?? []),
+        ...(resources.commands ?? []),
+        ...(typeof resources.instructions === "object"
+            ? [resources.instructions]
+            : []),
+    ];
+    for (const ref of refs) {
+        if (ref.kind !== "inline")
+            continue;
+        verifyCandidateResourceBytes(ref, ref.content, ref.name);
+    }
+}
+function verifyCandidateResourceBytes(ref, content, label) {
+    const bytes = Buffer.from(content, "utf8");
+    const digest = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+    if (bytes.byteLength !== ref.byteLength || digest !== ref.sha256) {
+        throw new Error(`Candidate resource integrity mismatch: ${label}`);
+    }
+}

package/dist/commands.d.ts

@@ -0,0 +1,2 @@
+export declare function materializeCommand(h: HarnessId, name: string, body: string, add: (path: string, content: string, mode?: number) => void, unsupported: (d: Unsupported["dimension"], r: string) => void): void;
+import type { HarnessId, Unsupported } from "./plan-types.js";

package/dist/commands.js

@@ -0,0 +1,32 @@
+export function materializeCommand(h, name, body, add, unsupported) {
+    switch (h) {
+        case "claude-code":
+        case "nanoclaw":
+            add(`.claude/commands/${name}.md`, body.endsWith("\n") ? body : `${body}\n`);
+            break;
+        case "opencode":
+            add(`.opencode/commands/${name}.md`, body.endsWith("\n") ? body : `${body}\n`);
+            break;
+        case "gemini":
+            add(`.gemini/commands/${name}.toml`, `prompt = ${tomlStr(body)}\n`);
+            break;
+        case "pi":
+            add(`.pi/prompts/${name}.md`, body.endsWith("\n") ? body : `${body}\n`);
+            break;
+        case "prime":
+            // Auto-discovered project prompt templates: <cwd>/.prime/agent/prompts
+            // (fork prompt-templates.ts:218 resolves CONFIG_DIR_NAME "prompts";
+            // package-manager.ts:2176-2180 auto-adds the same projectDirs.prompts).
+            add(`.prime/agent/prompts/${name}.md`, body.endsWith("\n") ? body : `${body}\n`);
+            break;
+        case "kimi-code":
+            unsupported("commands", "kimi commands ARE skills (/skill:<name>) — provide as a skill instead");
+            break;
+        case "codex":
+            unsupported("commands", "codex project commands unsupported (~/.codex/prompts is user-global only)");
+            break;
+        default:
+            unsupported("commands", `${h}: no cwd command path`);
+    }
+}
+import { tomlStr } from "./plan-json.js";

package/dist/control-maps.d.ts

@@ -0,0 +1,34 @@
+export declare function normalizedControlName(name: string): string;
+export declare function claudeToolName(name: string): string | undefined;
+/** Tool IDs reported by the OpenCode binary shipped in the Sandbox image. */
+export declare const OPENCODE_NATIVE_TOOL_IDS: readonly ["apply_patch", "bash", "codesearch", "edit", "glob", "grep", "question", "read", "skill", "task", "todowrite", "webfetch", "websearch", "write"];
+/** Resolve portable and legacy profile names to current OpenCode tool IDs. */
+export declare function openCodeNativeToolId(name: string): string | undefined;
+export declare function openCodeToolName(name: string): string | undefined;
+export declare function openCodePermissionName(name: string): string | undefined;
+export declare const PI_EXECUTION_CONTROL_EXTENSION_PATH = ".tangle/pi-execution-controls.ts";
+/**
+ * Translate only portable spellings whose Pi equivalent differs.
+ *
+ * Every other exact name is resolved against Pi's live registry, keeping
+ * extension and MCP tools profile-configurable without a static catalog.
+ */
+export declare function piToolId(name: string): string | undefined;
+export declare function mapSupportedBooleanEntries(entries: [string, boolean][], mapName: (name: string) => string | undefined, onUnsupported: (name: string) => void, label: string): [string, boolean][];
+export declare function permissionAllowsEverything(policy: AgentProfilePermission): boolean;
+export declare function mapSupportedPermissionEntries(entries: [string, AgentProfilePermission][], mapName: (name: string) => string | undefined, onUnsupported: (name: string) => void, label: string): [string, AgentProfilePermission][];
+export declare function claudePermissionRules(entries: [string, AgentProfilePermission][]): {
+    allow: string[];
+    ask: string[];
+    deny: string[];
+};
+export declare function sealClaudePermissionRules(rules: {
+    allow: string[];
+    ask: string[];
+    deny: string[];
+}): {
+    allow: string[];
+    ask: string[];
+    deny: string[];
+};
+import type { AgentProfilePermission } from "@tangle-network/agent-interface";

package/dist/control-maps.js

@@ -0,0 +1,185 @@
+export function normalizedControlName(name) {
+    return name.replace(/[^a-zA-Z0-9_]/g, "").toLowerCase();
+}
+function nativeWebToolKind(name) {
+    const posture = resolveNativeWebTools({ [name]: true });
+    if (posture.search === true && posture.fetch === undefined)
+        return "search";
+    if (posture.fetch === true && posture.search === undefined)
+        return "fetch";
+    return undefined;
+}
+const CLAUDE_TOOL_NAMES = {
+    askuserquestion: "AskUserQuestion",
+    bash: "Bash",
+    edit: "Edit",
+    glob: "Glob",
+    grep: "Grep",
+    notebookedit: "NotebookEdit",
+    read: "Read",
+    skill: "Skill",
+    task: "Task",
+    taskoutput: "TaskOutput",
+    todowrite: "TodoWrite",
+    webfetch: "WebFetch",
+    websearch: "WebSearch",
+    write: "Write",
+};
+export function claudeToolName(name) {
+    const web = nativeWebToolKind(name);
+    if (web === "search")
+        return "WebSearch";
+    if (web === "fetch")
+        return "WebFetch";
+    return CLAUDE_TOOL_NAMES[normalizedControlName(name)];
+}
+/** Tool IDs reported by the OpenCode binary shipped in the Sandbox image. */
+export const OPENCODE_NATIVE_TOOL_IDS = [
+    "apply_patch",
+    "bash",
+    "codesearch",
+    "edit",
+    "glob",
+    "grep",
+    "question",
+    "read",
+    "skill",
+    "task",
+    "todowrite",
+    "webfetch",
+    "websearch",
+    "write",
+];
+const OPENCODE_NATIVE_TOOL_ID_SET = new Set(OPENCODE_NATIVE_TOOL_IDS);
+/** Resolve portable and legacy profile names to current OpenCode tool IDs. */
+export function openCodeNativeToolId(name) {
+    const web = nativeWebToolKind(name);
+    if (web === "search")
+        return "websearch";
+    if (web === "fetch")
+        return "webfetch";
+    const normalized = normalizedControlName(name);
+    if (normalized === "patch")
+        return "apply_patch";
+    return OPENCODE_NATIVE_TOOL_ID_SET.has(normalized) ? normalized : undefined;
+}
+export function openCodeToolName(name) {
+    return openCodeNativeToolId(name);
+}
+export function openCodePermissionName(name) {
+    const normalized = normalizedControlName(name);
+    if (["write", "edit"].includes(normalized))
+        return "edit";
+    const web = nativeWebToolKind(name);
+    if (web === "search")
+        return "websearch";
+    if (web === "fetch")
+        return "webfetch";
+    if (["bash", "mcp", "doom_loop", "external_directory"].includes(normalized)) {
+        return normalized;
+    }
+    return normalized !== "read" && OPENCODE_NATIVE_TOOL_ID_SET.has(normalized)
+        ? normalized
+        : undefined;
+}
+export const PI_EXECUTION_CONTROL_EXTENSION_PATH = ".tangle/pi-execution-controls.ts";
+/**
+ * Translate only portable spellings whose Pi equivalent differs.
+ *
+ * Every other exact name is resolved against Pi's live registry, keeping
+ * extension and MCP tools profile-configurable without a static catalog.
+ */
+export function piToolId(name) {
+    const trimmed = name.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    const portableName = trimmed.toLowerCase();
+    if (portableName === "shell")
+        return "bash";
+    if (portableName === "glob")
+        return "find";
+    return trimmed;
+}
+export function mapSupportedBooleanEntries(entries, mapName, onUnsupported, label) {
+    return mapControlEntries(entries, mapName, onUnsupported, (left, right, nativeName) => {
+        if (left !== right)
+            throw new Error(`${label} aliases disagree for "${nativeName}"`);
+        return left;
+    });
+}
+export function permissionAllowsEverything(policy) {
+    return typeof policy === "string"
+        ? policy === "allow"
+        : Object.values(policy).every((value) => value === "allow");
+}
+export function mapSupportedPermissionEntries(entries, mapName, onUnsupported, label) {
+    return mapControlEntries(entries, mapName, onUnsupported, (left, right, nativeName) => mergePermissionPolicies(left, right, `${label} "${nativeName}"`));
+}
+function mapControlEntries(entries, mapName, onUnsupported, merge) {
+    const mapped = new Map();
+    for (const [name, value] of entries) {
+        const nativeName = mapName(name);
+        if (!nativeName) {
+            onUnsupported(name);
+            continue;
+        }
+        const previous = mapped.get(nativeName);
+        mapped.set(nativeName, previous === undefined ? value : merge(previous, value, nativeName));
+    }
+    return [...mapped.entries()].sort(([left], [right]) => compareStrings(left, right));
+}
+function mergePermissionPolicies(left, right, label) {
+    if (typeof left === "string" || typeof right === "string") {
+        if (left !== right)
+            throw new Error(`${label} aliases disagree`);
+        return left;
+    }
+    const merged = { ...left };
+    for (const [specifier, decision] of Object.entries(right)) {
+        const previous = merged[specifier];
+        if (previous !== undefined && previous !== decision) {
+            throw new Error(`${label} aliases disagree for "${specifier}"`);
+        }
+        merged[specifier] = decision;
+    }
+    return Object.fromEntries(Object.entries(merged).sort(([leftKey], [rightKey]) => compareStrings(leftKey, rightKey)));
+}
+export function claudePermissionRules(entries) {
+    const rules = {
+        allow: [],
+        ask: [],
+        deny: [],
+    };
+    for (const [tool, policy] of entries) {
+        if (typeof policy === "string") {
+            rules[policy].push(tool);
+            continue;
+        }
+        for (const [specifier, decision] of Object.entries(policy).sort(([left], [right]) => compareStrings(left, right))) {
+            rules[decision].push(specifier === "*" ? tool : `${tool}(${specifier})`);
+        }
+    }
+    rules.allow.sort(compareStrings);
+    rules.ask.sort(compareStrings);
+    rules.deny.sort(compareStrings);
+    return rules;
+}
+export function sealClaudePermissionRules(rules) {
+    const owner = new Map();
+    for (const decision of ["allow", "ask", "deny"]) {
+        for (const rule of rules[decision]) {
+            const previous = owner.get(rule);
+            if (previous && previous !== decision) {
+                throw new Error(`claude-code execution control "${rule}" conflicts between ${previous} and ${decision}`);
+            }
+            owner.set(rule, decision);
+        }
+    }
+    return {
+        allow: [...new Set(rules.allow)].sort(compareStrings),
+        ask: [...new Set(rules.ask)].sort(compareStrings),
+        deny: [...new Set(rules.deny)].sort(compareStrings),
+    };
+}
+import { resolveNativeWebTools } from "@tangle-network/agent-interface";
+import { compareStrings } from "./workspace-files.js";

package/dist/execution-controls.d.ts

@@ -0,0 +1,5 @@
+export declare function materializeExecutionControls(h: HarnessId, tools: Record<string, boolean> | undefined, permissions: Record<string, AgentProfilePermission> | undefined, modes: AgentProfile["modes"], plan: WorkspacePlan, add: AddPlanFile, unsupported: (d: Unsupported["dimension"], r: string) => void): void;
+import type { AgentProfile, AgentProfilePermission } from "@tangle-network/agent-interface";
+import type { HarnessId } from "./harness.js";
+import type { AddPlanFile } from "./plan-json.js";
+import type { Unsupported, WorkspacePlan } from "./plan-types.js";