@promptbook/cli 0.114.0-5 → 0.114.0-50

package/src/commands/FORMAT/formatCommandParser.ts

@@ -70,8 +70,10 @@ export const formatCommandParser: PipelineTaskCommandParser<FormatCommand> = {
      */
     $applyToTaskJson(command: FormatCommand, $taskJson: $TaskJson): $side_effect {
         if ($taskJson.format !== undefined && command.format !== $taskJson.format) {
-            throw new ParseError(`Format format is already defined to "${$taskJson.format}".
-                Now you try to redefine it by "${command.format}"`);
+            throw new ParseError(
+                spaceTrim(`Format format is already defined to "${$taskJson.format}".
+                Now you try to redefine it by "${command.format}"`),
+            );
         }
         $taskJson.format = command.format;
     },

package/src/commitments/FROM/FROM.ts

@@ -46,6 +46,12 @@ export class FromCommitmentDefinition extends BaseCommitmentDefinition<'FROM'> {
 
             Inherits agent source from another agent.
 
+            Every agent inherits from the core agent \`@Adam\` unless it says otherwise, so writing no ${this.type} at all
+            is the same as writing \`${this.type} @Adam\`. Write \`${this.type} @Null\` to inherit from nothing.
+
+            An agent has exactly one parent, so when ${this.type} is written more than once, the last one wins and
+            overrides every earlier one.
+
             ## Examples
 
             \`\`\`book
@@ -54,6 +60,13 @@ export class FromCommitmentDefinition extends BaseCommitmentDefinition<'FROM'> {
             FROM https://s6.ptbk.io/benjamin-white
             RULE Speak only in English.
             \`\`\`
+
+            \`\`\`book
+            My Standalone Agent
+
+            FROM @Null
+            RULE Speak only in English.
+            \`\`\`
         `);
     }
 

package/src/commitments/TEAM/TEAM.ts

@@ -171,6 +171,18 @@ export class TeamCommitmentDefinition extends BaseCommitmentDefinition<'TEAM'> {
 
             Registers teammate agents that the current agent can consult via tools.
 
+            The primary agent sends a question and relevant context to a teammate and receives an attributed answer.
+            Each teammate uses its own Book. Declaring a team makes advisers available when relevant; it does not
+            merge their rules into the primary agent or start every teammate automatically.
+
+            In \`ptbk coder run\` and \`ptbk coder plan\`, TEAM entries in the selected Book, its ancestors and imports
+            use the existing reference rules: \`@Name\`, \`{Agent Name}\`, \`{./lawyer.book}\`, project paths such as
+            \`{agents/lawyer.book}\`, and HTTP(S) Book URLs. Local advisers require no Agents Server. A remote Book
+            must be readable through its normal endpoint; private or inaccessible sources return errors.
+            Coding harnesses expose scoped command tools; planning uses restricted host tools and currently requires
+            OpenAI Codex. Planning restrictions apply to every adviser, including custom Developer Books.
+            The primary agent retains responsibility for the task, PRD proposals and final output.
+
             ## Examples
 
             \`\`\`book
@@ -216,22 +228,32 @@ export class TeamCommitmentDefinition extends BaseCommitmentDefinition<'TEAM'> {
         >;
 
         const resolvedTeammates: TeamTeammate[] = resolveTeamTeammateLabels(trimmedContent, teammates);
+        const toolUrls = new Map(existingTeammates.map((teammate) => [teammate.toolName, teammate.url]));
 
         const teamEntries: TeamToolEntry[] = resolvedTeammates.map((teammate) => {
             const profile = preResolvedProfiles[teammate.url];
             const resolvedLabel = profile?.agentName || teammate.label;
             const existingTeammate = existingTeammates.find((entry) => entry.url === teammate.url);
+            const baseToolName = existingTeammate?.toolName || createTeamToolName(teammate.url, resolvedLabel);
+            let toolName = baseToolName;
+            let suffix = 1;
+            // Explicit paths can identify distinct Books with the same display name or normalized label.
+            while (toolUrls.has(toolName) && toolUrls.get(toolName) !== teammate.url) {
+                toolName = `${baseToolName}_${++suffix}`;
+            }
+            toolUrls.set(toolName, teammate.url);
             return {
-                toolName: (existingTeammate?.toolName ||
-                    createTeamToolName(teammate.url, resolvedLabel)) as string_javascript_name,
+                toolName: toolName as string_javascript_name,
                 teammate: { ...teammate, label: resolvedLabel },
                 agentName,
                 description: profile?.personaDescription || null,
             };
         });
 
-        for (const entry of teamEntries) {
-            registerTeamTool(entry);
+        if (!requirements._metadata?.isTeamToolRegistrationDisabled) {
+            for (const entry of teamEntries) {
+                registerTeamTool(entry);
+            }
         }
 
         const existingTools: readonly LlmToolDefinition[] = requirements.tools || [];

package/src/commitments/WRITING_RULES/WRITING_RULES.ts

@@ -6,32 +6,39 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
 /**
  * `WRITING RULES` commitment definition.
  *
- * It adds constraints that apply strictly to writing style and presentation
- * rather than task-solving behavior.
+ * The `WRITING RULES`/`WRITING RULE` commitment adds constraints that apply strictly to writing style
+ * and presentation rather than task-solving behavior.
+ *
+ * Example usage in agent source:
+ *
+ * ```book
+ * WRITING RULES Keep every response under 120 words
+ * WRITING RULE Always end the message with an emoji
+ * ```
  *
  * @private [🪔] Maybe export the commitments through some package
  */
-export class WritingRulesCommitmentDefinition extends BaseCommitmentDefinition<'WRITING RULES'> {
-    public constructor() {
-        super('WRITING RULES');
+export class WritingRulesCommitmentDefinition extends BaseCommitmentDefinition<'WRITING RULES' | 'WRITING RULE'> {
+    public constructor(type: 'WRITING RULES' | 'WRITING RULE' = 'WRITING RULES') {
+        super(type);
     }
 
     /**
-     * Short one-line description of `WRITING RULES`.
+     * Short one-line description of `WRITING RULES`/`WRITING RULE`.
      */
     public get description(): string {
         return 'Add writing-only constraints such as tone, length, formatting, or emoji usage.';
     }
 
     /**
-     * Icon for `WRITING RULES`.
+     * Icon for `WRITING RULES`/`WRITING RULE`.
      */
     public get icon(): string {
         return '📝';
     }
 
     /**
-     * Markdown documentation for `WRITING RULES`.
+     * Markdown documentation for `WRITING RULES`/`WRITING RULE` commitment.
      */
     public get documentation(): string {
         return spaceTrim(`
@@ -41,6 +48,7 @@ export class WritingRulesCommitmentDefinition extends BaseCommitmentDefinition<'
 
             ## Key aspects
 
+            - All writing rules are treated equally regardless of singular/plural form.
             - Use it for writing-only constraints such as tone, formatting, length, emoji usage, punctuation, or reading level.
             - Do **not** use it for problem-solving behavior, policy, tool usage, or decision-making logic. Use \`RULE\` for that.
             - Newer writing-rules blocks override conflicting earlier writing-rules blocks.

package/src/commitments/index.ts

@@ -71,7 +71,8 @@ export const COMMITMENT_REGISTRY = [
     new LanguageCommitmentDefinition('LANGUAGE'),
     new LanguageCommitmentDefinition('LANGUAGES'),
     new WritingSampleCommitmentDefinition(),
-    new WritingRulesCommitmentDefinition(),
+    new WritingRulesCommitmentDefinition('WRITING RULES'),
+    new WritingRulesCommitmentDefinition('WRITING RULE'),
     new SampleCommitmentDefinition('SAMPLE'),
     new SampleCommitmentDefinition('EXAMPLE'),
     new FormatCommitmentDefinition('FORMAT'),

package/src/conversion/archive/loadJsZipModule.ts

@@ -7,4 +7,6 @@ import { createLazyModuleLoader } from '../../utils/misc/createLazyModuleLoader'
  *
  * @private internal utility of `loadArchive` and `saveArchive`
  */
-export const loadJsZipModule = createLazyModuleLoader(() => import('jszip'));
+export const loadJsZipModule: () => Promise<{ default: typeof import('jszip') }> = createLazyModuleLoader(
+    () => import('jszip'),
+);

package/src/executables/platforms/locateAppOnWindows.ts

@@ -1,4 +1,4 @@
-import { join } from 'path';
+import { delimiter, join } from 'path';
 import { assertsError } from '../../errors/assertsError';
 import { $provideFilesystemForNode } from '../../scrapers/_common/register/$provideFilesystemForNode';
 import type { string_executable_path } from '../../types/string_filename';
@@ -6,7 +6,7 @@ import { isExecutable } from '../../utils/files/isExecutable';
 import type { LocateAppOptions } from '../locateApp';
 
 /**
- * Attempts to locate the specified application on a Windows system by searching common installation directories.
+ * Attempts to locate the specified application on a Windows system by searching PATH and common installation directories.
  * Returns the path to the executable if found, or null otherwise.
  *
  * @private within the repository
@@ -16,18 +16,21 @@ export async function locateAppOnWindows({
     windowsSuffix,
 }: Pick<Required<LocateAppOptions>, 'appName' | 'windowsSuffix'>): Promise<string_executable_path | null> {
     try {
-        const prefixes = [
+        const EXECUTABLE_FILENAME = windowsSuffix.replace(/^.*[\\/]/, '');
+        const PATH_EXECUTABLE_PATHS = (process.env.PATH || '')
+            .split(delimiter)
+            .filter(Boolean)
+            .map((pathPrefix) => join(pathPrefix, EXECUTABLE_FILENAME));
+        const INSTALLATION_EXECUTABLE_PATHS = [
             process.env.LOCALAPPDATA,
             join(process.env.LOCALAPPDATA || '', 'Programs'),
             process.env.PROGRAMFILES,
             process.env['PROGRAMFILES(X86)'],
-        ];
+        ].map((pathPrefix) => pathPrefix + windowsSuffix);
 
-        for (const prefix of prefixes) {
-            const path = prefix + windowsSuffix;
-
-            if (await isExecutable(path, $provideFilesystemForNode())) {
-                return path;
+        for (const executablePath of [...PATH_EXECUTABLE_PATHS, ...INSTALLATION_EXECUTABLE_PATHS]) {
+            if (await isExecutable(executablePath, $provideFilesystemForNode())) {
+                return executablePath;
             }
         }
 

package/src/execution/translation/automatic-translate/translateMessages.ts

@@ -1,11 +1,11 @@
 import colors from 'colors'; // <- TODO: [🔶] Make system to put color and style to both node and browser
 import { readFile, writeFile } from 'fs';
-import glob from 'glob-promise'; // <- TODO: [🚰] Use just 'glob'
 import JSON5 from 'json5';
 import { join } from 'path';
 import { spaceTrim } from 'spacetrim';
 import { promisify } from 'util';
 import { PipelineExecutionError } from '../../../errors/PipelineExecutionError';
+import { findFilesByGlob } from '../../../utils/files/findFilesByGlob';
 import type { AutomaticTranslator } from './automatic-translators/AutomaticTranslator';
 import type { TranslatorOptions } from './automatic-translators/TranslatorOptions';
 
@@ -19,7 +19,7 @@ export async function translateMessages({
     from,
     to,
 }: { automaticTranslator: AutomaticTranslator } & TranslatorOptions) {
-    for (const filename of await glob(join(__dirname, '../../translations/', from || 'en', '/**/*.json5'))) {
+    for (const filename of await findFilesByGlob(join(__dirname, '../../translations/', from || 'en', '/**/*.json5'))) {
         //                       <- TODO: [😶]
         const fileData = JSON5.parse(await promisify(readFile)(filename, 'utf-8'));
 

package/src/llm-providers/openai/utils/buildToolInvocationScript.ts

@@ -1,3 +1,4 @@
+import { spaceTrim } from 'spacetrim';
 import {
     TOOL_PROGRESS_TOKEN_ARGUMENT,
     TOOL_PROGRESS_TOKEN_PARAMETER,
@@ -16,26 +17,28 @@ export function buildToolInvocationScript(options: {
 }): string {
     const { functionName, functionArgsExpression } = options;
 
-    return `
-        const args = ${functionArgsExpression};
-        const runtimeContextRaw =
-            typeof ${TOOL_RUNTIME_CONTEXT_PARAMETER} === 'undefined'
-                ? undefined
-                : ${TOOL_RUNTIME_CONTEXT_PARAMETER};
+    return spaceTrim(
+        (block) => `
+            const args = ${block(functionArgsExpression)};
+            const runtimeContextRaw =
+                typeof ${TOOL_RUNTIME_CONTEXT_PARAMETER} === 'undefined'
+                    ? undefined
+                    : ${TOOL_RUNTIME_CONTEXT_PARAMETER};
 
-        if (runtimeContextRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
-            args.${TOOL_RUNTIME_CONTEXT_ARGUMENT} = runtimeContextRaw;
-        }
+            if (runtimeContextRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
+                args.${TOOL_RUNTIME_CONTEXT_ARGUMENT} = runtimeContextRaw;
+            }
 
-        const toolProgressTokenRaw =
-            typeof ${TOOL_PROGRESS_TOKEN_PARAMETER} === 'undefined'
-                ? undefined
-                : ${TOOL_PROGRESS_TOKEN_PARAMETER};
+            const toolProgressTokenRaw =
+                typeof ${TOOL_PROGRESS_TOKEN_PARAMETER} === 'undefined'
+                    ? undefined
+                    : ${TOOL_PROGRESS_TOKEN_PARAMETER};
 
-        if (toolProgressTokenRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
-            args.${TOOL_PROGRESS_TOKEN_ARGUMENT} = toolProgressTokenRaw;
-        }
+            if (toolProgressTokenRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
+                args.${TOOL_PROGRESS_TOKEN_ARGUMENT} = toolProgressTokenRaw;
+            }
 
-        return await ${functionName}(args);
-    `;
+            return await ${functionName}(args);
+        `,
+    );
 }

package/src/llm-providers/vercel/VercelExecutionToolsOptions.ts

@@ -24,7 +24,12 @@ export type VercelExecutionToolsOptions = CommonToolsOptions &
         //       and not to pass it as a separate parameter
 
         /**
-         * Additional settings for chat models when calling `vercelProvider.chat('model-name', settings)`
+         * Additional settings for chat models, for example `temperature` or `providerOptions`
+         *
+         * Note: Since Vercel AI SDK v5 these settings belong to the model call, not to
+         *       `vercelProvider.chat('model-name')` which takes just the model name
          */
-        readonly additionalChatSettings?: Partial<Parameters<VercelProvider['chat']>[1]>;
+        readonly additionalChatSettings?: Partial<
+            Omit<Parameters<ReturnType<VercelProvider['chat']>['doGenerate']>[0], 'prompt'>
+        >;
     };

package/src/llm-providers/vercel/createExecutionToolsFromVercelProvider.ts

@@ -34,7 +34,9 @@ const VERCEL_PROVIDER_PROFILE: ChatParticipant = {
  */
 export function createExecutionToolsFromVercelProvider(options: VercelExecutionToolsOptions): LlmExecutionTools {
     let { title, description } = options;
-    const { vercelProvider, availableModels, userId, additionalChatSettings = {} } = options;
+    const { vercelProvider, availableModels, additionalChatSettings = {} } = options;
+    // <- Note: `userId` is not forwarded, because Vercel AI SDK moved provider-specific settings like `user` from
+    //          `vercelProvider.chat(modelName, settings)` into `providerOptions` which are keyed by the provider
 
     if (!/Vercel/i.test(title)) {
         title = `${title} (through Vercel)`;
@@ -89,10 +91,7 @@ export function createExecutionToolsFromVercelProvider(options: VercelExecutionT
                 );
             }
 
-            const model = await vercelProvider.chat(modelName, {
-                user: userId?.toString() || undefined,
-                ...additionalChatSettings,
-            });
+            const model = await vercelProvider.chat(modelName);
 
             const rawPromptContent = templateParameters(content, { ...parameters, modelName });
 
@@ -132,14 +131,9 @@ export function createExecutionToolsFromVercelProvider(options: VercelExecutionT
 
             const rawRequest: Parameters<typeof model.doGenerate>[0] = {
                 // <- TODO: [☂]
-                inputFormat: 'messages',
-                mode: {
-                    type: 'regular',
-                    tools: [
-                        /* <- TODO: Pass the tools */
-                    ],
-                },
                 prompt: promptMessages,
+                // <- TODO: Pass the tools via `tools`
+                ...additionalChatSettings,
             };
 
             const start: string_date_iso8601 = $getCurrentDate();
@@ -161,10 +155,17 @@ export function createExecutionToolsFromVercelProvider(options: VercelExecutionT
                 console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
             }
 
-            if (rawResponse.text === undefined) {
+            // Note: Vercel AI SDK returns ordered content parts, the chat message is made only of the text parts
+            const responseTextParts = rawResponse.content.flatMap((contentPart) =>
+                contentPart.type === 'text' ? [contentPart.text] : [],
+            );
+
+            if (responseTextParts.length === 0) {
                 throw new PipelineExecutionError('No response message');
             }
 
+            const responseText = responseTextParts.join('');
+
             const complete: string_date_iso8601 = $getCurrentDate();
 
             const duration = uncertainNumber((new Date(complete).getTime() - new Date(start).getTime()) / 1000);
@@ -173,15 +174,15 @@ export function createExecutionToolsFromVercelProvider(options: VercelExecutionT
                 price: UNCERTAIN_ZERO_VALUE, //  <- TODO: [🕘] Price count
                 duration,
                 input: {
-                    tokensCount: uncertainNumber(rawResponse.usage.promptTokens),
+                    tokensCount: uncertainNumber(rawResponse.usage.inputTokens),
                     ...computeUsageCounts(
                         rawPromptContent,
                         // <- TODO: [🕘][🙀] What about system message
                     ),
                 },
                 output: {
-                    tokensCount: uncertainNumber(rawResponse.usage.completionTokens),
-                    ...computeUsageCounts(rawResponse.text),
+                    tokensCount: uncertainNumber(rawResponse.usage.outputTokens),
+                    ...computeUsageCounts(responseText),
                 },
             };
 
@@ -189,7 +190,7 @@ export function createExecutionToolsFromVercelProvider(options: VercelExecutionT
                 name: 'promptResult',
                 message: `Result of \`createExecutionToolsFromVercelProvider.callChatModel\``,
                 value: {
-                    content: rawResponse.text,
+                    content: responseText,
                     modelName,
                     timing: {
                         start,