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

package/dist/plan-json.js

@@ -0,0 +1,91 @@
+export const tomlStr = (s) => JSON.stringify(s); // valid TOML basic string
+export function isProfilePublicConfigValue(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value.kind === "public" &&
+        typeof value.value === "string");
+}
+export function isProfileSecretRef(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value.kind === "secret-ref" &&
+        typeof value.key === "string");
+}
+export function workspacePlanConfigValue(value) {
+    return isProfilePublicConfigValue(value) ? value.value : { ...value };
+}
+export function serializeWorkspacePlanJson(value) {
+    const secretSlots = [];
+    const lower = (current, path, arrayEntry = false) => {
+        if (isProfilePublicConfigValue(current))
+            return current.value;
+        if (isProfileSecretRef(current)) {
+            secretSlots.push({ path: [...path], ref: { ...current } });
+            return null;
+        }
+        if (Array.isArray(current)) {
+            return current.map((entry, index) => lower(entry, [...path, index], true));
+        }
+        if (current && typeof current === "object") {
+            const output = Object.create(null);
+            for (const [key, entry] of Object.entries(current)) {
+                const lowered = lower(entry, [...path, key]);
+                if (lowered !== undefined) {
+                    Object.defineProperty(output, key, {
+                        value: lowered,
+                        enumerable: true,
+                        configurable: true,
+                        writable: true,
+                    });
+                }
+            }
+            return output;
+        }
+        return current === undefined && arrayEntry ? null : current;
+    };
+    const content = JSON.stringify(lower(value, []), null, 2);
+    if (content === undefined) {
+        throw new Error("Generated profile JSON must have a serializable root");
+    }
+    return {
+        content,
+        ...(secretSlots.length === 0 ? {} : { secretSlots }),
+    };
+}
+export function workspacePlanArgumentSegments(value) {
+    return typeof value === "string" ? [value] : [...value.segments];
+}
+export function concatWorkspacePlanArguments(...values) {
+    const segments = values.flatMap(workspacePlanArgumentSegments);
+    if (segments.every((segment) => typeof segment === "string")) {
+        return segments.join("");
+    }
+    return { kind: "workspace-plan-argument-template", segments };
+}
+export function joinWorkspacePlanArguments(values, separator) {
+    if (values.length === 0)
+        return "";
+    const joined = [];
+    for (const [index, value] of values.entries()) {
+        if (index > 0)
+            joined.push(separator);
+        joined.push(value);
+    }
+    return concatWorkspacePlanArguments(...joined);
+}
+export function tomlProfileConfigValue(value) {
+    if (isProfilePublicConfigValue(value))
+        return tomlStr(value.value);
+    return {
+        kind: "workspace-plan-argument-template",
+        segments: [
+            {
+                kind: "secret",
+                ref: { ...value },
+                encoding: "json-string",
+            },
+        ],
+    };
+}

package/dist/plan-normalize.d.ts

@@ -0,0 +1,13 @@
+export declare function mergeJsonFiles(files: PlanFile[]): PlanFile[];
+export interface NormalizedPlanFile {
+    relPath: string;
+    content: string;
+    mode: number;
+    ownership: NonNullable<PlanFile["ownership"]>;
+    secretSlots: PlanFileSecretSlot[];
+}
+export declare function valueAtJsonPath(root: unknown, path: readonly (string | number)[]): unknown;
+export declare function normalizePlanFileSecretSlots(file: PlanFile): PlanFileSecretSlot[];
+export declare function normalizePlanFiles(files: PlanFile[]): NormalizedPlanFile[];
+export declare function normalizeWorkspacePlanArgument(value: WorkspacePlanArgument): WorkspacePlanArgument;
+import type { PlanFile, PlanFileSecretSlot, WorkspacePlanArgument } from "./plan-types.js";

package/dist/plan-normalize.js

@@ -0,0 +1,156 @@
+export function mergeJsonFiles(files) {
+    const byPath = new Map();
+    for (const f of files) {
+        const prev = byPath.get(f.relPath);
+        if (!prev) {
+            byPath.set(f.relPath, f);
+            continue;
+        }
+        if (f.relPath.endsWith(".json")) {
+            try {
+                const next = JSON.parse(f.content);
+                const merged = {
+                    ...JSON.parse(prev.content),
+                    ...next,
+                };
+                const replacedRoots = new Set(Object.keys(next));
+                const secretSlots = [
+                    ...(prev.secretSlots ?? []).filter((slot) => typeof slot.path[0] === "string" &&
+                        !replacedRoots.has(slot.path[0])),
+                    ...(f.secretSlots ?? []),
+                ];
+                const { secretSlots: _previousSecretSlots, ...previousFile } = prev;
+                byPath.set(f.relPath, {
+                    ...previousFile,
+                    content: JSON.stringify(merged, null, 2),
+                    ...(secretSlots.length > 0 ? { mode: PRIVATE_FILE_MODE } : {}),
+                    ...(secretSlots.length === 0 ? {} : { secretSlots }),
+                });
+                continue;
+            }
+            catch {
+                /* fall through to last-wins */
+            }
+        }
+        byPath.set(f.relPath, f); // non-JSON or parse-fail: last wins
+    }
+    return [...byPath.values()];
+}
+export function valueAtJsonPath(root, path) {
+    let current = root;
+    for (const segment of path) {
+        if (current === null ||
+            typeof current !== "object" ||
+            !Object.hasOwn(current, segment)) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+export function normalizePlanFileSecretSlots(file) {
+    if (file.secretSlots === undefined)
+        return [];
+    if (file.source !== "generated" ||
+        !file.relPath.endsWith(".json") ||
+        file.secretSlots.length === 0) {
+        throw new Error(`Workspace secret slots require a generated JSON file: ${file.relPath}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(file.content);
+    }
+    catch {
+        throw new Error(`Workspace secret slots require valid JSON content: ${file.relPath}`);
+    }
+    const seen = new Set();
+    return file.secretSlots.map((slot) => {
+        if (!Array.isArray(slot.path) || slot.path.length === 0) {
+            throw new Error(`Workspace secret slot path must be non-empty: ${file.relPath}`);
+        }
+        const path = slot.path.map((segment) => {
+            if ((typeof segment !== "string" && typeof segment !== "number") ||
+                (typeof segment === "number" &&
+                    (!Number.isSafeInteger(segment) || segment < 0))) {
+                throw new Error(`Workspace secret slot path is invalid: ${file.relPath}`);
+            }
+            return segment;
+        });
+        const identity = JSON.stringify(path);
+        if (seen.has(identity)) {
+            throw new Error(`Duplicate workspace secret slot path: ${file.relPath} ${identity}`);
+        }
+        seen.add(identity);
+        if (valueAtJsonPath(parsed, path) !== null) {
+            throw new Error(`Workspace secret slot must point at a null placeholder: ${file.relPath} ${identity}`);
+        }
+        return {
+            path,
+            ref: agentProfileSecretRefSchema.parse(slot.ref),
+        };
+    });
+}
+export function normalizePlanFiles(files) {
+    const seen = new Set();
+    return files
+        .map((file) => {
+        const relPath = normalizeWorkspaceRelativePath(file.relPath);
+        if (seen.has(relPath)) {
+            throw new Error(`Duplicate workspace plan file: ${relPath}`);
+        }
+        seen.add(relPath);
+        if (typeof file.content !== "string") {
+            throw new Error(`Workspace file content must be a string: ${relPath}`);
+        }
+        const mode = validateFileMode(file.mode);
+        const secretSlots = normalizePlanFileSecretSlots(file);
+        if (secretSlots.length > 0 && (mode & 0o077) !== 0) {
+            throw new Error(`Workspace secret-bearing file must not grant group or other access: ${relPath}`);
+        }
+        return {
+            relPath,
+            content: file.content,
+            mode,
+            ownership: file.ownership ?? "shared",
+            secretSlots,
+        };
+    })
+        .sort((a, b) => compareStrings(a.relPath, b.relPath));
+}
+export function normalizeWorkspacePlanArgument(value) {
+    if (typeof value === "string")
+        return value;
+    if (value.kind !== "workspace-plan-argument-template" ||
+        !Array.isArray(value.segments) ||
+        value.segments.length === 0) {
+        throw new Error("Workspace plan argument template is malformed");
+    }
+    const segments = [];
+    for (const segment of value.segments) {
+        if (typeof segment === "string") {
+            const previous = segments.at(-1);
+            if (typeof previous === "string") {
+                segments[segments.length - 1] = previous + segment;
+            }
+            else if (segment.length > 0) {
+                segments.push(segment);
+            }
+            continue;
+        }
+        if (segment.kind !== "secret" ||
+            (segment.encoding !== "raw" && segment.encoding !== "json-string")) {
+            throw new Error("Workspace plan secret argument segment is malformed");
+        }
+        segments.push({
+            kind: "secret",
+            ref: agentProfileSecretRefSchema.parse(segment.ref),
+            encoding: segment.encoding,
+        });
+    }
+    if (segments.every((segment) => typeof segment === "string")) {
+        return segments.join("");
+    }
+    return { kind: "workspace-plan-argument-template", segments };
+}
+import { agentProfileSecretRefSchema } from "@tangle-network/agent-interface";
+import { compareStrings, normalizeWorkspaceRelativePath, PRIVATE_FILE_MODE, validateFileMode, } from "./workspace-files.js";

package/dist/plan-prompt.d.ts

@@ -0,0 +1,38 @@
+export declare function promptIntentFields<In, Out>(source: {
+    systemPrompt?: In;
+    appendSystemPrompt?: In;
+}, project: (value: In) => Out): {
+    systemPrompt?: Out;
+    appendSystemPrompt?: Out;
+};
+/** Identity projection for boundaries that pass the prompt intents through. */
+export declare const samePromptIntentValue: <T>(value: T) => T;
+/**
+ * The launcher-bound intent, projected onto an outgoing object and omitted when
+ * the source does not carry one.
+ *
+ * Beside {@link promptIntentFields} rather than inside it, because the two
+ * disagree on both ends: the candidate boundaries that helper also serves have
+ * no field for a binding — an {@link AgentCandidateWorkspacePlan} is built by a
+ * caller that declares none, so it can never hold one — and a value projection
+ * such as `candidatePublicString` has nothing to do to a structured binding.
+ * Every boundary that carries the plan's own prompt intents calls both.
+ */
+export declare function systemPromptBindingField(source: {
+    systemPromptBinding?: WorkspacePlanSystemPromptBinding;
+}): {
+    systemPromptBinding?: WorkspacePlanSystemPromptBinding;
+};
+/**
+ * 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;
+import type { ExecutorSystemPromptBinding, WorkspacePlanSpawnInputs, WorkspacePlanSystemPromptBinding } from "./plan-types.js";

package/dist/plan-prompt.js

@@ -0,0 +1,49 @@
+export function promptIntentFields(source, project) {
+    return {
+        ...(source.systemPrompt === undefined
+            ? {}
+            : { systemPrompt: project(source.systemPrompt) }),
+        ...(source.appendSystemPrompt === undefined
+            ? {}
+            : { appendSystemPrompt: project(source.appendSystemPrompt) }),
+    };
+}
+/** Identity projection for boundaries that pass the prompt intents through. */
+export const samePromptIntentValue = (value) => value;
+/**
+ * The launcher-bound intent, projected onto an outgoing object and omitted when
+ * the source does not carry one.
+ *
+ * Beside {@link promptIntentFields} rather than inside it, because the two
+ * disagree on both ends: the candidate boundaries that helper also serves have
+ * no field for a binding — an {@link AgentCandidateWorkspacePlan} is built by a
+ * caller that declares none, so it can never hold one — and a value projection
+ * such as `candidatePublicString` has nothing to do to a structured binding.
+ * Every boundary that carries the plan's own prompt intents calls both.
+ */
+export function systemPromptBindingField(source) {
+    return source.systemPromptBinding === undefined
+        ? {}
+        : { systemPromptBinding: { ...source.systemPromptBinding } };
+}
+/**
+ * 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 function takeSystemPromptBinding(spawn, control) {
+    const binding = spawn.systemPromptBinding;
+    if (!binding)
+        return undefined;
+    if (binding.control !== control) {
+        throw new Error(`Workspace plan carries a system-prompt ${binding.intent} bound to ` +
+            `${binding.control}, which this executor cannot apply; it binds ${control}`);
+    }
+    return binding.systemPrompt;
+}

package/dist/plan-support.d.ts

@@ -0,0 +1,9 @@
+import type { Unsupported, WorkspacePlan } from "./plan-types.js";
+export declare function formatUnsupported(unsupported: Unsupported[]): string;
+/** Fail when a profile asks for controls the chosen harness cannot execute. */
+export declare function assertWorkspacePlanSupported(plan: Pick<WorkspacePlan, "unsupported">): void;
+/**
+ * Enforce supportability under the profile's failOnError policy.
+ * Strict mode throws; best-effort mode returns visible warnings.
+ */
+export declare function enforceWorkspacePlanSupport(plan: Pick<WorkspacePlan, "unsupported">, failOnError: boolean | undefined): string[];

package/dist/plan-support.js

@@ -0,0 +1,22 @@
+export function formatUnsupported(unsupported) {
+    return `Unable to materialize ${unsupported.length} profile resource(s):\n${unsupported
+        .map(({ dimension, reason }) => `- ${dimension}: ${reason}`)
+        .join("\n")}`;
+}
+/** Fail when a profile asks for controls the chosen harness cannot execute. */
+export function assertWorkspacePlanSupported(plan) {
+    if (plan.unsupported.length > 0) {
+        throw new Error(formatUnsupported(plan.unsupported));
+    }
+}
+/**
+ * Enforce supportability under the profile's failOnError policy.
+ * Strict mode throws; best-effort mode returns visible warnings.
+ */
+export function enforceWorkspacePlanSupport(plan, failOnError) {
+    if (failOnError !== false) {
+        assertWorkspacePlanSupported(plan);
+        return [];
+    }
+    return plan.unsupported.map(({ dimension, reason }) => `${dimension}: ${reason}`);
+}

package/dist/plan-types.d.ts

@@ -0,0 +1,294 @@
+export type { HarnessId } from "./harness.js";
+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;
+/** Reject a dimension `materializeProfile` would not actually skip, rather than ignoring it. */
+export declare function assertSkippableDimensions(skip: readonly string[] | undefined): readonly 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];
+/** Reject a binding declaration this materializer has no lowering for, rather than ignoring it. */
+export declare function assertBindableLaunchControls(binds: readonly string[] | undefined): ReadonlySet<BindableLaunchControl>;
+/** 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;
+}
+import type { AgentProfileSecretRef } from "@tangle-network/agent-interface";
+import type { HarnessId } from "./harness.js";