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

package/dist/index.d.ts

@@ -1,624 +1,25 @@
-/**
- * materializeProfile — THE ONE per-harness profile materializer, shared by every
- * layer (cli-bridge host spawn, agent-dev-container box adapter, VB). It turns a
- * structured {@link AgentProfile} into a {@link WorkspacePlan}: the exact native
- * files to write into the run workspace (cwd), plus the env/flags some harnesses
- * need because they have NO cwd auto-discovery for certain dimensions.
- *
- * Routed per the VERIFIED capability matrix (harness-capability-matrix, 2026-06-14)
- * across every dimension (context, skills, mcp, hooks, subagents, commands).
- *
- * FAIL-CLOSED, not silent-drop: when a requested dimension has no path on the
- * chosen harness (e.g. kimi MCP is flag-only, hermes hooks are opt-in global), it
- * is recorded in `plan.unsupported` with the reason — never silently ignored,
- * which is exactly the "looks provisioned, loads nothing" trap.
- *
- * The ONLY trustworthy proof a dimension works is the in-session effect (skill
- * secret word, MCP tool called n>0, hook sentinel file) — see the canary tests.
- *
- * Types come from `@tangle-network/agent-interface` (the canonical AgentProfile
- * contract); this package adds only the harness-specific materialization + the
- * `node:fs` IO consumer. It was previously copied byte-for-byte into both
- * cli-bridge and agent-dev-container — this is the single source those re-export.
- */
+/** Stable public facade for profile materialization and workspace application. */
+export { applyAgentCandidateWorkspacePlan, materializeCandidateProfile, } from "./candidate.js";
+export type { AgentCandidateWorkspacePlan, AgentCandidateWorkspacePlanReceipt, MaterializeCandidateProfileOptions, } from "./candidate-types.js";
+export { OPENCODE_NATIVE_TOOL_IDS, openCodeNativeToolId, } from "./control-maps.js";
+export type { HarnessId } from "./harness.js";
+export { HARNESS_SKILL_DIRS, harnessAutoLoadsContextFile, harnessContextFile, isMaterializerHarness, MATERIALIZER_HARNESSES, skillDirForHarness, } from "./harness.js";
+export type { OpenCodeMcpConfig } from "./mcp.js";
+export { openCodeMcpConfig } from "./mcp.js";
 export { modelIdsMatch, qualifyModelId } from "./model-id.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, type PrimeProfileErrorKind, type PrimeThinkingLevel, parsePrimeModelsJson, primeAgentDirEnv, primeApiKeyEnvNames, primeThinkingLevel, stripPrimeJsonComments, } from "./prime-fork.js";
-import type { AgentCandidateConfigValue, AgentCandidateProfile, AgentCandidateProfileActivation, AgentCandidateProfileApplication, AgentCandidateProfilePlanEvidence, AgentCandidateProfilePlanMaterial, AgentProfile, AgentProfileConfigValue, AgentProfileMcpServer, AgentProfileSecretProvider, AgentProfileSecretRef, Sha256Digest } from "@tangle-network/agent-interface";
-export declare const UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER: AgentProfileSecretProvider;
-/**
- * The harnesses this materializer can lower an AgentProfile into. `satisfies` binds every id to
- * the canonical harness enum, so a rename upstream is a compile error here rather than an
- * `isMaterializerHarness` that silently returns false for a harness that still exists.
- */
-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 interface PlanFile {
-    relPath: string;
-    content: string;
-    /** chmod mode (e.g. 0o755 for hook scripts); default 0o644. */
-    mode?: number;
-    /**
-     * Provenance of this entry. `"generated"` = the materializer synthesized the
-     * content itself (native harness config, merged settings, lowered prompt/MCP/
-     * hooks/subagents). `"user"` = the exact bytes of a profile-declared resource
-     * ref (`resources.files`/`tools`/`agents`/`skills`/`commands`), passed through
-     * verbatim at the path the profile author chose.
-     *
-     * A consumer that needs to reinterpret a SPECIFIC generated file (e.g. parse
-     * `opencode.json` as the synthetic native config) MUST gate on
-     * `source === "generated"` at that relPath — matching by relPath alone cannot
-     * tell a harness-authored config apart from a user resource mount that
-     * happens to share the same conventional path, and treating arbitrary user
-     * content as trusted generated config is a fail-open bug, not a fallback.
-     *
-     * Optional: callers that hand-construct a {@link WorkspacePlan} directly for
-     * {@link applyWorkspacePlan} (tests, ad hoc writes) are not materializer
-     * output and have no provenance to report. `materializeProfile` always sets
-     * this on every file it emits.
-     */
-    source?: "user" | "generated";
-    /**
-     * Who owns the PATH — which decides whether an existing file there may be
-     * replaced.
-     *
-     * `"materializer"` = a path this package invented. No harness convention
-     * names it and no user authors it, so a file already there can only be this
-     * materializer's own output from an earlier application into the same
-     * workspace, and replacing it is how turn two of a resumed session gets the
-     * current profile instead of the previous one.
-     *
-     * `"shared"` (the default, and every other file) = a path the user or the
-     * harness also owns — `CLAUDE.md`, `AGENTS.md`, `opencode.json`,
-     * `.gemini/system.md` are all documented, user-authorable names. An existing
-     * file there may be the caller's own work, so it is never replaced.
-     *
-     * Optional because hand-constructed plans have no path provenance to report;
-     * absent reads as `"shared"`, the safe answer.
-     */
-    ownership?: "materializer" | "shared";
-    /**
-     * Secret leaves in a generated JSON document. `content` contains `null` at
-     * each path until the private executor resolves the named reference. The
-     * public plan, its digest, and its receipt retain only these references.
-     */
-    secretSlots?: PlanFileSecretSlot[];
-}
-export interface PlanFileSecretSlot {
-    path: Array<string | number>;
-    ref: AgentProfileSecretRef;
-}
-export interface WorkspacePlanSecretSegment {
-    kind: "secret";
-    ref: AgentProfileSecretRef;
-    /** Encoding applied after private resolution. */
-    encoding: "raw" | "json-string";
-}
-/** A launch argument whose private leaves are resolved immediately before spawn. */
-export interface WorkspacePlanArgumentTemplate {
-    kind: "workspace-plan-argument-template";
-    segments: Array<string | WorkspacePlanSecretSegment>;
-}
-export type WorkspacePlanArgument = string | WorkspacePlanArgumentTemplate;
-/** Public bytes stay strings; secret references stay opaque until application. */
-export type WorkspacePlanConfigValue = string | AgentProfileSecretRef;
-export interface Unsupported {
-    dimension: "files" | "skills" | "mcp" | "hooks" | "subagents" | "commands" | "instructions" | "systemPrompt" | "appendSystemPrompt" | "connections" | "confidential" | "permissions" | "tools" | "modes" | "extensions";
-    reason: string;
-}
-/**
- * The subset of {@link BINDABLE_LAUNCH_CONTROLS} the plan HANDS OVER rather than
- * executes: controls a caller reaches only by composing the harness's own
- * configuration, so no file, flag or env var the plan writes can touch them.
- *
- *   - `opencode.agent-prompt` — opencode's `agent.<name>.prompt` config field,
- *     the one control that replaces its built-in provider prompt. It binds to a
- *     SINGLE agent, and the agent is chosen at launch. A caller that builds
- *     opencode's config itself and picks the agent there reads neither
- *     `plan.files` nor `plan.flags`, so for that one the plan names the control
- *     and hands over the text in {@link WorkspacePlan.systemPromptBinding}.
- *
- * Every other bindable control names a capability the plan still lowers itself
- * once the caller has declared the plan's launch inputs really reach the spawn.
- */
-export declare const EXECUTOR_SYSTEM_PROMPT_BINDINGS: readonly ["opencode.agent-prompt"];
-export type ExecutorSystemPromptBinding = (typeof EXECUTOR_SYSTEM_PROMPT_BINDINGS)[number];
-export declare function isExecutorSystemPromptBinding(value: string): value is ExecutorSystemPromptBinding;
-/**
- * A system-prompt intent handed to the launcher that declared it owns the
- * control, instead of being lowered into the workspace.
- *
- * Distinct from {@link WorkspacePlan.systemPrompt} — a launch ARGUMENT the
- * executor hands to a harness flag — and from the file/flag/env lowerings the
- * plan performs on its own. This names the exact control that must receive the
- * text and which of the two intents it is, so the launcher cannot apply it to
- * the wrong channel. Never written into an additive channel and never dropped:
- * a caller that has not declared it owns `control` gets the plan's own lowering
- * (or a refusal where the harness has no control at all) instead of this field.
- */
-export interface WorkspacePlanSystemPromptBinding {
-    /** Which of the two prompt intents this is — never inferred from presence. */
-    intent: "replace";
-    /** The exact launcher control that must receive `systemPrompt`. */
-    control: ExecutorSystemPromptBinding;
-    /** Exact text the control receives. */
-    systemPrompt: string;
-}
-/**
- * The dimensions `materializeProfile`'s `skip` option honors.
- *
- * Every other dimension is materialized unconditionally: generated plan files are pushed through
- * a single site that carries no dimension tag, so there is nothing to gate them on. Naming the
- * honored set keeps `skip: ["hooks"]` a loud rejection instead of a silent no-op.
- */
-export declare const SKIPPABLE_DIMENSIONS: readonly ["mcp", "extensions"];
-export type SkippableDimension = (typeof SKIPPABLE_DIMENSIONS)[number];
-export declare function isSkippableDimension(value: string): value is SkippableDimension;
-/**
- * Launcher controls an executor can declare it OWNS via `materializeProfile`'s
- * `binds` option.
- *
- * Some harness controls live outside any workspace: opencode's exact
- * system-prompt replacement (`agent.<name>.prompt`) binds to the ONE agent
- * whoever starts the process selects, which a plan-forwarding executor cannot
- * guarantee — so the plan refuses the intent (harnessSystemPromptIntents in
- * @tangle-network/agent-interface answers `replace: false` for opencode).
- *
- * The two declarations describe the two executor shapes that CAN reach it, and
- * each gets the lowering it can actually apply:
- *
- *   - `systemPrompt` — the executor applies the plan's launch flags to the
- *     spawn it owns, so the plan writes the generated `mode: primary` agent and
- *     selects it with `--agent`.
- *   - `opencode.agent-prompt` — the executor composes opencode's own config and
- *     picks the agent there, reading neither plan files nor plan flags, so the
- *     plan hands the text over in {@link WorkspacePlan.systemPromptBinding}
- *     instead of writing a workspace agent that would never be selected.
- *
- * They are mutually exclusive claims about the same caller: declaring both is a
- * caller bug, not a broader capability.
- */
-export declare const BINDABLE_LAUNCH_CONTROLS: readonly ["systemPrompt", "opencode.agent-prompt"];
-export type BindableLaunchControl = (typeof BINDABLE_LAUNCH_CONTROLS)[number];
-/** The plan a caller writes into the run cwd, then applies to the spawn. */
-export interface WorkspacePlan {
-    harness: HarnessId;
-    /** Files to write relative to the run workspace (cwd). */
-    files: PlanFile[];
-    /** Env vars to set on the spawned process (for harnesses needing them). */
-    env: Record<string, WorkspacePlanConfigValue>;
-    /** Extra CLI flags to pass (e.g. kimi --mcp-config-file <path>). */
-    flags: WorkspacePlanArgument[];
-    /**
-     * Exact text that REPLACES the harness's own system prompt, for harnesses
-     * whose replacement control takes it as a launch argument the executor
-     * supplies (claude-code `--system-prompt`, pi `--system-prompt`).
-     *
-     * Absent does NOT mean "no replacement was requested": a harness whose
-     * control reads a file (codex, gemini) carries the replacement in
-     * {@link WorkspacePlan.files} plus a flag or env var instead. Present means
-     * the executor MUST bind it to that harness's replacement control — never to
-     * an additive one, which would leave the built-in prompt in force.
-     */
-    systemPrompt?: string;
-    /**
-     * Exact text ADDED to the harness's own system prompt, which stays intact.
-     *
-     * Separate from {@link WorkspacePlan.systemPrompt} because the two are
-     * different intents against the same channel, and every harness that has one
-     * control may lack the other. An executor binds this ONLY to an additive
-     * control (claude-code `--append-system-prompt`, pi
-     * `--append-system-prompt`); there is no harness for which folding it into
-     * the replacement is correct, because that would delete the built-in prompt
-     * the caller asked to keep.
-     */
-    appendSystemPrompt?: string;
-    /**
-     * A prompt intent no workspace file, flag, or env var can execute, addressed
-     * to the launcher control that can — see
-     * {@link WorkspacePlanSystemPromptBinding}.
-     *
-     * Present ONLY when the caller declared it owns the named control, so a plan
-     * built by a caller that forwards it to someone else's launcher never carries
-     * one; that caller gets the intent in {@link WorkspacePlan.unsupported}
-     * instead. Whoever reads it must bind it or throw — {@link
-     * takeSystemPromptBinding} does both.
-     */
-    systemPromptBinding?: WorkspacePlanSystemPromptBinding;
-    /** Dimensions requested but with NO cwd path on this harness — fail-closed record. */
-    unsupported: Unsupported[];
-    /**
-     * Prerequisites the workspace files CANNOT establish on their own.
-     *
-     * A plan is a set of files, an env map, and flags. Some harness capabilities need more than
-     * that to actually function: pi's MCP support is not built in, it arrives from an extension
-     * that must be installed into the harness's own package directory and permitted to load. No
-     * file written into a run workspace can make either true.
-     *
-     * Writing the config anyway and hoping is the failure this field exists to prevent: the
-     * harness starts, silently has no MCP, and the agent runs without the tools it was configured
-     * with while nothing reports a problem. So the plan states the requirement and the executor —
-     * which knows where its harness is installed and how it spawns — verifies or refuses it.
-     *
-     * Optional because this is an additive field on a published type: a plan built before it
-     * existed, or by a caller that does not construct one, is still a valid plan with no
-     * prerequisites. Every plan this package builds sets it.
-     */
-    requires?: PlanRequirement[];
-}
-/**
- * One prerequisite a {@link WorkspacePlan} depends on but cannot create.
- *
- * Declarative on purpose: this package builds plans and never probes a filesystem, spawns a
- * process, or reaches the network. The executor holds that context and does the checking.
- */
-export interface PlanRequirement {
-    /** The only kind so far: a harness extension/plugin that must be loaded for a dimension to work. */
-    kind: "harness-extension";
-    /** Dimension that produced the requirement, so a refusal can name what will not work. */
-    dimension: Unsupported["dimension"];
-    /** Package spec in the harness's own vocabulary, e.g. `npm:pi-mcp-adapter`. */
-    id: string;
-    /** Why the plan needs it — goes verbatim into the executor's refusal message. */
-    reason: string;
-    /** The exact command that satisfies it, so a failure is actionable without a doc lookup. */
-    remedy: string;
-}
-/**
- * Proof of the profile workspace inputs applied before a harness is spawned.
- * `workspacePlanDigest` covers only the {@link WorkspacePlan}; it is not an
- * execution-plan digest and does not attest unrelated files in `workspaceDir`.
- */
-export interface WorkspacePlanReceipt {
-    workspacePlanDigest: string;
-    /** Public launch identity only; secret values never enter this receipt. */
-    env: Record<string, WorkspacePlanConfigValue>;
-    /** Public launch identity only; templates retain opaque secret references. */
-    flags: WorkspacePlanArgument[];
-    systemPrompt?: string;
-    appendSystemPrompt?: string;
-    /** The launcher-bound intent, so a receipt says which control owed the work. */
-    systemPromptBinding?: WorkspacePlanSystemPromptBinding;
-    unsupported: Unsupported[];
-    written: string[];
-}
-/** Private values handed directly to the provider spawn, never to receipts. */
-export interface WorkspacePlanSpawnInputs {
-    env: Record<string, string>;
-    flags: string[];
-    systemPrompt?: string;
-    appendSystemPrompt?: string;
-    /** Read it with {@link takeSystemPromptBinding}, which refuses a foreign control. */
-    systemPromptBinding?: WorkspacePlanSystemPromptBinding;
-}
-/** Result of applying a public plan at the private executor boundary. */
-export interface WorkspacePlanApplication {
-    receipt: WorkspacePlanReceipt;
-    spawn: WorkspacePlanSpawnInputs;
-    /** Resolved generated files intentionally consumed in memory by the runtime. */
-    runtimeOnlyFiles: Record<string, string>;
-}
-/** The plan was applied, but one or more private staging files remain. */
-export declare class WorkspacePlanCleanupError extends AggregateError {
-    readonly receipt: WorkspacePlanReceipt;
-    readonly temporaryPaths: readonly string[];
-    constructor(errors: readonly unknown[], receipt: WorkspacePlanReceipt, temporaryPaths: readonly string[]);
-}
-export interface ApplyWorkspacePlanOptions {
-    /** Plan files consumed in memory by the runtime and never persisted to cwd. */
-    runtimeOnlyFiles?: readonly string[];
-    /** Existing workspace paths are either exact idempotent inputs or forbidden. */
-    existingFiles?: "allow-identical" | "reject";
-    /**
-     * `workspacePlanDigest` of a plan a prior call already applied into this
-     * workspace. When it equals this plan's digest, application writes no files:
-     * the workspace holds the running agent's live state, and a file the agent
-     * edited or removed since the prior application stays exactly as the agent
-     * left it. Env, flags, prompt intents, and the receipt are still produced.
-     * A different digest applies normally, so a plan that changed mid-session
-     * still meets the existing-file refusal.
-     */
-    appliedPlanDigest?: string;
-}
-/** 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.
- */
-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[];
-}
-/**
- * The replacement text this launcher must bind to `control`, or `undefined`
- * when the plan carries no launcher-bound intent.
- *
- * Throws for a binding addressed to a DIFFERENT control: the reader cannot
- * execute it, and answering `undefined` would start the agent with the
- * harness's own prompt still in force while nothing reported a problem — the
- * silent downgrade the binding exists to prevent. This is the seam where an
- * executor that cannot bind an intent says so, by name, instead of running a
- * profile whose prompt never took effect.
- */
-export declare function takeSystemPromptBinding(spawn: Pick<WorkspacePlanSpawnInputs, "systemPromptBinding">, control: ExecutorSystemPromptBinding): string | undefined;
-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[];
-}
-/**
- * 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`. `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;
-    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;
-/**
- * Build the WorkspacePlan for `profile` on `harness`. Pure — no IO. The caller
- * writes plan.files into the run cwd and applies plan.env/plan.flags to the spawn.
- * The explicit target harness takes precedence over the profile's default.
- */
-export declare function materializeProfile(inputProfile: AgentProfile, harness: HarnessId, opts?: {
-    skip?: SkippableDimension[];
-    /**
-     * Launcher controls THIS caller owns and will bind itself — see
-     * {@link BINDABLE_LAUNCH_CONTROLS}. Each names a control no workspace file,
-     * flag or env var reaches on its own, so declaring one turns a plan-time
-     * refusal into the lowering (or the hand-over) that control can execute.
-     *
-     * A promise, not a hint: declare a control only from the code that starts
-     * the harness and writes that control. A caller that hands the plan to
-     * someone else's launcher declares nothing and keeps the refusal, which is
-     * what it can actually deliver.
-     */
-    binds?: readonly BindableLaunchControl[];
-}): WorkspacePlan;
-/**
- * Materialize a sealed candidate profile without weakening its process values.
- * Codex and Claude hooks use generated no-shell wrappers to preserve executable,
- * argv, and environment values separately. Other hook formats fail closed.
- */
-export declare function materializeCandidateProfile(profile: AgentCandidateProfile, harness: HarnessId, opts?: MaterializeCandidateProfileOptions): AgentCandidateWorkspacePlan;
-/**
- * Hash the exact files, modes, flags, environment, and unsupported dimensions
- * represented by a plan. Array order is preserved only where it changes spawn
- * behavior; unordered maps and file records are canonicalized first.
- */
-export declare function hashWorkspacePlan(plan: WorkspacePlan): string;
-/** Build the exact digest-free identity document required by agent-interface. */
-export declare function agentCandidateProfilePlanMaterial(plan: AgentCandidateWorkspacePlan): AgentCandidateProfilePlanMaterial;
-/**
- * Return the RFC 8785 UTF-8 bytes and SHA-256 identity of a candidate profile
- * plan. The returned bytes are the exact bytes embedded in receipt evidence.
- */
-export declare function canonicalizeAgentCandidateProfilePlan(plan: AgentCandidateWorkspacePlan): {
-    material: AgentCandidateProfilePlanMaterial;
-    bytes: Uint8Array;
-    digest: Sha256Digest;
-};
-/** Capture portable evidence of the exact canonical profile-plan bytes. */
-export declare function captureAgentCandidateProfilePlan(plan: AgentCandidateWorkspacePlan): AgentCandidateProfilePlanEvidence;
-/**
- * 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;
-/**
- * Apply a public-only WorkspacePlan. A plan with any secret reference fails
- * before the first write; private executors use
- * {@link applyWorkspacePlanWithSecretProvider} instead.
- */
-export declare function applyWorkspacePlan(plan: WorkspacePlan, workspaceDir: string, options?: ApplyWorkspacePlanOptions): WorkspacePlanReceipt;
-/**
- * Resolve opaque profile references through an executor-owned provider, then
- * apply the resulting private native files and launch inputs. Resolution
- * completes before any workspace write, and resolved values never enter the
- * public plan, digest, receipt, logs, or error messages.
- */
-export declare function applyWorkspacePlanWithSecretProvider(plan: WorkspacePlan, workspaceDir: string, secretProvider: AgentProfileSecretProvider, options?: ApplyWorkspacePlanOptions): Promise<WorkspacePlanApplication>;
-/** 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";
-    url: string;
-    enabled: boolean;
-    headers?: Record<string, AgentProfileConfigValue>;
-} | {
-    type: "local";
-    command: Array<string | AgentProfileConfigValue>;
-    enabled: boolean;
-    environment?: Record<string, AgentProfileConfigValue>;
-}>;
-/** Lower canonical MCP definitions to OpenCode's native startup configuration. */
-export declare function openCodeMcpConfig(mcp: Record<string, AgentProfileMcpServer>): OpenCodeMcpConfig;
-export interface PrimeProfileSkill {
-    name: string;
-    content: string;
-}
-export interface PrimeProfileSubagent {
-    name: string;
-    description?: string;
-    prompt?: string;
-    metadata?: Record<string, unknown>;
-}
-/** Validated, materialization-ready view of the profile controls prime applies. */
-export interface PrimeProfileControls {
-    systemPrompt?: string;
-    appendSystemPrompt?: string;
-    /** Composed caller instructions, lowered to the agent dir's AGENTS.md. */
-    instructions?: string;
-    skills: PrimeProfileSkill[];
-    subagents: PrimeProfileSubagent[];
-}
-/** True when the controls materialize anything at all. */
-export declare function hasPrimeProfileMaterial(controls: PrimeProfileControls): boolean;
-/**
- * True when the controls must WRITE INTO the agent dir itself.
- *
- * Prompt files and skill dirs are named by a flag, so they can live anywhere
- * the agent can read (`--system-prompt` / `--append-system-prompt` resolve a
- * path when it exists, fork resource-loader.ts:41-56; `--skill` takes an
- * arbitrary dir, :437-442). The context file and the continual-harness store
- * are located BY the agent dir and have no flag, so they cannot move.
- *
- * An executor pointed at an agent dir it does not own (an operator's shared
- * dir) uses this to refuse exactly the controls it would have to write there,
- * while still binding the ones it can materialize elsewhere.
- */
-export declare function primeProfileNeedsAgentDir(controls: PrimeProfileControls): boolean;
-/**
- * Validate and extract the profile controls the prime agent-dir lowering
- * materializes. Throws {@link PrimeProfileError} on any control (or control
- * facet) the fork has no verified read path for — partial acceptance would
- * silently drop the rest.
- */
-export declare function readPrimeProfileControls(profile: AgentProfile | undefined): PrimeProfileControls;
-/**
- * Refuse a run whose selected model disagrees with the profile's own.
- *
- * One authority per run: a profile names the model it was written and scored
- * against, so running it on a different one silently scores a different agent.
- * Both sides go through {@link modelIdsMatch}, so the qualification level a
- * caller happened to use is not a conflict.
- *
- * `provider` is the executor's PROVIDER SELECTION, and is compared only when
- * the executor's provider is part of model identity. An executor whose
- * provider key is merely a namespace inside the agent dir passes it as
- * undefined and gets the model-name comparison alone.
- */
-export declare function assertPrimeModelAgreement(profile: AgentProfile | undefined, selected: {
-    provider?: string;
-    model: string;
-}): void;
-/** Deterministic harness-state entry id for a profile subagent name. */
-export declare function primeSubagentEntryId(name: string): string;
-/**
- * Write one agent-dir file atomically (temp + rename).
- *
- * Every file this lowering writes lands in a directory a LIVE agent may be
- * reading: prime reloads models.json at model-resolution time and re-reads the
- * harness store on every system-prompt build, so a partial write is observable.
- * `mode` is applied to the temp file before the rename, so the final file is
- * never briefly world-readable.
- */
-export declare function writePrimeAgentFile(path: string, data: string, mode?: number): void;
-export interface PrimeMaterializeOptions {
-    /**
-     * Where the FLAG-NAMED files go — the prompt files and the skills root.
-     * Defaults to `agentDir`. An executor that does not own the agent dir points
-     * this at a per-run directory of its own, so binding a profile's prompts and
-     * skills writes nothing into a dir it must not modify. The context file and
-     * the harness store have no flag and always land in `agentDir`; refuse those
-     * with {@link primeProfileNeedsAgentDir} instead.
-     */
-    flagFileRoot?: string;
-    /**
-     * Reports state the executor should see but that does not fail the run
-     * (currently: adopting entries a pre-shared executor left behind).
-     */
-    warn?: (msg: string, meta?: Record<string, unknown>) => void;
-}
-/**
- * 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
- * continual agent dir is re-pinned to the current profile on each fresh prime
- * process.
- */
-export declare function materializePrimeProfileControls(agentDir: string, controls: PrimeProfileControls, options?: PrimeMaterializeOptions): string[];
-/**
- * Remove the files a PREVIOUS materialization of this lowering wrote, so a
- * profile that shrank cannot leave a stale instruction file or skill behind for
- * the next run against the same dirs.
- *
- * Only the paths this lowering NAMES are removed. There is deliberately no
- * manifest: a manifest would live where the agent can write it, and reading a
- * delete list out of agent-writable state turns pruning into an arbitrary-path
- * delete.
- */
-export declare function prunePrimeProfileMaterial(agentDir: string, options?: Pick<PrimeMaterializeOptions, "flagFileRoot">): void;
-/**
- * Upsert profile subagent specs into the fork's global continual-harness
- * store and remove profile-sourced entries the current profile no longer
- * declares. Agent-written entries (`source: "agent"`) — and every top-level
- * key this lowering does not manage — are preserved untouched.
- *
- * A store that exists but no longer parses raises
- * {@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 { buildPiModelsConfig, buildPiModelsConfigFile, PI_MODELS_CONFIG_PATH, type PiModelsConfigFile, type PiModelsConfigInput, } 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 type { ApplyWorkspacePlanOptions, BindableLaunchControl, ExecutorSystemPromptBinding, PlanFile, PlanFileSecretSlot, PlanRequirement, SkippableDimension, Unsupported, WorkspacePlan, WorkspacePlanApplication, WorkspacePlanArgument, WorkspacePlanArgumentTemplate, WorkspacePlanConfigValue, WorkspacePlanReceipt, WorkspacePlanSecretSegment, WorkspacePlanSpawnInputs, WorkspacePlanSystemPromptBinding, } 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 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 { materializeProfile, UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER, } from "./profile-materializer.js";
+export type { ResolveAgentProfileResourcesOptions } from "./resource-resolution.js";
+export { normalizeSkillMd, resolveAgentProfileResources, } from "./resource-resolution.js";