@tangle-network/agent-profile-materialize 0.10.3 → 0.12.0

package/dist/index.d.ts

@@ -21,6 +21,7 @@
  * `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.
  */
+export { modelIdsMatch, qualifyModelId } from "./model-id.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;
 /**
@@ -28,7 +29,7 @@ export declare const UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER: AgentProfileSecr
  * 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", "gemini", "hermes", "openclaw"];
+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 {
@@ -56,6 +57,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
@@ -82,9 +102,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.
  *
@@ -95,6 +153,32 @@ export interface Unsupported {
 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;
@@ -104,8 +188,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;
+    /**
+     * 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[];
     /**
@@ -157,6 +275,9 @@ export interface WorkspacePlanReceipt {
     /** 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[];
 }
@@ -165,6 +286,9 @@ 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 {
@@ -207,6 +331,7 @@ export interface AgentCandidateWorkspacePlan {
     env: Record<string, AgentCandidateConfigValue>;
     flags: AgentCandidateConfigValue[];
     systemPrompt?: AgentCandidateConfigValue;
+    appendSystemPrompt?: AgentCandidateConfigValue;
     unsupported: Unsupported[];
 }
 export interface AgentCandidateWorkspacePlanReceipt {
@@ -215,8 +340,21 @@ export interface AgentCandidateWorkspacePlanReceipt {
     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>;
@@ -277,6 +415,18 @@ export declare function normalizeSkillMd(name: string, raw: string): string;
  */
 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.
@@ -339,3 +489,45 @@ export type OpenCodeMcpConfig = Record<string, {
 }>;
 /** 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;
+    skills: PrimeProfileSkill[];
+    subagents: PrimeProfileSubagent[];
+}
+/**
+ * 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.
+ */
+export declare function readPrimeProfileControls(profile: AgentProfile | undefined): PrimeProfileControls;
+/** 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.
+ */
+export declare function materializePrimeProfileControls(agentDir: string, controls: PrimeProfileControls, warn: (msg: string, meta?: Record<string, unknown>) => void): string[];
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function seedPrimeProfileSubagents(agentDir: string, subagents: PrimeProfileSubagent[], warn: (msg: string, meta?: Record<string, unknown>) => void): void;