@orxataguy/tyr 1.0.30 → 1.0.32

package/src/lib/PromptTemplateManager.ts

@@ -1,4 +1,4 @@
-import { AIContextManager } from './AIContextManager.js';
+import { AIContextManager, AGENT_TOOLS_DESCRIPTION, SEARCH_REPLACE_FORMAT_INSTRUCTIONS } from './AIContextManager.js';
 import { AIMessage } from './AIVendorManager.js';
 import { Logger } from '../core/Logger.js';
 import { TyrError } from '../core/TyrError.js';
@@ -8,6 +8,62 @@ export interface PromptTemplate {
     user: string;
 }
 
+const CODE_SYSTEM_PROMPT =
+    "You are a senior software engineer working inside an existing project. You are given the project's " +
+    'AGENTS.md (architecture and conventions) and its directory tree. Fulfil the user\'s request by ' +
+    'creating new files and/or modifying existing ones as needed, following the project\'s existing ' +
+    'conventions (naming, structure, style, imports) exactly as described in AGENTS.md. Regardless of the ' +
+    "language used elsewhere in the project's existing code or comments, or the language of the user's " +
+    'request, write ALL comments you add or rewrite (inline comments, JSDoc/docblocks, etc.) in English.\n\n' +
+    'Before writing any new file that is supposed to follow an existing convention or pattern (e.g. "a ' +
+    'command file", "a service class", any structure AGENTS.md only names without fully specifying), do ' +
+    'not guess its exact shape from the name alone: find and read at least one real existing example of ' +
+    'that pattern in the project first (list_directory / read_file / search_dependency_usage can help you ' +
+    'locate one), and follow its structure precisely. If the pattern depends on a framework or library ' +
+    'installed in the project and you are not certain of its exact API, do not assume — use ' +
+    'read_dependency_manifest to locate it in node_modules and see its entry points, then ' +
+    'list_dependency_files / read_dependency_file to read its real source or type definitions before you ' +
+    'write code against it.\n\n' +
+    SEARCH_REPLACE_FORMAT_INSTRUCTIONS +
+    '\n\n' + AGENT_TOOLS_DESCRIPTION +
+    " Do not assume the content of an existing file you need to modify that hasn't already been shown to " +
+    'you: request it with read_file before writing a SEARCH block against it — a SEARCH snippet that does ' +
+    "not match the file's real current content will simply fail to apply and that edit will be skipped.";
+
+const PROJECT_DESCRIBE_SYSTEM_PROMPT =
+    'You are a senior software architect writing a comprehensive AGENTS.md context file for an AI coding ' +
+    "assistant that will work on this project. You are given the project's README (when present) — treat " +
+    "it as a helpful guide to the project's intent and terminology, but not as the only source of truth, " +
+    'since it may be incomplete or outdated — and the project file tree, for structural grounding only ' +
+    '(an accurate tree will be appended to the document automatically after your response, so do not ' +
+    'reproduce or reformat it yourself). Everything else about the codebase — file contents, the ' +
+    "project's real dependencies, how they're used — is NOT included up front: request it yourself with " +
+    'the available tools before writing. Produce a thorough, well-structured Markdown document that: ' +
+    'describes the overall purpose of the project; walks through every directory and file, explaining ' +
+    'what it does and what it is responsible for; documents the public API surface (exported classes, ' +
+    'functions, types) of each module; and explains how the pieces fit together, so a newcomer AI ' +
+    'assistant can safely make changes without missing context. Be exhaustive and specific to this ' +
+    "codebase — do not include generic advice. Write the entire document in English, regardless of the " +
+    "language used in the project's source code, comments, filenames, README, or file contents.\n\n" +
+    AGENT_TOOLS_DESCRIPTION +
+    ' When you have everything you need, respond ONLY with the final Markdown document, with no additional ' +
+    'commentary or mentions of the tools you used.';
+
+const FILE_DESCRIBE_SYSTEM_PROMPT =
+    'You are a senior software architect writing an AGENTS.md-style context file for a single source ' +
+    'file, meant to be read by an AI coding assistant before it edits that file. You may also be given ' +
+    "the project's README and/or its existing AGENTS.md for overall context — use them to align " +
+    'terminology and to note how this file fits into the broader project, without repeating what they ' +
+    'already cover. Produce a thorough, well-structured Markdown document that: describes what the file ' +
+    'does end-to-end; documents every exported class, function, type and constant, what it is ' +
+    "responsible for, and how it is meant to be used; and calls out any non-obvious behaviour, edge " +
+    'cases or invariants a future editor needs to know. Be exhaustive and specific to this file — do not ' +
+    'include generic advice. Write the entire document in English, regardless of the language used in ' +
+    "the file's own code, comments, or the project's README/AGENTS.md.\n\n" +
+    AGENT_TOOLS_DESCRIPTION +
+    ' When you have everything you need, respond ONLY with the final Markdown document, with no additional ' +
+    'commentary or mentions of the tools you used.';
+
 const DEFAULT_TEMPLATES: Record<string, PromptTemplate> = {
     'analyze-bug': {
         system:
@@ -23,6 +79,13 @@ const DEFAULT_TEMPLATES: Record<string, PromptTemplate> = {
             'JSDoc comments on public methods. Output only the TypeScript code for the file, no commentary.',
         user: 'Command name: {{name}}\nRequested behaviour:\n{{description}}',
     },
+    'generate-code': {
+        system:
+            'You are a senior engineer. Follow the ' +
+            'existing conventions exactly: KISS, SOLID, DRY. Only make simple comments on the functions to give context if is necessary ' +
+            'Output only the code for the file, no commentary.',
+        user: 'Command name: {{name}}\nRequested behaviour:\n{{description}}',
+    },
     'explain-code': {
         system:
             'You are a senior software engineer. Explain what the given code does clearly and ' +
@@ -36,6 +99,25 @@ const DEFAULT_TEMPLATES: Record<string, PromptTemplate> = {
             'provide the full refactored code.',
         user: 'Code:\n```\n{{code}}\n```\n\nGoal:\n{{goal}}',
     },
+    // Used by the ai:code command. AGENTS.md is prepended automatically by build() (via
+    // AIContextManager.getContext) — {{tree}} is the only extra context seeded up front; the
+    // agent pulls in any specific file it needs itself via AGENT_TOOLS (see AIContextManager).
+    'ai-code': {
+        system: CODE_SYSTEM_PROMPT,
+        user: '# Project structure\n```\n{{tree}}\n```\n\n# Task\n{{task}}',
+    },
+    // Used by the ai:describe command when generating AGENTS.md for a whole project. Intentionally
+    // built with buildStandalone() rather than build(): forcing a guidelines file to exist before
+    // we've generated one yet would be circular.
+    'ai-describe-project': {
+        system: PROJECT_DESCRIBE_SYSTEM_PROMPT,
+        user: '{{readme}}\n\n# Project structure\n```\n{{tree}}\n```',
+    },
+    // Used by the ai:describe command when describing a single file.
+    'ai-describe-file': {
+        system: FILE_DESCRIBE_SYSTEM_PROMPT,
+        user: 'File path (relative to the project): {{path}}\nFile content:\n```\n{{content}}\n```\n\n{{context}}',
+    },
 };
 
 /**
@@ -128,6 +210,35 @@ export class PromptTemplateManager {
 
         return [systemMessage, ...contextMessages, userMessage];
     }
+
+    /**
+     * @method buildStandalone
+     * @description Like build(), but does NOT prepend the project's guidelines file — use this
+     * when the template itself is what generates that file (e.g. 'ai-describe-project', the very
+     * first run on a project with no AGENTS.md yet), where calling getContext() would force a
+     * separate, redundant guidelines generation first.
+     * @param {string} templateName - Name of a registered template (see listTemplates()).
+     * @param {Record<string,string>} vars - Values for the template's {{placeholders}}.
+     * @returns {AIMessage[]} Ordered messages: [system, user].
+     * @example
+     * const messages = prompts.buildStandalone('ai-describe-project', { tree, readme });
+     * const result = await aiContext.runDescribeAgent(projectDir, messages, tokens);
+     */
+    public buildStandalone(templateName: string, vars: Record<string, string>): AIMessage[] {
+        const template = this.templates[templateName];
+        if (!template) {
+            throw new TyrError(
+                `Unknown prompt template: '${templateName}'`,
+                null,
+                `Available templates: ${this.listTemplates().join(', ')}`
+            );
+        }
+
+        return [
+            { role: 'system', content: template.system },
+            { role: 'user', content: this.fill(template.user, vars) },
+        ];
+    }
 }
 
 export const PromptTemplateManagerTests = {

package/src/lib/TokenManager.ts

@@ -2,7 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import { homedir } from 'os';
 
-import { AIMessage } from './AIVendorManager.js';
+import { AIMessage, AIContentBlock } from './AIVendorManager.js';
 import { Logger } from '../core/Logger.js';
 import { TyrError } from '../core/TyrError.js';
 import { getEnvInt } from '../core/util/getenv.js';
@@ -56,6 +56,34 @@ export class TokenManager {
         return Math.ceil(text.length / CHARS_PER_TOKEN);
     }
 
+    /**
+     * @method contentToText
+     * @description Flattens an AIMessage's content — a plain string, or an AIContentBlock[] as
+     * used by the tool-use agent loop (text / tool_use / tool_result / image blocks) — into a
+     * single string for estimation purposes. Non-text blocks contribute an approximate stand-in
+     * length (JSON-stringified input/content) rather than being ignored, so a message full of
+     * large tool_result blocks isn't silently under-counted.
+     * @param {string | AIContentBlock[]} content - The raw content of an AIMessage.
+     * @returns {string} Flattened text.
+     * @example
+     * const text = tokens_.contentToText(message.content);
+     */
+    public contentToText(content: string | AIContentBlock[]): string {
+        if (typeof content === 'string') return content;
+
+        return content
+            .map((block) => {
+                switch (block.type) {
+                    case 'text': return block.text;
+                    case 'tool_use': return JSON.stringify(block.input ?? {});
+                    case 'tool_result': return block.content;
+                    case 'image': return ''; // billed very differently from text; excluded from the char-based heuristic
+                    default: return '';
+                }
+            })
+            .join('\n');
+    }
+
     /**
      * @method estimateMessagesTokens
      * @description Estimates the total token cost of a full list of prompt messages.
@@ -66,7 +94,7 @@ export class TokenManager {
      */
     public estimateMessagesTokens(messages: AIMessage[]): number {
         return messages.reduce(
-            (total, m) => total + this.estimateTokens(m.content) + PER_MESSAGE_OVERHEAD_TOKENS,
+            (total, m) => total + this.estimateTokens(this.contentToText(m.content)) + PER_MESSAGE_OVERHEAD_TOKENS,
             0
         );
     }