@tangle-network/agent-profile-materialize 0.25.3 → 0.26.0

package/dist/index.d.ts

@@ -5,10 +5,9 @@ export type { HarnessId } from "./harness.js";
 export { HARNESS_SKILL_DIRS, harnessAutoLoadsAgentContextFile, harnessAutoLoadsContextFile, harnessContextFile, isMaterializerHarness, MATERIALIZER_CONTEXT_PATHS, MATERIALIZER_HARNESSES, markMaterializerContextFile, skillDirForHarness, } from "./harness.js";
 export * from "./harness-prompt.js";
 export { type ConcurrentProfileRevision, ensurePublicConcurrentProfileRoots, type ManagedWorkspaceFileDigest, type ManagedWorkspaceManifest, preparePublicConcurrentProfileRevision, } from "./managed-workspace.js";
-export type { OpenCodeMcpConfig } from "./mcp.js";
-export { openCodeMcpConfig } from "./mcp.js";
+export { type OpenCodeMcpConfig, openCodeMcpConfig } from "./mcp.js";
 export { isMaterializerMcpConfig } from "./mcp-config-ownership.js";
-export { modelIdsMatch, qualifyModelId, unqualifyModelId, } from "./model-id.js";
+export * from "./model-id.js";
 export { buildPiModelsConfig, buildPiModelsConfigFile, PI_MODELS_CONFIG_PATH, type PiModelsConfigFile, type PiModelsConfigInput, type PiRuntimePaths, resolvePiRuntimePaths, } from "./pi-models-config.js";
 export { applyWorkspacePlan, applyWorkspacePlanWithSecretProvider, } from "./plan-application.js";
 export { agentCandidateProfilePlanMaterial, canonicalizeAgentCandidateProfilePlan, captureAgentCandidateProfilePlan, hashWorkspacePlan, } from "./plan-digest.js";
@@ -16,14 +15,14 @@ export { takeSystemPromptBinding } from "./plan-prompt.js";
 export { assertWorkspacePlanSupported, enforceWorkspacePlanSupport, } from "./plan-support.js";
 export type { ApplyWorkspacePlanOptions, BindableLaunchControl, ExecutorSystemPromptBinding, PlanFile, PlanFileRoot, PlanFileSecretSlot, PlanRequirement, SkippableDimension, Unsupported, WorkspacePlan, WorkspacePlanApplication, WorkspacePlanArgument, WorkspacePlanArgumentTemplate, WorkspacePlanConfigValue, WorkspacePlanReceipt, WorkspacePlanSecretSegment, WorkspacePlanSpawnInputs, WorkspacePlanSystemPromptBinding, WorkspacePlanWrittenFile, } from "./plan-types.js";
 export { BINDABLE_LAUNCH_CONTROLS, EXECUTOR_SYSTEM_PROMPT_BINDINGS, isExecutorSystemPromptBinding, isSkippableDimension, SKIPPABLE_DIMENSIONS, WorkspacePlanCleanupError, } from "./plan-types.js";
-export type { PrimeMaterializeOptions } from "./prime-agent-dir.js";
-export { materializePrimeProfileControls, prunePrimeProfileMaterial, seedPrimeProfileSubagents, writePrimeAgentFile, } from "./prime-agent-dir.js";
+export { materializePrimeProfileControls, type PrimeMaterializeOptions, primeHarnessStatePath, prunePrimeProfileMaterial, seedPrimeProfileSubagents, writePrimeAgentFile, } from "./prime-agent-dir.js";
 export type { PrimeProfileErrorKind, PrimeThinkingLevel, } from "./prime-fork.js";
 export { matchPrimeKernelDeadMarker, PRIME_AGENT_DIR_ENV_VAR, PRIME_AGENT_DIR_ENV_VARS, PRIME_FORK_INSTALL, PRIME_FORK_PIN, PRIME_HARNESS_STATE_ENV_DENYLIST, PRIME_KERNEL_DEAD_MARKERS, PRIME_KERNEL_ENV_PASSTHROUGH, PRIME_MCP_UNSUPPORTED_REASON, PRIME_THINKING_LEVELS, PrimeHarnessStateError, PrimeProfileError, parsePrimeModelsJson, primeAgentDirEnv, primeApiKeyEnvNames, primeThinkingLevel, stripPrimeJsonComments, } from "./prime-fork.js";
 export type { PrimeProfileControls, PrimeProfileSkill, PrimeProfileSubagent, } from "./prime-profile.js";
 export { assertPrimeModelAgreement, hasPrimeProfileMaterial, primeProfileNeedsAgentDir, primeSubagentEntryId, readPrimeProfileControls, } from "./prime-profile.js";
 export * from "./profile-bundle-cache.js";
 export { executionControlConflict, materializeProfile, UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER, } from "./profile-materializer.js";
+export * from "./profile-start-check.js";
 export type { ResolveAgentProfileResourcesOptions } from "./resource-resolution.js";
 export { normalizeSkillMd, resolveAgentProfileResources, } from "./resource-resolution.js";
 export { prepareSecretConcurrentProfileRevision } from "./secret-concurrent-revision.js";

package/dist/index.js

@@ -5,17 +5,18 @@ export * from "./harness-prompt.js";
 export { ensurePublicConcurrentProfileRoots, preparePublicConcurrentProfileRevision, } from "./managed-workspace.js";
 export { openCodeMcpConfig } from "./mcp.js";
 export { isMaterializerMcpConfig } from "./mcp-config-ownership.js";
-export { modelIdsMatch, qualifyModelId, unqualifyModelId, } from "./model-id.js";
+export * from "./model-id.js";
 export { buildPiModelsConfig, buildPiModelsConfigFile, PI_MODELS_CONFIG_PATH, resolvePiRuntimePaths, } from "./pi-models-config.js";
 export { applyWorkspacePlan, applyWorkspacePlanWithSecretProvider, } from "./plan-application.js";
 export { agentCandidateProfilePlanMaterial, canonicalizeAgentCandidateProfilePlan, captureAgentCandidateProfilePlan, hashWorkspacePlan, } from "./plan-digest.js";
 export { takeSystemPromptBinding } from "./plan-prompt.js";
 export { assertWorkspacePlanSupported, enforceWorkspacePlanSupport, } from "./plan-support.js";
 export { BINDABLE_LAUNCH_CONTROLS, EXECUTOR_SYSTEM_PROMPT_BINDINGS, isExecutorSystemPromptBinding, isSkippableDimension, SKIPPABLE_DIMENSIONS, WorkspacePlanCleanupError, } from "./plan-types.js";
-export { materializePrimeProfileControls, prunePrimeProfileMaterial, seedPrimeProfileSubagents, writePrimeAgentFile, } from "./prime-agent-dir.js";
+export { materializePrimeProfileControls, primeHarnessStatePath, prunePrimeProfileMaterial, seedPrimeProfileSubagents, writePrimeAgentFile, } from "./prime-agent-dir.js";
 export { matchPrimeKernelDeadMarker, PRIME_AGENT_DIR_ENV_VAR, PRIME_AGENT_DIR_ENV_VARS, PRIME_FORK_INSTALL, PRIME_FORK_PIN, PRIME_HARNESS_STATE_ENV_DENYLIST, PRIME_KERNEL_DEAD_MARKERS, PRIME_KERNEL_ENV_PASSTHROUGH, PRIME_MCP_UNSUPPORTED_REASON, PRIME_THINKING_LEVELS, PrimeHarnessStateError, PrimeProfileError, parsePrimeModelsJson, primeAgentDirEnv, primeApiKeyEnvNames, primeThinkingLevel, stripPrimeJsonComments, } from "./prime-fork.js";
 export { assertPrimeModelAgreement, hasPrimeProfileMaterial, primeProfileNeedsAgentDir, primeSubagentEntryId, readPrimeProfileControls, } from "./prime-profile.js";
 export * from "./profile-bundle-cache.js";
 export { executionControlConflict, materializeProfile, UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER, } from "./profile-materializer.js";
+export * from "./profile-start-check.js";
 export { normalizeSkillMd, resolveAgentProfileResources, } from "./resource-resolution.js";
 export { prepareSecretConcurrentProfileRevision } from "./secret-concurrent-revision.js";

package/dist/managed-workspace-bind.d.ts

@@ -1,4 +1,4 @@
 import type { WorkspacePlan, WorkspacePlanApplication } from "./plan-types.js";
 export declare function bindConcurrentLaunch(plan: WorkspacePlan, application: WorkspacePlanApplication, revisionWorkspaceDir: string, options?: {
-    readonly secretOpenCodeRevisionCwd?: boolean;
+    readonly secretOpenCodeConfigDirectory?: boolean;
 }): WorkspacePlanApplication["spawn"];

package/dist/managed-workspace-bind.js

@@ -4,15 +4,15 @@ import { join } from "node:path";
  * skills, and its standard agent and command definitions (OpenCode reads
  * `.opencode/{agent,agents}/**\/*.md` and `.opencode/{command,commands}/**\/*.md`).
  */
-const SECRET_REVISION_NATIVE_PATH = /^(?:reference\/|\.opencode\/skills\/|\.opencode\/(?:agents?|commands?)\/(?:[^./][^/]*\/)*[^./][^/]*\.md$)/u;
+const SECRET_REVISION_NATIVE_PATH = /^(?:\.opencode\/skills\/|\.opencode\/(?:agents?|commands?)\/(?:[^./][^/]*\/)*[^./][^/]*\.md$)/u;
 /**
- * A secret OpenCode revision runs OpenCode from its immutable, digest-attested
- * revision tree, so a file at one of OpenCode's own discovery paths is visible
- * there without a shared-workspace write. The binding stays limited to
+ * A secret OpenCode revision binds its immutable, digest-attested .opencode
+ * directory explicitly, so native agent, command and skill resources remain
+ * visible without discovering mutable shared-workspace configuration. The binding stays limited to
  * OpenCode's standard paths, never an app's own directory.
  */
 function ridesSecretRevision(plan, file, options) {
-    return (options.secretOpenCodeRevisionCwd === true &&
+    return (options.secretOpenCodeConfigDirectory === true &&
         plan.harness === "opencode" &&
         (file.root ?? "workspace") === "workspace" &&
         SECRET_REVISION_NATIVE_PATH.test(file.relPath));

package/dist/prime-agent-dir.d.ts

@@ -1,4 +1,19 @@
 export declare function writePrimeAgentFile(path: string, data: string, mode?: number): void;
+/**
+ * File access on a prime agent dir. The default reads and writes the local
+ * filesystem as the calling process. An executor whose agent dir belongs to
+ * another user (a root sidecar that demotes prime-agent) passes reads it took
+ * as that user and replays the writes as that user, so it never touches the
+ * agent's files with its own rights.
+ */
+export interface PrimeAgentDirIo {
+    /** The file's text, or undefined when it does not exist. */
+    read(path: string): string | undefined;
+    /** Replace the whole file: atomic and owner-only. */
+    write(path: string, data: string): void;
+}
+/** The fork's continual-harness store, the only agent-dir file a materialization reads. */
+export declare function primeHarnessStatePath(agentDir: string): string;
 export interface PrimeMaterializeOptions {
     /**
      * Where the FLAG-NAMED files go — the prompt files and the skills root.
@@ -14,6 +29,8 @@ export interface PrimeMaterializeOptions {
      * (currently: adopting entries a pre-shared executor left behind).
      */
     warn?: (msg: string, meta?: Record<string, unknown>) => void;
+    /** Agent-dir file access; the local filesystem when omitted. */
+    io?: PrimeAgentDirIo;
 }
 /**
  * Materialize the validated controls and return the extra spawn args that bind
@@ -43,5 +60,5 @@ export declare function prunePrimeProfileMaterial(agentDir: string, options?: Pi
  * {@link PrimeHarnessStateError}: the file is the agent's own self-modification
  * state, and overwriting it destroys what the run was supposed to observe.
  */
-export declare function seedPrimeProfileSubagents(agentDir: string, subagents: PrimeProfileSubagent[], warn?: (msg: string, meta?: Record<string, unknown>) => void): void;
+export declare function seedPrimeProfileSubagents(agentDir: string, subagents: PrimeProfileSubagent[], warn?: (msg: string, meta?: Record<string, unknown>) => void, io?: PrimeAgentDirIo): void;
 import type { PrimeProfileControls, PrimeProfileSubagent } from "./prime-profile.js";

package/dist/prime-agent-dir.js

@@ -4,6 +4,14 @@ export function writePrimeAgentFile(path, data, mode = 0o600) {
     writeFileSync(temp, data, { mode });
     renameSync(temp, path);
 }
+const localPrimeAgentDirIo = {
+    read: (path) => (existsSync(path) ? readFileSync(path, "utf8") : undefined),
+    write: (path, data) => writePrimeAgentFile(path, data),
+};
+/** The fork's continual-harness store, the only agent-dir file a materialization reads. */
+export function primeHarnessStatePath(agentDir) {
+    return join(agentDir, PRIME_HARNESS_DIR_NAME, PRIME_HARNESS_STATE_FILE);
+}
 /**
  * Materialize the validated controls and return the extra spawn args that bind
  * them. Runs before every spawn (same place models.json is materialized), so a
@@ -11,30 +19,30 @@ export function writePrimeAgentFile(path, data, mode = 0o600) {
  * process.
  */
 export function materializePrimeProfileControls(agentDir, controls, options = {}) {
-    const { flagFileRoot = agentDir, warn } = options;
+    const { flagFileRoot = agentDir, warn, io = localPrimeAgentDirIo } = options;
     const args = [];
     const profileDir = join(flagFileRoot, PRIME_PROFILE_DIR_NAME);
     if (controls.systemPrompt !== undefined) {
         const promptPath = join(profileDir, PRIME_SYSTEM_PROMPT_FILE);
-        writePrimeAgentFile(promptPath, controls.systemPrompt);
+        io.write(promptPath, controls.systemPrompt);
         args.push("--system-prompt", promptPath);
     }
     if (controls.appendSystemPrompt !== undefined) {
         const appendPath = join(profileDir, PRIME_APPEND_SYSTEM_PROMPT_FILE);
-        writePrimeAgentFile(appendPath, controls.appendSystemPrompt);
+        io.write(appendPath, controls.appendSystemPrompt);
         args.push("--append-system-prompt", appendPath);
     }
     if (controls.instructions !== undefined) {
-        writePrimeAgentFile(join(agentDir, PRIME_CONTEXT_FILE), `${controls.instructions}\n`);
+        io.write(join(agentDir, PRIME_CONTEXT_FILE), `${controls.instructions}\n`);
     }
     if (controls.skills.length > 0) {
         const skillsRoot = join(profileDir, PRIME_SKILLS_DIR_NAME);
         for (const skill of controls.skills) {
-            writePrimeAgentFile(join(skillsRoot, skill.name, "SKILL.md"), normalizeSkillMd(skill.name, skill.content));
+            io.write(join(skillsRoot, skill.name, "SKILL.md"), normalizeSkillMd(skill.name, skill.content));
         }
         args.push("--skill", skillsRoot);
     }
-    seedPrimeProfileSubagents(agentDir, controls.subagents, warn);
+    seedPrimeProfileSubagents(agentDir, controls.subagents, warn, io);
     return args;
 }
 /**
@@ -65,13 +73,14 @@ export function prunePrimeProfileMaterial(agentDir, options = {}) {
  * {@link PrimeHarnessStateError}: the file is the agent's own self-modification
  * state, and overwriting it destroys what the run was supposed to observe.
  */
-export function seedPrimeProfileSubagents(agentDir, subagents, warn) {
-    const statePath = join(agentDir, PRIME_HARNESS_DIR_NAME, PRIME_HARNESS_STATE_FILE);
+export function seedPrimeProfileSubagents(agentDir, subagents, warn, io = localPrimeAgentDirIo) {
+    const statePath = primeHarnessStatePath(agentDir);
     let state = {};
-    if (existsSync(statePath)) {
+    const stored = io.read(statePath);
+    if (stored !== undefined) {
         let parsed;
         try {
-            parsed = JSON.parse(readFileSync(statePath, "utf8"));
+            parsed = JSON.parse(stored);
         }
         catch (err) {
             throw new PrimeHarnessStateError(statePath, err instanceof Error ? err.message : String(err));
@@ -149,7 +158,7 @@ export function seedPrimeProfileSubagents(agentDir, subagents, warn) {
     }
     if (!changed)
         return;
-    writePrimeAgentFile(statePath, `${JSON.stringify({
+    io.write(statePath, `${JSON.stringify({
         ...state,
         schema: typeof state.schema === "number" ? state.schema : 1,
         entries,

package/dist/profile-start-check.d.ts

@@ -0,0 +1,32 @@
+import type { BindableLaunchControl } from "./plan-types.js";
+import { type ResolveAgentProfileResourcesOptions } from "./resource-resolution.js";
+/** Whether a profile starts on a harness, answered before any spawn. */
+export interface ProfileStartCheck {
+    readonly ok: boolean;
+    /** Each error a spawn would raise, in the materializer's own words. */
+    readonly refusals: readonly string[];
+    /** Controls `resources.failOnError: false` lets the run skip, as a spawn logs them. */
+    readonly warnings: readonly string[];
+}
+export interface CheckProfileStartsOptions extends ResolveAgentProfileResourcesOptions {
+    /** Harness to check; defaults to the profile's own `harness`. */
+    harness?: string;
+    /**
+     * Launch controls the launcher binds. Defaults to what the maintained
+     * launchers bind: `systemPrompt` on opencode (the sidecar and the opencode
+     * provider both pass it), nothing elsewhere, where binds change no refusal.
+     */
+    binds?: readonly BindableLaunchControl[];
+}
+/**
+ * Run the spawn path's profile steps without spawning: resolve resources,
+ * materialize for the harness, then enforce `resources.failOnError`.
+ *
+ * A refusal here is the error a spawn gives, word for word, because it is the
+ * same code. Profile builders and validators call this instead of copying the
+ * native tool maps, which change whenever a harness does. Inline resources
+ * need no network; GitHub refs are fetched exactly as a spawn fetches them.
+ * Model and harness compatibility is not decided here: its owner is
+ * `harnessModelSupportFor` in `@tangle-network/cli-agent-registry`.
+ */
+export declare function checkProfileStarts(input: unknown, options?: CheckProfileStartsOptions): Promise<ProfileStartCheck>;

package/dist/profile-start-check.js

@@ -0,0 +1,39 @@
+import { agentProfileSchema } from "@tangle-network/agent-interface";
+import { assertMaterializerHarness } from "./harness.js";
+import { enforceWorkspacePlanSupport } from "./plan-support.js";
+import { materializeProfile } from "./profile-materializer.js";
+import { resolveAgentProfileResources, } from "./resource-resolution.js";
+/**
+ * Run the spawn path's profile steps without spawning: resolve resources,
+ * materialize for the harness, then enforce `resources.failOnError`.
+ *
+ * A refusal here is the error a spawn gives, word for word, because it is the
+ * same code. Profile builders and validators call this instead of copying the
+ * native tool maps, which change whenever a harness does. Inline resources
+ * need no network; GitHub refs are fetched exactly as a spawn fetches them.
+ * Model and harness compatibility is not decided here: its owner is
+ * `harnessModelSupportFor` in `@tangle-network/cli-agent-registry`.
+ */
+export async function checkProfileStarts(input, options = {}) {
+    const { harness: harnessOption, binds, ...resolveOptions } = options;
+    try {
+        const parsed = agentProfileSchema.parse(input);
+        const harness = harnessOption ?? parsed.harness;
+        if (harness === undefined) {
+            return refused(["harness: the profile names no harness to start on"]);
+        }
+        assertMaterializerHarness(harness);
+        const profile = await resolveAgentProfileResources(parsed, resolveOptions);
+        const plan = materializeProfile(profile, harness, {
+            binds: binds ?? (harness === "opencode" ? ["systemPrompt"] : []),
+        });
+        const warnings = enforceWorkspacePlanSupport(plan, profile.resources?.failOnError);
+        return { ok: true, refusals: [], warnings };
+    }
+    catch (error) {
+        return refused([error instanceof Error ? error.message : String(error)]);
+    }
+}
+function refused(refusals) {
+    return { ok: false, refusals, warnings: [] };
+}

package/dist/secret-concurrent-revision.js

@@ -20,7 +20,20 @@ export async function prepareSecretConcurrentProfileRevision(input) {
         !input.ownerId) {
         throw new Error("Secret concurrent profile needs a root executor and reserved identity");
     }
+    for (const name of [
+        "OPENCODE_DISABLE_PROJECT_CONFIG",
+        "OPENCODE_CONFIG_DIR",
+        "TANGLE_SHARED_WORKSPACE",
+    ]) {
+        if (Object.hasOwn(input.plan.env, name)) {
+            throw new Error(`Secret OpenCode reserves ${name} for its launch binding`);
+        }
+    }
     let plan = prepareExplicitOpenCodePlan(input.plan);
+    if (plan.files.some((file) => (file.root ?? "workspace") === "workspace" &&
+        file.relPath.startsWith("reference/"))) {
+        throw new Error("Secret OpenCode cannot bind cwd-relative reference resources to a shared data workspace");
+    }
     if (input.providerConfig) {
         plan = {
             ...plan,
@@ -53,7 +66,13 @@ export async function prepareSecretConcurrentProfileRevision(input) {
             recursive: true,
             mode: 0o700,
         });
+        mkdirSync(join(prepared.root, "workspace", ".opencode"), {
+            recursive: true,
+            mode: 0o700,
+        });
         const identity = createHmac("sha256", input.namingKey)
+            .update(input.sharedWorkspaceDir)
+            .update("\0")
             .update(input.ownerId)
             .update("\0")
             .update(String(input.subprocessUid))
@@ -61,7 +80,16 @@ export async function prepareSecretConcurrentProfileRevision(input) {
             .update(prepared.manifest.materializedDigest)
             .digest("hex");
         const directory = join(input.launchRoot, `revision-${identity}`);
-        const spawn = bindConcurrentLaunch(plan, prepared.application, join(directory, "workspace"), { secretOpenCodeRevisionCwd: true });
+        const bound = bindConcurrentLaunch(plan, prepared.application, join(directory, "workspace"), { secretOpenCodeConfigDirectory: true });
+        const spawn = {
+            ...bound,
+            env: {
+                ...bound.env,
+                OPENCODE_DISABLE_PROJECT_CONFIG: "1",
+                OPENCODE_CONFIG_DIR: join(directory, "workspace", ".opencode"),
+                TANGLE_SHARED_WORKSPACE: input.sharedWorkspaceDir,
+            },
+        };
         prepared.manifest.launchDigest = createHash("sha256")
             .update(JSON.stringify(spawn))
             .digest("hex");

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.25.3",
-  "description": "Materialize an AgentProfile into the native per-harness workspace files (the one shared materializer for cli-bridge, agent-dev-container, and VB).",
+  "version": "0.26.0",
+  "description": "Materialize an AgentProfile into the native per-harness workspace files (the one shared materializer for cli-bridge, agent-container, and VB).",
   "type": "module",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/tangle-network/agent-dev-container.git",
+    "url": "git+https://github.com/tangle-network/agent-container.git",
     "directory": "packages/agent-profile-materialize"
   },
   "main": "./dist/index.js",