@tangle-network/agent-profile-materialize 0.5.1 → 0.6.0

package/dist/index.d.ts

@@ -74,6 +74,15 @@ export interface ApplyWorkspacePlanOptions {
 }
 /** Fail when a profile asks for controls the chosen harness cannot execute. */
 export declare function assertWorkspacePlanSupported(plan: Pick<WorkspacePlan, "unsupported">): void;
+/**
+ * Enforce plan supportability under the profile's `resources.failOnError`
+ * policy. Strict by default: `failOnError` absent or `true` throws on any
+ * unsupported dimension. An explicitly best-effort profile
+ * (`failOnError: false`) materializes the supported subset instead; the
+ * returned `"dimension: reason"` entries are what the caller must surface
+ * as a warning so the skipped dimensions stay visible to operators.
+ */
+export declare function enforceWorkspacePlanSupport(plan: Pick<WorkspacePlan, "unsupported">, failOnError: boolean | undefined): string[];
 /**
  * Candidate-safe workspace plan. Spawn values remain typed until the runtime
  * resolves them; the materializer never joins argv into a shell command.
@@ -99,6 +108,42 @@ export interface MaterializeCandidateProfileOptions {
     /** Exact text fetched from pinned resource refs, keyed by declared SHA-256. */
     resolvedResources?: ReadonlyMap<Sha256Digest, string>;
 }
+/**
+ * Whether the harness LOADS its {@link CONTEXT_FILE} from cwd on its own.
+ *
+ * True for every harness whose CLI discovers the file by name (CLAUDE.md,
+ * AGENTS.md, …). opencode is the exception: it reads only what its
+ * `opencode.json` `instructions[]` names, so a caller writing context for
+ * opencode must register the path as well as write it — see the `instructions`
+ * lowering below, and the interactive TUI's persona fold.
+ */
+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;
+/**
+ * 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` (after alias canonicalization: claude/claudish →
+ * claude-code, kimi → kimi-code). `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;
 export interface ResolveAgentProfileResourcesOptions {
     /** Repository used when a GitHub resource omits its own `repository`. */
     repository?: string;
@@ -154,6 +199,10 @@ export declare function applyAgentCandidateWorkspacePlan(plan: AgentCandidateWor
  * agent-dev-container box, and VB. Returns `unsupported` so the caller can log/fail.
  */
 export declare function applyWorkspacePlan(plan: WorkspacePlan, workspaceDir: string, options?: ApplyWorkspacePlanOptions): WorkspacePlanReceipt;
+/** 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;
 /** OpenCode-native MCP configuration used by workspace and startup paths. */
 export type OpenCodeMcpConfig = Record<string, {
     type: "remote";

package/dist/index.js

@@ -54,7 +54,52 @@ export function assertWorkspacePlanSupported(plan) {
         throw new Error(formatUnsupported(plan.unsupported));
     }
 }
+/**
+ * Enforce plan supportability under the profile's `resources.failOnError`
+ * policy. Strict by default: `failOnError` absent or `true` throws on any
+ * unsupported dimension. An explicitly best-effort profile
+ * (`failOnError: false`) materializes the supported subset instead; the
+ * returned `"dimension: reason"` entries are what the caller must surface
+ * as a warning so the skipped dimensions stay visible to operators.
+ */
+export function enforceWorkspacePlanSupport(plan, failOnError) {
+    if (failOnError === false) {
+        return plan.unsupported.map(({ dimension, reason }) => `${dimension}: ${reason}`);
+    }
+    assertWorkspacePlanSupported(plan);
+    return [];
+}
 // ─── Verified per-harness conventions (capability matrix) ───────────────────
+/**
+ * Whether the harness LOADS its {@link CONTEXT_FILE} from cwd on its own.
+ *
+ * True for every harness whose CLI discovers the file by name (CLAUDE.md,
+ * AGENTS.md, …). opencode is the exception: it reads only what its
+ * `opencode.json` `instructions[]` names, so a caller writing context for
+ * opencode must register the path as well as write it — see the `instructions`
+ * lowering below, and the interactive TUI's persona fold.
+ */
+export function harnessAutoLoadsContextFile(harness) {
+    return canonicalHarness(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) {
+    // 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[canonicalHarness(harness)];
+    if (!path) {
+        throw new Error(`No project context file is known for harness "${harness}"`);
+    }
+    return path;
+}
 /** Project context file each harness actually reads from cwd. NEVER a constant. */
 const CONTEXT_FILE = {
     "claude-code": "CLAUDE.md",
@@ -70,8 +115,15 @@ const CONTEXT_FILE = {
     hermes: "HERMES.md", // highest-priority native name; only ONE context loads (first match)
     openclaw: "AGENTS.md",
 };
-/** cwd-relative native skill dir, or null if the harness has no cwd skill primitive. */
-const SKILL_DIR = {
+/**
+ * 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",
     claude: ".claude/skills",
     claudish: ".claude/skills",
@@ -85,6 +137,18 @@ const SKILL_DIR = {
     hermes: null, // skills are ~/.hermes/skills (user) only — no cwd discovery
     openclaw: "skills", // <workspace>/skills/<name>/SKILL.md
 };
+const SKILL_DIR = HARNESS_SKILL_DIRS;
+/**
+ * Resolve the cwd-relative directory `resources.skills` refs materialize
+ * into on `harness` (after alias canonicalization: claude/claudish →
+ * claude-code, kimi → kimi-code). `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) {
+    return HARNESS_SKILL_DIRS[canonicalHarness(harness)];
+}
 function canonicalHarness(h) {
     if (h === "claude" || h === "claudish")
         return "claude-code";
@@ -1310,33 +1374,38 @@ function claudeToolName(name) {
         return "WebFetch";
     return CLAUDE_TOOL_NAMES[normalizedControlName(name)];
 }
-const OPENCODE_TOOL_NAMES = new Set([
+/** Tool IDs reported by the OpenCode binary shipped in the Sandbox image. */
+export const OPENCODE_NATIVE_TOOL_IDS = [
+    "apply_patch",
     "bash",
-    "batch",
     "codesearch",
     "edit",
     "glob",
     "grep",
-    "list",
-    "lsp",
-    "multiedit",
-    "patch",
+    "question",
     "read",
+    "skill",
     "task",
-    "todoread",
     "todowrite",
     "webfetch",
     "websearch",
     "write",
-]);
-function openCodeToolName(name) {
+];
+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);
-    return OPENCODE_TOOL_NAMES.has(normalized) ? normalized : undefined;
+    if (normalized === "patch")
+        return "apply_patch";
+    return OPENCODE_NATIVE_TOOL_ID_SET.has(normalized) ? normalized : undefined;
+}
+function openCodeToolName(name) {
+    return openCodeNativeToolId(name);
 }
 function openCodePermissionName(name) {
     const normalized = normalizedControlName(name);
@@ -1350,7 +1419,7 @@ function openCodePermissionName(name) {
     if (["bash", "mcp", "doom_loop", "external_directory"].includes(normalized)) {
         return normalized;
     }
-    return normalized !== "read" && OPENCODE_TOOL_NAMES.has(normalized)
+    return normalized !== "read" && OPENCODE_NATIVE_TOOL_ID_SET.has(normalized)
         ? normalized
         : undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "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",
@@ -16,7 +16,7 @@
     "dist"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "0.30.0"
+    "@tangle-network/agent-interface": "0.31.0"
   },
   "devDependencies": {
     "@types/node": "25.6.0",