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

package/dist/plan-types.js

@@ -0,0 +1,106 @@
+/**
+ * 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 const EXECUTOR_SYSTEM_PROMPT_BINDINGS = [
+    "opencode.agent-prompt",
+];
+const EXECUTOR_SYSTEM_PROMPT_BINDING_SET = new Set(EXECUTOR_SYSTEM_PROMPT_BINDINGS);
+export function isExecutorSystemPromptBinding(value) {
+    return EXECUTOR_SYSTEM_PROMPT_BINDING_SET.has(value);
+}
+/**
+ * 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 const SKIPPABLE_DIMENSIONS = [
+    "mcp",
+    "extensions",
+];
+const SKIPPABLE_DIMENSION_SET = new Set(SKIPPABLE_DIMENSIONS);
+export function isSkippableDimension(value) {
+    return SKIPPABLE_DIMENSION_SET.has(value);
+}
+/** Reject a dimension `materializeProfile` would not actually skip, rather than ignoring it. */
+export function assertSkippableDimensions(skip) {
+    if (!skip)
+        return [];
+    const unsupportedSkips = skip.filter((dimension) => !isSkippableDimension(dimension));
+    if (unsupportedSkips.length > 0) {
+        throw new Error(`materializeProfile: cannot skip ${unsupportedSkips.join(", ")}. ` +
+            `Skippable dimensions are: ${SKIPPABLE_DIMENSIONS.join(", ")}.`);
+    }
+    return skip;
+}
+/**
+ * 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 const BINDABLE_LAUNCH_CONTROLS = [
+    "systemPrompt",
+    ...EXECUTOR_SYSTEM_PROMPT_BINDINGS,
+];
+const BINDABLE_LAUNCH_CONTROL_SET = new Set(BINDABLE_LAUNCH_CONTROLS);
+/** Reject a binding declaration this materializer has no lowering for, rather than ignoring it. */
+export function assertBindableLaunchControls(binds) {
+    if (!binds)
+        return new Set();
+    const unknown = binds.filter((control) => !BINDABLE_LAUNCH_CONTROL_SET.has(control));
+    if (unknown.length > 0) {
+        throw new Error(`materializeProfile: cannot bind ${unknown.join(", ")}. ` +
+            `Bindable launch controls are: ${BINDABLE_LAUNCH_CONTROLS.join(", ")}.`);
+    }
+    const declared = new Set(binds);
+    const handedOver = [...EXECUTOR_SYSTEM_PROMPT_BINDINGS].filter((control) => declared.has(control));
+    if (declared.has("systemPrompt") && handedOver.length > 0) {
+        throw new Error(`materializeProfile: cannot bind systemPrompt together with ${handedOver.join(", ")}. ` +
+            "The first says the plan's launch flags reach the spawn; the second says " +
+            "the caller composes the harness config itself and reads neither.");
+    }
+    return declared;
+}
+/** The plan was applied, but one or more private staging files remain. */
+export class WorkspacePlanCleanupError extends AggregateError {
+    receipt;
+    temporaryPaths;
+    constructor(errors, receipt, temporaryPaths) {
+        super(errors, "Applied workspace plan but failed to remove temporary files");
+        this.name = "WorkspacePlanCleanupError";
+        this.receipt = receipt;
+        this.temporaryPaths = Object.freeze([...temporaryPaths]);
+    }
+}

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

@@ -0,0 +1,47 @@
+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;
+import type { PrimeProfileControls, PrimeProfileSubagent } from "./prime-profile.js";

package/dist/prime-agent-dir.js

@@ -0,0 +1,164 @@
+export function writePrimeAgentFile(path, data, mode = 0o600) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temp, data, { mode });
+    renameSync(temp, path);
+}
+/**
+ * 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 function materializePrimeProfileControls(agentDir, controls, options = {}) {
+    const { flagFileRoot = agentDir, warn } = options;
+    const args = [];
+    const profileDir = join(flagFileRoot, PRIME_PROFILE_DIR_NAME);
+    if (controls.systemPrompt !== undefined) {
+        const promptPath = join(profileDir, PRIME_SYSTEM_PROMPT_FILE);
+        writePrimeAgentFile(promptPath, controls.systemPrompt);
+        args.push("--system-prompt", promptPath);
+    }
+    if (controls.appendSystemPrompt !== undefined) {
+        const appendPath = join(profileDir, PRIME_APPEND_SYSTEM_PROMPT_FILE);
+        writePrimeAgentFile(appendPath, controls.appendSystemPrompt);
+        args.push("--append-system-prompt", appendPath);
+    }
+    if (controls.instructions !== undefined) {
+        writePrimeAgentFile(join(agentDir, PRIME_CONTEXT_FILE), `${controls.instructions}\n`);
+    }
+    if (controls.skills.length > 0) {
+        const skillsRoot = join(profileDir, PRIME_SKILLS_DIR_NAME);
+        for (const skill of controls.skills) {
+            writePrimeAgentFile(join(skillsRoot, skill.name, "SKILL.md"), normalizeSkillMd(skill.name, skill.content));
+        }
+        args.push("--skill", skillsRoot);
+    }
+    seedPrimeProfileSubagents(agentDir, controls.subagents, warn);
+    return args;
+}
+/**
+ * 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 function prunePrimeProfileMaterial(agentDir, options = {}) {
+    const { flagFileRoot = agentDir } = options;
+    rmSync(join(flagFileRoot, PRIME_PROFILE_DIR_NAME), {
+        recursive: true,
+        force: true,
+    });
+    rmSync(join(agentDir, PRIME_CONTEXT_FILE), { force: true });
+}
+/**
+ * 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 function seedPrimeProfileSubagents(agentDir, subagents, warn) {
+    const statePath = join(agentDir, PRIME_HARNESS_DIR_NAME, PRIME_HARNESS_STATE_FILE);
+    let state = {};
+    if (existsSync(statePath)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(statePath, "utf8"));
+        }
+        catch (err) {
+            throw new PrimeHarnessStateError(statePath, err instanceof Error ? err.message : String(err));
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new PrimeHarnessStateError(statePath, "the store is not a JSON object");
+        }
+        state = parsed;
+    }
+    else if (subagents.length === 0) {
+        // Nothing to pin and nothing stale to remove.
+        return;
+    }
+    const rawEntries = state.entries;
+    const entries = rawEntries && typeof rawEntries === "object" && !Array.isArray(rawEntries)
+        ? rawEntries
+        : {};
+    for (const kind of PRIME_HARNESS_KINDS) {
+        const records = entries[kind];
+        if (!records || typeof records !== "object" || Array.isArray(records)) {
+            entries[kind] = {};
+        }
+    }
+    const existing = entries.subagent;
+    const desiredIds = new Set(subagents.map((s) => primeSubagentEntryId(s.name)));
+    let changed = false;
+    for (const [id, entry] of Object.entries(existing)) {
+        const source = entry?.source;
+        const isLegacy = typeof source === "string" &&
+            PRIME_LEGACY_PROFILE_ENTRY_SOURCES.includes(source);
+        if (isLegacy) {
+            warn?.("prime: adopting a subagent entry left by a pre-shared executor", {
+                statePath,
+                id,
+                source,
+            });
+        }
+        if ((source === PRIME_PROFILE_ENTRY_SOURCE || isLegacy) &&
+            !desiredIds.has(id)) {
+            delete existing[id];
+            changed = true;
+        }
+    }
+    const now = new Date().toISOString();
+    for (const spec of subagents) {
+        const id = primeSubagentEntryId(spec.name);
+        const content = [spec.description?.trim(), spec.prompt?.trim()]
+            .filter((part) => !!part)
+            .join("\n\n");
+        const previous = existing[id];
+        if (previous &&
+            previous.source === PRIME_PROFILE_ENTRY_SOURCE &&
+            previous.title === spec.name &&
+            previous.content === content) {
+            continue;
+        }
+        existing[id] = {
+            id,
+            kind: "subagent",
+            title: spec.name,
+            content,
+            path: PRIME_PROFILE_ENTRY_SOURCE,
+            scope: "global",
+            reference: {},
+            arguments: {},
+            metadata: spec.metadata ?? {},
+            source: PRIME_PROFILE_ENTRY_SOURCE,
+            created_at: previous?.created_at ?? now,
+            updated_at: now,
+            version: previous && typeof previous.version === "number"
+                ? previous.version + 1
+                : 1,
+        };
+        changed = true;
+    }
+    if (!changed)
+        return;
+    writePrimeAgentFile(statePath, `${JSON.stringify({
+        ...state,
+        schema: typeof state.schema === "number" ? state.schema : 1,
+        entries,
+        refinements: Array.isArray(state.refinements) ? state.refinements : [],
+    }, null, 2)}\n`);
+}
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { PrimeHarnessStateError } from "./prime-fork.js";
+import { PRIME_APPEND_SYSTEM_PROMPT_FILE, PRIME_CONTEXT_FILE, PRIME_HARNESS_DIR_NAME, PRIME_HARNESS_KINDS, PRIME_HARNESS_STATE_FILE, PRIME_LEGACY_PROFILE_ENTRY_SOURCES, PRIME_PROFILE_DIR_NAME, PRIME_PROFILE_ENTRY_SOURCE, PRIME_SKILLS_DIR_NAME, PRIME_SYSTEM_PROMPT_FILE, primeSubagentEntryId, } from "./prime-profile.js";
+import { normalizeSkillMd } from "./resource-resolution.js";

package/dist/prime-profile.d.ts

@@ -0,0 +1,88 @@
+export declare const PRIME_PROFILE_DIR_NAME = "profile";
+export declare const PRIME_SKILLS_DIR_NAME = "skills";
+export declare const PRIME_SYSTEM_PROMPT_FILE = "system-prompt.md";
+export declare const PRIME_APPEND_SYSTEM_PROMPT_FILE = "append-system-prompt.md";
+/** Agent-dir global context file the fork reads (resource-loader.ts:59,86). */
+export declare const PRIME_CONTEXT_FILE = "AGENTS.md";
+/** Fork continual-harness store location under the agent dir (refinement.ts:269-279). */
+export declare const PRIME_HARNESS_DIR_NAME = "harness";
+export declare const PRIME_HARNESS_STATE_FILE = "harness_state.json";
+export declare const PRIME_HARNESS_KINDS: readonly ["prompt", "memory", "skill", "subagent"];
+/**
+ * Provenance marker for entries pinned from the profile. Stale removal keys on
+ * it, so agent-written (`source: "agent"`) and user-written entries are never
+ * touched.
+ */
+export declare const PRIME_PROFILE_ENTRY_SOURCE = "profile";
+/**
+ * Provenance markers written by executors that predate this shared lowering.
+ *
+ * Pruning keys on the source tag, so an executor that switches to the shared
+ * implementation would otherwise leave its own earlier entries behind forever:
+ * they match no current profile and no current source, and the model's
+ * spawnable roster silently accumulates duplicates of every subagent. They are
+ * adopted (pruned or replaced) on the first shared run instead.
+ */
+export declare const PRIME_LEGACY_PROFILE_ENTRY_SOURCES: readonly string[];
+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;
+import type { AgentProfile } from "@tangle-network/agent-interface";