@pennyfarthing/core 11.0.0-alpha.0 → 11.1.0

package/packages/core/dist/consultation/consultation-protocol.js

@@ -0,0 +1,178 @@
+/**
+ * Consultation Protocol for Story 86-2
+ *
+ * Active request/response mechanism for tandem agent consultation.
+ * Unlike passive backseat observation (95-2), consultation is leader-initiated:
+ * the primary agent spawns a partner agent with a focused question and receives
+ * a structured recommendation.
+ */
+// =============================================================================
+// Constants
+// =============================================================================
+const VALID_CONFIDENCE_LEVELS = new Set(['high', 'medium', 'low']);
+// =============================================================================
+// Implementations
+// =============================================================================
+/**
+ * Format a consultation request as structured markdown.
+ */
+export function formatConsultationRequest(request) {
+    const alternatives = request.alternativesConsidered
+        .map(alt => `- ${alt}`)
+        .join('\n');
+    return `**Leader:** ${request.leader} (${request.leaderCharacter})
+**Partner:** ${request.partner}
+**Context:** ${request.context}
+**Question:** ${request.question}
+**Alternatives Considered:**
+${alternatives}
+**Relevant Code/Files:** ${request.relevantCode}
+**Token Budget:** ${request.tokenBudget}`;
+}
+/**
+ * Extract a markdown field value from text.
+ * Handles leading/trailing whitespace around the value.
+ */
+function extractField(markdown, fieldName) {
+    const pattern = new RegExp(`\\*\\*${fieldName}:\\*\\*\\s*(.+)`, 'i');
+    const match = markdown.match(pattern);
+    return match ? match[1].trim() : undefined;
+}
+/**
+ * Parse a consultation response from partner's markdown output.
+ * Returns null if the response cannot be parsed.
+ */
+export function parseConsultationResponse(markdown) {
+    const recommendation = extractField(markdown, 'Recommendation');
+    if (!recommendation) {
+        return null;
+    }
+    const rationale = extractField(markdown, 'Rationale') ?? '';
+    const watchOutFor = extractField(markdown, 'Watch-Out-For') ?? '';
+    const confidenceRaw = extractField(markdown, 'Confidence');
+    const tokenCountRaw = extractField(markdown, 'Token Count');
+    if (!confidenceRaw || !VALID_CONFIDENCE_LEVELS.has(confidenceRaw)) {
+        return null;
+    }
+    const tokenCount = tokenCountRaw ? parseInt(tokenCountRaw, 10) : 0;
+    return {
+        recommendation,
+        rationale,
+        watchOutFor,
+        confidence: confidenceRaw,
+        tokenCount: Number.isNaN(tokenCount) ? 0 : tokenCount,
+    };
+}
+/**
+ * Validate a consultation request has all required fields.
+ */
+export function validateConsultationRequest(request) {
+    const errors = [];
+    if (!request.leader)
+        errors.push('leader is required');
+    if (!request.partner)
+        errors.push('partner is required');
+    if (!request.context)
+        errors.push('context is required');
+    if (!request.question)
+        errors.push('question is required');
+    if (!request.relevantCode)
+        errors.push('relevantCode is required');
+    if (request.tokenBudget <= 0)
+        errors.push('tokenBudget must be a positive number');
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Validate a consultation response has all required fields.
+ */
+export function validateConsultationResponse(response) {
+    const errors = [];
+    if (!response.recommendation)
+        errors.push('recommendation is required');
+    if (!response.rationale)
+        errors.push('rationale is required');
+    if (!response.watchOutFor)
+        errors.push('watchOutFor is required');
+    if (!VALID_CONFIDENCE_LEVELS.has(response.confidence)) {
+        errors.push('confidence must be high, medium, or low');
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Build the full prompt for spawning the consultation partner.
+ * Includes: agent definition, persona, formatted request, token budget instruction.
+ */
+export function buildPartnerPrompt(params) {
+    return `${params.agentDefinition}
+
+${params.personaBlock}
+
+# Consultation Request
+
+${params.formattedRequest}
+
+# Response Format
+
+Respond using this exact format:
+
+**Recommendation:** {your concise recommendation}
+**Rationale:** {why you recommend this approach}
+**Watch-Out-For:** {pitfalls or edge cases}
+**Confidence:** {high|medium|low}
+**Token Count:** {approximate token count of your response}
+
+Your response must not exceed ${params.tokenBudget} tokens. Be concise and focused.`;
+}
+/**
+ * Build spawn parameters for the consultation partner.
+ * Returns model: 'sonnet' per ADR-0012 (advisors use Sonnet, not Haiku).
+ */
+export function buildConsultationSpawnParams(request) {
+    return {
+        model: 'sonnet',
+        partner: request.partner,
+    };
+}
+/**
+ * Execute a full consultation: format request → build prompt → spawn partner → parse response.
+ * On failure, returns degraded result so leader can continue solo.
+ */
+export async function executeConsultation(params) {
+    const { request, agentDefinition, personaBlock, adapter } = params;
+    const formattedRequest = formatConsultationRequest(request);
+    const prompt = buildPartnerPrompt({
+        agentDefinition,
+        personaBlock,
+        formattedRequest,
+        tokenBudget: request.tokenBudget,
+    });
+    const spawnParams = buildConsultationSpawnParams(request);
+    let responseText;
+    try {
+        const result = await adapter.spawn({ prompt, model: spawnParams.model });
+        responseText = result.responseText;
+    }
+    catch (err) {
+        return {
+            success: false,
+            degraded: true,
+            error: `Consultation failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    const parsed = parseConsultationResponse(responseText);
+    if (!parsed) {
+        return {
+            success: false,
+            degraded: true,
+            error: 'Failed to parse consultation response',
+        };
+    }
+    return {
+        success: true,
+        data: {
+            response: parsed,
+            overBudget: parsed.tokenCount > request.tokenBudget,
+        },
+    };
+}
+//# sourceMappingURL=consultation-protocol.js.map

package/packages/core/dist/consultation/consultation-protocol.js.map

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

package/packages/core/dist/consultation/consultation-protocol.test.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tests for Story 86-2: Consultation Protocol Implementation
+ *
+ * RED state tests for the tandem consultation protocol.
+ * Consultation is an active request/response mechanism where a leader agent
+ * spawns a partner agent with a focused question and receives a structured recommendation.
+ *
+ * ACs covered:
+ *   AC1: Consultation request format (context, question, options, code)
+ *   AC2: Consultation response format (recommendation, rationale, watch-out-for, confidence)
+ *   AC3: Leader spawns partner via Task tool with model: sonnet
+ *   AC4: Partner prompt includes: agent definition, persona, consultation request
+ *   AC5: Response parsed and available to leader for continued work
+ *   AC6: Graceful degradation: partner failure → leader continues solo
+ *   AC7: Token budget enforced via prompt instruction
+ *
+ * Run with: npm test
+ */
+export {};
+//# sourceMappingURL=consultation-protocol.test.d.ts.map

package/packages/core/dist/consultation/consultation-protocol.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consultation-protocol.test.d.ts","sourceRoot":"","sources":["../../src/consultation/consultation-protocol.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}