@tangle-network/agent-profile-materialize 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -22,6 +22,7 @@
  * cli-bridge and agent-dev-container — this is the single source those re-export.
  */
 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;
 /**
@@ -57,6 +58,25 @@ export interface PlanFile {
      * 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
@@ -83,9 +103,47 @@ 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" | "connections" | "confidential" | "permissions" | "tools" | "modes" | "extensions";
+    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.
  *
@@ -104,13 +162,23 @@ export declare function isSkippableDimension(value: string): value is SkippableD
  * 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). An
- * executor that really applies the plan's launch flags to the spawn it owns
- * (selecting the generated primary agent via the plan's `--agent` flag) states
- * so with `binds: ["systemPrompt"]`, which turns that refusal into the
- * primary-agent lowering the executor must then apply.
+ * @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"];
+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 {
@@ -121,18 +189,42 @@ export interface WorkspacePlan {
     env: Record<string, WorkspacePlanConfigValue>;
     /** Extra CLI flags to pass (e.g. kimi --mcp-config-file <path>). */
     flags: WorkspacePlanArgument[];
-    /** Exact system-prompt replacement supplied to the harness. */
+    /**
+     * 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;
     /**
-     * Additive system-prompt text: the harness's own prompt stays in force and
-     * this text is added after it. The OPPOSITE intent of {@link systemPrompt} on
-     * the same channel — an executor must never bind one to the other's control
-     * (an addition on the replacement flag deletes the prompt the caller asked to
-     * keep; a replacement on the additive flag leaves the harness's prompt
-     * running). Set only for harnesses whose own control executes the addition
-     * (harnessSystemPromptIntents in @tangle-network/agent-interface).
+     * 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[];
     /**
@@ -185,6 +277,8 @@ export interface WorkspacePlanReceipt {
     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[];
 }
@@ -194,6 +288,8 @@ export interface WorkspacePlanSpawnInputs {
     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 {
@@ -248,6 +344,18 @@ export interface AgentCandidateWorkspacePlanReceipt {
     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>;
@@ -308,7 +416,17 @@ export declare function normalizeSkillMd(name: string, raw: string): string;
  */
 export declare function materializeProfile(inputProfile: AgentProfile, harness: HarnessId, opts?: {
     skip?: SkippableDimension[];
-    /** Launcher controls the calling executor owns — see {@link BINDABLE_LAUNCH_CONTROLS}. */
+    /**
+     * 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;
 /**
@@ -386,31 +504,105 @@ export interface PrimeProfileSubagent {
 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 on any control (or control facet) the fork has no
- * verified read path for — partial acceptance would silently drop the rest.
+ * 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;
 /**
- * Materialize the validated controls into `agentDir` 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.
+ * 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 materializePrimeProfileControls(agentDir: string, controls: PrimeProfileControls, warn: (msg: string, meta?: Record<string, unknown>) => void): string[];
+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"`) are never touched.
+ * declares. Agent-written entries (`source: "agent"`) — and every top-level
+ * key this lowering does not manage — are preserved untouched.
  *
- * A pre-existing unparsable store degrades to empty exactly like the fork's
- * own loader (refinement.ts:290-300 — "a corrupt state file must degrade to
- * empty rather than throw"), with a warning so the reset is visible.
+ * 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 declare function seedPrimeProfileSubagents(agentDir: string, subagents: PrimeProfileSubagent[], warn?: (msg: string, meta?: Record<string, unknown>) => void): void;