@promptbook/cli 0.114.0-38 → 0.114.0-39

package/esm/index.es.js

@@ -1,13 +1,13 @@
 import colors from 'colors';
 import commander, { Option } from 'commander';
 import _spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
-import { writeFile, stat, readdir, mkdir, readFile, rm, cp, lstat, symlink, rename, unlink, appendFile, realpath, copyFile, statfs, access, constants, watch, rmdir } from 'fs/promises';
+import { writeFile, stat, readdir, mkdir, readFile, rm, cp, lstat, symlink, rename, unlink, appendFile, realpath, copyFile, statfs, access, constants as constants$1, watch, rmdir } from 'fs/promises';
 import { join, delimiter, relative, basename, resolve, dirname, isAbsolute, extname } from 'path';
 import { createHash, randomBytes } from 'crypto';
 import { spawn, spawnSync, execFile } from 'child_process';
 import moment from 'moment';
 import * as fs from 'fs';
-import { createWriteStream, mkdirSync, writeFileSync, statSync, readFileSync, existsSync, promises } from 'fs';
+import { createWriteStream, mkdirSync, writeFileSync, constants, statSync, readFileSync, existsSync, promises } from 'fs';
 import * as dotenv from 'dotenv';
 import * as readline from 'readline';
 import { createInterface, emitKeypressEvents, cursorTo, clearLine } from 'readline';
@@ -30,9 +30,9 @@ import ignore from 'ignore';
 import { EventEmitter } from 'events';
 import { tmpdir } from 'os';
 import { lookup, extension } from 'mime-types';
+import { pathToFileURL } from 'url';
 import papaparse from 'papaparse';
 import '@supabase/supabase-js';
-import { pathToFileURL } from 'url';
 
 // ⚠️ WARNING: This code has been generated so that any manual changes will be overwritten
 /**
@@ -48,7 +48,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.114.0-38';
+const PROMPTBOOK_ENGINE_VERSION = '0.114.0-39';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -1319,6 +1319,12 @@ const DEFAULT_INTERMEDIATE_FILES_STRATEGY = 'HIDE_AND_KEEP';
  * @public exported from `@promptbook/core`
  */
 const DEFAULT_MAX_PARALLEL_COUNT = 5; // <- TODO: [🤹‍♂️]
+/**
+ * The maximum depth to which recursion can occur
+ *
+ * @public exported from `@promptbook/core`
+ */
+const DEFAULT_MAX_RECURSION = 10;
 /**
  * The maximum number of attempts to execute LLM task before giving up
  *
@@ -5655,6 +5661,13 @@ const PSEUDO_AGENT_REFERENCE_KIND_MAP = {
     user: 'USER',
     ...Object.fromEntries(VOID_ALIAS_ENTRIES),
 };
+/**
+ * Maps pseudo-agent kinds to canonical pseudo-agent URLs.
+ */
+const PSEUDO_AGENT_URL_BY_KIND = {
+    USER: PSEUDO_AGENT_USER_URL,
+    VOID: PSEUDO_AGENT_VOID_URL,
+};
 /**
  * Unwraps a compact reference token (`{Name}` or `@Name`) to plain reference payload.
  *
@@ -5720,6 +5733,28 @@ function resolvePseudoAgentKindFromUrl(agentUrl) {
     }
     return null;
 }
+/**
+ * Checks whether a URL points to a pseudo-agent.
+ *
+ * @param agentUrl - URL to inspect.
+ * @returns True when the URL identifies a pseudo-agent.
+ *
+ * @private internal utility of pseudo-agent resolution
+ */
+function isPseudoAgentUrl(agentUrl) {
+    return resolvePseudoAgentKindFromUrl(agentUrl) !== null;
+}
+/**
+ * Creates canonical pseudo-agent URL by pseudo-agent kind.
+ *
+ * @param pseudoAgentKind - Pseudo-agent kind.
+ * @returns Canonical pseudo-agent URL.
+ *
+ * @private internal utility of pseudo-agent resolution
+ */
+function createPseudoAgentUrl(pseudoAgentKind) {
+    return PSEUDO_AGENT_URL_BY_KIND[pseudoAgentKind];
+}
 /**
  * Creates a deterministic human-readable pseudonym for the `{User}` pseudo-agent.
  *
@@ -5758,6 +5793,23 @@ function isVoidPseudoAgentReference(rawReference) {
     const normalizedReference = normalizePseudoReferenceKey(rawReference);
     return LEGACY_VOID_ALIASES.has(normalizedReference);
 }
+/**
+ * Checks whether a pseudo-agent can be used inside the specified commitment.
+ *
+ * `USER` is intentionally disallowed in FROM/IMPORT commitments.
+ *
+ * @param pseudoAgentKind - Pseudo-agent kind to validate.
+ * @param commitmentType - Commitment where it is used.
+ * @returns True when the pseudo-agent is allowed in the commitment.
+ *
+ * @private internal utility of pseudo-agent resolution
+ */
+function isPseudoAgentAllowedInCommitment(pseudoAgentKind, commitmentType) {
+    if (pseudoAgentKind === 'USER') {
+        return commitmentType === 'TEAM';
+    }
+    return true;
+}
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
@@ -39682,8 +39734,8 @@ function extractMcpServers(agentSource) {
 /**
  * Compiles agent source into the behavior text passed to CLI harness runners.
  */
-async function createAgentRunnerSystemMessage(agentSource) {
-    return formatAgentModelRequirementsForRunner(await createAgentModelRequirements(agentSource));
+async function createAgentRunnerSystemMessage(agentSource, options) {
+    return formatAgentModelRequirementsForRunner(await createAgentModelRequirements(agentSource, undefined, undefined, undefined, options));
 }
 /**
  * Formats prepared model requirements for a text-only CLI harness prompt.
@@ -43679,6 +43731,59 @@ function buildPromptSlug$1(templateSlugPrefix, title) {
 // Note: [🟡] Code for CLI command [generate-boilerplates](src/cli/cli-commands/coder/generate-boilerplates.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
+/**
+ * Locates a bundled agent in either the source checkout or the generated CLI package.
+ *
+ * @private internal utility of CLI agent initialization
+ */
+async function resolveBundledAgentBookPath(relativeFilePath) {
+    const candidates = [
+        join(__dirname, '..', relativeFilePath),
+        join(__dirname, '..', '..', '..', '..', relativeFilePath),
+    ];
+    for (const candidate of candidates) {
+        if (await stat(candidate).then((entry) => entry.isFile(), () => false)) {
+            return candidate;
+        }
+    }
+    throw new NotFoundError(spaceTrim$1((block) => `
+            Cannot find the bundled agent book \`${relativeFilePath}\`.
+
+            Checked:
+            ${block(candidates.map((candidate) => `- \`${candidate}\``).join('\n'))}
+        `));
+}
+
+/**
+ * Adam's location relative to a directory of local agents.
+ *
+ * @private internal constant of CLI agent initialization
+ */
+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
+ */
+async function ensureAdamAgentBook(agentDirectoryPath) {
+    const adamBookPath = join(agentDirectoryPath, ADAM_AGENT_BOOK_RELATIVE_PATH);
+    if (await stat(adamBookPath).then((entry) => entry.isFile(), () => false)) {
+        return 'unchanged';
+    }
+    const bundledAdamBookPath = await resolveBundledAgentBookPath('agents/default/.core/adam.book');
+    await mkdir(dirname(adamBookPath), { recursive: true });
+    try {
+        await copyFile(bundledAdamBookPath, adamBookPath, constants.COPYFILE_EXCL);
+        return 'created';
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            return 'unchanged';
+        }
+        throw error;
+    }
+}
+
 /**
  * Asks the user in the terminal to confirm one optional change.
  *
@@ -44482,29 +44587,9 @@ async function ensureCoderDeveloperAgentFile(projectPath) {
     if (await isExistingFile$2(absoluteFilePath)) {
         return 'unchanged';
     }
-    await copyFile(await resolveDefaultCoderDeveloperAgentFilePath(), absoluteFilePath);
+    await copyFile(await resolveBundledAgentBookPath(DEFAULT_CODER_DEVELOPER_AGENT_SOURCE_FILE_PATH), absoluteFilePath);
     return 'created';
 }
-/**
- * Resolves the bundled developer agent from a source checkout or generated CLI package.
- */
-async function resolveDefaultCoderDeveloperAgentFilePath() {
-    const candidates = [
-        join(__dirname, '..', DEFAULT_CODER_DEVELOPER_AGENT_SOURCE_FILE_PATH),
-        join(__dirname, '..', '..', '..', '..', DEFAULT_CODER_DEVELOPER_AGENT_SOURCE_FILE_PATH),
-    ];
-    for (const candidate of candidates) {
-        if (await isExistingFile$2(candidate)) {
-            return candidate;
-        }
-    }
-    throw new NotAllowed(spaceTrim$1(`
-            Cannot find the bundled Promptbook developer agent.
-
-            Checked:
-            ${candidates.map((candidate) => `- \`${candidate}\``).join('\n')}
-        `));
-}
 /**
  * Checks whether a path exists and is a file.
  */
@@ -44987,6 +45072,7 @@ async function initializeCoderProjectConfiguration(projectPath) {
     const promptsDoneDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DONE_DIRECTORY_PATH);
     const promptsTemplatesDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_TEMPLATES_DIRECTORY_PATH);
     const agentsDirectoryStatus = await ensureDirectory(projectPath, CODER_AGENTS_DIRECTORY_PATH);
+    const adamAgentFileStatus = await ensureAdamAgentBook(join(projectPath, CODER_AGENTS_DIRECTORY_PATH));
     const { envFileStatus, initializedEnvVariableNames } = await ensureCoderEnvFile(projectPath);
     const gitignoreFileStatus = await ensureCoderGitignoreFile(projectPath);
     const { status: packageJsonFileStatus, addedEntryKeys: addedPackageJsonScriptNames } = await ensureCoderPackageJsonFile(projectPath);
@@ -44997,6 +45083,7 @@ async function initializeCoderProjectConfiguration(projectPath) {
         promptsDoneDirectoryStatus,
         promptsTemplatesDirectoryStatus,
         agentsDirectoryStatus,
+        adamAgentFileStatus,
         envFileStatus,
         gitignoreFileStatus,
         packageJsonFileStatus,
@@ -45019,6 +45106,7 @@ function printInitializationSummary(summary) {
     printInitializationStatusLine('prompts/done/', summary.promptsDoneDirectoryStatus);
     printInitializationStatusLine('prompts/templates/', summary.promptsTemplatesDirectoryStatus);
     printInitializationStatusLine('agents/', summary.agentsDirectoryStatus);
+    printInitializationStatusLine(`${CODER_AGENTS_DIRECTORY_PATH}/${ADAM_AGENT_BOOK_RELATIVE_PATH}`, summary.adamAgentFileStatus);
     printInitializationStatusLine('.env', summary.envFileStatus);
     printInitializationStatusLine('.gitignore', summary.gitignoreFileStatus);
     printInitializationStatusLine('package.json', summary.packageJsonFileStatus);
@@ -45093,6 +45181,7 @@ function $initializeCoderInitCommand(program) {
                 - prompts/done/
                 ${block(listDefaultCoderProjectPromptTemplateDisplayPaths())}
                 - ${CODER_DEVELOPER_AGENT_FILE_PATH}
+                - ${CODER_AGENTS_DIRECTORY_PATH}/${ADAM_AGENT_BOOK_RELATIVE_PATH}
                 - ${AGENTS_FILE_PATH}
                 - .gitignore with local artifacts from every supported harness
                 - package.json
@@ -45237,8 +45326,7 @@ function $initializeCoderListCommand(program) {
         const runnerOptions = normalizePromptRunnerSelectionCliOptions(cliOptions, { isAgentRequired: false });
         const resolvedCoderAgentBook = agent === undefined
             ? undefined
-            : await (await Promise.resolve().then(function () { return resolveCoderAgent$1; }))
-                .resolveCoderAgentBook(agent, process.cwd());
+            : await (await Promise.resolve().then(function () { return resolveCoderAgent$1; })).resolveCoderAgentBook(agent, process.cwd());
         const promptRunnerIdentity = runnerOptions.agentName === undefined &&
             runnerOptions.model === undefined &&
             resolvedCoderAgentBook === undefined
@@ -45995,6 +46083,8 @@ function $initializeCoderRunCommand(program) {
             ${block(QUESTIONS_DESCRIPTION)}
 
             Features:
+            - Resolves FROM, IMPORT and TEAM by agent name, book-relative path, project path or URL
+            - Creates a missing .core/adam.book beside the selected agent for default inheritance
             - Automatically stages and commits changes with agent identity unless --no-commit is used
             - Commits only the prompt file and the files the coding agent has changed, leaving unrelated changes alone
             - Refuses to start on a dirty working tree unless --git-changes says what should happen with the changes
@@ -46968,7 +47058,7 @@ function $provideFilesystemForNode(options) {
     return {
         stat,
         access,
-        constants,
+        constants: constants$1,
         readFile,
         writeFile,
         readdir,
@@ -75829,6 +75919,929 @@ var findUnwrittenPrompts$1 = /*#__PURE__*/Object.freeze({
     findUnwrittenPrompts: findUnwrittenPrompts
 });
 
+/**
+ * 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+(.*))?$`);
+/**
+ * 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
+ */
+function collectExplicitFromCommitments(sourceLines) {
+    const explicitFromCommitments = [];
+    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
+ */
+function getEffectiveExplicitFromCommitment(agentSource) {
+    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
+ */
+function getExplicitFromCommitmentContent(agentSource) {
+    var _a;
+    return (_a = getEffectiveExplicitFromCommitment(agentSource)) === null || _a === void 0 ? void 0 : _a.content;
+}
+// Note: [💞] Ignore a discrepancy between file name and exported helper names.
+
+/**
+ * Type guard for issue-tracking resolver implementations.
+ *
+ * @param resolver - Resolver instance to check.
+ * @returns True when the resolver provides `consumeResolutionIssues`.
+ */
+function isIssueTrackingAgentReferenceResolver(resolver) {
+    return typeof resolver.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
+ */
+function consumeAgentReferenceResolutionIssues(resolver) {
+    if (!resolver) {
+        return [];
+    }
+    if (!isIssueTrackingAgentReferenceResolver(resolver)) {
+        return [];
+    }
+    return resolver.consumeResolutionIssues();
+}
+
+/**
+ * Gets the corpus of an agent source (removes title and trailing status)
+ *
+ * @param agentSource The agent source
+ * @returns The agent source corpus
+ */
+function getAgentSourceCorpus(agentSource) {
+    // Remove trailing OPEN or CLOSED if present
+    const agentSourceWithoutStatus = agentSource.replace(/\n?(OPEN|CLOSED)\s*$/i, '');
+    // <- TODO: [🈲] Simple and encapsulated way to get book corpus
+    // Remove the first line (title) from agent source
+    const agentSourceCorpus = spaceTrim(agentSourceWithoutStatus.replace(/^.*$/m, ''));
+    // <- TODO: [🈲] Simple and encapsulated way to get book corpus
+    return agentSourceCorpus;
+}
+/**
+ * Formats a resolver issue into a visible NOTE line in resolved agent source.
+ *
+ * @param issue - Tracked missing-reference issue.
+ * @returns Single-line NOTE statement.
+ */
+function formatResolutionIssueAsNote(issue) {
+    const commitmentType = issue.commitmentType === 'IMPORTS' ? 'IMPORT' : issue.commitmentType;
+    if (commitmentType === 'FROM') {
+        return `NOTE Referenced agent "${issue.reference}" in FROM commitment was not found. Inheritance skipped.`;
+    }
+    if (commitmentType === 'IMPORT') {
+        return `NOTE Referenced agent "${issue.reference}" in IMPORT commitment was not found. Import skipped.`;
+    }
+    if (commitmentType === 'TEAM') {
+        return `NOTE Referenced agent "${issue.reference}" in TEAM commitment was not found. Teammate disabled.`;
+    }
+    return `NOTE Referenced agent "${issue.reference}" in ${commitmentType} commitment was not found.`;
+}
+/**
+ * Appends NOTE lines for unresolved references while avoiding duplicates.
+ *
+ * @param targetChunks - Output chunks being assembled for the resolved book.
+ * @param issues - Missing-reference issues to materialize into NOTE lines.
+ */
+function appendResolutionIssueNotes(targetChunks, issues) {
+    const seenIssueKeys = new Set();
+    for (const issue of issues) {
+        const key = `${issue.commitmentType}:${issue.reference}`.toLowerCase();
+        if (seenIssueKeys.has(key)) {
+            continue;
+        }
+        seenIssueKeys.add(key);
+        targetChunks.push(formatResolutionIssueAsNote(issue), '');
+    }
+}
+/**
+ * Inserts NOTE lines right after the title line in a book.
+ *
+ * @param agentSource - Original agent source.
+ * @param notes - NOTE lines to insert.
+ * @returns Updated book with notes placed after the title.
+ */
+function insertNotesAfterTitle(agentSource, notes) {
+    if (notes.length === 0) {
+        return agentSource;
+    }
+    const sourceLines = spaceTrim(agentSource).split(/\r?\n/);
+    const titleLine = sourceLines[0] || '';
+    const restLines = sourceLines.slice(1);
+    const nextLines = [titleLine, '', ...notes, '', ...restLines];
+    return padBook(validateBook(nextLines.join('\n')));
+}
+/**
+ * Resolves the effective `FROM` parent URL using only lightweight commitment parsing.
+ *
+ * @param rawAgentSource - Original source used for diagnostics.
+ * @param agentReferenceResolver - Optional compact-reference resolver.
+ * @returns Valid parent URL, explicit `null` for `FROM VOID`/blank `FROM`, or `undefined` when `FROM` is absent.
+ */
+async function resolveParentAgentUrlFromCommitments(rawAgentSource, agentReferenceResolver) {
+    const explicitFromContent = getExplicitFromCommitmentContent(rawAgentSource);
+    if (explicitFromContent === undefined) {
+        return undefined;
+    }
+    let resolvedParentReference = explicitFromContent.trim();
+    if (agentReferenceResolver && resolvedParentReference) {
+        resolvedParentReference = (await agentReferenceResolver.resolveCommitmentContent('FROM', resolvedParentReference)).trim();
+    }
+    if (!resolvedParentReference || isVoidPseudoAgentReference(resolvedParentReference)) {
+        return null;
+    }
+    if (!isValidAgentUrl(resolvedParentReference)) {
+        throw new ParseError(spaceTrim((block) => `
+                    Invalid parent agent URL in FROM "${resolvedParentReference}" commitment:
+
+                    \`\`\`book
+                    ${block(rawAgentSource)}
+                    \`\`\`
+            
+                `));
+    }
+    return resolvedParentReference;
+}
+/**
+ * Normalizes agent URLs used for cycle detection and lineage reporting.
+ *
+ * @param agentUrl - Raw agent URL.
+ * @returns URL without trailing slashes.
+ */
+function normalizeAgentUrl(agentUrl) {
+    return agentUrl.replace(/\/+$/g, '');
+}
+/**
+ * Builds the current resolution lineage ending with the agent being resolved now.
+ *
+ * @param options - Resolution options with current agent metadata.
+ * @returns Ordered lineage without empty values.
+ */
+function createResolutionLineage(options) {
+    const lineage = [...((options === null || options === void 0 ? void 0 : options.inheritancePath) || [])];
+    if (options === null || options === void 0 ? void 0 : options.currentAgentUrl) {
+        lineage.push(options.currentAgentUrl);
+    }
+    for (const alias of (options === null || options === void 0 ? void 0 : options.currentAgentAliases) || []) {
+        lineage.push(alias);
+    }
+    return [...new Set(lineage.map(normalizeAgentUrl))];
+}
+/**
+ * Finds a cycle that would be closed by resolving one more agent reference.
+ *
+ * @param referenceUrl - Next agent reference to resolve.
+ * @param options - Current resolution options.
+ * @returns Cycle details, or `null` when the reference is not in the current lineage.
+ *
+ * @private internal helper for Agents Server inherited/imported agent resolution
+ */
+function findResolutionCycle(referenceUrl, options) {
+    const normalizedReferenceUrl = normalizeAgentUrl(referenceUrl);
+    const lineage = createResolutionLineage(options);
+    const cycleStartIndex = lineage.findIndex((visitedUrl) => visitedUrl === normalizedReferenceUrl);
+    if (cycleStartIndex === -1) {
+        return null;
+    }
+    return { normalizedReferenceUrl, lineage, cycleStartIndex };
+}
+/**
+ * Creates the shared import context used throughout one resolution pass.
+ *
+ * @param options - Resolution options passed to `resolveInheritedAgentSource`.
+ * @returns Normalized shared import context.
+ */
+function createAgentImportContext(options) {
+    return {
+        adamAgentUrl: (options === null || options === void 0 ? void 0 : options.adamAgentUrl) || 'https://core.ptbk.io/agents/adam',
+        agentReferenceResolver: options === null || options === void 0 ? void 0 : options.agentReferenceResolver,
+        importAgentOptions: {
+            recursionLevel: (options === null || options === void 0 ? void 0 : options.recursionLevel) || 0,
+            inheritancePath: createResolutionLineage(options),
+        },
+        agentSourceImporter: options.agentSourceImporter,
+        resolutionOptions: options,
+    };
+}
+/**
+ * Computes the effective parent URL after applying explicit `FROM` and Adam fallback rules.
+ *
+ * @param resolvedParentAgentUrl - Parent URL derived from lightweight commitment parsing.
+ * @param hasExplicitFromCommitment - Whether the source explicitly declared `FROM`.
+ * @param adamAgentUrl - Default Adam ancestor URL.
+ * @param currentAgentUrl - Canonical URL of the source being resolved.
+ * @param currentAgentAliases - Additional URLs that identify the source being resolved.
+ * @param agentSource - Raw source used for unexpected diagnostics.
+ * @returns Effective parent URL or `null` when inheritance is disabled.
+ */
+function determineParentAgentUrl(resolvedParentAgentUrl, hasExplicitFromCommitment, adamAgentUrl, currentAgentUrl, currentAgentAliases, agentSource) {
+    if (isValidAgentUrl(resolvedParentAgentUrl)) {
+        return resolvedParentAgentUrl;
+    }
+    if (resolvedParentAgentUrl === null && hasExplicitFromCommitment) {
+        return null;
+    }
+    if (resolvedParentAgentUrl === undefined || resolvedParentAgentUrl === null) {
+        const currentAgentUrls = [currentAgentUrl, ...(currentAgentAliases || [])].filter((agentUrl) => Boolean(agentUrl));
+        const isCurrentAgentAdam = currentAgentUrls.some((agentUrl) => normalizeAgentUrl(agentUrl) === normalizeAgentUrl(adamAgentUrl));
+        return isCurrentAgentAdam ? null : adamAgentUrl;
+    }
+    throw new ParseError(spaceTrim((block) => `
+                Invalid parent agent URL in FROM "${resolvedParentAgentUrl}" commitment:
+
+                \`\`\`book
+                ${block(agentSource || '')}
+                \`\`\`
+            `));
+}
+/**
+ * Imports one referenced agent and returns only its body content ready to be embedded as a NOTE block.
+ *
+ * @param agentUrl - Canonical referenced agent URL.
+ * @param commitmentType - Commitment that introduced the reference.
+ * @param context - Shared import context for the current resolution pass.
+ * @returns Imported source body without title/status.
+ */
+async function importAgentCorpus(agentUrl, commitmentType, context) {
+    assertNoResolutionCycle(agentUrl, commitmentType, context.resolutionOptions);
+    const importedAgentSource = await context.agentSourceImporter(agentUrl, {
+        commitmentType,
+        importAgentOptions: context.importAgentOptions,
+    });
+    return getAgentSourceCorpus(importedAgentSource);
+}
+/**
+ * Resolves the effective parent state before the source body is rewritten.
+ *
+ * @param agentSource - Raw child agent source.
+ * @param context - Shared import context for the current resolution pass.
+ * @returns Parent URL, imported parent body, and unresolved `FROM` issues.
+ */
+async function resolveParentAgentContext(agentSource, context) {
+    var _a, _b;
+    const explicitFromContent = getExplicitFromCommitmentContent(agentSource);
+    const hasExplicitFromCommitment = explicitFromContent !== undefined;
+    const resolvedParentAgentUrl = await resolveParentAgentUrlFromCommitments(agentSource, context.agentReferenceResolver);
+    const fromResolutionIssues = consumeAgentReferenceResolutionIssues(context.agentReferenceResolver).filter((issue) => issue.commitmentType === 'FROM');
+    const parentAgentUrl = determineParentAgentUrl(resolvedParentAgentUrl, hasExplicitFromCommitment, context.adamAgentUrl, (_a = context.resolutionOptions) === null || _a === void 0 ? void 0 : _a.currentAgentUrl, (_b = context.resolutionOptions) === null || _b === void 0 ? void 0 : _b.currentAgentAliases, agentSource);
+    const isCyclicFrom = Boolean(parentAgentUrl && findResolutionCycle(parentAgentUrl, context.resolutionOptions));
+    const effectiveParentAgentUrl = isCyclicFrom ? null : parentAgentUrl;
+    const parentAgentSourceCorpus = effectiveParentAgentUrl
+        ? await importAgentCorpus(effectiveParentAgentUrl, 'FROM', context)
+        : null;
+    return {
+        // A parent that closes the current lineage has the same runtime effect as `FROM @Null`.
+        parentAgentUrl: effectiveParentAgentUrl,
+        parentAgentSourceCorpus,
+        fromResolutionIssues,
+        isCyclicFrom,
+    };
+}
+/**
+ * Formats one embedded agent body into the NOTE block used by inheritance/import resolution.
+ *
+ * @param noteLine - First NOTE line describing the embedded source.
+ * @param sourceCorpus - Imported source body to embed.
+ * @returns Multi-line NOTE block.
+ */
+function createEmbeddedAgentSourceNote(noteLine, sourceCorpus) {
+    return spaceTrim((block) => `
+
+            ${noteLine}
+            ${block(sourceCorpus)}
+
+            NOTE ===========
+    `);
+}
+/**
+ * Resolves one `IMPORT ...` line into embedded source or leaves non-agent imports untouched.
+ *
+ * @param line - Current source line.
+ * @param context - Shared import context for the current resolution pass.
+ * @returns Output lines replacing the original line.
+ */
+async function resolveImportCommitmentLine(line, context) {
+    const rawImportedUrlOrPath = line
+        .trim()
+        .replace(/^IMPORTS?\s+/, '')
+        .trim();
+    let importedUrlOrPath = rawImportedUrlOrPath;
+    let importResolutionIssues = [];
+    if (context.agentReferenceResolver && rawImportedUrlOrPath) {
+        try {
+            importedUrlOrPath = await context.agentReferenceResolver.resolveCommitmentContent('IMPORT', rawImportedUrlOrPath);
+        }
+        catch (error) {
+            console.warn('[AgentReferenceResolver] Failed to resolve IMPORT commitment references:', error);
+        }
+        finally {
+            importResolutionIssues = consumeAgentReferenceResolutionIssues(context.agentReferenceResolver).filter((issue) => issue.commitmentType === 'IMPORT' || issue.commitmentType === 'IMPORTS');
+        }
+    }
+    const resolvedChunks = [];
+    appendResolutionIssueNotes(resolvedChunks, importResolutionIssues);
+    if (!importedUrlOrPath) {
+        return resolvedChunks;
+    }
+    if (!isValidAgentUrl(importedUrlOrPath)) {
+        resolvedChunks.push(line);
+        return resolvedChunks;
+    }
+    const importedAgentUrl = importedUrlOrPath;
+    const importedAgentSourceCorpus = await importAgentCorpus(importedAgentUrl, 'IMPORT', context);
+    resolvedChunks.push(createEmbeddedAgentSourceNote(`NOTE Imported from ${importedAgentUrl}`, importedAgentSourceCorpus), '');
+    return resolvedChunks;
+}
+/**
+ * Resolves the effective `FROM ...` line into inherited content or fallback NOTE lines.
+ *
+ * @param line - Current source line.
+ * @param parentContext - Effective parent state computed earlier in the resolution.
+ * @returns Output lines and remaining `FROM` issues.
+ */
+function resolveFromCommitmentLine(line, parentContext) {
+    if (parentContext.parentAgentUrl === null) {
+        const agentSourceChunks = [parentContext.isCyclicFrom ? 'FROM @Null' : line];
+        if (parentContext.fromResolutionIssues.length > 0) {
+            appendResolutionIssueNotes(agentSourceChunks, parentContext.fromResolutionIssues);
+        }
+        return {
+            agentSourceChunks,
+            fromResolutionIssues: [],
+        };
+    }
+    if (parentContext.parentAgentSourceCorpus) {
+        return {
+            agentSourceChunks: [
+                createEmbeddedAgentSourceNote(`NOTE Inherited FROM ${parentContext.parentAgentUrl}`, parentContext.parentAgentSourceCorpus),
+                '', // <- Note: Add an extra newline for separation
+            ],
+            fromResolutionIssues: parentContext.fromResolutionIssues,
+        };
+    }
+    return {
+        agentSourceChunks: [
+            `NOTE Parent agent "${parentContext.parentAgentUrl}" was not found or could not be loaded. Inheritance skipped.`,
+            '',
+        ],
+        fromResolutionIssues: parentContext.fromResolutionIssues,
+    };
+}
+/**
+ * Finds the `FROM` lines that a later `FROM` takes precedence over.
+ *
+ * A book is allowed to repeat `FROM`; the last one wins, so every earlier one is dropped instead of being resolved.
+ * The Book editor warns about this while the author is still writing the book.
+ *
+ * @param explicitFromCommitments - Explicit parent declarations found in source order.
+ * @returns Zero-based indexes of every overridden `FROM` line, empty when at most one `FROM` is present.
+ */
+function collectOverriddenFromLineIndexes(explicitFromCommitments) {
+    return new Set(explicitFromCommitments.slice(0, -1).map((explicitFromCommitment) => explicitFromCommitment.lineIndex));
+}
+/**
+ * Rewrites the source body line by line while delegating each branching step to a focused helper.
+ *
+ * @param agentSource - Raw child agent source.
+ * @param context - Shared import context for the current resolution pass.
+ * @param parentContext - Effective parent state computed earlier in the resolution.
+ * @returns Rewritten chunks plus final `FROM` bookkeeping.
+ */
+async function resolveAgentSourceBuild(agentSource, context, parentContext) {
+    const agentSourceChunks = spaceTrim(agentSource).split(/\r?\n/);
+    const resolvedAgentSourceChunks = [];
+    const explicitFromCommitments = collectExplicitFromCommitments(agentSourceChunks);
+    const effectiveFromCommitment = explicitFromCommitments[explicitFromCommitments.length - 1];
+    const overriddenFromLineIndexes = collectOverriddenFromLineIndexes(explicitFromCommitments);
+    let isFromResolved = false;
+    let isInsideCodeBlock = false;
+    let fromResolutionIssues = parentContext.fromResolutionIssues;
+    // <- TODO: [🈲] Simple and encapsulated way to split book into commitments
+    for (let lineIndex = 0; lineIndex < agentSourceChunks.length; lineIndex++) {
+        const line = agentSourceChunks[lineIndex] || '';
+        if (line.trim().startsWith('```')) {
+            isInsideCodeBlock = !isInsideCodeBlock;
+        }
+        if (isInsideCodeBlock || line.trim().startsWith('```')) {
+            resolvedAgentSourceChunks.push(line);
+            continue;
+        }
+        // Note: A repeated `FROM` is overridden by the last one, so the outdated line is dropped from the resolved source.
+        if (overriddenFromLineIndexes.has(lineIndex)) {
+            continue;
+        }
+        if (lineIndex > 0 && /^IMPORTS?\s+/.test(line.trim())) {
+            resolvedAgentSourceChunks.push(...(await resolveImportCommitmentLine(line, context)));
+            continue;
+        }
+        if ((effectiveFromCommitment === null || effectiveFromCommitment === void 0 ? void 0 : effectiveFromCommitment.lineIndex) === lineIndex) {
+            const resolvedFromCommitment = resolveFromCommitmentLine(line, {
+                ...parentContext,
+                fromResolutionIssues,
+            });
+            resolvedAgentSourceChunks.push(...resolvedFromCommitment.agentSourceChunks);
+            fromResolutionIssues = resolvedFromCommitment.fromResolutionIssues;
+            isFromResolved = true;
+            continue;
+        }
+        resolvedAgentSourceChunks.push(line);
+    }
+    // <- TODO: [🈲] Simple and encapsulated way to split book into commitments
+    return {
+        agentSourceChunks: resolvedAgentSourceChunks,
+        isFromResolved,
+        fromResolutionIssues,
+    };
+}
+/**
+ * Materializes the implicit Adam inheritance block when no explicit `FROM ...` was present.
+ *
+ * @param build - Current rewritten source build.
+ * @param parentContext - Effective parent state computed earlier in the resolution.
+ * @param adamAgentUrl - Default Adam ancestor URL.
+ * @returns Updated source build with implicit Adam inheritance applied when needed.
+ */
+function applyImplicitAdamInheritance(build, parentContext, adamAgentUrl) {
+    if (build.isFromResolved || parentContext.parentAgentUrl !== adamAgentUrl) {
+        return build;
+    }
+    const titleLine = build.agentSourceChunks[0] || '';
+    const restLines = build.agentSourceChunks.slice(1);
+    const agentSourceChunks = [titleLine, ''];
+    if (parentContext.parentAgentSourceCorpus) {
+        agentSourceChunks.push(createEmbeddedAgentSourceNote(`NOTE Inherited Adam FROM ${parentContext.parentAgentUrl}`, parentContext.parentAgentSourceCorpus), ...restLines);
+    }
+    else {
+        agentSourceChunks.push(`NOTE Default parent agent "${parentContext.parentAgentUrl}" was not found or could not be loaded. Inheritance skipped.`, '', ...restLines);
+    }
+    return {
+        ...build,
+        agentSourceChunks,
+    };
+}
+/**
+ * Validates and pads the resolved source, then inserts any deferred unresolved-`FROM` notes.
+ *
+ * @param build - Final rewritten source build.
+ * @returns Valid resolved book.
+ */
+function finalizeResolvedAgentSource(build) {
+    const resolvedAgentSource = padBook(validateBook(build.agentSourceChunks.join('\n')));
+    if (build.fromResolutionIssues.length === 0) {
+        return resolvedAgentSource;
+    }
+    const unresolvedFromNotes = build.fromResolutionIssues.map(formatResolutionIssueAsNote);
+    return insertNotesAfterTitle(resolvedAgentSource, unresolvedFromNotes);
+}
+/**
+ * Throws when a `FROM`/`IMPORT` edge would create an inheritance cycle.
+ *
+ * @param referenceUrl - Next referenced agent URL.
+ * @param commitmentType - Commitment that introduced the reference.
+ * @param options - Current resolution options.
+ */
+function assertNoResolutionCycle(referenceUrl, commitmentType, options) {
+    const resolutionCycle = findResolutionCycle(referenceUrl, options);
+    if (!resolutionCycle) {
+        return;
+    }
+    const cycleChain = [
+        ...resolutionCycle.lineage.slice(resolutionCycle.cycleStartIndex),
+        resolutionCycle.normalizedReferenceUrl,
+    ]
+        .map((visitedUrl) => `- \`${visitedUrl}\``)
+        .join('\n');
+    throw new ParseError(spaceTrim((block) => `
+                Cyclic \`${commitmentType}\` reference detected while resolving agent source.
+
+                Resolution chain:
+                ${block(cycleChain)}
+            `));
+}
+/**
+ * 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
+ */
+async function resolveInheritedAgentSource(agentSource, options) {
+    const context = createAgentImportContext(options);
+    const parentContext = await resolveParentAgentContext(agentSource, context);
+    const resolvedBuild = await resolveAgentSourceBuild(agentSource, context, parentContext);
+    const finalizedBuild = applyImplicitAdamInheritance(resolvedBuild, parentContext, context.adamAgentUrl);
+    return finalizeResolvedAgentSource(finalizedBuild);
+}
+// TODO: [🈲] Create a function that can manipulate books by modifying commitments, splitting the book up into commitments or syntactic tokens, and editing or deleting these via object methods.
+
+/**
+ * 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
+ */
+function extractAgentReferenceTokens(content) {
+    var _a, _b;
+    const matches = [];
+    let match;
+    AGENT_REFERENCE_TOKEN_REGEX.lastIndex = 0;
+    while ((match = AGENT_REFERENCE_TOKEN_REGEX.exec(content)) !== null) {
+        const token = match[1];
+        const reference = ((_b = (_a = match[2]) !== null && _a !== void 0 ? _a : match[3]) !== null && _b !== void 0 ? _b : '').trim();
+        const index = match.index;
+        if (!token || index === undefined) {
+            continue;
+        }
+        matches.push({
+            token,
+            reference,
+            index,
+            length: token.length,
+        });
+    }
+    return matches;
+}
+
+/**
+ * Creates a resolver scoped to the book which declares each reference.
+ *
+ * @private internal utility of CLI agent resolution
+ */
+function createLocalAgentReferenceResolver(collection, declaringBook) {
+    /** Resolves pseudo-agents using the same aliases and restrictions as the Agent Server. */
+    async function resolveReference(commitmentType, reference) {
+        const pseudoAgentKind = resolvePseudoAgentKindFromReference(reference);
+        if (!pseudoAgentKind) {
+            return collection.resolveReference(reference, declaringBook);
+        }
+        if (!isPseudoAgentAllowedInCommitment(pseudoAgentKind, commitmentType)) {
+            throw new ParseError(spaceTrim$1(`Pseudo-agent \`${reference}\` cannot be used in \`${commitmentType}\`.`));
+        }
+        if (pseudoAgentKind === 'VOID' && commitmentType === 'FROM') {
+            return VOID_PSEUDO_AGENT_REFERENCE;
+        }
+        if (pseudoAgentKind === 'VOID' && (commitmentType === 'IMPORT' || commitmentType === 'IMPORTS')) {
+            return '';
+        }
+        return createPseudoAgentUrl(pseudoAgentKind);
+    }
+    return {
+        resolveCommitmentContent: async (commitmentType, content) => {
+            const tokens = extractAgentReferenceTokens(content);
+            if (tokens.length === 0) {
+                if (commitmentType !== 'TEAM' && content.trim()) {
+                    return resolveReference(commitmentType, content.trim());
+                }
+                return content;
+            }
+            const parts = [];
+            let previousEnd = 0;
+            for (const token of tokens) {
+                parts.push(content.slice(previousEnd, token.index));
+                parts.push(await resolveReference(commitmentType, token.reference));
+                previousEnd = token.index + token.length;
+            }
+            parts.push(content.slice(previousEnd));
+            return parts.join('');
+        },
+    };
+}
+
+/**
+ * Internal URLs allow the shared Book commitments to identify local books without an HTTP server.
+ * These identifiers are always intercepted by this collection and are never fetched.
+ */
+const LOCAL_AGENT_URL_PREFIX = 'https://local-agent.promptbook/';
+/**
+ * Directories which cannot contain project-owned agent definitions.
+ */
+const IGNORED_DIRECTORY_NAMES = new Set(['.git', 'node_modules']);
+/**
+ * Reads repository books and indexes their first-line names for CLI reference resolution.
+ *
+ * @private internal utility of CLI agent resolution
+ */
+class LocalAgentBookCollection {
+    /** Creates a collection rooted at the primary book's directory. */
+    constructor(agentDirectoryPath, currentWorkingDirectory) {
+        this.agentDirectoryPath = agentDirectoryPath;
+        this.currentWorkingDirectory = currentWorkingDirectory;
+        this.booksByUrl = new Map();
+        this.booksByName = new Map();
+        /** Files initialized by this collection, for the coder's normal commit handling. */
+        this.createdAgentBookPaths = [];
+    }
+    /** Discovers nested books, including the hidden `.core` directory. */
+    async initialize() {
+        await this.readDirectory(this.agentDirectoryPath);
+    }
+    /** Identifies the default ancestor without creating an unused book for FROM null/void. */
+    getAdamAgentUrl() {
+        var _a;
+        (_a = this.adamAgentUrl) !== null && _a !== void 0 ? _a : (this.adamAgentUrl = this.booksByName.has(normalizeAgentName('Adam'))
+            ? this.findByName('Adam').url
+            : createLocalAgentBookUrl(join(this.agentDirectoryPath, ADAM_AGENT_BOOK_RELATIVE_PATH)));
+        return this.adamAgentUrl;
+    }
+    /** Resolves a unique first-line name, refusing ambiguous matches. */
+    findByName(name) {
+        const matches = this.booksByName.get(normalizeAgentName(name)) || [];
+        if (matches.length === 1) {
+            return matches[0];
+        }
+        if (matches.length > 1) {
+            throw new ParseError(spaceTrim$1((block) => `
+                Agent reference \`${name}\` is ambiguous. Use an explicit book path.
+
+                Matching books:
+                ${block(matches.map((book) => `- \`${book.filePath || book.url}\``).join('\n'))}
+            `));
+        }
+        throw new NotFoundError(spaceTrim$1(`
+            Agent \`${name}\` was not found in \`${this.agentDirectoryPath}\` or its subdirectories.
+
+            References use the agent's **first-line name**. You can also use an explicit \`.book\` path or URL.
+        `));
+    }
+    /** Resolves a name, a path relative to its declaring book, or a path relative to the CLI cwd. */
+    async resolveReference(reference, declaringBook) {
+        const isRemoteReference = Boolean(isValidAgentUrl(reference));
+        if (isRemoteReference) {
+            return reference;
+        }
+        const isBookPath = /\.book$/i.test(reference) || isAbsolute(reference);
+        if (!isBookPath) {
+            if (normalizeAgentName(reference) === normalizeAgentName('Adam')) {
+                return this.getAdamAgentUrl();
+            }
+            return this.findByName(reference).url;
+        }
+        const isRelativeToBook = /^\.{1,2}[\\/]/.test(reference);
+        if (!declaringBook.filePath && isRelativeToBook) {
+            return new URL(reference.replaceAll('\\', '/'), declaringBook.url).href;
+        }
+        const directoryPath = isRelativeToBook && declaringBook.filePath ? dirname(declaringBook.filePath) : this.currentWorkingDirectory;
+        return (await this.readBook(resolve(directoryPath, reference))).url;
+    }
+    /** Reads a local book once, canonicalizing symlinks so aliases cannot bypass cycle detection. */
+    async readBook(filePath) {
+        try {
+            const canonicalFilePath = await realpath(filePath);
+            const url = createLocalAgentBookUrl(canonicalFilePath);
+            const existingBook = this.booksByUrl.get(url);
+            if (existingBook) {
+                return existingBook;
+            }
+            return this.registerBook(url, await readFile(canonicalFilePath, 'utf-8'), canonicalFilePath);
+        }
+        catch (error) {
+            if (['ENOENT', 'EISDIR', 'ENOTDIR'].includes(error.code || '')) {
+                throw new NotFoundError(spaceTrim$1(`Agent book \`${filePath}\` was not found or is not a file.`));
+            }
+            throw error;
+        }
+    }
+    /** Loads a referenced remote book, while keeping local identifiers entirely inside the collection. */
+    async getBook(url) {
+        var _a;
+        const existingBook = this.booksByUrl.get(url);
+        if (existingBook) {
+            return existingBook;
+        }
+        if (url === this.getAdamAgentUrl()) {
+            const adamBookPath = join(this.agentDirectoryPath, ADAM_AGENT_BOOK_RELATIVE_PATH);
+            if ((await ensureAdamAgentBook(this.agentDirectoryPath)) === 'created') {
+                this.createdAgentBookPaths.push(adamBookPath);
+            }
+            const adamBook = await this.readBook(adamBookPath);
+            this.booksByUrl.set(url, adamBook);
+            return adamBook;
+        }
+        if (url.startsWith(LOCAL_AGENT_URL_PREFIX)) {
+            throw new NotFoundError(spaceTrim$1(`Local agent book \`${url}\` is not registered.`));
+        }
+        const bookUrl = new URL(url);
+        if (!/\.(book|md)$/i.test(bookUrl.pathname) && !bookUrl.pathname.endsWith('/api/book')) {
+            bookUrl.pathname = bookUrl.pathname.replace(/\/$/, '') + '/api/book';
+        }
+        const response = await fetch(bookUrl.href);
+        if (!response.ok) {
+            throw new NotFoundError(spaceTrim$1(`Cannot load agent book \`${url}\`: **${response.status} ${response.statusText}**.`));
+        }
+        let source;
+        if ((_a = response.headers.get('content-type')) === null || _a === void 0 ? void 0 : _a.includes('application/json')) {
+            const payload = await response.json();
+            source = typeof payload === 'string' ? payload : payload === null || payload === void 0 ? void 0 : payload.source;
+        }
+        else {
+            source = await response.text();
+        }
+        if (typeof source !== 'string') {
+            throw new ParseError(spaceTrim$1(`Agent book \`${url}\` did not return a text source.`));
+        }
+        return this.registerBook(url, source);
+    }
+    /** Adds a book under its normalized first-line name and preserves the display name for TEAM. */
+    registerBook(url, source, filePath) {
+        const agentSource = source;
+        const parsedSource = parseAgentSource(agentSource);
+        const book = {
+            url,
+            filePath,
+            source: agentSource,
+            profile: {
+                agentName: parsedSource.meta.fullname || parsedSource.agentName,
+                personaDescription: parsedSource.personaDescription,
+            },
+        };
+        this.booksByUrl.set(url, book);
+        // Remote titles must not shadow repository-local names.
+        if (filePath) {
+            const agentName = normalizeAgentName(parsedSource.agentName);
+            this.booksByName.set(agentName, [...(this.booksByName.get(agentName) || []), book]);
+        }
+        return book;
+    }
+    /** Walks real directories in deterministic order without following directory symlink loops. */
+    async readDirectory(directoryPath) {
+        const entries = await readdir(directoryPath, { withFileTypes: true });
+        for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+            const entryPath = join(directoryPath, entry.name);
+            if (entry.isDirectory() && !IGNORED_DIRECTORY_NAMES.has(entry.name)) {
+                await this.readDirectory(entryPath);
+            }
+            else if (entry.isFile() && entry.name.toLowerCase().endsWith('.book')) {
+                await this.readBook(entryPath);
+            }
+        }
+    }
+}
+/** Creates an internal URL for a local path without requiring that the file already exists. */
+function createLocalAgentBookUrl(filePath) {
+    return LOCAL_AGENT_URL_PREFIX + encodeURIComponent(pathToFileURL(filePath).href);
+}
+
+/**
+ * Applies the shared Agent Server inheritance rules to a repository's local and remote books.
+ *
+ * @private internal utility of CLI agent resolution
+ */
+async function resolveLocalAgentSource(agentBookPath, currentWorkingDirectory) {
+    const collection = new LocalAgentBookCollection(dirname(agentBookPath), currentWorkingDirectory);
+    await collection.initialize();
+    const primaryBook = await collection.readBook(agentBookPath);
+    const adamAgentUrl = collection.getAdamAgentUrl();
+    /** Resolves each dependency with its own location and the current inheritance stack. */
+    async function resolveBook(book, inheritancePath = []) {
+        if (inheritancePath.length > DEFAULT_MAX_RECURSION) {
+            throw new ParseError(spaceTrim$1(`Agent inheritance exceeds **${DEFAULT_MAX_RECURSION}** levels at \`${book.filePath || book.url}\`.`));
+        }
+        const agentReferenceResolver = createLocalAgentReferenceResolver(collection, book);
+        const source = await resolveBookCommitmentReferences(book.source, agentReferenceResolver);
+        return resolveInheritedAgentSource(source, {
+            adamAgentUrl,
+            currentAgentUrl: book.url,
+            inheritancePath,
+            agentSourceImporter: async (url, context) => resolveBook(await collection.getBook(url), context.importAgentOptions.inheritancePath),
+        });
+    }
+    return {
+        agentSource: await resolveBook(primaryBook),
+        agentReferenceResolver: {
+            ...createLocalAgentReferenceResolver(collection, primaryBook),
+            resolveTeammateProfile: async (url) => {
+                if (isPseudoAgentUrl(url)) {
+                    return null;
+                }
+                const book = await collection.getBook(url);
+                const parsedSource = parseAgentSource(await resolveBook(book));
+                return {
+                    agentName: book.profile.agentName,
+                    personaDescription: parsedSource.personaDescription,
+                };
+            },
+        },
+        createdAgentBookPaths: collection.createdAgentBookPaths,
+    };
+}
+/**
+ * Resolves reference blocks before embedding dependencies so inherited TEAM paths keep their original directory.
+ * Parser-provided locations keep examples, unknown commitments and ordinary prose untouched.
+ */
+async function resolveBookCommitmentReferences(source, resolver) {
+    var _a;
+    const parsedSource = parseAgentSourceWithCommitments(source);
+    const lines = source.split(/\r?\n/);
+    const commitmentStartLines = [...parsedSource.commitments, ...(parsedSource.unknownCommitments || [])]
+        .map((commitment) => commitment.lineNumber - 1)
+        .sort((left, right) => left - right);
+    const effectiveFrom = getEffectiveExplicitFromCommitment(source);
+    for (const commitment of [...parsedSource.commitments].reverse()) {
+        if (!['FROM', 'IMPORT', 'IMPORTS', 'TEAM'].includes(commitment.type)) {
+            continue;
+        }
+        const startLine = commitment.lineNumber - 1;
+        if (commitment.type === 'FROM' && (effectiveFrom === null || effectiveFrom === void 0 ? void 0 : effectiveFrom.lineIndex) !== startLine) {
+            continue;
+        }
+        let endLine = (_a = commitmentStartLines.find((lineNumber) => lineNumber > startLine)) !== null && _a !== void 0 ? _a : lines.length;
+        // A horizontal rule also terminates a commitment before the next registered keyword.
+        for (let lineIndex = startLine + 1; lineIndex < endLine; lineIndex++) {
+            if (/^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/.test(lines[lineIndex] || '')) {
+                endLine = lineIndex;
+                break;
+            }
+        }
+        const content = await resolver.resolveCommitmentContent(commitment.type, commitment.content);
+        const commitmentType = commitment.type === 'IMPORTS' ? 'IMPORT' : commitment.type;
+        const replacement = content.trim()
+            ? `${commitmentType} ${content}\n`
+            : commitmentType === 'FROM'
+                ? 'FROM @Null\n'
+                : '';
+        lines.splice(startLine, endLine - startLine, ...replacement.split('\n'));
+    }
+    return lines.join('\n');
+}
+
 /**
  * Reads an optional agent `.book` file and prepares the references that route prompts to it.
  *
@@ -75873,9 +76886,14 @@ async function resolveCoderAgent(agentBookReference, currentWorkingDirectory) {
     if (resolvedAgentBook === undefined) {
         return undefined;
     }
+    const resolvedSource = await resolveLocalAgentSource(resolve(currentWorkingDirectory, agentBookReference.trim()), currentWorkingDirectory);
     return {
         ...resolvedAgentBook,
-        systemMessage: await createAgentRunnerSystemMessage(resolvedAgentBook.agentSource),
+        agentSource: resolvedSource.agentSource,
+        systemMessage: await createAgentRunnerSystemMessage(resolvedSource.agentSource, {
+            agentReferenceResolver: resolvedSource.agentReferenceResolver,
+        }),
+        createdAgentBookPaths: resolvedSource.createdAgentBookPaths,
     };
 }
 /**
@@ -76996,6 +78014,23 @@ function listenForCoderRunControls() {
     });
 }
 
+/**
+ * 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.
+ */
+async function commitInitializedAgentBooks(projectPath, createdAgentBookPaths) {
+    if (createdAgentBookPaths.length === 0) {
+        return;
+    }
+    const createdPaths = new Set(createdAgentBookPaths.map((filePath) => resolve(filePath)));
+    const changedPaths = await listWorkingTreeChangedFiles(projectPath);
+    const relevantPaths = changedPaths.filter((filePath) => createdPaths.has(resolve(projectPath, filePath)));
+    if (relevantPaths.length === 0) {
+        return;
+    }
+    await commitChanges('Initialize Adam agent', { projectPath, relevantPaths });
+}
+
 /**
  * Checks working tree clean.
  */
@@ -80365,6 +81400,9 @@ async function runCodexPrompts(providedOptions) {
         if (await runDryRunIfRequested(options)) {
             return;
         }
+        if (!options.noCommit && resolvedCoderAgent) {
+            await commitInitializedAgentBooks(process.cwd(), resolvedCoderAgent.createdAgentBookPaths);
+        }
         const { runner, actualRunnerModel, runnerMetadata: harnessRunnerMetadata } = resolvePromptRunner(options);
         // Note: The harness only knows itself, so the Book agent it runs as is joined here - this is the single
         //       place where the whole run report of prompt status lines and run traces is put together