clementine-agent 1.0.0

package/dist/agent/metacognition.js

@@ -0,0 +1,221 @@
+/**
+ * Clementine TypeScript — Metacognitive Monitor.
+ *
+ * Tracks reasoning quality signals during query/cron/unleashed execution.
+ * Detects stuck loops, circular reasoning, confidence drops, and strategy
+ * mismatches. Injects guidance when the agent appears to need a nudge.
+ *
+ * This is the foundation layer — everything else (user model, self-improve,
+ * skills) works better when the agent can evaluate its own thinking.
+ */
+import { createHash } from 'node:crypto';
+// ── Tool categories ─────────────────────────────────────────────────
+const READ_TOOLS = new Set([
+    'Read', 'Glob', 'Grep', 'memory_read', 'memory_search', 'memory_recall',
+    'transcript_search', 'vault_stats', 'task_list', 'goal_list', 'goal_get',
+    'workspace_list', 'workspace_info', 'cron_list', 'team_list',
+    'outlook_inbox', 'outlook_search', 'outlook_calendar', 'github_prs',
+    'rss_fetch', 'WebSearch', 'WebFetch',
+]);
+const ACTION_TOOLS = new Set([
+    'Write', 'Edit', 'Bash', 'Agent', 'Task', 'delegate_task',
+    'memory_write', 'note_create', 'note_take',
+    'task_add', 'task_update', 'goal_create', 'goal_update', 'goal_work',
+    'add_cron_job', 'create_agent', 'update_agent', 'delete_agent',
+    'team_message', 'discord_channel_send', 'outlook_draft', 'outlook_send',
+    'set_timer', 'self_restart', 'feedback_log', 'teach_skill', 'create_tool',
+]);
+// ── MetacognitiveMonitor ────────────────────────────────────────────
+export class MetacognitiveMonitor {
+    toolCalls = [];
+    uniqueTools = new Set();
+    consecutiveReads = 0;
+    turnCount = 0;
+    outputCharCount = 0;
+    interventionCount = 0;
+    signals = [];
+    confidence = 'high';
+    /**
+     * Record a tool call. Returns a signal if the pattern is concerning.
+     */
+    recordToolCall(name, input) {
+        const inputHash = createHash('sha256').update(JSON.stringify(input)).digest('hex').slice(0, 12);
+        this.toolCalls.push({ name, inputHash, timestamp: Date.now() });
+        this.uniqueTools.add(name);
+        // Normalize MCP tool names: "mcp__clementine-tools__memory_write" → "memory_write"
+        const normalizedName = name.replace(/^mcp__[^_]+__/, '');
+        // Track read/action balance (check both raw and normalized names)
+        if (READ_TOOLS.has(name) || READ_TOOLS.has(normalizedName)) {
+            this.consecutiveReads++;
+        }
+        else if (ACTION_TOOLS.has(name) || ACTION_TOOLS.has(normalizedName)) {
+            this.consecutiveReads = 0;
+        }
+        // Signal: too many consecutive reads without action
+        // Fires on every read past the threshold (not just once) so the stall breaker stays active
+        if (this.consecutiveReads >= 12) {
+            this.confidence = 'low';
+            if (!this.signals.includes('research_without_action'))
+                this.signals.push('research_without_action');
+            this.interventionCount++;
+            return {
+                type: 'intervene',
+                reason: 'research_without_action',
+                guidance: `You've done ${this.consecutiveReads} consecutive reads without acting. STOP reading and either act on what you have or tell the user what's blocking you.`,
+            };
+        }
+        if (this.consecutiveReads >= 8) {
+            this.confidence = 'medium';
+            if (!this.signals.includes('research_without_action'))
+                this.signals.push('research_without_action');
+            return {
+                type: 'warn',
+                reason: 'research_without_action',
+                guidance: `You've done ${this.consecutiveReads} consecutive reads without acting. Pick a strategy: ` +
+                    `(1) Delegate — spawn sub-agents via the Agent tool for parallel work. ` +
+                    `(2) Plan — respond with [PLAN_NEEDED: description] for complex tasks. ` +
+                    `(3) Act on partial info — start editing with what you know. ` +
+                    `(4) Ask the user a specific question if scope is unclear.`,
+            };
+        }
+        // Signal: same tool + similar input called 3+ times
+        const recentSame = this.toolCalls
+            .slice(-10)
+            .filter(t => t.name === name && t.inputHash === inputHash);
+        if (recentSame.length >= 3) {
+            this.confidence = 'low';
+            const signal = {
+                type: 'intervene',
+                reason: 'circular_reasoning',
+                guidance: `You've called ${name} with the same input ${recentSame.length} times. Try a different approach or tool.`,
+            };
+            if (!this.signals.includes('circular_reasoning'))
+                this.signals.push('circular_reasoning');
+            this.interventionCount++;
+            return signal;
+        }
+        // Signal: excessive tool calls (>20 in a single execution)
+        if (this.toolCalls.length > 20 && this.outputCharCount < 200) {
+            this.confidence = 'low';
+            if (!this.signals.includes('high_effort_low_output')) {
+                this.signals.push('high_effort_low_output');
+                return {
+                    type: 'warn',
+                    reason: 'high_effort_low_output',
+                    guidance: 'You\'ve made 20+ tool calls with minimal output. Step back and simplify your approach.',
+                };
+            }
+        }
+        return { type: 'ok' };
+    }
+    /**
+     * Assess the quality of the current turn after the assistant responds.
+     */
+    assessTurn(responseText, toolCallsThisTurn) {
+        this.turnCount++;
+        this.outputCharCount += responseText.length;
+        // Reset consecutive reads if the agent produced substantial output
+        if (responseText.length > 100 && toolCallsThisTurn === 0) {
+            this.consecutiveReads = 0;
+        }
+        const efficiency = this.turnCount > 0
+            ? Math.min(1, this.outputCharCount / (this.turnCount * 500))
+            : 0;
+        // Detect turns with no progress
+        if (responseText.length < 20 && toolCallsThisTurn === 0) {
+            if (!this.signals.includes('empty_turn'))
+                this.signals.push('empty_turn');
+        }
+        // Build guidance if confidence is low
+        let guidance;
+        if (this.confidence === 'low' && this.interventionCount < 3) {
+            guidance = this.buildGuidance();
+            if (guidance)
+                this.interventionCount++;
+        }
+        return {
+            confidence: this.confidence,
+            efficiency,
+            signals: [...this.signals],
+            guidance,
+        };
+    }
+    /**
+     * Get the final metacognitive summary for this execution.
+     */
+    getSummary() {
+        const efficiency = this.turnCount > 0
+            ? Math.min(1, this.outputCharCount / (this.turnCount * 500))
+            : 0;
+        return {
+            efficiency: Math.round(efficiency * 100) / 100,
+            toolCallCount: this.toolCalls.length,
+            uniqueTools: this.uniqueTools.size,
+            stuckDetected: this.signals.includes('circular_reasoning') || this.signals.includes('research_without_action'),
+            interventionCount: this.interventionCount,
+            confidenceFinal: this.confidence,
+            signals: [...this.signals],
+        };
+    }
+    /**
+     * Build contextual guidance based on current signals.
+     */
+    buildGuidance() {
+        if (this.signals.includes('circular_reasoning')) {
+            return '[SELF-CHECK: You appear to be going in circles. Try a completely different approach to this problem.]';
+        }
+        if (this.signals.includes('research_without_action')) {
+            return '[SELF-CHECK: You\'ve been researching extensively. Time to act on what you\'ve gathered — deliver a result with what you know.]';
+        }
+        if (this.signals.includes('high_effort_low_output')) {
+            return '[SELF-CHECK: High effort, low output. Can you accomplish this more directly? Simplify your approach.]';
+        }
+        return undefined;
+    }
+    /**
+     * Detect when the agent's text promises action but no tools were called.
+     * Call this after the query completes with the full response text.
+     *
+     * @returns A signal if the response looks like a stall (promised action, didn't deliver).
+     */
+    detectPromiseWithoutAction(responseText, toolCallCount) {
+        if (toolCallCount > 2)
+            return { type: 'ok' };
+        const lower = responseText.toLowerCase();
+        const ACTION_PROMISES = [
+            /\blet me (?:read|grab|check|pull|get|look at|open|find|fetch|load)\b/,
+            /\bi'?ll (?:read|grab|check|pull|get|look at|open|find|fetch|start|work on)\b/,
+            /\bstarting (?:with|on|now)\b/,
+            /\bstill (?:on it|working|reading|looking)\b/,
+            /\bgive me (?:a moment|a sec|one moment)\b/,
+            /\bworking on (?:it|that|this)\b/,
+            /\blet me (?:take|have) a look\b/,
+        ];
+        const promisedAction = ACTION_PROMISES.some((rx) => rx.test(lower));
+        if (!promisedAction)
+            return { type: 'ok' };
+        // The agent said it would do something but made 0-2 tool calls — likely stalled
+        if (!this.signals.includes('promise_without_action')) {
+            this.signals.push('promise_without_action');
+        }
+        this.confidence = 'low';
+        this.interventionCount++;
+        return {
+            type: 'intervene',
+            reason: 'promise_without_action',
+            guidance: 'You said you would take action but did not follow through. ' +
+                'Do not promise to read/grab/check something without actually doing it in the same turn.',
+        };
+    }
+    /** Reset for a new execution (e.g., new phase in unleashed). */
+    reset() {
+        this.toolCalls = [];
+        this.uniqueTools.clear();
+        this.consecutiveReads = 0;
+        this.turnCount = 0;
+        this.outputCharCount = 0;
+        this.signals = [];
+        // Keep interventionCount and confidence across phases for learning
+    }
+}
+//# sourceMappingURL=metacognition.js.map

package/dist/agent/orchestrator.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Clementine TypeScript — Plan Orchestrator.
+ *
+ * Decomposes a task into steps, runs independent steps in parallel
+ * via concurrent query() calls, then synthesizes a final response.
+ */
+import type { PersonalAssistant } from './assistant.js';
+import type { AgentProfile, PlanStep, ExecutionPlan, PlanProgressUpdate } from '../types.js';
+/**
+ * Compute execution waves from a dependency graph via topological sort.
+ * Steps with empty dependsOn = wave 0. Steps whose deps are all in wave N = wave N+1.
+ */
+export declare function computeWaves(steps: PlanStep[]): PlanStep[][];
+/**
+ * Run promises with a concurrency limit.
+ */
+export declare function settledWithLimit<T>(tasks: (() => Promise<T>)[], limit: number): Promise<PromiseSettledResult<T>[]>;
+/** Persistent state for a plan execution — survives interruptions. */
+interface PlanState {
+    id: string;
+    goal: string;
+    status: 'planning' | 'executing' | 'synthesizing' | 'complete' | 'failed';
+    startedAt: string;
+    updatedAt: string;
+    plan?: ExecutionPlan;
+    totalWaves: number;
+    wavesCompleted: number;
+    results: Record<string, string>;
+    errors: Array<{
+        stepId: string;
+        error: string;
+    }>;
+    retries: Record<string, number>;
+}
+export declare class PlanOrchestrator {
+    private assistant;
+    private stepStatuses;
+    private stepStartTimes;
+    private startTime;
+    private stateId;
+    private agentProfiles;
+    constructor(assistant: PersonalAssistant);
+    private saveState;
+    private cleanupState;
+    /** Load a previously interrupted plan state (for future resumability). */
+    static loadState(stateId: string): PlanState | null;
+    /**
+     * Main entry: plan → approve → execute → synthesize → return final response.
+     */
+    run(taskDescription: string, onProgress?: (updates: PlanProgressUpdate[]) => Promise<void>, onApproval?: (planSummary: string, steps: PlanStep[]) => Promise<boolean | string>, availableAgents?: AgentProfile[]): Promise<string>;
+    /**
+     * Goal-backward verification pass using Haiku after plan synthesis.
+     * Verifies outcomes rather than just rating quality:
+     * - Did each step produce a real result?
+     * - Is the synthesized output substantive (not restating the question)?
+     * - Are there gaps between request and output?
+     */
+    private runReflection;
+    /**
+     * Get formatted progress lines for display.
+     */
+    getProgressLines(): string[];
+    /**
+     * Inter-wave spot-check: verify that step results contain substance.
+     * Catches empty outputs, error-only results, and placeholder/stub responses
+     * before downstream waves try to build on them.
+     */
+    private spotCheckWaveResults;
+    /** Check if a step has downstream dependents in the plan. */
+    private hasDependents;
+    /** Fast Haiku call to decide how to repair a failed critical step. */
+    private getRepairDecision;
+    private generatePlan;
+    private parseJsonFromResponse;
+    private buildStepPrompt;
+    private buildSynthesisPrompt;
+    private runSingleStep;
+    private getAllUpdates;
+}
+export {};
+//# sourceMappingURL=orchestrator.d.ts.map