@promptbook/cli 0.114.0-38 → 0.114.0-39

package/esm/scripts/run-agent-messages/messages/createAgentRunnerSystemMessage.d.ts

@@ -1,9 +1,10 @@
 import type { AgentModelRequirements } from '../../../src/book-2.0/agent-source/AgentModelRequirements';
+import type { CreateAgentModelRequirementsOptions } from '../../../src/book-2.0/agent-source/CreateAgentModelRequirementsOptions';
 import type { string_book } from '../../../src/book-2.0/agent-source/string_book';
 /**
  * Compiles agent source into the behavior text passed to CLI harness runners.
  */
-export declare function createAgentRunnerSystemMessage(agentSource: string_book): Promise<string>;
+export declare function createAgentRunnerSystemMessage(agentSource: string_book, options?: CreateAgentModelRequirementsOptions): Promise<string>;
 /**
  * Formats prepared model requirements for a text-only CLI harness prompt.
  */

package/esm/scripts/run-codex-prompts/common/resolveCoderAgent.d.ts

@@ -26,10 +26,14 @@ export type ResolvedCoderAgentBook = {
  * Agent data resolved from the optional `--agent` book file.
  */
 export type ResolvedCoderAgent = ResolvedCoderAgentBook & {
+    /** Source with inheritance and imports applied, also used for the coder's agent visual. */
+    readonly agentSource: string_book;
     /**
      * Compiled system message injected into each coding prompt.
      */
     readonly systemMessage: string;
+    /** Books created during resolution, committed according to the coder's normal commit setting. */
+    readonly createdAgentBookPaths: ReadonlyArray<string>;
 };
 /**
  * Reads an optional agent `.book` file and prepares the references that route prompts to it.

package/esm/scripts/run-codex-prompts/git/commitInitializedAgentBooks.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Commits newly initialized, non-ignored agent books before the coder's clean-tree checkpoint.
+ * Only books created by this run are eligible; existing books and unrelated changes remain outside the commit.
+ */
+export declare function commitInitializedAgentBooks(projectPath: string, createdAgentBookPaths: ReadonlyArray<string>): Promise<void>;

package/esm/src/book-2.0/agent-source/AgentReferenceResolutionIssue.d.ts

@@ -0,0 +1,45 @@
+import type { BookCommitment } from '../../commitments/_base/BookCommitment';
+import type { AgentReferenceResolver } from './AgentReferenceResolver';
+/**
+ * Structured issue captured when compact agent reference resolution fails.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export type AgentReferenceResolutionIssue = {
+    /**
+     * Commitment where the unresolved token appeared.
+     */
+    readonly commitmentType: BookCommitment;
+    /**
+     * Original token text (for example `{Unknown Agent}` or `@UnknownAgent`).
+     */
+    readonly token: string;
+    /**
+     * Normalized token payload used for lookup.
+     */
+    readonly reference: string;
+    /**
+     * Human-readable explanation of why the token could not be resolved.
+     */
+    readonly message: string;
+};
+/**
+ * Extension implemented by resolvers that can expose accumulated resolution issues.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export type IssueTrackingAgentReferenceResolver = AgentReferenceResolver & {
+    /**
+     * Returns tracked issues and clears the internal queue.
+     */
+    consumeResolutionIssues(): Array<AgentReferenceResolutionIssue>;
+};
+/**
+ * Drains unresolved compact-reference issues from a resolver when supported.
+ *
+ * @param resolver - Resolver instance that may implement issue tracking.
+ * @returns Collected issues or an empty list.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export declare function consumeAgentReferenceResolutionIssues(resolver?: AgentReferenceResolver): Array<AgentReferenceResolutionIssue>;

package/esm/src/book-2.0/agent-source/explicitFromCommitment.d.ts

@@ -0,0 +1,62 @@
+import type { string_book } from './string_book';
+/**
+ * One explicit `FROM` commitment written in a book.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export type ExplicitFromCommitment = {
+    /**
+     * Zero-based index of the line the commitment was found on, within the scanned lines.
+     */
+    readonly lineIndex: number;
+    /**
+     * Trimmed commitment content, empty string for a blank `FROM`.
+     */
+    readonly content: string;
+};
+/**
+ * Collects every explicit single-line `FROM` commitment of one book.
+ *
+ * This lightweight parser is intentionally limited to the subset needed by inheritance
+ * resolution so it stays safe to bundle into the Next.js proxy path.
+ *
+ * @param sourceLines - Book source already split into lines.
+ * @returns Found `FROM` commitments in source order, empty when the book declares no parent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export declare function collectExplicitFromCommitments(sourceLines: ReadonlyArray<string>): ReadonlyArray<ExplicitFromCommitment>;
+/**
+ * Returns the effective explicit `FROM` commitment of one book.
+ *
+ * A book may repeat `FROM`, in which case the last one wins and overrides every earlier one.
+ *
+ * @param agentSource - Raw book source.
+ * @returns The last explicit `FROM` commitment, or `undefined` when the book declares no parent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export declare function getEffectiveExplicitFromCommitment(agentSource: string_book): ExplicitFromCommitment | undefined;
+/**
+ * Returns the effective explicit `FROM` commitment content of one book.
+ *
+ * A book may repeat `FROM`, in which case the last one wins and overrides every earlier one.
+ *
+ * @param agentSource - Raw book source.
+ * @returns Trimmed commitment content, empty string for a blank explicit `FROM`, or `undefined` when `FROM` is absent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export declare function getExplicitFromCommitmentContent(agentSource: string_book): string | undefined;
+/**
+ * Returns true when one book declares no parent at all and therefore implicitly inherits from `@Adam`.
+ *
+ * Writing no `FROM` commitment is equivalent to writing `FROM @Adam`, so only an explicit
+ * `FROM @Null` / `FROM {Void}` turns the inheritance off.
+ *
+ * @param agentSource - Raw book source.
+ * @returns True when the implicit `@Adam` ancestor applies to this book.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export declare function isImplicitAdamInheritance(agentSource: string_book): boolean;

package/esm/src/book-2.0/agent-source/extractAgentReferenceTokens.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Matched compact agent reference token inside commitment content.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export type AgentReferenceTokenMatch = {
+    /**
+     * Original token text, for example `{Agent Name}` or `@AgentId`.
+     */
+    readonly token: string;
+    /**
+     * Token payload used for lookup.
+     */
+    readonly reference: string;
+    /**
+     * Zero-based character offset of `token` in the scanned content.
+     */
+    readonly index: number;
+    /**
+     * Length of `token` in characters.
+     */
+    readonly length: number;
+};
+/**
+ * Extracts compact agent-reference tokens from commitment content.
+ *
+ * @param content - Commitment content to inspect.
+ * @returns Matched compact reference tokens.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export declare function extractAgentReferenceTokens(content: string): Array<AgentReferenceTokenMatch>;

package/esm/src/book-2.0/agent-source/resolveInheritedAgentSource.d.ts

@@ -0,0 +1,73 @@
+import type { string_agent_url } from '../../types/string_agent_url';
+import type { string_book } from './string_book';
+import type { AgentReferenceResolver } from './AgentReferenceResolver';
+/**
+ * Shared options for resolving one agent source with inheritance and imports applied.
+ *
+ * @private internal utility of agent source resolution
+ */
+export type ResolveInheritedAgentSourceOptions = {
+    /** Current recursion depth, forwarded to the source importer. */
+    readonly recursionLevel?: number;
+    /**
+     * The URL of the Adam agent to use as the default ancestor
+     *
+     * @default 'https://core.ptbk.io/agents/adam'
+     */
+    readonly adamAgentUrl?: string_agent_url;
+    /**
+     * Custom resolver used to expand compact agent references.
+     */
+    readonly agentReferenceResolver?: AgentReferenceResolver;
+    /**
+     * Canonical URL of the currently resolved agent.
+     */
+    readonly currentAgentUrl?: string_agent_url;
+    /**
+     * Additional equivalent URLs that should be treated as the current agent while detecting cycles.
+     */
+    readonly currentAgentAliases?: ReadonlyArray<string_agent_url>;
+    /**
+     * Already visited agent URLs in the current resolution stack.
+     */
+    readonly inheritancePath?: ReadonlyArray<string_agent_url>;
+    /**
+     * Source importer supplied by the host application.
+     */
+    readonly agentSourceImporter: AgentSourceImporter;
+};
+/**
+ * Context passed to a custom agent source importer.
+ *
+ * @private internal utility of agent source resolution
+ */
+export type AgentSourceImporterContext = {
+    /**
+     * Commitment that requested the imported source.
+     */
+    readonly commitmentType: 'FROM' | 'IMPORT';
+    /**
+     * Import options propagated from the current resolution pass.
+     */
+    readonly importAgentOptions: {
+        readonly recursionLevel?: number;
+        readonly inheritancePath?: ReadonlyArray<string_agent_url>;
+    };
+};
+/**
+ * Loads and recursively resolves one referenced agent using the caller's transport.
+ *
+ * @private internal utility of agent source resolution
+ */
+export type AgentSourceImporter = (agentUrl: string_agent_url, context: AgentSourceImporterContext) => Promise<string_book>;
+/**
+ * Resolves agent source with inheritance (FROM commitment)
+ *
+ * It recursively fetches the parent agent source and merges it with the current source.
+ *
+ * @param agentSource The initial agent source
+ * @returns The resolved agent source with inheritance applied
+ *
+ * @private internal utility of agent source resolution
+ */
+export declare function resolveInheritedAgentSource(agentSource: string_book, options: ResolveInheritedAgentSourceOptions): Promise<string_book>;

package/esm/src/cli/cli-commands/coder/initializeCoderProjectConfiguration.d.ts

@@ -10,6 +10,7 @@ export type CoderInitializationSummary = {
     readonly promptsDoneDirectoryStatus: InitializationStatus;
     readonly promptsTemplatesDirectoryStatus: InitializationStatus;
     readonly agentsDirectoryStatus: InitializationStatus;
+    readonly adamAgentFileStatus: InitializationStatus;
     readonly envFileStatus: InitializationStatus;
     readonly gitignoreFileStatus: InitializationStatus;
     readonly packageJsonFileStatus: InitializationStatus;

package/esm/src/cli/cli-commands/common/LocalAgentBookCollection.d.ts

@@ -0,0 +1,46 @@
+import type { string_book } from '../../../book-2.0/agent-source/string_book';
+import type { TeammateProfile } from '../../../book-2.0/agent-source/TeammateProfileResolver';
+/**
+ * A book's source and identity, retaining its location for nested relative references.
+ *
+ * @private internal type of CLI agent resolution
+ */
+export type LocalAgentBook = {
+    readonly url: string;
+    readonly filePath?: string;
+    readonly source: string_book;
+    readonly profile: TeammateProfile;
+};
+/**
+ * Reads repository books and indexes their first-line names for CLI reference resolution.
+ *
+ * @private internal utility of CLI agent resolution
+ */
+export declare class LocalAgentBookCollection {
+    private readonly agentDirectoryPath;
+    private readonly currentWorkingDirectory;
+    private readonly booksByUrl;
+    private readonly booksByName;
+    /** Stable default ancestor selected from the initial repository scan. */
+    private adamAgentUrl;
+    /** Files initialized by this collection, for the coder's normal commit handling. */
+    readonly createdAgentBookPaths: string[];
+    /** Creates a collection rooted at the primary book's directory. */
+    constructor(agentDirectoryPath: string, currentWorkingDirectory: string);
+    /** Discovers nested books, including the hidden `.core` directory. */
+    initialize(): Promise<void>;
+    /** Identifies the default ancestor without creating an unused book for FROM null/void. */
+    getAdamAgentUrl(): string;
+    /** Resolves a unique first-line name, refusing ambiguous matches. */
+    findByName(name: string): LocalAgentBook;
+    /** Resolves a name, a path relative to its declaring book, or a path relative to the CLI cwd. */
+    resolveReference(reference: string, declaringBook: LocalAgentBook): Promise<string>;
+    /** Reads a local book once, canonicalizing symlinks so aliases cannot bypass cycle detection. */
+    readBook(filePath: string): Promise<LocalAgentBook>;
+    /** Loads a referenced remote book, while keeping local identifiers entirely inside the collection. */
+    getBook(url: string): Promise<LocalAgentBook>;
+    /** Adds a book under its normalized first-line name and preserves the display name for TEAM. */
+    private registerBook;
+    /** Walks real directories in deterministic order without following directory symlink loops. */
+    private readDirectory;
+}

package/esm/src/cli/cli-commands/common/createLocalAgentReferenceResolver.d.ts

@@ -0,0 +1,8 @@
+import type { AgentReferenceResolver } from '../../../book-2.0/agent-source/AgentReferenceResolver';
+import type { LocalAgentBook, LocalAgentBookCollection } from './LocalAgentBookCollection';
+/**
+ * Creates a resolver scoped to the book which declares each reference.
+ *
+ * @private internal utility of CLI agent resolution
+ */
+export declare function createLocalAgentReferenceResolver(collection: LocalAgentBookCollection, declaringBook: LocalAgentBook): AgentReferenceResolver;

package/esm/src/cli/cli-commands/common/ensureAdamAgentBook.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Adam's location relative to a directory of local agents.
+ *
+ * @private internal constant of CLI agent initialization
+ */
+export declare const ADAM_AGENT_BOOK_RELATIVE_PATH = ".core/adam.book";
+/**
+ * Creates the same Adam book used by the Agent Server without overwriting a project-owned book.
+ *
+ * @private internal utility of CLI agent initialization
+ */
+export declare function ensureAdamAgentBook(agentDirectoryPath: string): Promise<'created' | 'unchanged'>;

package/esm/src/cli/cli-commands/common/resolveBundledAgentBookPath.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Locates a bundled agent in either the source checkout or the generated CLI package.
+ *
+ * @private internal utility of CLI agent initialization
+ */
+export declare function resolveBundledAgentBookPath(relativeFilePath: string): Promise<string>;

package/esm/src/cli/cli-commands/common/resolveLocalAgentSource.d.ts

@@ -0,0 +1,19 @@
+import type { AgentReferenceResolver } from '../../../book-2.0/agent-source/AgentReferenceResolver';
+import type { string_book } from '../../../book-2.0/agent-source/string_book';
+/**
+ * Resolved source together with the profile resolver used when compiling TEAM commitments.
+ *
+ * @private internal type of CLI agent resolution
+ */
+export type ResolvedLocalAgentSource = {
+    readonly agentSource: string_book;
+    readonly agentReferenceResolver: AgentReferenceResolver;
+    /** Newly created books which the coder may include in its initialization commit. */
+    readonly createdAgentBookPaths: ReadonlyArray<string>;
+};
+/**
+ * Applies the shared Agent Server inheritance rules to a repository's local and remote books.
+ *
+ * @private internal utility of CLI agent resolution
+ */
+export declare function resolveLocalAgentSource(agentBookPath: string, currentWorkingDirectory: string): Promise<ResolvedLocalAgentSource>;

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.114.0-37`).
+ * It follows semantic versioning (e.g., `0.114.0-38`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.114.0-38",
+    "version": "0.114.0-39",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,

package/src/book-2.0/agent-source/AgentReferenceResolutionIssue.ts

@@ -0,0 +1,75 @@
+import type { BookCommitment } from '../../commitments/_base/BookCommitment';
+import type { AgentReferenceResolver } from './AgentReferenceResolver';
+
+/**
+ * Structured issue captured when compact agent reference resolution fails.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export type AgentReferenceResolutionIssue = {
+    /**
+     * Commitment where the unresolved token appeared.
+     */
+    readonly commitmentType: BookCommitment;
+
+    /**
+     * Original token text (for example `{Unknown Agent}` or `@UnknownAgent`).
+     */
+    readonly token: string;
+
+    /**
+     * Normalized token payload used for lookup.
+     */
+    readonly reference: string;
+
+    /**
+     * Human-readable explanation of why the token could not be resolved.
+     */
+    readonly message: string;
+};
+
+/**
+ * Extension implemented by resolvers that can expose accumulated resolution issues.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export type IssueTrackingAgentReferenceResolver = AgentReferenceResolver & {
+    /**
+     * Returns tracked issues and clears the internal queue.
+     */
+    consumeResolutionIssues(): Array<AgentReferenceResolutionIssue>;
+};
+
+/**
+ * Type guard for issue-tracking resolver implementations.
+ *
+ * @param resolver - Resolver instance to check.
+ * @returns True when the resolver provides `consumeResolutionIssues`.
+ */
+function isIssueTrackingAgentReferenceResolver(
+    resolver: AgentReferenceResolver,
+): resolver is IssueTrackingAgentReferenceResolver {
+    return typeof (resolver as Partial<IssueTrackingAgentReferenceResolver>).consumeResolutionIssues === 'function';
+}
+
+/**
+ * Drains unresolved compact-reference issues from a resolver when supported.
+ *
+ * @param resolver - Resolver instance that may implement issue tracking.
+ * @returns Collected issues or an empty list.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export function consumeAgentReferenceResolutionIssues(
+    resolver?: AgentReferenceResolver,
+): Array<AgentReferenceResolutionIssue> {
+    if (!resolver) {
+        return [];
+    }
+
+    if (!isIssueTrackingAgentReferenceResolver(resolver)) {
+        return [];
+    }
+
+    return resolver.consumeResolutionIssues();
+}

package/src/book-2.0/agent-source/explicitFromCommitment.ts

@@ -0,0 +1,132 @@
+import type { string_book } from './string_book';
+
+/**
+ * Commitment keyword that declares the parent agent of one book.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+const FROM_COMMITMENT_TYPE = 'FROM';
+
+/**
+ * Matches one standalone `FROM` commitment line and captures its inline content.
+ *
+ * The Book parser accepts horizontal whitespace between a commitment keyword and its value, so inheritance resolution
+ * must do the same. Keeping this pattern here makes every server-side consumer agree on which `FROM` lines are real.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+const FROM_COMMITMENT_LINE_PATTERN = new RegExp(`^${FROM_COMMITMENT_TYPE}(?:\\s+(.*))?$`);
+
+/**
+ * One explicit `FROM` commitment written in a book.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export type ExplicitFromCommitment = {
+    /**
+     * Zero-based index of the line the commitment was found on, within the scanned lines.
+     */
+    readonly lineIndex: number;
+
+    /**
+     * Trimmed commitment content, empty string for a blank `FROM`.
+     */
+    readonly content: string;
+};
+
+/**
+ * Collects every explicit single-line `FROM` commitment of one book.
+ *
+ * This lightweight parser is intentionally limited to the subset needed by inheritance
+ * resolution so it stays safe to bundle into the Next.js proxy path.
+ *
+ * @param sourceLines - Book source already split into lines.
+ * @returns Found `FROM` commitments in source order, empty when the book declares no parent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export function collectExplicitFromCommitments(
+    sourceLines: ReadonlyArray<string>,
+): ReadonlyArray<ExplicitFromCommitment> {
+    const explicitFromCommitments: Array<ExplicitFromCommitment> = [];
+    let hasSeenTitle = false;
+    let isInsideCodeBlock = false;
+
+    for (let lineIndex = 0; lineIndex < sourceLines.length; lineIndex++) {
+        const trimmedLine = (sourceLines[lineIndex] || '').trim();
+
+        if (!hasSeenTitle) {
+            if (!trimmedLine) {
+                continue;
+            }
+
+            hasSeenTitle = true;
+            continue;
+        }
+
+        if (trimmedLine.startsWith('```')) {
+            isInsideCodeBlock = !isInsideCodeBlock;
+            continue;
+        }
+
+        if (isInsideCodeBlock) {
+            continue;
+        }
+
+        const fromCommitmentMatch = FROM_COMMITMENT_LINE_PATTERN.exec(trimmedLine);
+        if (fromCommitmentMatch) {
+            explicitFromCommitments.push({
+                lineIndex,
+                content: (fromCommitmentMatch[1] || '').trim(),
+            });
+        }
+    }
+
+    return explicitFromCommitments;
+}
+
+/**
+ * Returns the effective explicit `FROM` commitment of one book.
+ *
+ * A book may repeat `FROM`, in which case the last one wins and overrides every earlier one.
+ *
+ * @param agentSource - Raw book source.
+ * @returns The last explicit `FROM` commitment, or `undefined` when the book declares no parent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export function getEffectiveExplicitFromCommitment(agentSource: string_book): ExplicitFromCommitment | undefined {
+    const explicitFromCommitments = collectExplicitFromCommitments(agentSource.split(/\r?\n/));
+    return explicitFromCommitments[explicitFromCommitments.length - 1];
+}
+
+/**
+ * Returns the effective explicit `FROM` commitment content of one book.
+ *
+ * A book may repeat `FROM`, in which case the last one wins and overrides every earlier one.
+ *
+ * @param agentSource - Raw book source.
+ * @returns Trimmed commitment content, empty string for a blank explicit `FROM`, or `undefined` when `FROM` is absent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export function getExplicitFromCommitmentContent(agentSource: string_book): string | undefined {
+    return getEffectiveExplicitFromCommitment(agentSource)?.content;
+}
+
+/**
+ * Returns true when one book declares no parent at all and therefore implicitly inherits from `@Adam`.
+ *
+ * Writing no `FROM` commitment is equivalent to writing `FROM @Adam`, so only an explicit
+ * `FROM @Null` / `FROM {Void}` turns the inheritance off.
+ *
+ * @param agentSource - Raw book source.
+ * @returns True when the implicit `@Adam` ancestor applies to this book.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export function isImplicitAdamInheritance(agentSource: string_book): boolean {
+    return getExplicitFromCommitmentContent(agentSource) === undefined;
+}
+
+// Note: [💞] Ignore a discrepancy between file name and exported helper names.

package/src/book-2.0/agent-source/extractAgentReferenceTokens.ts

@@ -0,0 +1,65 @@
+/**
+ * Matched compact agent reference token inside commitment content.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export type AgentReferenceTokenMatch = {
+    /**
+     * Original token text, for example `{Agent Name}` or `@AgentId`.
+     */
+    readonly token: string;
+
+    /**
+     * Token payload used for lookup.
+     */
+    readonly reference: string;
+
+    /**
+     * Zero-based character offset of `token` in the scanned content.
+     */
+    readonly index: number;
+
+    /**
+     * Length of `token` in characters.
+     */
+    readonly length: number;
+};
+
+/**
+ * Matches supported compact reference token syntaxes in commitment content.
+ */
+const AGENT_REFERENCE_TOKEN_REGEX = /(\{([^}]+)\}|@([A-Za-z0-9_-]+))/g;
+
+/**
+ * Extracts compact agent-reference tokens from commitment content.
+ *
+ * @param content - Commitment content to inspect.
+ * @returns Matched compact reference tokens.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export function extractAgentReferenceTokens(content: string): Array<AgentReferenceTokenMatch> {
+    const matches: Array<AgentReferenceTokenMatch> = [];
+    let match: RegExpExecArray | null;
+
+    AGENT_REFERENCE_TOKEN_REGEX.lastIndex = 0;
+
+    while ((match = AGENT_REFERENCE_TOKEN_REGEX.exec(content)) !== null) {
+        const token = match[1];
+        const reference = (match[2] ?? match[3] ?? '').trim();
+        const index = match.index;
+
+        if (!token || index === undefined) {
+            continue;
+        }
+
+        matches.push({
+            token,
+            reference,
+            index,
+            length: token.length,
+        });
+    }
+
+    return matches;
+}