@promptbook/cli 0.114.0-2 → 0.114.0-21

package/apps/agents-server/src/utils/agentReferenceResolver/createAgentInheritanceDiagnostics.ts

@@ -0,0 +1,457 @@
+import { CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES } from '../../../../../servers';
+import type { AgentReferenceResolver } from '../../../../../src/book-2.0/agent-source/AgentReferenceResolver';
+import { isVoidPseudoAgentReference } from '../../../../../src/book-2.0/agent-source/pseudoAgentReferences';
+import type {
+    string_agent_permanent_id,
+    string_agent_url,
+    string_book,
+} from '../../../../../src/_packages/types.index';
+import type { AgentCollection } from '../../../../../src/collection/agent-collection/AgentCollection';
+import { isValidAgentUrl } from '../../../../../src/utils/validators/url/isValidAgentUrl';
+import { getEffectiveExplicitFromCommitment, type ExplicitFromCommitment } from '../explicitFromCommitment';
+import {
+    createLocalAgentUrl,
+    normalizeLocalServerUrls,
+    resolveLocalAgentRouteReference,
+} from '../localAgentRouteReferences';
+import { createBookScopedAgentReferenceResolver, resolveBookScopedAgentContext } from './bookScopedAgentReferences';
+import { createServerAgentReferenceResolver } from './createServerAgentReferenceResolver';
+import type { AgentReferenceDiagnostic } from './createUnresolvedAgentReferenceDiagnostics';
+
+/**
+ * Maximum number of local inheritance links inspected while preparing Book editor diagnostics.
+ *
+ * A real local cycle is found much sooner, while this bound keeps an unexpectedly deep graph from delaying the editor.
+ *
+ * @private utility of Agents Server inheritance diagnostics
+ */
+const MAX_LOCAL_INHERITANCE_DIAGNOSTIC_DEPTH = 100;
+
+/**
+ * Monaco marker source used for invalid root and circular inheritance warnings.
+ *
+ * @private utility of Agents Server inheritance diagnostics
+ */
+const AGENT_INHERITANCE_DIAGNOSTIC_SOURCE = 'agent-inheritance';
+
+/**
+ * Dependencies needed to validate the effective local `FROM` chain of one in-editor book.
+ *
+ * @private utility of Agents Server inheritance diagnostics
+ */
+export type CreateAgentInheritanceDiagnosticsOptions = {
+    /**
+     * Current unsaved source from the Book editor.
+     */
+    readonly agentSource: string_book;
+
+    /**
+     * Stable permanent id of the agent being edited.
+     */
+    readonly agentPermanentId: string_agent_permanent_id;
+
+    /**
+     * Collection used to load local ancestors and their Book sources.
+     */
+    readonly collection: AgentCollection;
+
+    /**
+     * Current server origin used to build and recognize local agent URLs.
+     */
+    readonly localServerUrl: string;
+};
+
+/**
+ * One local agent source participating in an inheritance-chain walk.
+ *
+ * @private utility of Agents Server inheritance diagnostics
+ */
+type LocalInheritanceNode = {
+    /**
+     * Editable source before `FROM` materialization.
+     */
+    readonly agentSource: string_book;
+
+    /**
+     * Canonical local route used to identify the node in the chain.
+     */
+    readonly canonicalAgentUrl: string_agent_url;
+
+    /**
+     * Friendly title displayed in a cycle warning.
+     */
+    readonly title: string;
+
+    /**
+     * Resolver scoped to embedded agents declared by this Book.
+     */
+    readonly agentReferenceResolver: AgentReferenceResolver;
+
+    /**
+     * Last explicit parent declaration, when the Book has one.
+     */
+    readonly effectiveFromCommitment: ExplicitFromCommitment | undefined;
+
+    /**
+     * Whether this source is the server's root Adam agent.
+     */
+    readonly isAdamAgent: boolean;
+};
+
+/**
+ * Creates Book editor warnings for a circular local inheritance chain and for an Adam source that is not rooted in
+ * `Null`/`Void`.
+ *
+ * The runtime remains the authority that materializes local and federated sources. This intentionally lightweight
+ * graph walk only follows local `FROM` links, which is enough to point an author at the exact Book line before a
+ * cycle can make runtime resolution fail.
+ *
+ * @param options - Current editable source and local-server dependencies.
+ * @returns Warning markers suitable for the Book editor.
+ *
+ * @private utility of Agents Server Book editor diagnostics
+ */
+export async function createAgentInheritanceDiagnostics(
+    options: CreateAgentInheritanceDiagnosticsOptions,
+): Promise<Array<AgentReferenceDiagnostic>> {
+    const { agentSource, agentPermanentId, collection, localServerUrl } = options;
+    const normalizedLocalServerUrl = localServerUrl.replace(/\/+$/g, '');
+    const baseAgentReferenceResolver = await createServerAgentReferenceResolver({
+        agentCollection: collection,
+        localServerUrl: normalizedLocalServerUrl,
+    });
+    const adamCanonicalAgentUrl = await resolveAdamCanonicalAgentUrl(collection, normalizedLocalServerUrl);
+    const rootNode = createRootInheritanceNode({
+        agentSource,
+        agentPermanentId,
+        localServerUrl: normalizedLocalServerUrl,
+        adamCanonicalAgentUrl,
+        baseAgentReferenceResolver,
+    });
+    const adamDiagnostics = createAdamRootDiagnostics(rootNode);
+    const cycleDiagnostic = await createCycleDiagnostic({
+        rootNode,
+        collection,
+        localServerUrl: normalizedLocalServerUrl,
+        adamCanonicalAgentUrl,
+        baseAgentReferenceResolver,
+    });
+
+    return cycleDiagnostic ? [...adamDiagnostics, cycleDiagnostic] : adamDiagnostics;
+}
+
+/**
+ * Resolves Adam's canonical current route from its well-known name.
+ *
+ * @param collection - Collection containing local core agents.
+ * @param localServerUrl - Current server origin.
+ * @returns Canonical Adam route or `null` when the core agent is missing.
+ *
+ * @private utility of `createAgentInheritanceDiagnostics`
+ */
+async function resolveAdamCanonicalAgentUrl(
+    collection: Pick<AgentCollection, 'getAgentPermanentId'>,
+    localServerUrl: string,
+): Promise<string_agent_url | null> {
+    try {
+        const adamPermanentId = await collection.getAgentPermanentId(CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES.ADAM);
+        return createLocalAgentUrl(localServerUrl, adamPermanentId);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Creates the first graph node from the source currently being edited rather than its last saved database version.
+ *
+ * @param options - Current source and dependencies shared by the diagnostics pass.
+ * @returns Root node of the local inheritance walk.
+ *
+ * @private utility of `createAgentInheritanceDiagnostics`
+ */
+function createRootInheritanceNode(options: {
+    readonly agentSource: string_book;
+    readonly agentPermanentId: string_agent_permanent_id;
+    readonly localServerUrl: string;
+    readonly adamCanonicalAgentUrl: string_agent_url | null;
+    readonly baseAgentReferenceResolver: AgentReferenceResolver;
+}): LocalInheritanceNode {
+    const { agentSource, agentPermanentId, localServerUrl, adamCanonicalAgentUrl, baseAgentReferenceResolver } =
+        options;
+    const canonicalAgentUrl = createLocalAgentUrl(localServerUrl, agentPermanentId);
+    const title = readAgentSourceTitle(agentSource, agentPermanentId);
+
+    return {
+        agentSource,
+        canonicalAgentUrl,
+        title,
+        agentReferenceResolver: createBookScopedAgentReferenceResolver({
+            parentAgentSource: agentSource,
+            parentAgentIdentifier: agentPermanentId,
+            localServerUrl,
+            fallbackResolver: baseAgentReferenceResolver,
+        }),
+        effectiveFromCommitment: getEffectiveExplicitFromCommitment(agentSource),
+        isAdamAgent:
+            canonicalAgentUrl === adamCanonicalAgentUrl ||
+            title.trim().toLowerCase() === CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES.ADAM,
+    };
+}
+
+/**
+ * Creates the Adam-specific warning when the root agent does not explicitly inherit from `Null`/`Void`.
+ *
+ * @param node - Root node being edited.
+ * @returns One warning for invalid Adam ancestry, otherwise an empty list.
+ *
+ * @private utility of `createAgentInheritanceDiagnostics`
+ */
+function createAdamRootDiagnostics(node: LocalInheritanceNode): Array<AgentReferenceDiagnostic> {
+    if (node.isAdamAgent && !isExplicitNoParentCommitment(node.effectiveFromCommitment)) {
+        return [
+            createInheritanceMarker(
+                node.agentSource,
+                node.effectiveFromCommitment,
+                'The core `Adam` agent must explicitly use `FROM @Null` (or the equivalent `FROM @Void`) so it remains the root of the inheritance chain.',
+            ),
+        ];
+    }
+
+    return [];
+}
+
+/**
+ * Checks whether an effective `FROM` commitment explicitly opts out of inheritance.
+ *
+ * @param fromCommitment - Effective parent declaration, if present.
+ * @returns True only for an explicit `Null`/`Void` parent.
+ *
+ * @private utility of `createAgentInheritanceDiagnostics`
+ */
+function isExplicitNoParentCommitment(fromCommitment: ExplicitFromCommitment | undefined): boolean {
+    return Boolean(fromCommitment && isVoidPseudoAgentReference(fromCommitment.content));
+}
+
+/**
+ * Walks the local parent chain and creates one warning when it reaches a previously visited agent.
+ *
+ * @param options - Root node and dependencies shared by the graph walk.
+ * @returns Cycle warning marker or `null` when the chain is safe or leaves the local server.
+ *
+ * @private utility of `createAgentInheritanceDiagnostics`
+ */
+async function createCycleDiagnostic(options: {
+    readonly rootNode: LocalInheritanceNode;
+    readonly collection: AgentCollection;
+    readonly localServerUrl: string;
+    readonly adamCanonicalAgentUrl: string_agent_url | null;
+    readonly baseAgentReferenceResolver: AgentReferenceResolver;
+}): Promise<AgentReferenceDiagnostic | null> {
+    const { rootNode } = options;
+    const inheritancePath: Array<LocalInheritanceNode> = [rootNode];
+    let currentNode = rootNode;
+
+    for (let depth = 0; depth < MAX_LOCAL_INHERITANCE_DIAGNOSTIC_DEPTH; depth++) {
+        const parentNode = await resolveLocalParentNode(currentNode, options);
+        if (!parentNode) {
+            return null;
+        }
+
+        const cycleStartIndex = inheritancePath.findIndex(
+            (pathNode) => pathNode.canonicalAgentUrl === parentNode.canonicalAgentUrl,
+        );
+        if (cycleStartIndex !== -1) {
+            const cycleTitles = [...inheritancePath.slice(cycleStartIndex), parentNode]
+                .map((cycleNode) => `\`${cycleNode.title}\``)
+                .join(' → ');
+
+            return createInheritanceMarker(
+                rootNode.agentSource,
+                rootNode.effectiveFromCommitment,
+                `Cyclic \`FROM\` inheritance detected: ${cycleTitles}. Change one of these parent references to break the cycle.`,
+            );
+        }
+
+        inheritancePath.push(parentNode);
+        currentNode = parentNode;
+    }
+
+    return null;
+}
+
+/**
+ * Resolves one node's effective local parent, or returns `null` for explicit no-parent, missing, or remote parents.
+ *
+ * @param node - Node whose parent should be followed.
+ * @param options - Shared local resolution dependencies.
+ * @returns The next local node, or `null` when the diagnostic walk should stop.
+ *
+ * @private utility of `createAgentInheritanceDiagnostics`
+ */
+async function resolveLocalParentNode(
+    node: LocalInheritanceNode,
+    options: {
+        readonly collection: AgentCollection;
+        readonly localServerUrl: string;
+        readonly adamCanonicalAgentUrl: string_agent_url | null;
+        readonly baseAgentReferenceResolver: AgentReferenceResolver;
+    },
+): Promise<LocalInheritanceNode | null> {
+    const { effectiveFromCommitment } = node;
+
+    if (!effectiveFromCommitment) {
+        if (node.isAdamAgent) {
+            return null;
+        }
+
+        const adamAgentUrl = createLocalAgentUrl(
+            options.localServerUrl,
+            CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES.ADAM,
+        );
+        return loadLocalInheritanceNode(adamAgentUrl, options);
+    }
+
+    if (!effectiveFromCommitment.content || isVoidPseudoAgentReference(effectiveFromCommitment.content)) {
+        return null;
+    }
+
+    let resolvedParentReference: string;
+    try {
+        resolvedParentReference = await node.agentReferenceResolver.resolveCommitmentContent(
+            'FROM',
+            effectiveFromCommitment.content,
+        );
+    } catch {
+        return null;
+    }
+
+    if (!resolvedParentReference || isVoidPseudoAgentReference(resolvedParentReference)) {
+        return null;
+    }
+
+    if (!isValidAgentUrl(resolvedParentReference)) {
+        return null;
+    }
+
+    return loadLocalInheritanceNode(resolvedParentReference as string_agent_url, options);
+}
+
+/**
+ * Loads one local parent node through the same book-scoped context used by the regular runtime resolver.
+ *
+ * @param parentAgentUrl - Resolved parent URL to inspect.
+ * @param options - Shared local resolution dependencies.
+ * @returns Loaded local node, or `null` for a remote/unavailable parent.
+ *
+ * @private utility of `createAgentInheritanceDiagnostics`
+ */
+async function loadLocalInheritanceNode(
+    parentAgentUrl: string_agent_url,
+    options: {
+        readonly collection: AgentCollection;
+        readonly localServerUrl: string;
+        readonly adamCanonicalAgentUrl: string_agent_url | null;
+        readonly baseAgentReferenceResolver: AgentReferenceResolver;
+    },
+): Promise<LocalInheritanceNode | null> {
+    const localRouteReference = resolveLocalAgentRouteReference(
+        parentAgentUrl,
+        normalizeLocalServerUrls([options.localServerUrl]),
+        [],
+    );
+    if (!localRouteReference) {
+        return null;
+    }
+
+    try {
+        const resolvedAgentContext = await resolveBookScopedAgentContext({
+            collection: options.collection,
+            agentIdentifier: localRouteReference.agentIdentifier,
+            localServerUrl: options.localServerUrl,
+            fallbackResolver: options.baseAgentReferenceResolver,
+        });
+        const title = readAgentSourceTitle(
+            resolvedAgentContext.unresolvedAgentSource,
+            resolvedAgentContext.resolvedAgentName,
+        );
+
+        return {
+            agentSource: resolvedAgentContext.unresolvedAgentSource,
+            canonicalAgentUrl: resolvedAgentContext.canonicalAgentUrl,
+            title,
+            agentReferenceResolver: resolvedAgentContext.scopedAgentReferenceResolver,
+            effectiveFromCommitment: getEffectiveExplicitFromCommitment(resolvedAgentContext.unresolvedAgentSource),
+            isAdamAgent:
+                resolvedAgentContext.canonicalAgentUrl === options.adamCanonicalAgentUrl ||
+                title.trim().toLowerCase() === CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES.ADAM,
+        };
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Reads a Book's visible title for friendly diagnostics, with a stable fallback for incomplete editor content.
+ *
+ * @param agentSource - Source to inspect.
+ * @param fallbackTitle - Stable fallback when the source has no title yet.
+ * @returns First non-empty source line or the fallback title.
+ *
+ * @private utility of `createAgentInheritanceDiagnostics`
+ */
+function readAgentSourceTitle(agentSource: string_book, fallbackTitle: string): string {
+    for (const line of agentSource.split(/\r?\n/)) {
+        const title = line.trim();
+        if (title) {
+            return title;
+        }
+    }
+
+    return fallbackTitle;
+}
+
+/**
+ * Creates a warning marker on the effective `FROM` keyword, or on the title when inheritance is implicit.
+ *
+ * @param agentSource - Source whose marker should be displayed.
+ * @param fromCommitment - Effective explicit `FROM`, if one exists.
+ * @param message - Human-readable warning shown by Monaco.
+ * @returns Monaco-compatible warning marker.
+ *
+ * @private utility of `createAgentInheritanceDiagnostics`
+ */
+function createInheritanceMarker(
+    agentSource: string_book,
+    fromCommitment: ExplicitFromCommitment | undefined,
+    message: string,
+): AgentReferenceDiagnostic {
+    const sourceLines = agentSource.split(/\r?\n/);
+
+    if (fromCommitment) {
+        const sourceLine = sourceLines[fromCommitment.lineIndex] || '';
+        const keywordIndex = Math.max(0, sourceLine.indexOf('FROM'));
+
+        return {
+            startLineNumber: fromCommitment.lineIndex + 1,
+            startColumn: keywordIndex + 1,
+            endLineNumber: fromCommitment.lineIndex + 1,
+            endColumn: keywordIndex + 'FROM'.length + 1,
+            message,
+            source: AGENT_INHERITANCE_DIAGNOSTIC_SOURCE,
+            severity: 'warning',
+        };
+    }
+
+    const titleLineIndex = sourceLines.findIndex((sourceLine) => sourceLine.trim().length > 0);
+    const sourceLine = sourceLines[titleLineIndex] || '';
+
+    return {
+        startLineNumber: Math.max(0, titleLineIndex) + 1,
+        startColumn: 1,
+        endLineNumber: Math.max(0, titleLineIndex) + 1,
+        endColumn: Math.max(2, sourceLine.length + 1),
+        message,
+        source: AGENT_INHERITANCE_DIAGNOSTIC_SOURCE,
+        severity: 'warning',
+    };
+}

package/apps/agents-server/src/utils/agentReferenceResolver/createUnresolvedAgentReferenceDiagnostics.ts

@@ -5,6 +5,8 @@ import type { BookCommitment } from '../../../../../src/commitments/_base/BookCo
 import type { ParsedCommitment } from '../../../../../src/commitments/_base/ParsedCommitment';
 import { consumeAgentReferenceResolutionIssues } from './AgentReferenceResolutionIssue';
 import { extractAgentReferenceTokens } from './extractAgentReferenceTokens';
+import type { MissingCoreAgentRecovery } from './MissingCoreAgentRecovery';
+import { getEffectiveExplicitFromCommitment } from '../explicitFromCommitment';
 
 /**
  * Monaco-compatible diagnostic payload for unresolved compact agent references.
@@ -39,6 +41,11 @@ export type AgentReferenceDiagnostic = {
      * Optional source label shown by Monaco.
      */
     readonly source?: string;
+
+    /**
+     * Optional marker severity. Missing references use Monaco's default error severity.
+     */
+    readonly severity?: 'error' | 'warning' | 'info' | 'hint';
 };
 
 /**
@@ -48,6 +55,19 @@ export type MissingAgentReference = {
     readonly reference: string;
     readonly token: string;
     readonly commitmentType: BookCommitment;
+
+    /**
+     * Whether the reference is implied by the Book language itself instead of being written in the book.
+     *
+     * A book without any `FROM` commitment implicitly inherits from `@Adam`, so a missing Adam has to be reported
+     * even though no token points at it.
+     */
+    readonly isImplicit?: boolean;
+
+    /**
+     * Reinstatement offered when the missing reference points to one of the bundled core agents.
+     */
+    readonly coreAgentRecovery?: MissingCoreAgentRecovery;
 };
 
 /**
@@ -186,6 +206,7 @@ export async function createUnresolvedAgentReferenceDiagnostics(
 function collectAgentReferenceTokenLocations(agentSource: string_book): Array<AgentReferenceTokenLocation> {
     const parsed = parseAgentSourceWithCommitments(agentSource);
     const sourceLines = agentSource.split(/\r?\n/);
+    const effectiveFromCommitment = getEffectiveExplicitFromCommitment(agentSource);
     const tokenLocations: Array<AgentReferenceTokenLocation> = [];
 
     for (let commitmentIndex = 0; commitmentIndex < parsed.commitments.length; commitmentIndex++) {
@@ -194,6 +215,12 @@ function collectAgentReferenceTokenLocations(agentSource: string_book): Array<Ag
             continue;
         }
 
+        // A parent is singular: only the final FROM participates in resolution, so diagnostics must not report an
+        // overridden reference as missing. The Book editor separately marks every duplicate FROM with an explanation.
+        if (commitment.type === 'FROM' && effectiveFromCommitment?.lineIndex !== commitment.lineNumber - 1) {
+            continue;
+        }
+
         const startLineNumber = commitment.lineNumber;
         const nextCommitmentStartLine = parsed.commitments[commitmentIndex + 1]?.lineNumber ?? sourceLines.length + 1;
         const endLineNumber = resolveCommitmentEndLine(sourceLines, startLineNumber, nextCommitmentStartLine - 1);

package/apps/agents-server/src/utils/agentReferenceResolver/resolveCoreAgentAwareMissingReferences.ts

@@ -0,0 +1,156 @@
+import { CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES } from '../../../../../servers';
+import { normalizeAgentName } from '../../../../../src/book-2.0/agent-source/normalizeAgentName';
+import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
+import { resolveDefaultAgentsStatus, type CoreAgentReport } from '../defaultAgents/resolveDefaultAgentsStatus';
+import { isImplicitAdamInheritance } from '../explicitFromCommitment';
+import type { MissingAgentReference } from './createUnresolvedAgentReferenceDiagnostics';
+import type { MissingCoreAgentRecovery } from './MissingCoreAgentRecovery';
+
+/**
+ * Dependencies needed to enrich unresolved references with bundled-core-agent recovery.
+ *
+ * @private utility of Agents Server agent-reference diagnostics
+ */
+export type ResolveCoreAgentAwareMissingReferencesOptions = {
+    /**
+     * Agent source currently edited in the Book editor.
+     */
+    readonly agentSource: string_book;
+
+    /**
+     * Unresolved compact references already detected in `agentSource`.
+     */
+    readonly missingAgentReferences: ReadonlyArray<MissingAgentReference>;
+
+    /**
+     * Whether the current user is allowed to reinstate the missing core agents.
+     */
+    readonly isReinstateAllowed: boolean;
+};
+
+/**
+ * Extends unresolved compact references of one book with bundled-core-agent recovery.
+ *
+ * Two things are added here:
+ *
+ * 1. A reference naming a bundled core agent is marked as recoverable, because such an agent should be reinstated
+ *    from its bundled book instead of being created empty from scratch.
+ * 2. A book without any explicit `FROM` implicitly inherits from `@Adam`, so a missing Adam is reported right away
+ *    even though no token in the book points at it.
+ *
+ * @param options - Current book, already-detected missing references, and the reinstate permission.
+ * @returns Missing references carrying core-agent recovery, with the implicit `@Adam` ancestor first when missing.
+ *
+ * @private utility of Agents Server agent-reference diagnostics
+ */
+export async function resolveCoreAgentAwareMissingReferences(
+    options: ResolveCoreAgentAwareMissingReferencesOptions,
+): Promise<ReadonlyArray<MissingAgentReference>> {
+    const { agentSource, missingAgentReferences, isReinstateAllowed } = options;
+    const isAdamImplicitlyInherited = isImplicitAdamInheritance(agentSource);
+
+    if (!isAdamImplicitlyInherited && missingAgentReferences.length === 0) {
+        return missingAgentReferences;
+    }
+
+    const missingCoreAgents = await resolveMissingCoreAgents();
+
+    if (missingCoreAgents.length === 0) {
+        return missingAgentReferences;
+    }
+
+    const coreAgentRecovery: MissingCoreAgentRecovery = {
+        missingCoreAgentTitles: missingCoreAgents.map((missingCoreAgent) => missingCoreAgent.title),
+        isReinstateAllowed,
+    };
+    const recoverableMissingAgentReferences = missingAgentReferences.map((missingAgentReference) =>
+        findMissingCoreAgent(missingCoreAgents, missingAgentReference.reference)
+            ? { ...missingAgentReference, coreAgentRecovery }
+            : missingAgentReference,
+    );
+
+    if (!isAdamImplicitlyInherited) {
+        return recoverableMissingAgentReferences;
+    }
+
+    const missingAdamAgent = findMissingCoreAgent(missingCoreAgents, CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES.ADAM);
+
+    if (!missingAdamAgent || hasMissingAgentReferenceFor(recoverableMissingAgentReferences, missingAdamAgent)) {
+        return recoverableMissingAgentReferences;
+    }
+
+    return [
+        createImplicitAdamMissingReference(missingAdamAgent, coreAgentRecovery),
+        ...recoverableMissingAgentReferences,
+    ];
+}
+
+/**
+ * Resolves which bundled core agents are absent from the current server.
+ *
+ * Presence comes from the same status the Core Agents admin page renders, so the panel linking to that page can never
+ * disagree with it. Implicit inheritance always loads Adam from this very server, so a federated namesake elsewhere
+ * must not count as present.
+ *
+ * @returns Reports of the bundled core agents that are missing, in bundled order.
+ */
+async function resolveMissingCoreAgents(): Promise<ReadonlyArray<CoreAgentReport>> {
+    try {
+        const { coreAgents } = await resolveDefaultAgentsStatus();
+        return coreAgents.filter((coreAgent) => !coreAgent.isPresent);
+    } catch (error) {
+        console.warn('[AgentReferenceResolver] Failed to resolve the bundled core agent status:', error);
+        return [];
+    }
+}
+
+/**
+ * Finds the missing bundled core agent one reference points to.
+ *
+ * @param missingCoreAgents - Bundled core agents currently missing on this server.
+ * @param reference - Raw reference payload, for example `Adam` or `adam`.
+ * @returns Matching missing core agent, or `undefined` when the reference names something else.
+ */
+function findMissingCoreAgent(
+    missingCoreAgents: ReadonlyArray<CoreAgentReport>,
+    reference: string,
+): CoreAgentReport | undefined {
+    const normalizedReference = normalizeAgentName(reference);
+    return missingCoreAgents.find((missingCoreAgent) => missingCoreAgent.agentName === normalizedReference);
+}
+
+/**
+ * Checks whether one missing core agent is already reported by an explicit reference written in the book.
+ *
+ * @param missingAgentReferences - Missing references detected in the book.
+ * @param missingCoreAgent - Missing core agent to look for.
+ * @returns True when the book already shows a card for that agent.
+ */
+function hasMissingAgentReferenceFor(
+    missingAgentReferences: ReadonlyArray<MissingAgentReference>,
+    missingCoreAgent: CoreAgentReport,
+): boolean {
+    return missingAgentReferences.some(
+        (missingAgentReference) => normalizeAgentName(missingAgentReference.reference) === missingCoreAgent.agentName,
+    );
+}
+
+/**
+ * Creates the missing-reference entry standing for the implicit `FROM @Adam` ancestor.
+ *
+ * @param missingAdamAgent - Report of the missing Adam core agent.
+ * @param coreAgentRecovery - Reinstatement offered for the missing core agents.
+ * @returns Missing reference shown exactly like an explicitly referenced agent that was not found.
+ */
+function createImplicitAdamMissingReference(
+    missingAdamAgent: CoreAgentReport,
+    coreAgentRecovery: MissingCoreAgentRecovery,
+): MissingAgentReference {
+    return {
+        reference: missingAdamAgent.title,
+        token: `{${missingAdamAgent.title}}`,
+        commitmentType: 'FROM',
+        isImplicit: true,
+        coreAgentRecovery,
+    };
+}