@promptbook/cli 0.112.0-112 → 0.112.0-114

package/src/cli/cli-commands/agent/agentCliOptions.ts

@@ -0,0 +1,92 @@
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+import { NotAllowed } from '../../../errors/NotAllowed';
+import type {
+    NormalizedPromptRunnerSelectionCliOptions,
+    PromptRunnerSelectionCliOptions,
+} from '../common/promptRunnerCliOptions';
+import { normalizePromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
+
+/**
+ * Commander option bag shared by `ptbk agent` subcommands.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export type AgentCommandCliOptions = PromptRunnerSelectionCliOptions & {
+    readonly agent?: string;
+    readonly context?: string;
+    readonly message?: string;
+};
+
+/**
+ * Normalized shared options used by local `ptbk agent` subcommands.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export type NormalizedAgentCommandRunnerOptions = NormalizedPromptRunnerSelectionCliOptions & {
+    readonly isVerbose: boolean;
+};
+
+/**
+ * Normalizes shared runner flags for local agent subcommands.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export function normalizeAgentCommandRunnerOptions(
+    cliOptions: AgentCommandCliOptions,
+    command: Program,
+): NormalizedAgentCommandRunnerOptions {
+    return {
+        ...normalizePromptRunnerSelectionCliOptions(cliOptions, {
+            isAgentRequired: true,
+        }),
+        isVerbose: resolveCommandVerboseOption(command),
+    };
+}
+
+// Note: [🟡] Code for CLI command options [agent](src/cli/cli-commands/agent/agentCliOptions.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and exported helper names
+
+/**
+ * Returns the required agent book path from Commander options.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export function resolveRequiredAgentPath(cliOptions: AgentCommandCliOptions): string {
+    const agentPath = cliOptions.agent?.trim();
+
+    if (!agentPath) {
+        throw new NotAllowed('Pass an agent book path in `--agent`.');
+    }
+
+    return agentPath;
+}
+
+/**
+ * Returns the required single-turn user message from Commander options.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export function resolveRequiredAgentMessage(cliOptions: AgentCommandCliOptions): string {
+    const message = cliOptions.message?.trim();
+
+    if (!message) {
+        throw new NotAllowed('Pass a non-empty user message in `--message`.');
+    }
+
+    return message;
+}
+
+/**
+ * Resolves the inherited `--verbose` flag from the current Commander command chain.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+function resolveCommandVerboseOption(command: Program): boolean {
+    const globalOptions = command.optsWithGlobals() as {
+        readonly verbose?: boolean;
+    };
+
+    return globalOptions.verbose ?? false;
+}

package/src/cli/cli-commands/agent/chat.ts

@@ -0,0 +1,54 @@
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+import { spaceTrim } from 'spacetrim';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { handleActionErrors } from '../common/handleActionErrors';
+import {
+    addPromptRunnerRuntimeOptions,
+    addPromptRunnerSelectionOptions,
+    PROMPT_RUNNER_DESCRIPTION,
+} from '../common/promptRunnerCliOptions';
+import type { AgentCommandCliOptions } from './agentCliOptions';
+import { normalizeAgentCommandRunnerOptions, resolveRequiredAgentPath } from './agentCliOptions';
+
+/**
+ * Initializes `agent chat` command for Promptbook CLI utilities.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export function $initializeAgentChatCommand(program: Program): $side_effect {
+    const command = program.command('chat');
+    command.description(
+        spaceTrim(`
+            Run an interactive CLI chat with one Promptbook agent book
+
+            ${PROMPT_RUNNER_DESCRIPTION}
+        `),
+    );
+
+    command.requiredOption('--agent <agent-book-path>', 'Path to the agent .book file');
+    addPromptRunnerSelectionOptions(command);
+    addPromptRunnerRuntimeOptions(command);
+    command.option('--context <context-or-file>', 'Append extra context either inline or from a file path');
+
+    command.action(
+        handleActionErrors(async (cliOptions, commandProgram) => {
+            const options = cliOptions as AgentCommandCliOptions;
+            const runnerOptions = normalizeAgentCommandRunnerOptions(options, commandProgram as Program);
+            const { runAgentChat } = await import('../../../../scripts/run-agent-chat/runAgentChat');
+
+            await runAgentChat({
+                agentPath: resolveRequiredAgentPath(options),
+                context: options.context,
+                currentWorkingDirectory: process.cwd(),
+                ...runnerOptions,
+            });
+        }),
+    );
+}
+
+// Note: [🟡] Code for CLI command [agent chat](src/cli/cli-commands/agent/chat.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/cli/cli-commands/agent/exec.ts

@@ -0,0 +1,60 @@
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+import { spaceTrim } from 'spacetrim';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { handleActionErrors } from '../common/handleActionErrors';
+import {
+    addPromptRunnerRuntimeOptions,
+    addPromptRunnerSelectionOptions,
+    PROMPT_RUNNER_DESCRIPTION,
+} from '../common/promptRunnerCliOptions';
+import type { AgentCommandCliOptions } from './agentCliOptions';
+import {
+    normalizeAgentCommandRunnerOptions,
+    resolveRequiredAgentMessage,
+    resolveRequiredAgentPath,
+} from './agentCliOptions';
+
+/**
+ * Initializes `agent exec` command for Promptbook CLI utilities.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export function $initializeAgentExecCommand(program: Program): $side_effect {
+    const command = program.command('exec');
+    command.description(
+        spaceTrim(`
+            Run one non-interactive message with a Promptbook agent book and print the answer
+
+            ${PROMPT_RUNNER_DESCRIPTION}
+        `),
+    );
+
+    command.requiredOption('--agent <agent-book-path>', 'Path to the agent .book file');
+    command.requiredOption('--message <message>', 'User message to send to the agent');
+    addPromptRunnerSelectionOptions(command);
+    addPromptRunnerRuntimeOptions(command);
+    command.option('--context <context-or-file>', 'Append extra context either inline or from a file path');
+
+    command.action(
+        handleActionErrors(async (cliOptions, commandProgram) => {
+            const options = cliOptions as AgentCommandCliOptions;
+            const runnerOptions = normalizeAgentCommandRunnerOptions(options, commandProgram as Program);
+            const { runAgentExec } = await import('../../../../scripts/run-agent-chat/runAgentExec');
+
+            await runAgentExec({
+                agentPath: resolveRequiredAgentPath(options),
+                context: options.context,
+                message: resolveRequiredAgentMessage(options),
+                currentWorkingDirectory: process.cwd(),
+                ...runnerOptions,
+            });
+        }),
+    );
+}
+
+// Note: [🟡] Code for CLI command [agent exec](src/cli/cli-commands/agent/exec.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/cli/cli-commands/agent.ts

@@ -0,0 +1,44 @@
+import colors from 'colors';
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+import { spaceTrim } from 'spacetrim';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+import { $initializeAgentChatCommand } from './agent/chat';
+import { $initializeAgentExecCommand } from './agent/exec';
+
+/**
+ * Initializes `agent` command with subcommands for Promptbook CLI utilities.
+ *
+ * The agent command runs one `.book` source directly through a selected CLI harness:
+ * - chat: Run an interactive terminal chat session
+ * - exec: Send one message and print the response
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export function $initializeAgentCommand(program: Program): $side_effect {
+    const agentCommand = program.command('agent');
+    agentCommand.description(
+        spaceTrim(`
+            Run a Promptbook agent book directly in the terminal
+
+            Subcommands:
+            - chat: Run an interactive terminal chat session
+            - exec: Send one message and print the response
+        `),
+    );
+
+    $initializeAgentChatCommand(agentCommand);
+    $initializeAgentExecCommand(agentCommand);
+
+    agentCommand.action(() => {
+        console.info(colors.yellow('Please specify a subcommand.'));
+        console.info('');
+        agentCommand.help();
+    });
+}
+
+// Note: [🟡] Code for CLI command [agent](src/cli/cli-commands/agent.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/cli/cli-commands/agents-server/startAgentsServer.ts

@@ -6,7 +6,7 @@ import { join } from 'path';
 import * as dotenv from 'dotenv';
 import { spaceTrim } from 'spacetrim';
 import type { ThinkingLevel } from '../coder/ThinkingLevel';
-import type { PromptRunnerAgentName } from '../common/promptRunnerCliOptions';
+import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
 import { NotAllowed } from '../../../errors/NotAllowed';
 import type { number_port } from '../../../types/number_positive';
 import { resolvePromptbookTemporaryPath } from '../../../utils/filesystem/promptbookTemporaryPath';
@@ -107,13 +107,6 @@ const PTBK_AGENTS_SERVER_SQLITE_PATH_ENV = 'PTBK_AGENTS_SERVER_SQLITE_PATH';
  */
 const PTBK_HOSTNAME_ENV = 'PTBK_HOSTNAME';
 
-/**
- * Explicit installed `.env` file passed by standalone VPS pm2/runtime launchers.
- *
- * @private internal constant of `ptbk agents-server`
- */
-const PTBK_AGENTS_SERVER_ENV_FILE_ENV = 'PTBK_AGENTS_SERVER_ENV_FILE';
-
 /**
  * Entropy size for the local-only token shared by the CLI pump and the Next app.
  *
@@ -135,7 +128,7 @@ export type AgentsServerNextRuntimeMode = 'start' | 'dev';
  */
 export type StartAgentsServerOptions = {
     readonly port: number_port;
-    readonly agentName: PromptRunnerAgentName;
+    readonly agentName: PromptRunnerHarnessName;
     readonly model?: string;
     readonly noUi: boolean;
     readonly thinkingLevel?: ThinkingLevel;
@@ -362,20 +355,11 @@ async function prepareAgentsServerDevelopmentRuntime(
 }
 
 /**
- * Loads Agents Server runtime environment from the installed `.env` file when explicitly configured and falls back
- * to the launch-directory `.env`.
+ * Loads launch-directory `.env` values without overriding explicit process environment.
  *
  * @private internal utility of `ptbk agents-server`
  */
 export function loadAgentsServerProjectEnvironment(launchWorkingDirectory: string): void {
-    const explicitEnvFilePath = process.env[PTBK_AGENTS_SERVER_ENV_FILE_ENV]?.trim();
-    if (explicitEnvFilePath) {
-        const explicitLoadResult = dotenv.config({ path: explicitEnvFilePath, override: true });
-        if (!explicitLoadResult.error) {
-            return;
-        }
-    }
-
     dotenv.config({ path: join(launchWorkingDirectory, AGENTS_SERVER_PROJECT_ENV_FILE_NAME) });
 }
 

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

@@ -4,7 +4,7 @@
 const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
     'coder:generate-boilerplates': 'ptbk coder generate-boilerplates --template ./prompts/templates/common.md',
     'coder:run':
-        'ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --no-wait',
+        'ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --no-wait',
     'coder:find-refactor-candidates': 'ptbk coder find-refactor-candidates',
     'coder:verify': 'ptbk coder verify',
 } as const satisfies Readonly<Record<string, string>>;

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

@@ -12,7 +12,7 @@ import { THINKING_LEVEL_VALUES } from '../coder/ThinkingLevel';
  *
  * @private internal utility of `promptbookCli`
  */
-export const PROMPT_RUNNER_AGENT_NAMES = [
+export const PROMPT_RUNNER_HARNESS_NAMES = [
     'openai-codex',
     'github-copilot',
     'cline',
@@ -22,11 +22,11 @@ export const PROMPT_RUNNER_AGENT_NAMES = [
 ] as const;
 
 /**
- * Environment variable used as the default runner identifier when `--agent` is omitted.
+ * Environment variable used as the default runner identifier when `--harness` is omitted.
  *
  * @private internal utility of `promptbookCli`
  */
-export const PTBK_AGENT_ENV = 'PTBK_AGENT';
+export const PTBK_HARNESS_ENV = 'PTBK_HARNESS';
 
 /**
  * Environment variable used as the default runner model when `--model` is omitted.
@@ -47,7 +47,7 @@ export const PTBK_THINKING_LEVEL_ENV = 'PTBK_THINKING_LEVEL';
  *
  * @private internal utility of `promptbookCli`
  */
-export type PromptRunnerAgentName = (typeof PROMPT_RUNNER_AGENT_NAMES)[number];
+export type PromptRunnerHarnessName = (typeof PROMPT_RUNNER_HARNESS_NAMES)[number];
 
 /**
  * Commander option bag for shared runner flags.
@@ -55,7 +55,7 @@ export type PromptRunnerAgentName = (typeof PROMPT_RUNNER_AGENT_NAMES)[number];
  * @private internal utility of `promptbookCli`
  */
 export type PromptRunnerCliOptions = {
-    readonly agent?: string;
+    readonly harness?: string;
     readonly model?: string;
     readonly ui: boolean;
     readonly thinkingLevel?: ThinkingLevel;
@@ -74,7 +74,7 @@ export type PromptRunnerCliOptions = {
  */
 export type PromptRunnerSelectionCliOptions = Pick<
     PromptRunnerCliOptions,
-    'agent' | 'model' | 'ui' | 'thinkingLevel' | 'allowCredits'
+    'harness' | 'model' | 'ui' | 'thinkingLevel' | 'allowCredits'
 >;
 
 /**
@@ -83,7 +83,7 @@ export type PromptRunnerSelectionCliOptions = Pick<
  * @private internal utility of `promptbookCli`
  */
 export type NormalizedPromptRunnerCliOptions = {
-    readonly agentName?: PromptRunnerAgentName;
+    readonly agentName?: PromptRunnerHarnessName;
     readonly model?: string;
     readonly noUi: boolean;
     readonly thinkingLevel?: ThinkingLevel;
@@ -121,11 +121,11 @@ export const PROMPT_RUNNER_DESCRIPTION = spaceTrim(`
 `);
 
 /**
- * Commander description for the `--agent` option.
+ * Commander description for the `--harness` option.
  *
  * @private internal utility of `promptbookCli`
  */
-export const PROMPT_RUNNER_AGENT_OPTION_DESCRIPTION =
+export const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION =
     'Select runner: openai-codex, github-copilot, cline, claude-code, opencode, gemini (required for non-dry-run)';
 
 /**
@@ -146,7 +146,9 @@ export const PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION = spaceTrim(`
  * @private internal utility of `promptbookCli`
  */
 export function addPromptRunnerSelectionOptions(command: Program): void {
-    command.addOption(new Option('--agent <agent-name>', PROMPT_RUNNER_AGENT_OPTION_DESCRIPTION).env(PTBK_AGENT_ENV));
+    command.addOption(
+        new Option('--harness <harness-name>', PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION).env(PTBK_HARNESS_ENV),
+    );
     command.addOption(new Option('--model <model>', PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION).env(PTBK_MODEL_ENV));
 }
 
@@ -227,7 +229,7 @@ export function normalizePromptRunnerSelectionCliOptions(
     },
 ): NormalizedPromptRunnerSelectionCliOptions {
     return {
-        agentName: resolvePromptRunnerAgentName(cliOptions.agent, options),
+        agentName: resolvePromptRunnerHarnessName(cliOptions.harness, options),
         model: cliOptions.model,
         noUi: !cliOptions.ui,
         thinkingLevel: cliOptions.thinkingLevel,
@@ -236,38 +238,40 @@ export function normalizePromptRunnerSelectionCliOptions(
 }
 
 /**
- * Parses and validates one runner agent name.
+ * Parses and validates one runner harness name.
  */
-function resolvePromptRunnerAgentName(
-    agent: string | undefined,
+function resolvePromptRunnerHarnessName(
+    harness: string | undefined,
     options: {
         readonly isAgentRequired: boolean;
     },
-): PromptRunnerAgentName | undefined {
-    if (!agent) {
+): PromptRunnerHarnessName | undefined {
+    if (!harness) {
         if (!options.isAgentRequired) {
             return undefined;
         }
 
         throw new Error(
             colors.red(
-                'You must choose an agent using --agent <openai-codex|github-copilot|cline|claude-code|opencode|gemini>',
+                'You must choose a harness using --harness <openai-codex|github-copilot|cline|claude-code|opencode|gemini>',
             ),
         );
     }
 
-    if (isPromptRunnerAgentName(agent)) {
-        return agent;
+    if (isPromptRunnerHarnessName(harness)) {
+        return harness;
     }
 
-    throw new Error(colors.red(`Invalid agent "${agent}". Must be one of: ${PROMPT_RUNNER_AGENT_NAMES.join(', ')}`));
+    throw new Error(
+        colors.red(`Invalid harness "${harness}". Must be one of: ${PROMPT_RUNNER_HARNESS_NAMES.join(', ')}`),
+    );
 }
 
 /**
- * Checks whether a string is one supported runner agent name.
+ * Checks whether a string is one supported runner harness name.
  */
-function isPromptRunnerAgentName(agent: string): agent is PromptRunnerAgentName {
-    return PROMPT_RUNNER_AGENT_NAMES.includes(agent as PromptRunnerAgentName);
+function isPromptRunnerHarnessName(harness: string): harness is PromptRunnerHarnessName {
+    return PROMPT_RUNNER_HARNESS_NAMES.includes(harness as PromptRunnerHarnessName);
 }
 
 // Note: [🟡] Code for CLI runner options [promptRunnerCliOptions](src/cli/cli-commands/common/promptRunnerCliOptions.ts) should never be published outside of `@promptbook/cli`

package/src/cli/promptbookCli.ts

@@ -6,6 +6,7 @@ import { EnvironmentMismatchError } from '../errors/EnvironmentMismatchError';
 import { $isRunningInNode } from '../utils/environment/$isRunningInNode';
 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';
@@ -93,6 +94,7 @@ export async function promptbookCli(): Promise<void> {
     $initializeListScrapersCommand(program);
     $initializeStartAgentsServerCommand(program);
     $initializeStartPipelinesServerCommand(program);
+    $initializeAgentCommand(program);
     $initializeAgentFolderCommand(program);
     $initializeAgentsServerCommand(program);
     $initializeCoderCommand(program);