tuplet 2.7.0

package/dist/prompt/main-agent-builder.js

@@ -0,0 +1,287 @@
+/**
+ * Main Agent Prompt Builder
+ *
+ * Fluent API for building main agent system prompts.
+ */
+import { getBuiltInAgents } from '../built-in-agents/index.js';
+import { roleSection, subAgentsTable, subAgentParametersSection, questionHandlingSection, directToolsSection, workspaceStorageSection, rulesSection, taskExamplesSection } from './templates.js';
+export class MainAgentBuilder {
+    config = {
+        subAgents: [],
+        directTools: [],
+        workspacePaths: [],
+        rules: [],
+        examples: [],
+        customSections: []
+    };
+    _skipBuiltInAgents = false;
+    /**
+     * Skip auto-injecting built-in agents (used when Tuplet already merges them)
+     */
+    skipBuiltInAgents() {
+        this._skipBuiltInAgents = true;
+        return this;
+    }
+    /**
+     * Set the agent's role identity
+     */
+    role(role) {
+        this.config.role = role;
+        return this;
+    }
+    /**
+     * Set the agent's description
+     */
+    description(description) {
+        this.config.description = description;
+        return this;
+    }
+    /**
+     * Set sub-agents from actual SubAgentConfig objects
+     * Extracts name, description, and input parameters automatically
+     */
+    agents(configs) {
+        for (const config of configs) {
+            // Extract input parameters from inputSchema
+            const inputParams = [];
+            if (config.inputSchema?.properties) {
+                const required = config.inputSchema.required || [];
+                for (const [name, prop] of Object.entries(config.inputSchema.properties)) {
+                    inputParams.push({
+                        name,
+                        description: prop.description || '',
+                        required: required.includes(name)
+                    });
+                }
+            }
+            this.config.subAgents.push({
+                name: config.name,
+                purpose: config.description,
+                whenToUse: config.description,
+                inputParams: inputParams.length > 0 ? inputParams : undefined
+            });
+        }
+        return this;
+    }
+    /**
+     * Configure question handling behavior
+     */
+    questionHandling(options) {
+        this.config.questionHandling = options;
+        return this;
+    }
+    /**
+     * Set tools from actual Tool objects
+     * Extracts name and description automatically
+     */
+    tools(toolObjects) {
+        for (const tool of toolObjects) {
+            // Extract first line of description for brevity
+            const desc = tool.description.split('\n')[0].trim();
+            this.config.directTools.push({
+                name: tool.name,
+                description: desc
+            });
+        }
+        return this;
+    }
+    /**
+     * Add a workspace path definition
+     */
+    addWorkspacePath(path, description) {
+        this.config.workspacePaths.push({ path, description });
+        return this;
+    }
+    /**
+     * Add multiple workspace paths at once
+     */
+    addWorkspacePaths(paths) {
+        this.config.workspacePaths.push(...paths);
+        return this;
+    }
+    /**
+     * Add a behavioral rule
+     */
+    addRule(rule) {
+        this.config.rules.push(rule);
+        return this;
+    }
+    /**
+     * Add multiple rules at once
+     */
+    addRules(rules) {
+        this.config.rules.push(...rules);
+        return this;
+    }
+    /**
+     * Add a task example showing the flow
+     */
+    addExample(example) {
+        this.config.examples.push(example);
+        return this;
+    }
+    /**
+     * Add multiple examples at once
+     */
+    addExamples(examples) {
+        this.config.examples.push(...examples);
+        return this;
+    }
+    /**
+     * Add a custom section with title and content
+     */
+    addSection(title, content) {
+        this.config.customSections.push({ title, content });
+        return this;
+    }
+    /**
+     * Get the current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Build the final system prompt string
+     */
+    build() {
+        const sections = [];
+        // Auto-inject built-in agent defs (unless skipBuiltInAgents or user already added same name)
+        let builtInDefs = [];
+        if (!this._skipBuiltInAgents) {
+            const userAgentNames = new Set((this.config.subAgents || []).map(a => a.name));
+            const builtInAgents = getBuiltInAgents();
+            const newBuiltIns = builtInAgents.filter(a => !userAgentNames.has(a.name));
+            builtInDefs = newBuiltIns.map(a => ({
+                name: a.name,
+                purpose: a.description,
+                whenToUse: a.description,
+            }));
+        }
+        else {
+            // When called from Tuplet, built-ins are already merged into subAgents.
+            // Detect which ones are built-in by checking against getBuiltInAgents().
+            const builtInNames = new Set(getBuiltInAgents().map(a => a.name));
+            builtInDefs = (this.config.subAgents || [])
+                .filter(a => builtInNames.has(a.name))
+                .map(a => ({ name: a.name, purpose: a.purpose, whenToUse: a.whenToUse }));
+        }
+        const allSubAgents = [...(this.config.subAgents || []), ...(this._skipBuiltInAgents ? [] : builtInDefs)];
+        // Role section (required, with default)
+        const role = this.config.role || 'an AI assistant';
+        sections.push(roleSection(role, this.config.description));
+        // Current date
+        const today = new Date().toISOString().split('T')[0];
+        sections.push('');
+        sections.push(`Today's date is ${today}.`);
+        // Your Role header if we have sub-agents (orchestrator pattern)
+        if (allSubAgents.length > 0) {
+            sections.push('');
+            sections.push('## Your Role');
+            sections.push('');
+            if (builtInDefs.length > 0) {
+                sections.push('1. **Explore first** - Use the `explore` sub-agent to check workspace state. You are a lead — give it a SPECIFIC brief: what paths to check, what data to look for, what keywords to search. Example: "List top-level paths with `ls`, then check if `data/` has any funding-related JSON files." Do NOT send vague instructions like "explore everything"');
+                sections.push('2. **Clarify if needed** - If the request is vague or ambiguous, ask the user using __ask_user__ BEFORE doing work. Examples of things to clarify: what "small" means, where to save results, what format, what criteria to use, what sources to prefer');
+                sections.push('3. **Formulate requirements** - Before planning or delegating, synthesize your findings into a structured brief:');
+                sections.push('   - Context: current state and exploration findings');
+                sections.push('   - Goal: what the user wants to achieve');
+                sections.push('   - Affected areas: workspace paths and components involved');
+                sections.push('   - Constraints: limitations and dependencies');
+                sections.push('   - Success criteria: how to verify completion');
+                sections.push('4. **Plan** - For any task that involves multiple steps (searching, processing, saving), pass the structured brief to the `plan` sub-agent. Do NOT skip planning and jump straight into execution');
+                sections.push('5. **Create tasks from the plan** - After receiving the plan, create one task per plan step using TaskCreate. Each task should match a plan step: clear goal, relevant context, and expected outcome. This is MANDATORY for multi-step plans — do not skip task creation and jump straight to execution');
+                sections.push('6. **Execute** — Work through tasks in order. For each task: mark it in_progress, delegate to the `worker` sub-agent, then mark it completed. Delegate like a team lead assigns work to a developer — give the goal, relevant context, requirements, and constraints. Do NOT micromanage — the worker decides HOW to accomplish the goal');
+                sections.push('7. **Verify** — Use the `explore` sub-agent to verify results (read saved files, check data quality)');
+                sections.push('8. **Present results** - After ALL tasks are completed, output a clear summary to the user');
+            }
+            else {
+                sections.push('1. **Delegate** - Call __sub_agent__ tool to spawn sub-agents');
+                sections.push('2. **Present results** - After sub-agent completes, you MUST output a text message to the user');
+            }
+            sections.push('');
+            sections.push('⚠️ CRITICAL:');
+            sections.push('- Make actual tool calls, never write tool names as text');
+            sections.push('- After receiving tool results, ALWAYS respond with a text message to the user');
+            sections.push('- Never return an empty response');
+        }
+        // Sub-agents table
+        if (allSubAgents.length > 0) {
+            sections.push('');
+            sections.push(subAgentsTable(allSubAgents));
+            // Add sub-agent parameters documentation
+            const paramsSection = subAgentParametersSection(allSubAgents);
+            if (paramsSection) {
+                sections.push('');
+                sections.push(paramsSection);
+            }
+        }
+        // Built-in agents usage instructions (always present)
+        if (builtInDefs.length > 0) {
+            sections.push('');
+            sections.push('## Built-in Agents — Mandatory Usage');
+            sections.push('');
+            sections.push('These agents are always available. You MUST use them:');
+            sections.push('');
+            sections.push('- **explore**: ALWAYS call this BEFORE handling any user request. Give it a focused brief — tell it exactly what to look for and where. It should only read files that are relevant to the task, not explore the entire workspace.');
+            sections.push('- **plan**: Pure planner — does NOT explore or execute. Call this AFTER exploring, BEFORE executing. Feed it your exploration findings as a structured brief (context, goal, constraints, success criteria) and it returns a step-by-step execution plan where each step is a worker mission.');
+            sections.push('- **worker**: The ONLY way to execute actions. Delegate like a team lead to a developer — describe WHAT needs to be done and WHY, provide relevant context (paths, URLs, data formats), state requirements and constraints, but let the worker figure out the implementation details. Include hints only when you have specific domain knowledge that would save time. Examples: "We need to extract company data from this page (URL). Save each company with name, url, and description to the workspace at data/companies.json" or "Push these companies to the CRM API (endpoint: X, auth token is in env). Map our name field to their company_name field."');
+            sections.push('');
+            sections.push('The `explore` and `plan` agents are read-only. The `worker` agent has full read-write access.');
+        }
+        // Question handling (only when explicitly configured)
+        if (this.config.questionHandling) {
+            sections.push('');
+            sections.push(questionHandlingSection(this.config.questionHandling?.description, this.config.questionHandling?.exampleFlow));
+        }
+        // Direct tools
+        if (this.config.directTools && this.config.directTools.length > 0) {
+            sections.push('');
+            sections.push(directToolsSection(this.config.directTools));
+        }
+        // Workspace storage
+        if (this.config.workspacePaths && this.config.workspacePaths.length > 0) {
+            sections.push('');
+            sections.push(workspaceStorageSection(this.config.workspacePaths));
+        }
+        // Task examples
+        if (this.config.examples && this.config.examples.length > 0) {
+            sections.push('');
+            sections.push(taskExamplesSection(this.config.examples));
+        }
+        // Custom sections
+        for (const section of this.config.customSections || []) {
+            sections.push('');
+            sections.push(`## ${section.title}`);
+            sections.push('');
+            sections.push(section.content);
+        }
+        // Rules (always at the end): combine default rules with user rules
+        const defaultRules = [
+            'ALWAYS call the `explore` sub-agent at the start of each user request to check workspace state before doing anything else',
+            'ALWAYS use the `plan` sub-agent before executing any multi-step task. After receiving the plan, create one task per plan step using TaskCreate BEFORE starting execution. Never jump straight from planning to execution without creating tasks first',
+            'For vague or ambiguous requests, ask the user to clarify BEFORE starting work. Use __ask_user__ to confirm key details: criteria, format, where to save, what sources to use. Do not guess — ask',
+            'NEVER assume credentials, API keys, or secrets exist. Before any authenticated API call, first check what variables and credentials are actually available in the workspace. If they are not there, ask the user using __ask_user__ — do not guess or fabricate values',
+            'Prefer free public APIs and resources that require no authentication. If auth is needed and credentials are not in workspace, ask the user',
+            'If a tool call fails, read the response carefully and decide how to proceed. Do not blindly retry the same approach',
+            'After completing work, verify results by reading back saved data. Present a summary to the user',
+        ];
+        const allRules = [...defaultRules, ...(this.config.rules || [])];
+        sections.push('');
+        sections.push(rulesSection(allRules));
+        return sections.join('\n');
+    }
+    /**
+     * Reset the builder to initial state
+     */
+    reset() {
+        this.config = {
+            subAgents: [],
+            directTools: [],
+            workspacePaths: [],
+            rules: [],
+            examples: [],
+            customSections: []
+        };
+        return this;
+    }
+}
+//# sourceMappingURL=main-agent-builder.js.map

package/dist/prompt/main-agent-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main-agent-builder.js","sourceRoot":"","sources":["../../src/prompt/main-agent-builder.ts"],"names":[],"mappings":"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"}

package/dist/prompt/sub-agent-builder.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Sub-Agent Prompt Builder
+ *
+ * Fluent API for building sub-agent system prompts.
+ */
+import type { WorkflowStep, OutputFormat, SubAgentPromptConfig, WorkspacePathDef, ToolStepRef, ChecklistItem, SubAgentExample } from './types.js';
+import type { Tool, JSONSchema } from '../types.js';
+export declare class SubAgentBuilder {
+    private config;
+    /**
+     * Set the sub-agent's role (e.g., "a Nutrition Counter assistant")
+     */
+    role(role: string): this;
+    /**
+     * Set the task description
+     */
+    task(task: string): this;
+    /**
+     * Add step-by-step instructions
+     */
+    instructions(instructions: string[]): this;
+    /**
+     * Add a single instruction
+     */
+    addInstruction(instruction: string): this;
+    /**
+     * Enable todo tracking - AI will plan and track its own work
+     * @param options.exampleSteps - Example todos to guide the AI (optional)
+     */
+    useTodoTracking(options?: {
+        exampleSteps?: string[];
+    }): this;
+    /**
+     * Add guidance items (without todo tracking)
+     * @deprecated Use useTodoTracking() for progress tracking, or addGuidelines() for static guidance
+     */
+    checklist(items: (string | ChecklistItem)[], options?: {
+        sequential?: boolean;
+        trackProgress?: boolean;
+    }): this;
+    /**
+     * Add an input/output example
+     */
+    addExample(input: string, output: string, explanation?: string): this;
+    /**
+     * Add multiple examples at once
+     */
+    examples(examples: SubAgentExample[]): this;
+    /**
+     * Add a constraint (thing to avoid)
+     */
+    addConstraint(constraint: string): this;
+    /**
+     * Add multiple constraints at once
+     */
+    constraints(constraints: string[]): this;
+    /**
+     * Add a workflow step
+     */
+    addStep(step: WorkflowStep): this;
+    /**
+     * Add a step that may ask a question
+     */
+    addQuestionStep(description: string, askQuestion: {
+        condition?: string;
+        question: string;
+        options?: string[];
+    }): this;
+    /**
+     * Add a guideline
+     */
+    addGuideline(guideline: string): this;
+    /**
+     * Add multiple guidelines at once
+     */
+    addGuidelines(guidelines: string[]): this;
+    /**
+     * Enable workspace discovery - agent will check workspace before starting work
+     */
+    useWorkspace(): this;
+    /**
+     * Add a workspace path the agent should check
+     */
+    addWorkspacePath(path: string, description: string): this;
+    /**
+     * Add multiple workspace paths at once
+     */
+    addWorkspacePaths(paths: WorkspacePathDef[]): this;
+    /**
+     * Set the output format
+     */
+    output(format: OutputFormat): this;
+    /**
+     * Shorthand for common output format
+     * @deprecated Use outputSchema() instead for type-safe output definition
+     */
+    outputWithSummary(summaryTemplate: string, dataFields: Record<string, string>, errorCase?: {
+        condition: string;
+        data: Record<string, unknown>;
+    }): this;
+    /**
+     * Set output schema - generates output instructions from the schema
+     * This is the preferred way to define output format (type-safe)
+     */
+    outputSchema(schema: JSONSchema): this;
+    /**
+     * Set available tools from actual Tool objects
+     * Extracts name and description automatically for documentation
+     */
+    tools(toolObjects: Tool[]): this;
+    /**
+     * Add a workflow step that uses specific tools
+     * Type-safe alternative to addToolStep with string arrays
+     */
+    addToolsStep(description: string, toolRefs: ToolStepRef[]): this;
+    /**
+     * Add a custom section
+     */
+    addSection(title: string, content: string): this;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): SubAgentPromptConfig;
+    /**
+     * Build the final system prompt string
+     */
+    build(): string;
+    /**
+     * Reset the builder to initial state
+     */
+    reset(): this;
+}
+//# sourceMappingURL=sub-agent-builder.d.ts.map

package/dist/prompt/sub-agent-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-agent-builder.d.ts","sourceRoot":"","sources":["../../src/prompt/sub-agent-builder.ts"],"names":[],"mappings":"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"}