@promptbook/cli 0.114.0-35 → 0.114.0-39

package/src/cli/$initializePromptbookCliProgram.ts

@@ -0,0 +1,87 @@
+import type { Command } from 'commander';
+import { CLAIM } from '../config';
+import { PROMPTBOOK_ENGINE_VERSION } from '../version';
+import { $initializeAboutCommand } from './cli-commands/about';
+import { $initializeAgentCommand } from './cli-commands/agent';
+import { $initializeAgentFolderCommand } from './cli-commands/agent-folder';
+import { $initializeAgentsServerCommand } from './cli-commands/agents-server';
+import { $initializeCoderCommand } from './cli-commands/coder';
+import { $initializeHelloCommand } from './cli-commands/hello';
+import { $initializeListModelsCommand } from './cli-commands/list-models';
+import { $initializeListScrapersCommand } from './cli-commands/list-scrapers';
+import { $initializeLoginCommand } from './cli-commands/login';
+import { $initializeMakeCommand } from './cli-commands/make';
+import { $initializePrettifyCommand } from './cli-commands/prettify';
+import { $initializeRunCommand } from './cli-commands/run';
+import { $initializeStartAgentsServerCommand } from './cli-commands/start-agents-server';
+import { $initializeStartPipelinesServerCommand } from './cli-commands/start-pipelines-server';
+import { $initializeTestCommand } from './cli-commands/test-command';
+import { $addGlobalOptionsToCommand } from './common/$addGlobalOptionsToCommand';
+import { $deprecateCliCommand } from './common/$deprecateCliCommand';
+
+/**
+ * Shared deprecation text for top-level CLI commands backed by the old pipeline system.
+ */
+const OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE = 'This command is part of the old pipeline system.';
+
+/**
+ * Shared deprecation text for top-level CLI commands backed by the old pre-agent system.
+ */
+const OLD_SYSTEM_DEPRECATION_MESSAGE = 'This command is part of the old system.';
+
+/**
+ * Deprecation guidance for top-level `ptbk` commands that remain for compatibility.
+ */
+const DEPRECATED_TOP_LEVEL_COMMAND_MESSAGES: Readonly<Record<string, string>> = {
+    run: OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
+    login: OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
+    make: OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
+    prettify: OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
+    test: OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
+    'list-models': OLD_SYSTEM_DEPRECATION_MESSAGE,
+    'list-scrapers': OLD_SYSTEM_DEPRECATION_MESSAGE,
+    'start-agents-server': 'Use `ptbk agents-server start` instead.',
+    'start-pipelines-server': OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
+};
+
+/**
+ * Registers the CLI commands on a fresh Commander program without parsing arguments or running an action.
+ * Tests can configure output and exit handling before registration, so subcommands inherit those settings.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function $initializePromptbookCliProgram(program: Command): void {
+    program.name('promptbook');
+    program.alias('ptbk');
+    program.version(PROMPTBOOK_ENGINE_VERSION);
+    program.description(CLAIM);
+
+    // Commands are listed in registration order. Keep `coder` first and hide deprecated commands below.
+    $initializeCoderCommand(program);
+    $initializeAgentCommand(program);
+    $initializeAgentFolderCommand(program);
+    $initializeAgentsServerCommand(program);
+    $initializeAboutCommand(program);
+    $initializeHelloCommand(program);
+    $initializeRunCommand(program);
+    $initializeLoginCommand(program);
+    $initializeMakeCommand(program);
+    $initializePrettifyCommand(program);
+    $initializeTestCommand(program);
+    $initializeListModelsCommand(program);
+    $initializeListScrapersCommand(program);
+    $initializeStartAgentsServerCommand(program);
+    $initializeStartPipelinesServerCommand(program);
+
+    for (const command of program.commands) {
+        const deprecationMessage = DEPRECATED_TOP_LEVEL_COMMAND_MESSAGES[command.name()];
+
+        if (deprecationMessage !== undefined) {
+            $deprecateCliCommand(command, deprecationMessage);
+        }
+    }
+
+    program.commands.forEach($addGlobalOptionsToCommand);
+}
+
+// Note: [🟡] Code for CLI command registration [$initializePromptbookCliProgram](src/cli/$initializePromptbookCliProgram.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/coder/ensureCoderDeveloperAgentFile.ts

@@ -1,7 +1,6 @@
 import { copyFile, stat } from 'fs/promises';
 import { join } from 'path';
-import { spaceTrim } from 'spacetrim';
-import { NotAllowed } from '../../../errors/NotAllowed';
+import { resolveBundledAgentBookPath } from '../common/resolveBundledAgentBookPath';
 import type { InitializationStatus } from './boilerplateTemplates';
 
 /**
@@ -36,35 +35,10 @@ export async function ensureCoderDeveloperAgentFile(projectPath: string): Promis
         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(): Promise<string> {
-    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(candidate)) {
-            return candidate;
-        }
-    }
-
-    throw new NotAllowed(
-        spaceTrim(`
-            Cannot find the bundled Promptbook developer agent.
-
-            Checked:
-            ${candidates.map((candidate) => `- \`${candidate}\``).join('\n')}
-        `),
-    );
-}
-
 /**
  * Checks whether a path exists and is a file.
  */

package/src/cli/cli-commands/coder/init.ts

@@ -3,6 +3,7 @@ import type {
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { ADAM_AGENT_BOOK_RELATIVE_PATH } from '../common/ensureAdamAgentBook';
 import type { CoderGitSyncCliOptions } from '../common/coderGitSyncCliOptions';
 import {
     addCoderGitSyncOptions,
@@ -22,7 +23,7 @@ import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
 import { AGENTS_FILE_PATH } from './agentsFile';
 import { DEFAULT_BOILERPLATE_COUNT } from './boilerplateCount';
 import { getDefaultCoderProjectPromptTemplateDefinitions, PROMPTS_DIRECTORY_PATH } from './boilerplateTemplates';
-import { CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
+import { CODER_AGENTS_DIRECTORY_PATH, CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
 import { isDirectoryEmpty } from './ensureDirectory';
 import { formatDisplayPath } from './formatDisplayPath';
 import { generatePromptBoilerplate } from './generate-boilerplates';
@@ -61,6 +62,7 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
                 - 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

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

@@ -1,3 +1,5 @@
+import { join } from 'path';
+import { ensureAdamAgentBook } from '../common/ensureAdamAgentBook';
 import type { InitializationStatus } from './boilerplateTemplates';
 import {
     PROMPTS_DIRECTORY_PATH,
@@ -24,6 +26,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;
@@ -46,6 +49,7 @@ export async function initializeCoderProjectConfiguration(projectPath: string):
     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 } =
@@ -61,6 +65,7 @@ export async function initializeCoderProjectConfiguration(projectPath: string):
         promptsDoneDirectoryStatus,
         promptsTemplatesDirectoryStatus,
         agentsDirectoryStatus,
+        adamAgentFileStatus,
         envFileStatus,
         gitignoreFileStatus,
         packageJsonFileStatus,

package/src/cli/cli-commands/coder/list.ts

@@ -52,7 +52,8 @@ export function $initializeCoderListCommand(program: Program): $side_effect {
                 readonly priority?: number;
                 readonly minPriority?: number;
                 readonly maxPriority?: number;
-            } & PromptRunnerSelectionCliOptions & CoderAgentCliOptions;
+            } & PromptRunnerSelectionCliOptions &
+                CoderAgentCliOptions;
             const runnerOptions = normalizePromptRunnerSelectionCliOptions(
                 cliOptions as PromptRunnerSelectionCliOptions,
                 { isAgentRequired: false },
@@ -60,8 +61,9 @@ export function $initializeCoderListCommand(program: Program): $side_effect {
             const resolvedCoderAgentBook =
                 agent === undefined
                     ? undefined
-                    : await (await import('../../../../scripts/run-codex-prompts/common/resolveCoderAgent'))
-                          .resolveCoderAgentBook(agent, process.cwd());
+                    : await (
+                          await import('../../../../scripts/run-codex-prompts/common/resolveCoderAgent')
+                      ).resolveCoderAgentBook(agent, process.cwd());
             const promptRunnerIdentity =
                 runnerOptions.agentName === undefined &&
                 runnerOptions.model === undefined &&

package/src/cli/cli-commands/coder/printInitializationSummary.ts

@@ -1,4 +1,6 @@
 import colors from 'colors';
+import { ADAM_AGENT_BOOK_RELATIVE_PATH } from '../common/ensureAdamAgentBook';
+import { CODER_AGENTS_DIRECTORY_PATH } from './ensureCoderDeveloperAgentFile';
 import type { InitializationStatus } from './boilerplateTemplates';
 import type { CoderReferencedArtifactStatus } from './coderReferencedArtifacts';
 import { formatDisplayPath } from './formatDisplayPath';
@@ -15,6 +17,10 @@ export function printInitializationSummary(summary: CoderInitializationSummary):
     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);

package/src/cli/cli-commands/coder/run.ts

@@ -54,6 +54,8 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             ${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
@@ -194,7 +196,8 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 readonly auto: boolean;
                 readonly autoMigrate: boolean;
                 readonly allowDestructiveAutoMigrate: boolean;
-            } & PromptRunnerCliOptions & CoderAgentCliOptions;
+            } & PromptRunnerCliOptions &
+                CoderAgentCliOptions;
 
             const configuredTestCommand = normalizeCommandOptionValue(test);
             const testCommand = configuredTestCommand ?? (testBefore === 'no' ? undefined : DEFAULT_CODER_TEST_COMMAND);

package/src/cli/cli-commands/coder/server.ts

@@ -166,7 +166,8 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 readonly auto: boolean;
                 readonly autoMigrate: boolean;
                 readonly allowDestructiveAutoMigrate: boolean;
-            } & PromptRunnerCliOptions & CoderAgentCliOptions;
+            } & PromptRunnerCliOptions &
+                CoderAgentCliOptions;
 
             const port = parseCoderServerPort(rawPort);
             const testCommand = normalizeCommandOptionValue(test);

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

@@ -0,0 +1,220 @@
+import { readFile, readdir, realpath } from 'fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'path';
+import { pathToFileURL } from 'url';
+import { spaceTrim } from 'spacetrim';
+import { normalizeAgentName } from '../../../book-2.0/agent-source/normalizeAgentName';
+import { parseAgentSource } from '../../../book-2.0/agent-source/parseAgentSource';
+import type { string_book } from '../../../book-2.0/agent-source/string_book';
+import type { TeammateProfile } from '../../../book-2.0/agent-source/TeammateProfileResolver';
+import { NotFoundError } from '../../../errors/NotFoundError';
+import { ParseError } from '../../../errors/ParseError';
+import { isValidAgentUrl } from '../../../utils/validators/url/isValidAgentUrl';
+import { ADAM_AGENT_BOOK_RELATIVE_PATH, ensureAdamAgentBook } from './ensureAdamAgentBook';
+
+/**
+ * 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;
+};
+
+/**
+ * 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
+ */
+export class LocalAgentBookCollection {
+    private readonly booksByUrl = new Map<string, LocalAgentBook>();
+    private readonly booksByName = new Map<string, LocalAgentBook[]>();
+    /** Stable default ancestor selected from the initial repository scan. */
+    private adamAgentUrl: string | undefined;
+    /** Files initialized by this collection, for the coder's normal commit handling. */
+    public readonly createdAgentBookPaths: string[] = [];
+
+    /** Creates a collection rooted at the primary book's directory. */
+    public constructor(private readonly agentDirectoryPath: string, private readonly currentWorkingDirectory: string) {}
+
+    /** Discovers nested books, including the hidden `.core` directory. */
+    public async initialize(): Promise<void> {
+        await this.readDirectory(this.agentDirectoryPath);
+    }
+
+    /** Identifies the default ancestor without creating an unused book for FROM null/void. */
+    public getAdamAgentUrl(): string {
+        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. */
+    public findByName(name: string): LocalAgentBook {
+        const matches = this.booksByName.get(normalizeAgentName(name)) || [];
+        if (matches.length === 1) {
+            return matches[0]!;
+        }
+
+        if (matches.length > 1) {
+            throw new ParseError(
+                spaceTrim(
+                    (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(`
+            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. */
+    public async resolveReference(reference: string, declaringBook: LocalAgentBook): Promise<string> {
+        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. */
+    public async readBook(filePath: string): Promise<LocalAgentBook> {
+        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 as NodeJS.ErrnoException).code || '')) {
+                throw new NotFoundError(spaceTrim(`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. */
+    public async getBook(url: string): Promise<LocalAgentBook> {
+        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(`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(`Cannot load agent book \`${url}\`: **${response.status} ${response.statusText}**.`),
+            );
+        }
+        let source: unknown;
+        if (response.headers.get('content-type')?.includes('application/json')) {
+            const payload: unknown = await response.json();
+            source = typeof payload === 'string' ? payload : (payload as { source?: unknown } | null)?.source;
+        } else {
+            source = await response.text();
+        }
+        if (typeof source !== 'string') {
+            throw new ParseError(spaceTrim(`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. */
+    private registerBook(url: string, source: string, filePath?: string): LocalAgentBook {
+        const agentSource = source as string_book;
+        const parsedSource = parseAgentSource(agentSource);
+        const book: LocalAgentBook = {
+            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. */
+    private async readDirectory(directoryPath: string): Promise<void> {
+        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: string): string {
+    return LOCAL_AGENT_URL_PREFIX + encodeURIComponent(pathToFileURL(filePath).href);
+}

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

@@ -0,0 +1,62 @@
+import { spaceTrim } from 'spacetrim';
+import type { AgentReferenceResolver } from '../../../book-2.0/agent-source/AgentReferenceResolver';
+import { extractAgentReferenceTokens } from '../../../book-2.0/agent-source/extractAgentReferenceTokens';
+import {
+    createPseudoAgentUrl,
+    isPseudoAgentAllowedInCommitment,
+    resolvePseudoAgentKindFromReference,
+    VOID_PSEUDO_AGENT_REFERENCE,
+} from '../../../book-2.0/agent-source/pseudoAgentReferences';
+import type { BookCommitment } from '../../../commitments/_base/BookCommitment';
+import { ParseError } from '../../../errors/ParseError';
+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 function createLocalAgentReferenceResolver(
+    collection: LocalAgentBookCollection,
+    declaringBook: LocalAgentBook,
+): AgentReferenceResolver {
+    /** Resolves pseudo-agents using the same aliases and restrictions as the Agent Server. */
+    async function resolveReference(commitmentType: BookCommitment, reference: string): Promise<string> {
+        const pseudoAgentKind = resolvePseudoAgentKindFromReference(reference);
+        if (!pseudoAgentKind) {
+            return collection.resolveReference(reference, declaringBook);
+        }
+        if (!isPseudoAgentAllowedInCommitment(pseudoAgentKind, commitmentType)) {
+            throw new ParseError(spaceTrim(`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: string[] = [];
+            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('');
+        },
+    };
+}

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

@@ -0,0 +1,40 @@
+import { constants } from 'fs';
+import { copyFile, mkdir, stat } from 'fs/promises';
+import { dirname, join } from 'path';
+import { resolveBundledAgentBookPath } from './resolveBundledAgentBookPath';
+
+/**
+ * Adam's location relative to a directory of local agents.
+ *
+ * @private internal constant of CLI agent initialization
+ */
+export 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 async function ensureAdamAgentBook(agentDirectoryPath: string): Promise<'created' | 'unchanged'> {
+    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 as NodeJS.ErrnoException).code === 'EEXIST') {
+            return 'unchanged';
+        }
+        throw error;
+    }
+}

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

@@ -0,0 +1,38 @@
+import { stat } from 'fs/promises';
+import { join } from 'path';
+import { spaceTrim } from 'spacetrim';
+import { NotFoundError } from '../../../errors/NotFoundError';
+
+/**
+ * Locates a bundled agent in either the source checkout or the generated CLI package.
+ *
+ * @private internal utility of CLI agent initialization
+ */
+export async function resolveBundledAgentBookPath(relativeFilePath: string): Promise<string> {
+    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(
+            (block) => `
+            Cannot find the bundled agent book \`${relativeFilePath}\`.
+
+            Checked:
+            ${block(candidates.map((candidate) => `- \`${candidate}\``).join('\n'))}
+        `,
+        ),
+    );
+}