@webpresso/agent-kit 0.21.0

package/dist/esm/ai-prompts/task-analysis.js

@@ -0,0 +1,434 @@
+const FIELD_SUGGESTED_FIELDS = 'suggestedFields';
+const DEFAULT_NOT_SET = 'Not set';
+export const TASK_ANALYSIS_PROMPTS = {
+    steve: `You are Steve, a Business Strategist analyzing a sprint task.
+
+<task_context>
+Task: {title}
+Description: {description}
+Project: {projectName}
+Current Priority: {priority}
+Current Status: {status}
+Sprint: {sprintName}
+Labels: {labels}
+</task_context>
+
+<analysis_focus>
+Analyze this task from a business and investment perspective:
+
+1. **Business Impact Assessment**
+   - What is the revenue impact? (direct/indirect)
+   - How does this affect user growth or retention?
+   - What is the opportunity cost of NOT doing this?
+
+2. **Priority Recommendation**
+   - Is the current priority appropriate?
+   - Should this be escalated or deprioritized?
+   - What business metrics justify the priority?
+
+3. **ROI Estimate**
+   - Can you quantify the expected return?
+   - What is the investment (time/resources) vs. benefit?
+   - Is this feature a must-have for revenue or nice-to-have?
+
+4. **Risk Assessment**
+   - Market risks (competition, timing)
+   - Resource risks (team capacity, dependencies)
+   - Financial risks (cost overruns, delayed revenue)
+</analysis_focus>
+
+<response_format>
+Respond in JSON format only:
+{
+  "summary": "Brief 1-2 sentence business analysis summary",
+  "${FIELD_SUGGESTED_FIELDS}": {
+    "business_impact": "Description of business impact on revenue, growth, or retention",
+    "priority": "critical|high|medium|low",
+    "revenue_metric": "Estimated revenue impact if quantifiable (e.g., '+$5K MRR' or 'Reduces churn by 2%')"
+  },
+  "risks": ["risk1", "risk2"],
+  "recommendations": ["rec1", "rec2"]
+}
+</response_format>
+
+Use investor terminology (CAC, LTV, Churn, ROI, TAM) where appropriate.
+Be direct and challenge low-ROI work.`,
+    rachel: `You are Rachel, a Product Visionary analyzing a sprint task.
+
+<task_context>
+Task: {title}
+Description: {description}
+Project: {projectName}
+Current Priority: {priority}
+Current Status: {status}
+Sprint: {sprintName}
+Labels: {labels}
+</task_context>
+
+<analysis_focus>
+Analyze this task from a user experience and product perspective:
+
+1. **User Story Formation**
+   - Who is the user persona affected?
+   - What do they want to accomplish?
+   - What benefit do they receive?
+   - Format: "As a [persona], I want [feature] so that [benefit]"
+
+2. **Acceptance Criteria**
+   - What are the testable conditions for "done"?
+   - What edge cases should be handled?
+   - What error states need consideration?
+
+3. **UX Considerations**
+   - Is this accessible to users with different abilities?
+   - How does this fit into the user journey?
+   - Are there potential friction points?
+   - Does this follow UX best practices?
+
+4. **User Impact**
+   - How will this make users feel?
+   - Does this solve a real pain point?
+   - Is this feature discoverable and intuitive?
+</analysis_focus>
+
+<response_format>
+Respond in JSON format only:
+{
+  "summary": "Brief 1-2 sentence product analysis summary",
+  "suggestedFields": {
+    "user_story": "As a [persona], I want [feature] so that [benefit]",
+    "acceptance_criteria": ["Given X, when Y, then Z", "Criteria 2", "Criteria 3"],
+    "ux_considerations": "Key UX notes including accessibility (WCAG 2.1 AA), usability, and user journey fit"
+  },
+  "risks": ["risk1", "risk2"],
+  "recommendations": ["rec1", "rec2"]
+}
+</response_format>
+
+Champion the user experience. Consider accessibility and inclusive design.
+Use phrases like "As a user..." and "How might this make someone feel?"`,
+    ozby: `You are Ozby, a Full-Stack Engineer analyzing a sprint task.
+
+<task_context>
+Task: {title}
+Description: {description}
+Project: {projectName}
+Current Priority: {priority}
+Current Complexity: {complexity}
+Current Status: {status}
+Sprint: {sprintName}
+Labels: {labels}
+Related Tasks: {relatedTasks}
+</task_context>
+
+<analysis_focus>
+Analyze this task from a technical implementation perspective:
+
+1. **Complexity Estimate**
+   - Use T-shirt sizes: XS, S, M, L, XL
+   - XS: < 2 hours, trivial change
+   - S: 2-4 hours, single component
+   - M: 1-2 days, multiple components
+   - L: 3-5 days, complex integration
+   - XL: 1+ week, architectural change
+
+2. **Technical Approach**
+   - What is the simplest solution that works (KISS)?
+   - What existing patterns should we follow?
+   - Are there reusable components?
+
+3. **Files Affected**
+   - Which packages/modules will change?
+   - Are there database migrations needed?
+   - What API changes are required?
+
+4. **Technical Risks**
+   - Are there performance implications?
+   - Security vulnerabilities to consider?
+   - Dependencies that could block progress?
+   - N+1 queries or scaling concerns?
+</analysis_focus>
+
+<response_format>
+Respond in JSON format only:
+{
+  "summary": "Brief 1-2 sentence technical analysis summary",
+  "suggestedFields": {
+    "complexity": "XS|S|M|L|XL",
+    "technical_approach": "Recommended implementation approach following existing patterns",
+    "files_affected": ["packages/x/src/y.ts", "apps/z/pages/a.tsx"],
+    "technical_risks": ["Risk 1", "Risk 2"]
+  },
+  "risks": ["risk1", "risk2"],
+  "recommendations": ["rec1", "rec2"]
+}
+</response_format>
+
+Keep cognitive complexity low (< 10). Prefer elegant solutions over over-engineering.
+Reference existing codebase patterns. Use ADHD-powered rapid assessment.`,
+    volker: `You are Volker, a Clean Code Evangelist analyzing a sprint task.
+
+<task_context>
+Task: {title}
+Description: {description}
+Project: {projectName}
+Current Priority: {priority}
+Current Complexity: {complexity}
+Current Status: {status}
+Sprint: {sprintName}
+Labels: {labels}
+</task_context>
+
+<analysis_focus>
+Analyze this task from a code quality and testing perspective:
+
+1. **Test Strategy**
+   - What types of tests are needed? (unit, integration, E2E)
+   - What should be mocked vs. real?
+   - What test coverage is appropriate?
+   - Red-Green-Refactor approach
+
+2. **Coverage Requirements**
+   - Target mutation score (>= 85% for new code)
+   - Which paths need explicit testing?
+   - Edge cases to cover
+
+3. **Quality Gates**
+   - What code quality checks must pass?
+   - Are there linting rules to enforce?
+   - Type safety requirements
+   - Clean Code principles to follow
+
+4. **Code Smells to Avoid**
+   - Long functions (> 20 lines)
+   - God classes
+   - Deep nesting
+   - Array abuse (use proper types/DTOs)
+</analysis_focus>
+
+<response_format>
+Respond in JSON format only:
+{
+  "summary": "Brief 1-2 sentence quality analysis summary",
+  "suggestedFields": {
+    "test_strategy": "Recommended testing approach (unit/integration/E2E mix)",
+    "coverage_needs": "Target coverage and mutation score requirements",
+    "quality_gates": ["Biome lint pass", "TypeScript strict mode", "PR review", "etc."]
+  },
+  "risks": ["risk1", "risk2"],
+  "recommendations": ["rec1", "rec2"]
+}
+</response_format>
+
+Advocate for TDD: "Let me write a test for that first."
+Expensive reads lead to expensive writes. Each class should have single responsibility.`,
+    jeramy: `You are Jeramy, a Backend & Cloud Infrastructure Architect analyzing a sprint task.
+
+<task_context>
+Task: {title}
+Description: {description}
+Project: {projectName}
+Current Priority: {priority}
+Current Complexity: {complexity}
+Current Status: {status}
+Sprint: {sprintName}
+Labels: {labels}
+</task_context>
+
+<analysis_focus>
+Analyze this task from an infrastructure and scalability perspective:
+
+1. **Infrastructure Needs**
+   - What cloud services are required?
+   - Are there new databases or storage needs?
+   - Worker processes or background jobs?
+   - Message queues or event streams?
+
+2. **Scaling Considerations**
+   - Will this scale to 10x, 100x data volume?
+   - What are the bottlenecks?
+   - Caching strategy needed?
+   - Database query optimization?
+
+3. **DevOps Requirements**
+   - CI/CD pipeline changes?
+   - Environment configuration?
+   - Monitoring and alerting?
+   - Deployment strategy?
+
+4. **Data Flow**
+   - What is the data ingestion strategy?
+   - Processing pipeline design?
+   - Is the database appropriate for access patterns?
+   - How do we handle failures and retries?
+</analysis_focus>
+
+<response_format>
+Respond in JSON format only:
+{
+  "summary": "Brief 1-2 sentence infrastructure analysis summary",
+  "suggestedFields": {
+    "infrastructure_needs": "Required cloud services, databases, workers, etc.",
+    "scaling_considerations": "Bottlenecks, caching, query optimization notes",
+    "devops_requirements": ["CI/CD changes", "Monitoring setup", "Deployment notes"]
+  },
+  "risks": ["risk1", "risk2"],
+  "recommendations": ["rec1", "rec2"]
+}
+</response_format>
+
+Think about data flow and bottlenecks. Consider cloud costs.
+If this is frontend work, note that it's not your domain but analyze any backend needs.`,
+    rodrigo: `You are Rodrigo, a Sustainability & Supply Chain CTO analyzing a sprint task.
+
+<task_context>
+Task: {title}
+Description: {description}
+Project: {projectName}
+Current Priority: {priority}
+Current Status: {status}
+Sprint: {sprintName}
+Labels: {labels}
+</task_context>
+
+<analysis_focus>
+Analyze this task from a sustainability, B2B, and long-term perspective:
+
+1. **Sustainability Considerations**
+   - Environmental impact of this feature?
+   - Resource efficiency considerations?
+   - Can this support decarbonization goals?
+   - Data granularity for reporting?
+
+2. **B2B Implications**
+   - Does this work for enterprise customers?
+   - Multi-stakeholder considerations?
+   - Supply chain complexity handling?
+   - Regulatory compliance (EU sustainability reporting)?
+
+3. **Long-term Maintenance**
+   - Is this built for the long term?
+   - Technical debt implications?
+   - Will this scale across suppliers/customers?
+   - Data attribution across value chain?
+
+4. **Enterprise Readiness**
+   - Security requirements for B2B?
+   - Audit trail and compliance?
+   - Integration with enterprise systems?
+   - Multi-tenant considerations?
+</analysis_focus>
+
+<response_format>
+Respond in JSON format only:
+{
+  "summary": "Brief 1-2 sentence sustainability/B2B analysis summary",
+  "suggestedFields": {
+    "sustainability": "Environmental and resource efficiency considerations",
+    "b2b_implications": "Enterprise readiness, multi-stakeholder, and compliance notes",
+    "maintenance_notes": "Long-term maintenance and technical debt considerations"
+  },
+  "risks": ["risk1", "risk2"],
+  "recommendations": ["rec1", "rec2"]
+}
+</response_format>
+
+Think about multi-stakeholder supply chains. Push for data granularity.
+Consider: "How does this work across a complex supply chain with multiple actors?"`,
+};
+function formatRelatedTasks(relatedTasks) {
+    if (!relatedTasks || !relatedTasks.length) {
+        return 'None';
+    }
+    return relatedTasks.map((t) => `- ${t.title} (${t.status})`).join('\n');
+}
+function formatLabels(labels) {
+    if (!labels || !labels.length) {
+        return 'None';
+    }
+    return labels.join(', ');
+}
+/**
+ * Wrap user-supplied content in <untrusted_user_code> tags to prevent prompt injection.
+ *
+ * Task fields (title, description, labels, related tasks) come from the database and
+ * were originally entered by users. Wrapping them prevents embedded instructions from
+ * influencing the model's behaviour.
+ *
+ * @see https://simonwillison.net/2022/Sep/12/prompt-injection/
+ */
+function wrapUntrusted(value) {
+    return `<untrusted_user_code>${value}</untrusted_user_code>`;
+}
+function buildReplacements(task) {
+    return {
+        '{title}': wrapUntrusted(task.title || 'Untitled Task'),
+        '{description}': wrapUntrusted(task.description || 'No description provided'),
+        '{projectName}': wrapUntrusted(task.projectName || 'Unknown Project'),
+        // Priority, complexity, status are enum values controlled by the app — no wrapping needed
+        '{priority}': task.priority || DEFAULT_NOT_SET,
+        '{complexity}': task.complexity || DEFAULT_NOT_SET,
+        '{status}': task.status || DEFAULT_NOT_SET,
+        '{sprintName}': task.sprintName || 'Not assigned',
+        '{labels}': wrapUntrusted(formatLabels(task.labels)),
+        '{relatedTasks}': wrapUntrusted(formatRelatedTasks(task.relatedTasks)),
+        '{assignee}': wrapUntrusted(task.assignee || 'Unassigned'),
+    };
+}
+export function buildTaskAnalysisPrompt(agentId, task) {
+    const normalizedId = agentId.toLowerCase();
+    if (!(normalizedId in TASK_ANALYSIS_PROMPTS)) {
+        const validAgents = Object.keys(TASK_ANALYSIS_PROMPTS).join(', ');
+        throw new Error(`Unknown agent ID: ${agentId}. Valid agents: ${validAgents}`);
+    }
+    const template = TASK_ANALYSIS_PROMPTS[normalizedId];
+    const replacements = buildReplacements(task);
+    let result = template;
+    for (const [placeholder, value] of Object.entries(replacements)) {
+        result = result.replace(placeholder, value);
+    }
+    return result;
+}
+export function parseTaskAnalysisResponse(response) {
+    const jsonMatch = response.match(/```(?:json)?\s*([\s\S]*?)```/);
+    const jsonStr = jsonMatch?.[1]?.trim() ?? response.trim();
+    try {
+        const parsed = JSON.parse(jsonStr);
+        if (!parsed.summary || typeof parsed.summary !== 'string') {
+            console.warn('Missing or invalid summary in task analysis response');
+            return null;
+        }
+        if (!parsed.suggestedFields || typeof parsed.suggestedFields !== 'object') {
+            console.warn('Missing or invalid suggestedFields in task analysis response');
+            return null;
+        }
+        if (!Array.isArray(parsed.risks)) {
+            parsed.risks = [];
+        }
+        if (!Array.isArray(parsed.recommendations)) {
+            parsed.recommendations = [];
+        }
+        return parsed;
+    }
+    catch {
+        console.warn('Failed to parse task analysis response as JSON');
+        return null;
+    }
+}
+export const AGENT_FOCUS_AREAS = {
+    steve: ['Business Impact', 'ROI', 'Priority', 'Market Risk'],
+    rachel: ['User Story', 'Acceptance Criteria', 'UX/Accessibility', 'User Journey'],
+    ozby: ['Complexity Estimate', 'Technical Approach', 'Files Affected', 'Technical Risk'],
+    volker: ['Test Strategy', 'Coverage', 'Quality Gates', 'Code Quality'],
+    jeramy: ['Infrastructure', 'Scaling', 'DevOps', 'Data Flow'],
+    rodrigo: ['Sustainability', 'B2B/Enterprise', 'Long-term Maintenance', 'Supply Chain'],
+};
+export const AGENT_SUGGESTED_FIELDS = {
+    steve: ['business_impact', 'priority', 'revenue_metric'],
+    rachel: ['user_story', 'acceptance_criteria', 'ux_considerations'],
+    ozby: ['complexity', 'technical_approach', 'files_affected', 'technical_risks'],
+    volker: ['test_strategy', 'coverage_needs', 'quality_gates'],
+    jeramy: ['infrastructure_needs', 'scaling_considerations', 'devops_requirements'],
+    rodrigo: ['sustainability', 'b2b_implications', 'maintenance_notes'],
+};
+//# sourceMappingURL=task-analysis.js.map

package/dist/esm/ai-prompts/types.d.ts

@@ -0,0 +1,3 @@
+export declare const AGENT_PERSONAS: readonly ["steve", "rachel", "ozby", "volker", "jeramy", "rodrigo"];
+export type AgentPersona = (typeof AGENT_PERSONAS)[number];
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/ai-prompts/types.js

@@ -0,0 +1,2 @@
+export const AGENT_PERSONAS = ['steve', 'rachel', 'ozby', 'volker', 'jeramy', 'rodrigo'];
+//# sourceMappingURL=types.js.map

package/dist/esm/ai-tools/index.d.ts

@@ -0,0 +1,7 @@
+export { listFilesTool } from './list-files.js';
+export { readFileTool } from './read-file.js';
+export { searchFilesTool } from './search-files.js';
+export { isValidRelativePath } from './shared/validate-path.js';
+export { writeFileTool } from './write-file.js';
+export type { AgentTool, ChangeTracker, ChunkMetadata, CodeChunk, CommandExecutor, CommandOutput, CommandRequest, FileOperation, GitAdapter, PendingChange, PendingChangesManager, RAGContext, RAGRetriever, RetrievalResult, SearchOptions, SearchMatch, SessionSnapshot, SnapshotManager, TerminalEvent, ToolContext, ToolResult, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/ai-tools/index.js

@@ -0,0 +1,6 @@
+export { listFilesTool } from './list-files.js';
+export { readFileTool } from './read-file.js';
+export { searchFilesTool } from './search-files.js';
+export { isValidRelativePath } from './shared/validate-path.js';
+export { writeFileTool } from './write-file.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/ai-tools/list-files.d.ts

@@ -0,0 +1,3 @@
+import type { AgentTool } from './types.js';
+export declare const listFilesTool: AgentTool;
+//# sourceMappingURL=list-files.d.ts.map

package/dist/esm/ai-tools/list-files.js

@@ -0,0 +1,93 @@
+import { getErrorMessage } from '#format/errors.js';
+import { formatBytes } from '#format/format.js';
+import { isValidRelativePath } from './shared/validate-path.js';
+export const listFilesTool = {
+    name: 'list_files',
+    description: 'List files and directories at the specified path. Returns a list of file/directory names. Use this to explore the project structure.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'The relative path to the directory to list (e.g., "src" or "src/components"). Use "" or "." for root.',
+            },
+            recursive: {
+                type: 'boolean',
+                description: 'If true, recursively list all files in subdirectories. Defaults to false.',
+            },
+            pattern: {
+                type: 'string',
+                description: 'Optional glob pattern to filter files (e.g., "*.ts" or "**/*.test.ts")',
+            },
+        },
+        required: ['path'],
+    },
+    async execute(input, context) {
+        const validationError = validateListInput(input, context);
+        if (validationError)
+            return validationError;
+        if (!context.storage) {
+            return {
+                success: false,
+                output: 'Storage adapter not configured',
+                error: 'No storage adapter provided in context',
+            };
+        }
+        const path = input.path || '.';
+        const recursive = input.recursive ?? false;
+        const pattern = input.pattern;
+        try {
+            const normalizedPath = path === '.' ? '' : path;
+            const files = await context.storage.listFiles(normalizedPath, { recursive, pattern });
+            return formatListResult(path, files);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            return {
+                success: false,
+                output: `Failed to list files: ${message}`,
+                error: message,
+            };
+        }
+    },
+};
+function validateListInput(input, context) {
+    const path = input.path || '.';
+    if (!isValidRelativePath(path)) {
+        return {
+            success: false,
+            output: 'Invalid path: path traversal not allowed',
+            error: 'Path must be relative and cannot contain ".."',
+        };
+    }
+    if (!context.storage) {
+        return {
+            success: false,
+            output: 'Storage adapter not configured',
+            error: 'No storage adapter provided in context',
+        };
+    }
+    return null;
+}
+function formatListResult(path, files) {
+    if (!files.length) {
+        return {
+            success: true,
+            output: `Directory "${path}" is empty or does not exist`,
+            data: { path, files: [], count: 0 },
+        };
+    }
+    const formatted = files
+        .map((f) => {
+        const icon = f.type === 'directory' ? '📁' : '📄';
+        const size = f.size !== undefined ? ` (${formatBytes(f.size)})` : '';
+        return `${icon} ${f.path}${size}`;
+    })
+        .join('\n');
+    return {
+        success: true,
+        output: formatted,
+        data: { path, files, count: files.length },
+    };
+}
+//# sourceMappingURL=list-files.js.map

package/dist/esm/ai-tools/read-file.d.ts

@@ -0,0 +1,3 @@
+import type { AgentTool } from './types.js';
+export declare const readFileTool: AgentTool;
+//# sourceMappingURL=read-file.d.ts.map

package/dist/esm/ai-tools/read-file.js

@@ -0,0 +1,108 @@
+import { getErrorMessage } from '#format/errors.js';
+import { isValidRelativePath } from './shared/validate-path.js';
+async function getSemanticContext(semanticContext, ragRetriever, path) {
+    if (!semanticContext || !ragRetriever) {
+        return '';
+    }
+    try {
+        const ctx = await ragRetriever.retrieve(path, { topK: 3 });
+        if (!ctx.chunks.length) {
+            return '';
+        }
+        const formatted = ctx.chunks
+            .map((r) => {
+            const meta = r.chunk.metadata;
+            const filepath = meta?.filepath ?? 'unknown';
+            const start = meta?.startLine;
+            const end = meta?.endLine;
+            const loc = start && end ? `${filepath}:${start}-${end}` : filepath;
+            const snippet = (r.chunk.content || '').split('\n').slice(0, 5).join('\n');
+            return `${loc}\n${snippet}`;
+        })
+            .join('\n\n');
+        return `\n\nSemantic context:\n${formatted}`;
+    }
+    catch (error) {
+        console.warn('read_file semantic context failed', error);
+        return '';
+    }
+}
+function handleReadFileError(error, path) {
+    const message = getErrorMessage(error);
+    if (message.includes('ENOENT')) {
+        return {
+            success: false,
+            output: `File not found: ${path}`,
+            error: `File "${path}" does not exist`,
+        };
+    }
+    return {
+        success: false,
+        output: `Failed to read file: ${message}`,
+        error: message,
+    };
+}
+export const readFileTool = {
+    name: 'read_file',
+    description: 'Read the contents of a file at the specified path. Returns the file content as text. Use this to understand existing code before making changes.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'The relative path to the file to read (e.g., "src/index.ts")',
+            },
+            startLine: {
+                type: 'number',
+                description: 'Optional starting line number (1-indexed). If omitted, reads from the beginning.',
+            },
+            endLine: {
+                type: 'number',
+                description: 'Optional ending line number (1-indexed, inclusive). If omitted, reads to the end.',
+            },
+            semanticContext: {
+                type: 'boolean',
+                description: 'If true and ragRetriever is available, returns top semantic matches for this file path.',
+            },
+        },
+        required: ['path'],
+    },
+    async execute(input, context) {
+        const path = input.path;
+        const startLine = input.startLine;
+        const endLine = input.endLine;
+        const semanticContext = input.semanticContext ?? false;
+        if (!isValidRelativePath(path)) {
+            return {
+                success: false,
+                output: 'Invalid path: path traversal not allowed',
+                error: 'Path must be relative and cannot contain ".."',
+            };
+        }
+        if (!context.storage) {
+            return {
+                success: false,
+                output: 'Storage adapter not configured',
+                error: 'No storage adapter provided in context',
+            };
+        }
+        try {
+            const content = await context.storage.readFile(path, { startLine, endLine });
+            const lines = content.split('\n');
+            const startIdx = startLine ?? 1;
+            const numberedContent = lines
+                .map((line, i) => `${String(startIdx + i).padStart(4, ' ')}│ ${line}`)
+                .join('\n');
+            const semanticSection = await getSemanticContext(semanticContext, context.ragRetriever, path);
+            return {
+                success: true,
+                output: numberedContent + semanticSection,
+                data: { path, lineCount: lines.length, startLine: startIdx },
+            };
+        }
+        catch (error) {
+            return handleReadFileError(error, path);
+        }
+    },
+};
+//# sourceMappingURL=read-file.js.map

package/dist/esm/ai-tools/search-files.d.ts

@@ -0,0 +1,3 @@
+import type { AgentTool } from './types.js';
+export declare const searchFilesTool: AgentTool;
+//# sourceMappingURL=search-files.d.ts.map