@ai-agent-forge/agent-forge 0.85.0

package/dist/profiles/suite-loader.js

@@ -0,0 +1,823 @@
+/**
+ * Suite workspace location, lazy provisioning, and assembly (方案系统设计.md v2
+ * §4/§5/§8/§9/§11/§12, M1a).
+ *
+ * The loader is the assembler layer of the suite system: it resolves the
+ * active suite id (explicit > AGENT_FORGE_SUITE > project settings > global
+ * settings > "assistant"), provisions the builtin suite workspaces under
+ * `<agentDir>/suites/<id>/`, assembles the agents.md three-level chain
+ * (system -> suite -> project, 设计 §8), gates the global SYSTEM.md/
+ * APPEND_SYSTEM.md system prompt channel by inheritSystemAgentsMd (设计 §4:
+ * the project-level `<cwd>/.agent-forge/` layer always passes), and bridges
+ * the assembled suite onto the existing ProfileIdentityV1/ProfileLock
+ * mechanisms. The project level of the chain is delegated to the existing
+ * resource loader — the ancestor chain logic itself is never reimplemented
+ * here.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { CONFIG_DIR_NAME } from "../config.js";
+import { loadSkills } from "../core/skills.js";
+import { buildProfileIdentityV1, stableJsonDigest } from "../profile/identity.js";
+import { createProfileLock, verifyProfileLock } from "../profile/lock.js";
+import { resolveBuiltinPluginProfileV1 } from "../profile/plugin-profiles.js";
+import { createProfileRegistry } from "../profile/profile-registry.js";
+import { stripBom } from "../utils/text.js";
+import { BUILTIN_SUITES, DEFAULT_SUITE_ID, FACTORY_CONTENTS_VERSION, getBuiltinSuite, isBuiltinSuiteId, isValidSuiteId, ORIENTATION_PROMPTS, parseSuiteJson, SUITE_SCHEMA_VERSION, serializeSuiteJson, } from "./builtin-suites.js";
+export { DEFAULT_SUITE_ID };
+export const SUITES_DIR_NAME = "suites";
+export const SUITE_MANIFEST_FILENAME = "suite.json";
+export const SUITE_AGENTS_MD_FILENAME = "agents.md";
+export const SUITE_ENV_VAR = "AGENT_FORGE_SUITE";
+/** customType of the session custom entry recording the suite a session was created with (设计 §10.1). */
+export const SUITE_SESSION_ENTRY_TYPE = "suite";
+/** Persisted suite profile lock inside the suite workspace (M4, 设计 §12). */
+export const SUITE_LOCK_FILENAME = ".profile-lock.json";
+export function getSuitesRootDir(agentDir) {
+    return join(agentDir, SUITES_DIR_NAME);
+}
+export function getSuiteWorkspaceDir(agentDir, suiteId) {
+    return join(getSuitesRootDir(agentDir), suiteId);
+}
+/** The suite-local skill layer directory (统一修复轮 B): `<suiteDir>/skills`. */
+export function getSuiteLocalSkillsDir(agentDir, suiteId) {
+    return join(getSuiteWorkspaceDir(agentDir, suiteId), "skills");
+}
+/** The suite-local capability-plugin layer directory (统一修复轮 B): `<suiteDir>/plugins`. */
+export function getSuiteLocalPluginsDir(agentDir, suiteId) {
+    return join(getSuiteWorkspaceDir(agentDir, suiteId), "plugins");
+}
+/** Structured error for unknown suite ids; lists the available ids (设计 §9). */
+export class SuiteResolutionError extends Error {
+    requestedId;
+    availableSuiteIds;
+    constructor(requestedId, availableSuiteIds) {
+        super(`Unknown suite "${requestedId}". Available suites: ${availableSuiteIds.join(", ")}`);
+        this.name = "SuiteResolutionError";
+        this.requestedId = requestedId;
+        this.availableSuiteIds = Object.freeze([...availableSuiteIds]);
+    }
+}
+/** Structured error for resuming a session under a suite it is not bound to. */
+export class SuiteRebindError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SuiteRebindError";
+    }
+}
+/**
+ * Every suite id resolvable on this host: the builtin pair plus user
+ * workspaces that already contain a suite.json.
+ */
+export function listSuiteIds(agentDir) {
+    const ids = new Set(BUILTIN_SUITES.map((suite) => suite.id));
+    const rootDir = getSuitesRootDir(agentDir);
+    if (existsSync(rootDir)) {
+        for (const entry of readdirSync(rootDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            if (!existsSync(join(rootDir, entry.name, SUITE_MANIFEST_FILENAME)))
+                continue;
+            ids.add(entry.name);
+        }
+    }
+    return [...ids].sort();
+}
+function normalizeCandidate(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * Resolves the active suite id: explicit > env AGENT_FORGE_SUITE > project
+ * settings `suite` > global settings `suite` > "assistant" (设计 §9). The
+ * first configured value wins; an unknown or malformed value is a structured
+ * error, never a silent fallback.
+ */
+export function resolveSuiteId(options) {
+    const candidate = normalizeCandidate(options.explicit) ??
+        normalizeCandidate(options.envSuite) ??
+        (options.settings === undefined ? undefined : normalizeCandidate(options.settings.getProjectSettings().suite)) ??
+        (options.settings === undefined ? undefined : normalizeCandidate(options.settings.getGlobalSettings().suite));
+    if (candidate === undefined)
+        return DEFAULT_SUITE_ID;
+    if (!isValidSuiteId(candidate))
+        throw new SuiteResolutionError(candidate, listSuiteIds(options.agentDir));
+    if (!isBuiltinSuiteId(candidate)) {
+        const workspaceManifest = join(getSuiteWorkspaceDir(options.agentDir, candidate), SUITE_MANIFEST_FILENAME);
+        if (!existsSync(workspaceManifest))
+            throw new SuiteResolutionError(candidate, listSuiteIds(options.agentDir));
+    }
+    return candidate;
+}
+/**
+ * Serializes a ProfileLockV1 to the canonical `.profile-lock.json` text
+ * (stable field order, trailing newline). Round-trips through
+ * parseSuiteProfileLockFile.
+ */
+export function serializeSuiteProfileLockFile(lock) {
+    const ordered = {
+        identity: {
+            profileId: lock.identity.profileId,
+            profileVersion: lock.identity.profileVersion,
+            manifestDigest: lock.identity.manifestDigest,
+            capabilityVersions: lock.identity.capabilityVersions.map((ref) => ({ id: ref.id, version: ref.version })),
+        },
+        lockedAt: lock.lockedAt,
+        lockedBy: lock.lockedBy,
+        generation: lock.generation,
+    };
+    return `${JSON.stringify(ordered, null, 2)}\n`;
+}
+/**
+ * Parses `.profile-lock.json` text back into a ProfileLockV1. Throws on any
+ * structural mismatch so callers can apply their corruption policy.
+ */
+export function parseSuiteProfileLockFile(text) {
+    const value = JSON.parse(text);
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(".profile-lock.json must be a JSON object");
+    }
+    const record = value;
+    const identityRecord = record.identity;
+    if (identityRecord === null || typeof identityRecord !== "object" || Array.isArray(identityRecord)) {
+        throw new Error(".profile-lock.json identity must be a JSON object");
+    }
+    const identity = identityRecord;
+    if (typeof identity.profileId !== "string" ||
+        typeof identity.profileVersion !== "string" ||
+        typeof identity.manifestDigest !== "string" ||
+        !Array.isArray(identity.capabilityVersions)) {
+        throw new Error(".profile-lock.json identity must carry profileId/profileVersion/manifestDigest/capabilityVersions");
+    }
+    const capabilityVersions = identity.capabilityVersions.map((entry) => {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new Error(".profile-lock.json identity.capabilityVersions entries must be objects");
+        }
+        const capability = entry;
+        if (typeof capability.id !== "string" || typeof capability.version !== "number") {
+            throw new Error(".profile-lock.json identity.capabilityVersions entries must carry id/version");
+        }
+        return { id: capability.id, version: capability.version };
+    });
+    if (typeof record.lockedAt !== "number" ||
+        typeof record.lockedBy !== "string" ||
+        typeof record.generation !== "number") {
+        throw new Error(".profile-lock.json must carry lockedAt/lockedBy/generation");
+    }
+    return Object.freeze({
+        identity: Object.freeze({
+            profileId: identity.profileId,
+            profileVersion: identity.profileVersion,
+            manifestDigest: identity.manifestDigest,
+            capabilityVersions: Object.freeze(capabilityVersions.map((ref) => Object.freeze({ ...ref }))),
+        }),
+        lockedAt: record.lockedAt,
+        lockedBy: record.lockedBy,
+        generation: record.generation,
+    });
+}
+/**
+ * Locates and lazily provisions `<agentDir>/suites/<id>/`: the builtin pair
+ * gets its factory suite.json plus an empty agents.md skeleton on first start
+ * (设计 §5). Corruption policy (设计 §9): builtin suites fall back to factory
+ * content with diagnostics; user suites fail fast with the file path.
+ */
+export function loadSuiteWorkspace(options) {
+    const { agentDir, suiteId } = options;
+    const suiteDir = getSuiteWorkspaceDir(agentDir, suiteId);
+    const suiteJsonPath = join(suiteDir, SUITE_MANIFEST_FILENAME);
+    const agentsMdPath = join(suiteDir, SUITE_AGENTS_MD_FILENAME);
+    const diagnostics = [];
+    let suite;
+    if (!existsSync(suiteJsonPath)) {
+        const builtin = getBuiltinSuite(suiteId);
+        if (builtin === undefined)
+            throw new SuiteResolutionError(suiteId, listSuiteIds(agentDir));
+        mkdirSync(suiteDir, { recursive: true });
+        writeFileSync(suiteJsonPath, serializeSuiteJson(builtin), "utf8");
+        // D-075 S4 第三批：首启不再预种角色文件——种子移到 subagent-delegate 插件
+        // 注册期（entry 的幂等 seedFactoryRoleCatalog 补缺），插件安装并注册时
+        // `<agentDir>/roles/{explore,reviewer}.json` 自然到位。
+        suite = builtin;
+    }
+    else {
+        const parsed = parseSuiteJson(readFileSync(suiteJsonPath, "utf8"), {
+            expectedBuiltin: getBuiltinSuite(suiteId) !== undefined,
+            expectedId: suiteId,
+        });
+        const builtin = getBuiltinSuite(suiteId);
+        if (parsed.valid && parsed.suite) {
+            suite = parsed.suite;
+        }
+        else if (builtin !== undefined) {
+            // Builtin corruption policy (设计 §9): fall back to factory content
+            // with diagnostics instead of locking the user out. The file on disk
+            // is left untouched; recovery (reset) is an explicit M4 flow.
+            suite = builtin;
+            diagnostics.push(`suite.json at ${suiteJsonPath} is invalid; falling back to the factory content for builtin suite "${suiteId}". Errors: ${parsed.errors.join("; ")}`);
+        }
+        else {
+            throw new Error(`Invalid suite.json at ${suiteJsonPath}: ${parsed.errors.join("; ")}. Fix the file, or delete the suite workspace directory ${suiteDir} and recreate it.`);
+        }
+    }
+    if (!existsSync(agentsMdPath)) {
+        writeFileSync(agentsMdPath, "", "utf8");
+    }
+    // Suite profile lock persistence (M4, 设计 §12): an existing lock file is
+    // verified against the current identity (drift/migration recorded, never
+    // blocking and never silently replaced); without one a fresh lock is frozen
+    // and persisted. A lock file that cannot be parsed is recreated with a
+    // diagnostic — it carries no openable identity, so nothing is silently
+    // replaced.
+    const lockPath = join(suiteDir, SUITE_LOCK_FILENAME);
+    let previousLock;
+    if (existsSync(lockPath)) {
+        try {
+            previousLock = parseSuiteProfileLockFile(readFileSync(lockPath, "utf8"));
+        }
+        catch (error) {
+            diagnostics.push(`Profile lock at ${lockPath} is unreadable; recreating it over the current suite identity. Errors: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const bridge = bridgeSuiteProfileLock({
+        suite,
+        ...(options.pluginProfile === undefined ? {} : { pluginProfile: options.pluginProfile }),
+        ...(previousLock === undefined ? {} : { previousLock }),
+        lockedBy: "suite-loader",
+    });
+    diagnostics.push(...bridge.diagnostics);
+    if (previousLock === undefined) {
+        try {
+            writeFileSync(lockPath, serializeSuiteProfileLockFile(bridge.lock), "utf8");
+        }
+        catch (error) {
+            diagnostics.push(`Failed to persist the suite profile lock at ${lockPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return {
+        suite,
+        suiteDir,
+        suiteJsonPath,
+        agentsMdPath,
+        diagnostics: Object.freeze(diagnostics),
+        lockPath,
+        lock: bridge.lock,
+        identity: bridge.identity,
+        ...(bridge.verification === undefined ? {} : { lockVerification: bridge.verification }),
+    };
+}
+function readContextFile(path) {
+    try {
+        return stripBom(readFileSync(path, "utf8"));
+    }
+    catch {
+        return "";
+    }
+}
+function isUnderDir(path, dir) {
+    const resolvedPath = resolve(path);
+    const resolvedDir = resolve(dir);
+    const prefix = resolvedDir.endsWith(sep) ? resolvedDir : `${resolvedDir}${sep}`;
+    return resolvedPath.startsWith(prefix);
+}
+/**
+ * Assembles the agents.md three-level chain (设计 §8): system layer (the
+ * agentDir context file the resource loader's agentsFiles already carries,
+ * e.g. AGENTS.md, gated by inheritSystemAgentsMd) -> suite layer
+ * (`suites/<id>/agents.md`) -> project layer (existing ancestor chain, passed
+ * in unchanged). The global SYSTEM.md/APPEND_SYSTEM.md never ride the chain:
+ * they keep their native system prompt channel and are gated there by
+ * createSuiteSystemPromptGate, so both channels stay single-sourced. Every
+ * entry carries its source label; missing layers are skipped. Diagnostics
+ * record a blocked system layer (one-time migration hint) and the empty
+ * association counts (设计 §11.3: 惰性 + 可观测).
+ */
+export function assembleSuiteAgentsMdChain(options) {
+    const { suite, agentDir, suiteJsonPath, suiteAgentsMdPath, projectAgentsFiles } = options;
+    const diagnostics = [];
+    // System-layer candidates are the agentDir entries already present in the
+    // loader's agentsFiles; they are never read from disk here again.
+    const systemCandidates = projectAgentsFiles
+        .filter((entry) => isUnderDir(entry.path, agentDir))
+        .map((entry) => ({ path: entry.path, content: entry.content }));
+    const projectEntries = projectAgentsFiles.filter((entry) => !isUnderDir(entry.path, agentDir));
+    const chain = [];
+    if (suite.inheritSystemAgentsMd) {
+        for (const candidate of systemCandidates) {
+            chain.push({ source: "system", path: candidate.path, content: candidate.content });
+        }
+    }
+    else if (systemCandidates.length > 0) {
+        diagnostics.push(`Suite "${suite.id}" does not inherit the system agents.md layer (inheritSystemAgentsMd=false); system-layer file(s) kept out of the suite chain: ${systemCandidates
+            .map((candidate) => candidate.path)
+            .join(", ")}. Migrate them into ${suiteAgentsMdPath} or set "inheritSystemAgentsMd": true in ${suiteJsonPath}.`);
+    }
+    chain.push({ source: "suite", path: suiteAgentsMdPath, content: readContextFile(suiteAgentsMdPath) });
+    for (const entry of projectEntries) {
+        chain.push({ source: "project", path: entry.path, content: entry.content });
+    }
+    // Plugin associations are wired since M3 (the sdk filters the external
+    // capability plugin pool by associations.plugins); mcp stays
+    // declaration-only until M4.
+    diagnostics.push(`Suite "${suite.id}" mcp associations are declaration-only until M4; MCP association filtering is unwired.`);
+    return { chain: Object.freeze(chain), diagnostics: Object.freeze(diagnostics) };
+}
+/**
+ * Merges the assembled chain with the resource loader's own agentsFiles for
+ * the contextFiles injection channel: chain entries are prepended unless they
+ * are empty or already present in the base. Entries with empty content inject
+ * nothing, so a fresh factory skeleton changes no prompt bytes. Base entries
+ * under agentDir are dropped unconditionally (设计 §8): with
+ * inheritSystemAgentsMd=false the switch blocks the system layer, with true
+ * the chain already carries it at the head — keeping it in the base too would
+ * duplicate it and pin it after the suite layer, breaking the
+ * system -> suite -> project order.
+ */
+export function mergeSuiteAgentsFiles(chain, base, options) {
+    const retainedBase = base.filter((entry) => !isUnderDir(entry.path, options.agentDir));
+    const basePathSet = new Set(retainedBase.map((entry) => resolve(entry.path)));
+    const merged = [];
+    for (const entry of chain) {
+        if (entry.content.trim().length === 0)
+            continue;
+        if (basePathSet.has(resolve(entry.path)))
+            continue;
+        merged.push({ path: entry.path, content: entry.content });
+    }
+    merged.push(...retainedBase.map((entry) => ({ path: entry.path, content: entry.content })));
+    return merged;
+}
+/**
+ * Gates the global SYSTEM.md/APPEND_SYSTEM.md system prompt channel by
+ * inheritSystemAgentsMd (设计 §8: the switch governs the whole system layer,
+ * not just the agents.md chain). The resource loader feeds both overrides with
+ * the resolved content of exactly one discovered file — project-level
+ * `<cwd>/.agent-forge/<name>` first, else global `<agentDir>/<name>` — with no
+ * path attached, so project-level existence identifies the base origin:
+ * present means the project layer, which per 设计 §4 is the third level and
+ * always passes the switch; absent means a global source, which passes only
+ * when the suite inherits the system layer. Blocked global files are recorded
+ * in diagnostics with their paths (one-time migration hint, 设计 §11.3).
+ */
+export function createSuiteSystemPromptGate(suite, options) {
+    const diagnostics = [];
+    const passes = (filename) => {
+        const projectPath = join(options.cwd, CONFIG_DIR_NAME, filename);
+        if (existsSync(projectPath))
+            return true;
+        if (suite.inheritSystemAgentsMd)
+            return true;
+        const message = `Suite "${suite.id}" does not inherit the global system layer (inheritSystemAgentsMd=false); ` +
+            `global file kept out of the model context: ${join(options.agentDir, filename)}. Move it to the ` +
+            `project level (${projectPath}) or set "inheritSystemAgentsMd": true in the suite.json.`;
+        if (!diagnostics.includes(message))
+            diagnostics.push(message);
+        return false;
+    };
+    return {
+        systemPromptOverride: (base) => (base === undefined || passes("SYSTEM.md") ? base : undefined),
+        appendSystemPromptOverride: (base) => (base.length === 0 || passes("APPEND_SYSTEM.md") ? base : []),
+        diagnostics,
+    };
+}
+/**
+ * Single-sourced dangling-association diagnostic text (设计 §11.3): reported
+ * through the suiteDiagnostics channel, never thrown.
+ */
+export function suiteDanglingAssociationDiagnostic(suiteId, kind, name) {
+    return `Suite "${suiteId}" dangling association "${name}" (${kind}): not found in the discovered registry; ignored.`;
+}
+/**
+ * Filters the discovered skills down to the suite's skill associations (设计
+ * §3: the filter lives in the assembler; discovery stays untouched). Project
+ * scope (`<cwd>/.agent-forge/`) is the third layer (设计 §4) and always passes;
+ * every other entry is kept only when its `Skill.name` exactly matches an
+ * `associations.skills` entry. Association names that match no discovered
+ * skill — including case mismatches — are reported as dangling.
+ *
+ * `options.localSkillsDir` is the suite-local skill layer (统一修复轮 B:
+ * `<agentDir>/suites/<id>/skills`): its entries live inside the active suite
+ * workspace, so suite activation is their association and they pass the filter
+ * by path — the suite-local layer exemption — instead of requiring an
+ * association entry.
+ */
+export function filterSuiteSkills(suite, skills, options) {
+    const associated = new Set(suite.associations.skills);
+    const discovered = new Set(skills.map((skill) => skill.name));
+    const dangling = suite.associations.skills.filter((name) => !discovered.has(name));
+    const localSkillsDir = options?.localSkillsDir;
+    const kept = skills.filter((skill) => skill.sourceInfo.scope === "project" ||
+        (localSkillsDir !== undefined && isUnderDir(skill.filePath, localSkillsDir)) ||
+        associated.has(skill.name));
+    return { kept, dangling: Object.freeze(dangling) };
+}
+/**
+ * Decides one external capability plugin manifest against the suite's
+ * `associations.plugins` (方案设计 §10.4, M3 双键语义: associations.plugins
+ * governs only the external capability plugin pool; suite.capabilities governs
+ * the compiled builtin ids). The project-level pool
+ * (`<cwd>/.agent-forge/plugins`) is the third layer (设计 §4) and always
+ * passes; every other manifest is kept only when its id matches an
+ * association exactly. Filtered plugins surface as diagnostics, never as
+ * errors.
+ */
+export function decideSuiteCapabilityPlugin(suite, candidate, options) {
+    if (isUnderDir(candidate.manifestPath, join(options.cwd, CONFIG_DIR_NAME, "plugins")))
+        return { keep: true };
+    if (suite.associations.plugins.includes(candidate.manifestId))
+        return { keep: true };
+    return {
+        keep: false,
+        diagnostic: `Suite "${suite.id}" capability plugin "${candidate.manifestId}" at ${candidate.manifestPath} is not associated; not loaded.`,
+    };
+}
+/**
+ * Dangling `associations.plugins` entries: association ids that matched no
+ * candidate capability plugin manifest (设计 §11.3), single-sourced through
+ * the shared dangling diagnostic text. The caller decides what counts as a
+ * candidate: the sdk assembler passes every manifest id it loads, so explicit
+ * capabilityPluginPaths count toward satisfying an association even though
+ * they bypass the keep filter; only manifests absent from the passed ids
+ * surface as dangling.
+ */
+export function suiteDanglingPluginAssociations(suite, discoveredManifestIds) {
+    const discovered = new Set(discoveredManifestIds);
+    return suite.associations.plugins
+        .filter((id) => !discovered.has(id))
+        .map((id) => suiteDanglingAssociationDiagnostic(suite.id, "plugins", id));
+}
+/**
+ * Single-sourced assembly-layer context budget estimate (统一修复轮 B): pure
+ * chars/4 arithmetic over the assembled agents.md chain (per source layer),
+ * the orientation persona text, plus the count of suite-local workspace
+ * skills. Diagnostic-only: it never blocks, gates, or degrades anything.
+ */
+export function suiteContextBudgetDiagnostic(suiteId, chain, options) {
+    const layerChars = { system: 0, suite: 0, project: 0 };
+    for (const entry of chain) {
+        layerChars[entry.source] += entry.content.length;
+    }
+    const tokens = (chars) => Math.round(chars / 4);
+    const system = tokens(layerChars.system);
+    const suiteLayer = tokens(layerChars.suite);
+    const project = tokens(layerChars.project);
+    return `Suite "${suiteId}" context budget: agents.md ~${system + suiteLayer + project} tok (system ${system}/suite ${suiteLayer}/project ${project}), persona ~${tokens(options.personaChars)} tok, workspace skills ${options.workspaceSkillCount}`;
+}
+/**
+ * Plugin-profile diagnostics in the canonical suiteDiagnostics order.
+ *
+ * D-075 S2 soft degradation: a resolved Profile renders structured per-plugin
+ * misses (e.g. `manifest_missing` for a package-distributed plugin without an
+ * installed active version) as readable diagnostics, so the session keeps
+ * starting without the missing plugin's tools and the miss stays visible.
+ * Blocked resolutions already render every plugin diagnostic through
+ * `resolution.diagnostics`; the per-plugin lines are additive for the
+ * non-blocked branches only.
+ */
+function pluginProfileDiagnosticsV1(profile) {
+    if (profile.status === "not_found")
+        return [`Plugin profile unavailable: ${profile.profileId}`];
+    if (profile.status === "host_facts_required")
+        return [`Plugin profile host facts required: ${profile.profileId}`];
+    if (profile.status === "invalid_selection")
+        return [
+            `Plugin profile invalid selection: ${profile.profileId} (unknown: ${profile.unknownPluginIds.join(", ") || "none"}; duplicates: ${profile.duplicatePluginIds.join(", ") || "none"})`,
+        ];
+    const pluginMisses = profile.resolution.status === "blocked"
+        ? []
+        : profile.resolution.plugins
+            .filter((plugin) => plugin.status !== "installed-ready")
+            .flatMap((plugin) => plugin.diagnostics.map((diagnostic) => `Plugin profile plugin unavailable: ${plugin.pluginId} (${diagnostic.code}): ${diagnostic.message}`));
+    if (profile.resolution.status === "blocked")
+        return profile.resolution.diagnostics.map((diagnostic) => `Plugin profile blocked: ${diagnostic.message}`);
+    if (profile.assembly?.status === "unverified")
+        return [
+            ...profile.assembly.unverified.map((plugin) => `Plugin profile unverified: ${plugin.pluginId}@${plugin.pluginVersion}`),
+            ...pluginMisses,
+        ];
+    return pluginMisses;
+}
+/**
+ * The single suite assembly used by both first-party entry paths (sdk.ts
+ * self-built loader and agent-session-services `suiteAssembly`), so the two
+ * cannot drift. Loads the suite workspace, builds the system prompt gate, and
+ * returns the loader overrides plus a diagnostics collection channel.
+ */
+export function createSuiteAssembly(options) {
+    const { cwd, agentDir, suiteId } = options;
+    let pluginProfile = options.pluginProfile;
+    if (pluginProfile === undefined && options.pluginProfileId !== undefined) {
+        pluginProfile =
+            options.pluginHost === undefined
+                ? { status: "host_facts_required", profileId: options.pluginProfileId }
+                : resolveBuiltinPluginProfileV1({
+                    profileId: options.pluginProfileId,
+                    selectedPluginIds: options.selectedPluginIds,
+                    disabledPluginIds: options.disabledPluginIds,
+                    host: options.pluginHost,
+                    verifiedPlugins: options.verifiedPlugins,
+                    manifestOverrides: options.manifestOverrides,
+                });
+    }
+    const workspace = loadSuiteWorkspace({
+        agentDir,
+        suiteId,
+        ...(pluginProfile === undefined ? {} : { pluginProfile }),
+    });
+    const gate = createSuiteSystemPromptGate(workspace.suite, { cwd, agentDir });
+    // Suite-local asset layer (统一修复轮 B): present directories only, so
+    // missing and empty directories both contribute nothing.
+    const localSkillsDir = getSuiteLocalSkillsDir(agentDir, suiteId);
+    const localPluginsDir = getSuiteLocalPluginsDir(agentDir, suiteId);
+    const hasLocalSkillsDir = existsSync(localSkillsDir);
+    const hasLocalPluginsDir = existsSync(localPluginsDir);
+    const workspaceSkillCount = hasLocalSkillsDir
+        ? loadSkills({ cwd, agentDir, skillPaths: [localSkillsDir], includeDefaults: false }).skills.length
+        : 0;
+    let chainDiagnostics = [];
+    let skillDiagnostics = [];
+    // The assembled chain as far as the agentsFilesOverride has run; the budget
+    // line is only honest once the real chain is known.
+    let assembledChain;
+    // Factory upgrade proposal (M4, 设计 §9 升级合并): an unbounded registry
+    // resolve only proposes when the factory source wins, i.e. its revision is
+    // strictly greater than the disk revision. Daily assembly keeps the disk
+    // contents; adoption is an explicit --suite-reset.
+    const upgrade = detectSuiteFactoryUpgrade(workspace.suite);
+    const proposalDiagnostics = upgrade === undefined ? [] : [suiteFactoryUpgradeDiagnostic(suiteId, upgrade)];
+    const budgetDiagnostics = () => {
+        if (assembledChain === undefined)
+            return [];
+        return [
+            suiteContextBudgetDiagnostic(suiteId, assembledChain, {
+                personaChars: ORIENTATION_PROMPTS[workspace.suite.orientation].length,
+                workspaceSkillCount,
+            }),
+        ];
+    };
+    return {
+        workspace,
+        ...(pluginProfile === undefined ? {} : { pluginProfile }),
+        ...(hasLocalSkillsDir ? { localSkillsDir } : {}),
+        ...(hasLocalPluginsDir ? { localPluginsDir } : {}),
+        loaderOverrides: {
+            agentsFilesOverride: (base) => {
+                const assembly = assembleSuiteAgentsMdChain({
+                    suite: workspace.suite,
+                    agentDir,
+                    suiteJsonPath: workspace.suiteJsonPath,
+                    suiteAgentsMdPath: workspace.agentsMdPath,
+                    projectAgentsFiles: base.agentsFiles,
+                });
+                chainDiagnostics = assembly.diagnostics;
+                assembledChain = assembly.chain;
+                return { agentsFiles: mergeSuiteAgentsFiles(assembly.chain, base.agentsFiles, { agentDir }) };
+            },
+            skillsOverride: (base) => {
+                const filtered = filterSuiteSkills(workspace.suite, base.skills, { localSkillsDir });
+                skillDiagnostics = filtered.dangling.map((name) => suiteDanglingAssociationDiagnostic(suiteId, "skills", name));
+                return { skills: filtered.kept, diagnostics: base.diagnostics };
+            },
+            systemPromptOverride: gate.systemPromptOverride,
+            appendSystemPromptOverride: gate.appendSystemPromptOverride,
+        },
+        collectDiagnostics: () => Object.freeze([
+            ...workspace.diagnostics,
+            ...(pluginProfile === undefined ? [] : pluginProfileDiagnosticsV1(pluginProfile)),
+            ...proposalDiagnostics,
+            ...chainDiagnostics,
+            ...skillDiagnostics,
+            ...budgetDiagnostics(),
+            ...gate.diagnostics,
+        ]),
+    };
+}
+// ---------------------------------------------------------------------------
+// Session suite binding reader (设计 §10.1, 统一修复轮 B)
+// ---------------------------------------------------------------------------
+/**
+ * Reads the suite binding recorded as session protocol data (设计 §10.1): the
+ * suiteId of the latest `SUITE_SESSION_ENTRY_TYPE` custom entry. Undefined
+ * when the session carries no binding — pre-suite sessions, entries without a
+ * data payload, or payloads without a non-empty string suiteId.
+ */
+export function readSessionSuiteId(entries) {
+    return readSessionSuiteBinding(entries)?.suiteId;
+}
+function sessionProfileIdentity(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (typeof record.profileId !== "string" ||
+        record.profileId.trim() === "" ||
+        typeof record.profileVersion !== "string" ||
+        record.profileVersion.trim() === "" ||
+        typeof record.manifestDigest !== "string" ||
+        record.manifestDigest.trim() === "" ||
+        !Array.isArray(record.capabilityVersions)) {
+        return undefined;
+    }
+    const capabilityVersions = [];
+    for (const entry of record.capabilityVersions) {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+            return undefined;
+        const capability = entry;
+        if (typeof capability.id !== "string" ||
+            capability.id.trim() === "" ||
+            typeof capability.version !== "number" ||
+            !Number.isSafeInteger(capability.version) ||
+            capability.version < 1) {
+            return undefined;
+        }
+        capabilityVersions.push({ id: capability.id, version: capability.version });
+    }
+    return Object.freeze({
+        profileId: record.profileId,
+        profileVersion: record.profileVersion,
+        manifestDigest: record.manifestDigest,
+        capabilityVersions: Object.freeze(capabilityVersions),
+    });
+}
+/** Reads the latest suite and optional Profile identity bound to a session. */
+export function readSessionSuiteBinding(entries) {
+    for (let index = entries.length - 1; index >= 0; index--) {
+        const entry = entries[index];
+        if (entry.type !== "custom" || entry.customType !== SUITE_SESSION_ENTRY_TYPE)
+            continue;
+        const data = entry.data;
+        if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+            const suiteId = data.suiteId;
+            if (typeof suiteId === "string" && suiteId.length > 0) {
+                const profileIdentity = sessionProfileIdentity(data.profileIdentity);
+                return Object.freeze({
+                    suiteId,
+                    ...(profileIdentity === undefined ? {} : { profileIdentity }),
+                });
+            }
+        }
+        return undefined;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Suite -> ProfileIdentityV1 -> lock bridge (设计 §12)
+// ---------------------------------------------------------------------------
+function suiteToJsonValue(suite) {
+    return {
+        schemaVersion: suite.schemaVersion,
+        id: suite.id,
+        name: suite.name,
+        builtin: suite.builtin,
+        tools: [...suite.tools],
+        capabilities: [...suite.capabilities],
+        associations: {
+            skills: [...suite.associations.skills],
+            mcp: [...suite.associations.mcp],
+            plugins: [...suite.associations.plugins],
+        },
+        inheritSystemAgentsMd: suite.inheritSystemAgentsMd,
+        memory: suite.memory,
+        orientation: suite.orientation,
+        model: suite.model,
+        thinking: suite.thinking,
+        clonedFrom: suite.clonedFrom
+            ? { id: suite.clonedFrom.id, digest: suite.clonedFrom.digest, at: suite.clonedFrom.at }
+            : null,
+        ...(suite.factoryRevision === undefined ? {} : { factoryRevision: suite.factoryRevision }),
+    };
+}
+/** The stable suite.json digest that rides as the suite profile manifest digest. */
+export function suiteManifestDigest(suite) {
+    return stableJsonDigest(suiteToJsonValue(suite));
+}
+/**
+ * Builds the ProfileIdentityV1 for an assembled suite. The identity is a pure
+ * function of suite.json: the stable suite.json digest rides as the single
+ * resolved "manifest", and the declared capabilities map to capability
+ * references at version 1. No new identity/lock mechanism is introduced.
+ */
+export function buildSuiteProfileIdentity(suite, pluginProfile) {
+    const fingerprint = suiteManifestDigest(suite);
+    const suiteCapabilityRefs = suite.capabilities.map((id) => ({ id, version: 1 }));
+    const pluginRefs = pluginProfile?.status === "resolved" && pluginProfile.resolution.status === "ready"
+        ? pluginProfile.resolution.resolvedManifest.plugins
+        : [];
+    const capabilityRefs = [...suiteCapabilityRefs, ...pluginRefs.flatMap((plugin) => plugin.capabilityRefs)].sort((left, right) => left.id.localeCompare(right.id) || left.version - right.version);
+    return buildProfileIdentityV1({
+        profileId: suiteProfileId(suite.id),
+        profileVersion: `${SUITE_SCHEMA_VERSION}`,
+        resolvedPlugins: [
+            {
+                pluginId: `${suite.id}/suite.json`,
+                pluginVersion: fingerprint,
+                capabilityRefs: suiteCapabilityRefs,
+            },
+            ...(pluginProfile?.status === "resolved" && pluginProfile.resolution.status === "ready"
+                ? [
+                    {
+                        pluginId: `profile:${pluginProfile.profile.id}`,
+                        pluginVersion: pluginProfile.profile.version,
+                        capabilityRefs: [],
+                    },
+                    ...pluginRefs,
+                ]
+                : []),
+        ],
+        capabilityVersions: capabilityRefs,
+    });
+}
+// ---------------------------------------------------------------------------
+// ProfileRegistryV1 hookup: factory/disk sources and upgrade proposals (M4)
+// ---------------------------------------------------------------------------
+/** Registry profileId namespace for suites (设计 §12). */
+export function suiteProfileId(suiteId) {
+    return `suite:${suiteId}`;
+}
+export const SUITE_FACTORY_REGISTRY_SOURCE_ID = "suite-factory";
+export const SUITE_DISK_REGISTRY_SOURCE_ID = "suite-disk";
+/** Lower priority wins same-version ties: the disk contents beat the factory. */
+const SUITE_FACTORY_REGISTRY_PRIORITY = 10;
+const SUITE_DISK_REGISTRY_PRIORITY = 0;
+/** The effective on-disk revision: absent key means FACTORY_CONTENTS_VERSION. */
+function suiteDiskRevision(suite) {
+    return suite.factoryRevision ?? FACTORY_CONTENTS_VERSION;
+}
+/** Builds the registry entry of one suite definition (version = factoryRevision). */
+export function buildSuiteRegistryEntry(suite) {
+    return {
+        profileId: suiteProfileId(suite.id),
+        profileVersion: String(suiteDiskRevision(suite)),
+        manifestDigest: suiteManifestDigest(suite),
+    };
+}
+/** Factory source over the builtin declarations (priority 10). */
+export function buildSuiteFactoryRegistrySource() {
+    return {
+        sourceId: SUITE_FACTORY_REGISTRY_SOURCE_ID,
+        priority: SUITE_FACTORY_REGISTRY_PRIORITY,
+        profiles: BUILTIN_SUITES.map(buildSuiteRegistryEntry),
+    };
+}
+/** Disk source over workspace-effective definitions (priority 0; wins ties). */
+export function buildSuiteDiskRegistrySource(suites) {
+    return {
+        sourceId: SUITE_DISK_REGISTRY_SOURCE_ID,
+        priority: SUITE_DISK_REGISTRY_PRIORITY,
+        profiles: suites.map(buildSuiteRegistryEntry),
+    };
+}
+/** Single-sourced upgrade-proposal diagnostic text (设计 §9 升级合并). */
+export function suiteFactoryUpgradeDiagnostic(suiteId, upgrade) {
+    return `Suite "${suiteId}": factory revision ${upgrade.factoryRevision} available (disk has ${upgrade.diskRevision}); run "--suite-reset ${suiteId}" to review and adopt.`;
+}
+/**
+ * Detects a factory upgrade proposal for one disk-effective suite: an
+ * unbounded registry resolve over the factory source (all builtins) plus a
+ * disk source carrying exactly the effective definition. The factory source
+ * wins only when its revision is strictly greater — same-version resolves
+ * keep the disk contents (priority 0), so no proposal is emitted for
+ * unchanged suites, and user suites (no factory entry) never resolve to the
+ * factory. Pure function; the caller decides what to do with the proposal.
+ */
+export function detectSuiteFactoryUpgrade(diskSuite) {
+    const registry = createProfileRegistry();
+    registry.registerSource(buildSuiteFactoryRegistrySource());
+    registry.registerSource(buildSuiteDiskRegistrySource([diskSuite]));
+    const resolution = registry.resolve({ profileId: suiteProfileId(diskSuite.id) });
+    if (resolution.status !== "resolved" || resolution.sourceId !== SUITE_FACTORY_REGISTRY_SOURCE_ID) {
+        return undefined;
+    }
+    return {
+        factoryRevision: Number.parseInt(resolution.profileVersion, 10),
+        diskRevision: suiteDiskRevision(diskSuite),
+    };
+}
+/** Bridges an assembled suite onto the existing lock create/verify trio. */
+export function bridgeSuiteProfileLock(options) {
+    const identity = buildSuiteProfileIdentity(options.suite, options.pluginProfile);
+    const diagnostics = [];
+    let verification;
+    if (options.previousLock !== undefined) {
+        verification = verifyProfileLock(options.previousLock, identity);
+        if (verification.status === "drift") {
+            diagnostics.push(`Suite "${options.suite.id}" profile lock drift: ${verification.reason}`);
+        }
+        else if (verification.status === "migration_required") {
+            diagnostics.push(`Suite "${options.suite.id}" profile lock migration required: ${verification.reason}`);
+        }
+    }
+    const lock = options.previousLock ??
+        createProfileLock(identity, {
+            lockedBy: options.lockedBy ?? "suite-loader",
+            ...(options.now === undefined ? {} : { now: options.now }),
+        });
+    return {
+        identity,
+        lock,
+        ...(verification === undefined ? {} : { verification }),
+        diagnostics: Object.freeze(diagnostics),
+    };
+}
+//# sourceMappingURL=suite-loader.js.map