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

package/dist/resource-lowering.js

@@ -0,0 +1,103 @@
+import { materializeCommand } from "./commands.js";
+import { HARNESS_SKILL_DIRS } from "./harness.js";
+import { normalizeSkillMd, resolveInlineRef } from "./resource-resolution.js";
+import { codexAgentRoleName, registerCodexAgent } from "./subagents.js";
+import { DEFAULT_FILE_MODE, EXECUTABLE_FILE_MODE, normalizeWorkspaceRelativePath, } from "./workspace-files.js";
+export function lowerProfileResources(profile, harness, builder) {
+    const { plan, addExplicitResource, unsupported } = builder;
+    const fileMountPaths = new Set();
+    for (const mount of profile.resources?.files ?? []) {
+        const relPath = normalizeWorkspaceRelativePath(mount.path);
+        if (fileMountPaths.has(relPath)) {
+            throw new Error(`Duplicate workspace file mount: ${relPath}`);
+        }
+        fileMountPaths.add(relPath);
+        if (mount.executable !== undefined &&
+            typeof mount.executable !== "boolean") {
+            throw new Error(`Workspace file executable must be a boolean: ${relPath}`);
+        }
+        const resource = resolveInlineRef(mount.resource);
+        if (!resource) {
+            unsupported("files", `file mount "${relPath}" is not inline (github refs need async pre-resolution)`);
+            continue;
+        }
+        addExplicitResource("files", relPath, resource.content, mount.executable ? EXECUTABLE_FILE_MODE : DEFAULT_FILE_MODE);
+    }
+    for (const ref of profile.resources?.tools ?? []) {
+        const resource = resolveInlineRef(ref);
+        if (!resource) {
+            unsupported("tools", "tool ref is not inline (github refs need async pre-resolution)");
+            continue;
+        }
+        if (harness !== "opencode") {
+            unsupported("tools", `${harness}: no verified cwd-native file tool path; use MCP or a native extension`);
+            continue;
+        }
+        addExplicitResource("tools", `.opencode/tools/${resource.name}`, resource.content);
+    }
+    for (const ref of profile.resources?.agents ?? []) {
+        const resource = resolveInlineRef(ref);
+        if (!resource) {
+            unsupported("subagents", "agent ref is not inline (github refs need async pre-resolution)");
+            continue;
+        }
+        const directory = agentResourceDirectory(harness);
+        if (!directory) {
+            unsupported("subagents", `${harness}: agent definitions have no verified cwd-native resource path`);
+            continue;
+        }
+        const relPath = `${directory}/${resource.name}`;
+        addExplicitResource("subagents", relPath, resource.content);
+        if (harness === "codex") {
+            const roleName = codexAgentRoleName(resource.name);
+            if (!roleName) {
+                unsupported("subagents", `codex: agent resource "${resource.name}" must use a lowercase role name`);
+            }
+            else {
+                registerCodexAgent(plan, roleName, relPath, roleName);
+            }
+        }
+    }
+}
+export function lowerProfileSkills(profile, harness, builder) {
+    const { addExplicitResource, unsupported } = builder;
+    for (const ref of profile.resources?.skills ?? []) {
+        const resource = resolveInlineRef(ref);
+        if (!resource) {
+            unsupported("skills", "skill ref is not inline (github refs need async pre-resolution)");
+            continue;
+        }
+        const directory = HARNESS_SKILL_DIRS[harness];
+        if (!directory) {
+            unsupported("skills", `${harness}: no cwd skill dir (skills live in a user/global dir); skill "${resource.name}" not mounted`);
+            continue;
+        }
+        addExplicitResource("skills", `${directory}/${resource.name}/SKILL.md`, normalizeSkillMd(resource.name, resource.content));
+    }
+}
+export function lowerProfileCommands(profile, harness, builder) {
+    const { addExplicitResource, unsupported } = builder;
+    for (const ref of profile.resources?.commands ?? []) {
+        const resource = resolveInlineRef(ref);
+        if (!resource) {
+            unsupported("commands", "command ref is not inline (github needs pre-resolution)");
+            continue;
+        }
+        materializeCommand(harness, resource.name, resource.content, (path, content, mode) => addExplicitResource("commands", path, content, mode), unsupported);
+    }
+}
+export function agentResourceDirectory(harness) {
+    switch (harness) {
+        case "claude-code":
+        case "nanoclaw":
+            return ".claude/agents";
+        case "codex":
+            return ".codex/agents";
+        case "opencode":
+            return ".opencode/agents";
+        case "gemini":
+            return ".gemini/agents";
+        default:
+            return null;
+    }
+}

package/dist/resource-resolution.d.ts

@@ -0,0 +1,27 @@
+/** Resolve inline bytes already present on the profile. Remote resources must
+ * be resolved by {@link resolveAgentProfileResources} before materialization.
+ *
+ * FAIL-CLOSED: a ref that declares `kind: "inline"` is asserting its bytes are
+ * already resolved, so missing/non-string `content` is a caller bug, not an
+ * empty file — silently coercing it (`String(content ?? "")`) would produce a
+ * file that "looks provisioned, loads nothing", exactly the trap this module's
+ * docstring warns against. */
+export declare function resolveInlineRef(ref: AgentProfileResourceRef): {
+    name: string;
+    content: string;
+} | null;
+export interface ResolveAgentProfileResourcesOptions {
+    /** Repository used when a GitHub resource omits its own `repository`. */
+    repository?: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+/**
+ * Resolve every GitHub resource to exact inline bytes before materialization.
+ * The profile's default harness does not affect resource resolution.
+ */
+export declare function resolveAgentProfileResources(inputProfile: AgentProfile, options?: ResolveAgentProfileResourcesOptions): Promise<AgentProfile>;
+/** Normalize any skill markdown (VB frontmatter `skill:`/`description:`, or raw) into a
+ *  harness SKILL.md with `name:`/`description:` frontmatter the harnesses require. */
+export declare function normalizeSkillMd(name: string, raw: string): string;
+import type { AgentProfile, AgentProfileResourceRef } from "@tangle-network/agent-interface";

package/dist/resource-resolution.js

@@ -0,0 +1,241 @@
+function describeUnresolvedRef(r) {
+    const name = typeof r.name === "string" ? r.name : undefined;
+    const path = typeof r.path === "string" ? r.path : undefined;
+    if (name && path)
+        return `"${name}" (${path})`;
+    if (name)
+        return `"${name}"`;
+    if (path)
+        return `"${path}"`;
+    return "resource";
+}
+/** Resolve inline bytes already present on the profile. Remote resources must
+ * be resolved by {@link resolveAgentProfileResources} before materialization.
+ *
+ * FAIL-CLOSED: a ref that declares `kind: "inline"` is asserting its bytes are
+ * already resolved, so missing/non-string `content` is a caller bug, not an
+ * empty file — silently coercing it (`String(content ?? "")`) would produce a
+ * file that "looks provisioned, loads nothing", exactly the trap this module's
+ * docstring warns against. */
+export function resolveInlineRef(ref) {
+    const r = ref;
+    if (typeof r.content === "string") {
+        return { name: String(r.name ?? r.path ?? "resource"), content: r.content };
+    }
+    if (r.kind === "inline") {
+        throw new Error(`Profile resource ${describeUnresolvedRef(r)} declares kind "inline" but has no string content`);
+    }
+    return null; // github / unresolved
+}
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+const collapse = (s) => s.replace(/\s+/g, " ").trim();
+const DEFAULT_RESOURCE_FETCH_TIMEOUT_MS = 30_000;
+const MAX_RESOURCE_BYTES = 10 * 1024 * 1024;
+const MAX_PROFILE_RESOURCE_BYTES = 32 * 1024 * 1024;
+const MAX_PROFILE_RESOURCE_REFS = 128;
+const MAX_CONCURRENT_RESOURCE_FETCHES = 8;
+async function readResourceBody(response, description, consumeBytes) {
+    if (!response.body)
+        return "";
+    const reader = response.body.getReader();
+    const chunks = [];
+    let totalBytes = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            totalBytes += value.byteLength;
+            if (totalBytes > MAX_RESOURCE_BYTES) {
+                await reader.cancel().catch(() => undefined);
+                throw new Error(`GitHub profile resource exceeds ${MAX_RESOURCE_BYTES} bytes: ${description}`);
+            }
+            try {
+                consumeBytes(value.byteLength);
+            }
+            catch (error) {
+                await reader.cancel().catch(() => undefined);
+                throw error;
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength)), totalBytes).toString("utf8");
+}
+async function mapWithConcurrency(values, concurrency, controller, transform) {
+    const results = new Array(values.length);
+    let nextIndex = 0;
+    let firstFailure;
+    const worker = async () => {
+        while (!firstFailure) {
+            const index = nextIndex++;
+            if (index >= values.length)
+                return;
+            try {
+                results[index] = await transform(values[index]);
+            }
+            catch (error) {
+                if (!firstFailure) {
+                    firstFailure = { error };
+                    controller.abort(error);
+                }
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, async () => worker()));
+    if (firstFailure)
+        throw firstFailure.error;
+    return results;
+}
+/**
+ * Resolve every GitHub resource to exact inline bytes before materialization.
+ * The profile's default harness does not affect resource resolution.
+ */
+export async function resolveAgentProfileResources(inputProfile, options = {}) {
+    const profile = agentProfileSchema.parse(inputProfile);
+    const resources = profile.resources;
+    if (!resources)
+        return profile;
+    const refs = [
+        ...(resources.files?.map((mount) => mount.resource) ?? []),
+        ...(resources.tools ?? []),
+        ...(resources.skills ?? []),
+        ...(resources.agents ?? []),
+        ...(resources.commands ?? []),
+        ...(typeof resources.instructions === "object"
+            ? [resources.instructions]
+            : []),
+    ];
+    if (refs.length > MAX_PROFILE_RESOURCE_REFS) {
+        throw new Error(`AgentProfile may contain at most ${MAX_PROFILE_RESOURCE_REFS} resource references`);
+    }
+    const batchController = new AbortController();
+    let fetchedBytes = 0;
+    const consumeFetchedBytes = (bytes) => {
+        fetchedBytes += bytes;
+        if (fetchedBytes > MAX_PROFILE_RESOURCE_BYTES) {
+            throw new Error(`GitHub profile resources exceed ${MAX_PROFILE_RESOURCE_BYTES} total bytes`);
+        }
+    };
+    const resolveRef = async (ref) => {
+        if (ref.kind === "inline")
+            return ref;
+        const repository = ref.repository ?? options.repository;
+        if (!repository) {
+            throw new Error(`GitHub profile resource "${ref.path}" requires repository`);
+        }
+        const [owner, repo, ...extraRepositoryParts] = repository.split("/");
+        if (!owner ||
+            !repo ||
+            extraRepositoryParts.length > 0 ||
+            !/^[A-Za-z0-9_.-]+$/.test(owner) ||
+            !/^[A-Za-z0-9_.-]+$/.test(repo)) {
+            throw new Error(`GitHub profile resource repository must be owner/repo: ${repository}`);
+        }
+        const resourcePath = normalizeWorkspaceRelativePath(ref.path);
+        const gitRef = ref.ref ?? "main";
+        if (!gitRef ||
+            hasControlCharacter(gitRef) ||
+            gitRef.split("/").some((segment) => !segment || segment === "..")) {
+            throw new Error(`Invalid GitHub profile resource ref: ${gitRef}`);
+        }
+        const encoded = (value) => value.split("/").map(encodeURIComponent).join("/");
+        const url = `https://raw.githubusercontent.com/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/${encoded(gitRef)}/${encoded(resourcePath)}`;
+        const controller = new AbortController();
+        const abortRequest = () => controller.abort(batchController.signal.reason);
+        batchController.signal.addEventListener("abort", abortRequest, {
+            once: true,
+        });
+        const timeoutError = new Error(`GitHub profile resource timed out: ${repository}/${resourcePath}@${gitRef}`);
+        const timeout = setTimeout(() => controller.abort(timeoutError), options.timeoutMs ?? DEFAULT_RESOURCE_FETCH_TIMEOUT_MS);
+        try {
+            const fetchResource = options.fetch ?? globalThis.fetch;
+            const response = await fetchResource(url, { signal: controller.signal });
+            if (!response.ok) {
+                throw new Error(`Failed to fetch GitHub profile resource ${repository}/${resourcePath}@${gitRef}: ${response.status} ${response.statusText}`);
+            }
+            const contentLength = Number(response.headers.get("content-length"));
+            if (Number.isFinite(contentLength) &&
+                contentLength > MAX_RESOURCE_BYTES) {
+                throw new Error(`GitHub profile resource exceeds ${MAX_RESOURCE_BYTES} bytes: ${repository}/${resourcePath}`);
+            }
+            const content = await readResourceBody(response, `${repository}/${resourcePath}`, consumeFetchedBytes);
+            return {
+                kind: "inline",
+                name: ref.name ?? basename(resourcePath),
+                content,
+            };
+        }
+        catch (error) {
+            if (controller.signal.aborted && controller.signal.reason !== undefined) {
+                throw controller.signal.reason;
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeout);
+            batchController.signal.removeEventListener("abort", abortRequest);
+        }
+    };
+    const resolvedRefs = await mapWithConcurrency(refs, MAX_CONCURRENT_RESOURCE_FETCHES, batchController, resolveRef);
+    let resolvedIndex = 0;
+    const takeRef = () => resolvedRefs[resolvedIndex++];
+    const takeRefs = (values) => values?.map(takeRef);
+    const resolvedResources = {
+        ...resources,
+        files: resources.files === undefined
+            ? undefined
+            : resources.files.map((mount) => ({
+                ...mount,
+                resource: takeRef(),
+            })),
+        tools: takeRefs(resources.tools),
+        skills: takeRefs(resources.skills),
+        agents: takeRefs(resources.agents),
+        commands: takeRefs(resources.commands),
+        instructions: typeof resources.instructions === "object"
+            ? takeRef()
+            : resources.instructions,
+    };
+    return agentProfileSchema.parse({ ...profile, resources: resolvedResources });
+}
+/** Normalize any skill markdown (VB frontmatter `skill:`/`description:`, or raw) into a
+ *  harness SKILL.md with `name:`/`description:` frontmatter the harnesses require. */
+export function normalizeSkillMd(name, raw) {
+    const m = raw.match(FRONTMATTER_RE);
+    const fm = m?.[1] ?? "";
+    const body = (m?.[2] ?? raw).trim();
+    let desc = `Skill ${name}. Use when the task matches its domain.`;
+    if (fm) {
+        const lines = fm.split("\n");
+        const i = lines.findIndex((l) => /^description:/.test(l));
+        if (i >= 0) {
+            const inline = (lines[i] ?? "").replace(/^description:\s*/, "").trim();
+            if (inline && ![">", "|", ">-", "|-"].includes(inline))
+                desc = collapse(inline);
+            else {
+                const buf = [];
+                for (let j = i + 1; j < lines.length; j++) {
+                    const ln = lines[j] ?? "";
+                    if (/^\s+\S/.test(ln))
+                        buf.push(ln.trim());
+                    else if (ln.trim() === "")
+                        continue;
+                    else
+                        break;
+                }
+                if (buf.length)
+                    desc = collapse(buf.join(" "));
+            }
+        }
+    }
+    return `---\nname: ${name}\ndescription: ${JSON.stringify(desc)}\n---\n\n${body}\n`;
+}
+import { basename } from "node:path";
+import { agentProfileSchema } from "@tangle-network/agent-interface";
+import { hasControlCharacter, normalizeWorkspaceRelativePath, } from "./workspace-files.js";

package/dist/subagents.d.ts

@@ -0,0 +1,6 @@
+export declare function materializeSubagent(h: HarnessId, name: string, sa: AgentSubagentProfile, plan: WorkspacePlan, add: AddPlanFile, unsupported: (d: Unsupported["dimension"], r: string) => void): void;
+export declare function codexAgentRoleName(resourceName: string): string | undefined;
+export declare function registerCodexAgent(plan: WorkspacePlan, name: string, configFile: string, description: string): void;
+import type { AgentSubagentProfile } from "@tangle-network/agent-interface";
+import type { AddPlanFile } from "./plan-json.js";
+import type { HarnessId, Unsupported, WorkspacePlan } from "./plan-types.js";

package/dist/subagents.js

@@ -0,0 +1,133 @@
+export function materializeSubagent(h, name, sa, plan, add, unsupported) {
+    if (!/^[a-z0-9][a-z0-9_-]*$/.test(name)) {
+        unsupported("subagents", `${h}: subagent name "${name}" must use lowercase letters, digits, underscores, or hyphens`);
+        return;
+    }
+    switch (h) {
+        case "claude-code":
+        case "nanoclaw": {
+            const fm = ["---", `name: ${name}`];
+            fm.push(`description: ${JSON.stringify(sa.description ?? name)}`);
+            if (sa.model)
+                fm.push(`model: ${JSON.stringify(sa.model)}`);
+            if (sa.tools) {
+                const tools = Object.entries(sa.tools);
+                const allowed = tools
+                    .filter(([, enabled]) => enabled)
+                    .map(([tool]) => tool);
+                const denied = tools
+                    .filter(([, enabled]) => !enabled)
+                    .map(([tool]) => tool);
+                if (allowed.length > 0)
+                    fm.push(`tools: ${JSON.stringify(allowed)}`);
+                if (denied.length > 0)
+                    fm.push(`disallowedTools: ${JSON.stringify(denied)}`);
+            }
+            if (sa.maxSteps !== undefined)
+                fm.push(`maxTurns: ${sa.maxSteps}`);
+            reportUnsupportedSubagentFields(h, name, sa, new Set(["description", "prompt", "model", "tools", "maxSteps"]), unsupported);
+            fm.push("---", "", sa.prompt ?? sa.description ?? name);
+            add(`.claude/agents/${name}.md`, `${fm.join("\n")}\n`);
+            break;
+        }
+        case "opencode": {
+            const fm = [
+                "---",
+                `description: ${JSON.stringify(sa.description ?? name)}`,
+                "mode: subagent",
+            ];
+            if (sa.model)
+                fm.push(`model: ${JSON.stringify(sa.model)}`);
+            if (sa.tools)
+                fm.push(`tools: ${JSON.stringify(sa.tools)}`);
+            if (sa.permissions)
+                fm.push(`permission: ${JSON.stringify(sa.permissions)}`);
+            if (sa.maxSteps !== undefined)
+                fm.push(`steps: ${sa.maxSteps}`);
+            reportUnsupportedSubagentFields(h, name, sa, new Set([
+                "description",
+                "prompt",
+                "model",
+                "tools",
+                "permissions",
+                "maxSteps",
+            ]), unsupported);
+            fm.push("---", "", sa.prompt ?? "");
+            add(`.opencode/agents/${name}.md`, `${fm.join("\n")}\n`);
+            break;
+        }
+        case "gemini": {
+            const tools = sa.tools
+                ? Object.entries(sa.tools)
+                    .filter(([, enabled]) => enabled)
+                    .map(([tool]) => tool)
+                : undefined;
+            reportUnsupportedSubagentFields(h, name, sa, new Set(["description", "prompt", "model", "tools", "maxSteps"]), unsupported);
+            add(`.gemini/agents/${name}.md`, [
+                "---",
+                `name: ${name}`,
+                `description: ${JSON.stringify(sa.description ?? name)}`,
+                "kind: local",
+                ...(sa.model ? [`model: ${JSON.stringify(sa.model)}`] : []),
+                ...(tools ? [`tools: ${JSON.stringify(tools)}`] : []),
+                ...(sa.maxSteps !== undefined ? [`max_turns: ${sa.maxSteps}`] : []),
+                "---",
+                "",
+                sa.prompt ?? "",
+                "",
+            ].join("\n"));
+            break;
+        }
+        case "codex": {
+            const relPath = `.codex/agents/${name}.toml`;
+            const lines = [
+                `name = ${tomlStr(name)}`,
+                `description = ${tomlStr(sa.description ?? name)}`,
+                `developer_instructions = ${tomlStr(sa.prompt ?? sa.description ?? name)}`,
+            ];
+            if (sa.model)
+                lines.push(`model = ${tomlStr(sa.model)}`);
+            reportUnsupportedSubagentFields(h, name, sa, new Set(["description", "prompt", "model"]), unsupported);
+            add(relPath, `${lines.join("\n")}\n`);
+            registerCodexAgent(plan, name, relPath, sa.description ?? name);
+            break;
+        }
+        case "prime":
+            // Prime subagents ARE expressible — as entries in the continual-harness
+            // store at <agentDir>/harness/harness_state.json (fork refinement.ts:269-279,
+            // re-read on every system-prompt build: agent-session.ts:7548-7554) — but
+            // that store lives under the executor-owned agent dir, which no
+            // workspace-relative plan file can reach. Executors that own the agent
+            // dir seed it with seedPrimeProfileSubagents; the plan stays fail-closed
+            // so a plan-forwarding caller can never believe the roster is in force.
+            unsupported("subagents", `prime: subagents live in the agent-dir continual-harness store (<agentDir>/harness/harness_state.json), outside any workspace plan — seed "${name}" with seedPrimeProfileSubagents from the executor that owns the agent dir`);
+            break;
+        default:
+            unsupported("subagents", `${h}: subagents have no cwd file (config/flag/global only); "${name}" not mounted`);
+    }
+}
+export function codexAgentRoleName(resourceName) {
+    const name = resourceName.endsWith(".toml")
+        ? resourceName.slice(0, -".toml".length)
+        : resourceName;
+    return /^[a-z0-9][a-z0-9_-]*$/.test(name) ? name : undefined;
+}
+export function registerCodexAgent(plan, name, configFile, description) {
+    plan.flags.push("-c", `agents.${name}.description=${tomlStr(description)}`, "-c", `agents.${name}.config_file=${tomlStr(configFile)}`);
+}
+function reportUnsupportedSubagentFields(harness, name, subagent, supported, unsupported) {
+    for (const field of [
+        "description",
+        "prompt",
+        "model",
+        "tools",
+        "permissions",
+        "maxSteps",
+        "metadata",
+    ]) {
+        if (subagent[field] !== undefined && !supported.has(field)) {
+            unsupported("subagents", `${harness}: subagent "${name}" does not support ${field}`);
+        }
+    }
+}
+import { tomlStr } from "./plan-json.js";

package/dist/workspace-apply.d.ts

@@ -0,0 +1,12 @@
+export declare function applyResolvedWorkspacePlan(publicPlan: WorkspacePlan, resolvedPlan: ResolvedWorkspacePlan, workspaceDir: string, options: ApplyWorkspacePlanOptions, publicPlanDigest?: string): WorkspacePlanApplication;
+export interface ResolvedWorkspacePlan {
+    files: NormalizedPlanFile[];
+    env: Record<string, string>;
+    flags: string[];
+    systemPrompt?: string;
+    appendSystemPrompt?: string;
+    systemPromptBinding?: WorkspacePlanSystemPromptBinding;
+}
+export declare function safeWorkspacePlanReceipt(plan: WorkspacePlan, written: string[], workspacePlanDigest?: string): WorkspacePlanReceipt;
+import { type NormalizedPlanFile } from "./plan-normalize.js";
+import type { ApplyWorkspacePlanOptions, WorkspacePlan, WorkspacePlanApplication, WorkspacePlanReceipt, WorkspacePlanSystemPromptBinding } from "./plan-types.js";