clementine-agent 1.18.46 → 1.18.47

package/dist/agent/assistant.d.ts

@@ -284,6 +284,19 @@ export declare class PersonalAssistant {
      * having to recreate the surrounding plumbing.
      */
     triggerMemoryExtractionPostExchange(userMessage: string, assistantResponse: string, sessionKey?: string, profile?: AgentProfile): Promise<void>;
+    /**
+     * Public entry point for the post-cron quality reflection. Used by
+     * the new runAgentCron path (Phase 4) to keep the existing Haiku
+     * verification pass + cron-progress bridge without duplicating it.
+     * Always best-effort — failures are swallowed to never block.
+     */
+    triggerCronReflection(jobName: string, jobPrompt: string, deliverable: string, successCriteria?: string[]): Promise<void>;
+    /**
+     * Public entry point for procedural-memory skill extraction after a
+     * successful execution. Used by the new runAgentCron path (Phase 4)
+     * so the new code path keeps growing the skills library.
+     */
+    triggerSkillExtractionFromExecution(source: 'unleashed' | 'cron' | 'chat', jobName: string, prompt: string, output: string, durationMs: number, agentSlug?: string): Promise<void>;
     private spawnMemoryExtraction;
     private static readonly MEMORY_TOOL_NAMES;
     private extractMemory;

package/dist/agent/assistant.js

@@ -4892,6 +4892,23 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
     async triggerMemoryExtractionPostExchange(userMessage, assistantResponse, sessionKey, profile) {
         return this.spawnMemoryExtraction(userMessage, assistantResponse, sessionKey, profile);
     }
+    /**
+     * Public entry point for the post-cron quality reflection. Used by
+     * the new runAgentCron path (Phase 4) to keep the existing Haiku
+     * verification pass + cron-progress bridge without duplicating it.
+     * Always best-effort — failures are swallowed to never block.
+     */
+    async triggerCronReflection(jobName, jobPrompt, deliverable, successCriteria) {
+        return this.runCronReflection(jobName, jobPrompt, deliverable, successCriteria);
+    }
+    /**
+     * Public entry point for procedural-memory skill extraction after a
+     * successful execution. Used by the new runAgentCron path (Phase 4)
+     * so the new code path keeps growing the skills library.
+     */
+    async triggerSkillExtractionFromExecution(source, jobName, prompt, output, durationMs, agentSlug) {
+        return this.extractSkillFromExecution(source, jobName, prompt, output, durationMs, agentSlug);
+    }
     async spawnMemoryExtraction(userMessage, assistantResponse, sessionKey, profile) {
         // Guard: skip memory extraction if the user message looks like injection
         const memScan = scanner.scan(userMessage);

package/dist/agent/run-agent-cron.d.ts

@@ -18,6 +18,14 @@ import type { AgentProfile } from '../types.js';
 import type { AgentManager } from './agent-manager.js';
 import type { MemoryStore } from '../memory/store.js';
 import { type RunAgentResult } from './run-agent.js';
+/** Minimal interface for the post-task reflection + skill extraction
+ *  hooks. Lets `runAgentCron` stay decoupled from the full
+ *  PersonalAssistant import while still benefiting from the existing
+ *  procedures. */
+export interface CronPostTaskHooks {
+    triggerCronReflection: (jobName: string, jobPrompt: string, deliverable: string, successCriteria?: string[]) => Promise<void>;
+    triggerSkillExtractionFromExecution: (source: 'unleashed' | 'cron' | 'chat', jobName: string, prompt: string, output: string, durationMs: number, agentSlug?: string) => Promise<void>;
+}
 export interface RunAgentCronOptions {
     /** Job name from CRON.md. Used for telemetry, progress lookup, skill match. */
     jobName: string;
@@ -43,6 +51,10 @@ export interface RunAgentCronOptions {
     workDir?: string;
     /** Abort signal for cancellation. */
     abortSignal?: AbortSignal;
+    /** Post-task hooks (reflection + skill extraction). Pass the
+     *  PersonalAssistant — it implements both members. Optional so the
+     *  helper still works in tests without the full assistant graph. */
+    postTaskHooks?: CronPostTaskHooks | null;
 }
 export interface RunAgentCronResult extends RunAgentResult {
     /** The final prompt that was sent to the agent (after context injection).

package/dist/agent/run-agent-cron.js

@@ -296,6 +296,7 @@ export async function runAgentCron(opts) {
         droppedComposio: mcp.droppedComposio,
         promptChars: builtPrompt.length,
     }, 'runAgentCron: dispatching to runAgent');
+    const startedAt = Date.now();
     const result = await runAgent(builtPrompt, {
         sessionKey: `cron:${opts.jobName}`,
         source: 'cron',
@@ -309,6 +310,21 @@ export async function runAgentCron(opts) {
         abortSignal: opts.abortSignal,
         extraMcpServers: mcp.servers,
     });
+    // ── Post-task hooks: reflection + skill extraction ────────────────
+    // Both fire-and-forget — never block the cron deliverable on these.
+    // They are the same passes the legacy runCronJob fires; without them
+    // the new path would lose the success-grading + procedural-memory
+    // growth that makes Clementine self-improving.
+    const deliverable = result.text ?? '';
+    if (opts.postTaskHooks && deliverable && deliverable.trim() !== '__NOTHING__') {
+        const durationMs = Date.now() - startedAt;
+        opts.postTaskHooks
+            .triggerCronReflection(opts.jobName, opts.jobPrompt, deliverable, opts.successCriteria)
+            .catch(err => logger.debug({ err, job: opts.jobName }, 'runAgentCron: reflection failed (non-fatal)'));
+        opts.postTaskHooks
+            .triggerSkillExtractionFromExecution('cron', opts.jobName, opts.jobPrompt, deliverable, durationMs, agentSlug)
+            .catch(err => logger.debug({ err, job: opts.jobName }, 'runAgentCron: skill extraction failed (non-fatal)'));
+    }
     return {
         ...result,
         builtPrompt,

package/dist/agent/run-agent-heartbeat.d.ts

@@ -0,0 +1,24 @@
+import type { AgentProfile } from '../types.js';
+import type { MemoryStore } from '../memory/store.js';
+import { type RunAgentResult } from './run-agent.js';
+export interface RunAgentHeartbeatOptions {
+    standingInstructions: string;
+    changesSummary?: string;
+    timeContext?: string;
+    dedupContext?: string;
+    profile?: AgentProfile | null;
+    memoryStore?: MemoryStore | null;
+    abortSignal?: AbortSignal;
+    /** Optional model override — defaults to Haiku (cheapest, fastest). */
+    model?: string;
+    /** Optional budget override — defaults to $0.15 (heartbeats are 1 turn). */
+    maxBudgetUsd?: number;
+}
+/**
+ * Run a heartbeat decision via the canonical SDK runAgent path.
+ *
+ * No tools. No MCP. Single turn. The agent looks at the context
+ * blocks, decides, emits text, returns.
+ */
+export declare function runAgentHeartbeat(opts: RunAgentHeartbeatOptions): Promise<RunAgentResult>;
+//# sourceMappingURL=run-agent-heartbeat.d.ts.map

package/dist/agent/run-agent-heartbeat.js

@@ -0,0 +1,84 @@
+/**
+ * Clementine TypeScript — runAgent heartbeat wrapper.
+ *
+ * Phase 4 of the SDK-canonical migration (see
+ * /Users/nathan.reynolds/.claude/plans/sdk-canonical-migration.md).
+ *
+ * Heartbeats are tool-free decision-makers. They look at standing
+ * instructions, what changed, and the time of day, and decide whether
+ * there's anything worth flagging to the owner. Output is plain text;
+ * no MCP servers, no Composio toolkits, no subagents.
+ *
+ * Mirrors the legacy assistant.heartbeat() prompt shape exactly so the
+ * voice/dedup behavior stays identical, but routes the actual LLM call
+ * through the canonical runAgent() instead of buildOptions+query.
+ */
+import pino from 'pino';
+import { OWNER_NAME, MODELS, } from '../config.js';
+const OWNER = OWNER_NAME || 'the user';
+function formatDate(d) {
+    return d.toLocaleDateString('en-US', {
+        weekday: 'long', year: 'numeric', month: 'long', day: 'numeric',
+    });
+}
+function formatTime(d) {
+    return d.toLocaleTimeString('en-US', { hour: 'numeric', minute: '2-digit', hour12: true });
+}
+import { runAgent } from './run-agent.js';
+const logger = pino({ name: 'clementine.run-agent-heartbeat' });
+/**
+ * Run a heartbeat decision via the canonical SDK runAgent path.
+ *
+ * No tools. No MCP. Single turn. The agent looks at the context
+ * blocks, decides, emits text, returns.
+ */
+export async function runAgentHeartbeat(opts) {
+    const now = new Date();
+    const localTime = formatTime(now);
+    const localDate = formatDate(now);
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    const owner = OWNER;
+    const agentName = opts.profile?.name ?? 'personal assistant';
+    const promptParts = [
+        `[Heartbeat — ${localTime}, ${localDate} (${tz})]`,
+        `You're ${agentName}, casually checking in with ${owner}. Talk like a teammate — not a system.`,
+        `Do NOT call any tools. Everything you need is in the context below. ` +
+            `If you notice something that would need a tool to investigate or act on, just mention it conversationally and ask ${owner} if he wants you to look into it.`,
+    ];
+    if (opts.dedupContext) {
+        promptParts.push(`\n${opts.dedupContext}\n\nIf all of the above are unchanged, respond with exactly: __NOTHING__`);
+    }
+    if (opts.timeContext) {
+        promptParts.push(`\nTime of day: ${opts.timeContext}`);
+    }
+    if (opts.changesSummary) {
+        promptParts.push(`\nWhat's new:\n${opts.changesSummary}`);
+    }
+    promptParts.push(`\nIf nothing changed, respond with exactly: __NOTHING__\n` +
+        `Otherwise, keep it casual and brief (1-3 sentences). No bullet lists, no formal reports, no repeating info from previous check-ins. ` +
+        `Only mention what's genuinely new or worth flagging. Be a person, not a dashboard. ` +
+        `Tag topics with [topic: key] for dedup tracking.\n\n` +
+        `Standing instructions:\n${opts.standingInstructions}`);
+    const prompt = promptParts.join('\n');
+    logger.info({
+        agentName,
+        profile: opts.profile?.slug,
+        promptChars: prompt.length,
+    }, 'runAgentHeartbeat: dispatching to runAgent (no tools)');
+    return runAgent(prompt, {
+        sessionKey: `heartbeat:${opts.profile?.slug ?? 'clementine'}`,
+        source: 'heartbeat',
+        profile: opts.profile,
+        memoryStore: opts.memoryStore,
+        model: opts.model ?? MODELS.haiku,
+        effort: 'low',
+        maxBudgetUsd: opts.maxBudgetUsd ?? 0.15,
+        maxTurns: 1,
+        // No tools — heartbeats are decision-only. Empty list bypasses the
+        // CORE_TOOLS_FOR_AGENT_PARENT default and stops the SDK from
+        // exposing any tool schemas, keeping the prompt small.
+        allowedTools: [],
+        abortSignal: opts.abortSignal,
+    });
+}
+//# sourceMappingURL=run-agent-heartbeat.js.map

package/dist/agent/run-agent-team-task.d.ts

@@ -0,0 +1,27 @@
+import type { AgentProfile } from '../types.js';
+import type { AgentManager } from './agent-manager.js';
+import type { MemoryStore } from '../memory/store.js';
+import { type RunAgentResult } from './run-agent.js';
+export interface RunAgentTeamTaskOptions {
+    fromName: string;
+    fromSlug: string;
+    content: string;
+    profile: AgentProfile;
+    agentManager?: AgentManager | null;
+    memoryStore?: MemoryStore | null;
+    abortSignal?: AbortSignal;
+    /** Optional model override. Default: SDK default (Sonnet). */
+    model?: string;
+    /** Optional max-budget override. Default: $1.50 (more than cron because team tasks are
+     *  often ad-hoc and may need more research/tool calls). */
+    maxBudgetUsd?: number;
+    /** Optional max-turns cap. Default: undefined (SDK runs until done, bounded by budget). */
+    maxTurns?: number;
+}
+export interface RunAgentTeamTaskResult extends RunAgentResult {
+    builtPrompt: string;
+    composioConnected: string[];
+    externalConnected: string[];
+}
+export declare function runAgentTeamTask(opts: RunAgentTeamTaskOptions): Promise<RunAgentTeamTaskResult>;
+//# sourceMappingURL=run-agent-team-task.d.ts.map

package/dist/agent/run-agent-team-task.js

@@ -0,0 +1,72 @@
+/**
+ * Clementine TypeScript — runAgent team-task wrapper.
+ *
+ * Phase 4 of the SDK-canonical migration (see
+ * /Users/nathan.reynolds/.claude/plans/sdk-canonical-migration.md).
+ *
+ * A "team task" is one hired agent (or Clementine herself) sending a
+ * direct message to another agent. The recipient processes it
+ * autonomously — same toolset as cron, plus Composio + external MCP.
+ *
+ * Legacy `assistant.runTeamTask` ran a 10-phase loop with deadlines,
+ * stall guards, manual session resume, and a "recovery" phase. The
+ * canonical pattern is one runAgent call with a generous budget — the
+ * SDK owns the inner loop, compaction, and retry. Phases were a
+ * pre-SDK workaround; we don't need them anymore.
+ */
+import pino from 'pino';
+import { runAgent } from './run-agent.js';
+import { buildExtraMcpForRunAgent } from './run-agent-mcp.js';
+const logger = pino({ name: 'clementine.run-agent-team-task' });
+export async function runAgentTeamTask(opts) {
+    const taskName = `team-msg:${opts.fromSlug}-to-${opts.profile.slug}`;
+    const now = new Date();
+    const timestamp = now.toISOString().slice(0, 16).replace('T', ' ');
+    // Match the legacy phase-1 prompt shape so existing agent training
+    // (Sasha/Ross/Nora) keeps responding the same way. Phases 2+ are no
+    // longer needed — the SDK keeps the conversation in one session.
+    const builtPrompt = `[TEAM MESSAGE from ${opts.fromName} (${opts.fromSlug}) — ${timestamp}]\n\n` +
+        `You received a direct message from a teammate. Process it fully and autonomously.\n\n` +
+        `MESSAGE:\n${opts.content}\n\n` +
+        `IMPORTANT:\n` +
+        `- Complete the full task described in the message\n` +
+        `- Use all tools available to you — Salesforce, DataForSEO, Discord, etc.\n` +
+        `- Post results to Discord channels as instructed\n` +
+        `- When finished, output "TASK_COMPLETE:" followed by a brief summary of what you did`;
+    const mcp = await buildExtraMcpForRunAgent({
+        scopeText: [taskName, opts.content, opts.profile.description, opts.profile.systemPromptBody]
+            .filter(Boolean)
+            .join('\n\n'),
+        profile: opts.profile,
+    });
+    logger.info({
+        taskName,
+        fromSlug: opts.fromSlug,
+        toSlug: opts.profile.slug,
+        composioConnected: mcp.composioConnected,
+        externalConnected: mcp.externalConnected,
+        droppedClaudeAi: mcp.droppedClaudeAi,
+        droppedComposio: mcp.droppedComposio,
+        promptChars: builtPrompt.length,
+    }, 'runAgentTeamTask: dispatching to runAgent');
+    const result = await runAgent(builtPrompt, {
+        sessionKey: `team-task:${opts.fromSlug}->${opts.profile.slug}`,
+        source: 'team-task',
+        profile: opts.profile,
+        agentManager: opts.agentManager,
+        memoryStore: opts.memoryStore,
+        model: opts.model,
+        effort: 'medium',
+        maxBudgetUsd: opts.maxBudgetUsd ?? 1.50,
+        maxTurns: opts.maxTurns,
+        abortSignal: opts.abortSignal,
+        extraMcpServers: mcp.servers,
+    });
+    return {
+        ...result,
+        builtPrompt,
+        composioConnected: mcp.composioConnected,
+        externalConnected: mcp.externalConnected,
+    };
+}
+//# sourceMappingURL=run-agent-team-task.js.map

package/dist/gateway/router.js

@@ -2578,6 +2578,42 @@ export class Gateway {
             events.emit('heartbeat:start', { agent, timestamp: Date.now() });
             const hbStart = Date.now();
             try {
+                // ── Phase 4: opt-in canonical SDK heartbeat path ──────────────
+                // CLEMENTINE_USE_RUNAGENT_HEARTBEAT=1 routes through
+                // runAgentHeartbeat (no tools, Haiku, single turn). Default OFF;
+                // falls back to legacy on error.
+                const useRunAgentHeartbeat = process.env.CLEMENTINE_USE_RUNAGENT_HEARTBEAT === '1';
+                if (useRunAgentHeartbeat) {
+                    try {
+                        const { runAgentHeartbeat } = await import('../agent/run-agent-heartbeat.js');
+                        logger.info({ agent, path: 'runagent_heartbeat' }, 'Phase 4: routing heartbeat through runAgentHeartbeat');
+                        const result = await runAgentHeartbeat({
+                            standingInstructions,
+                            changesSummary,
+                            timeContext,
+                            dedupContext,
+                            profile,
+                            memoryStore: this.assistant.getMemoryStore?.() ?? null,
+                        });
+                        scanner.refreshIntegrity();
+                        events.emit('heartbeat:complete', {
+                            agent,
+                            durationMs: Date.now() - hbStart,
+                            responseLength: result.text?.length ?? 0,
+                        });
+                        logger.info({
+                            agent,
+                            cost: Number(result.totalCostUsd.toFixed(4)),
+                            numTurns: result.numTurns,
+                            durationMs: Date.now() - hbStart,
+                        }, 'runAgentHeartbeat: heartbeat complete');
+                        return result.text;
+                    }
+                    catch (err) {
+                        logger.warn({ err, agent }, 'runAgentHeartbeat path failed — falling back to legacy heartbeat path');
+                        // Fall through to legacy.
+                    }
+                }
                 const response = await this.assistant.heartbeat(standingInstructions, changesSummary, timeContext, dedupContext, profile);
                 // Re-baseline integrity checksums after heartbeat (may write to vault)
                 scanner.refreshIntegrity();
@@ -2625,6 +2661,10 @@ export class Gateway {
                             successCriteria,
                             model,
                             workDir,
+                            // Phase 4: post-task hooks restore reflection + skill
+                            // extraction on the new cron path. The PersonalAssistant
+                            // implements both members directly.
+                            postTaskHooks: this.assistant,
                         });
                         response = cronResult.text;
                         scanner.refreshIntegrity();
@@ -2680,6 +2720,48 @@ export class Gateway {
         const releaseLane = await lanes.acquire('cron');
         try {
             logger.info({ fromSlug, toSlug: profile.slug }, 'Running team message as autonomous task');
+            // ── Phase 4: opt-in canonical SDK team-task path ───────────────
+            // CLEMENTINE_USE_RUNAGENT_TEAM=1 routes through runAgentTeamTask
+            // (one runAgent call, SDK owns the loop — no phase wrapper).
+            // Default OFF; falls back to legacy on error.
+            const useRunAgentTeam = process.env.CLEMENTINE_USE_RUNAGENT_TEAM === '1';
+            if (useRunAgentTeam) {
+                try {
+                    const { runAgentTeamTask } = await import('../agent/run-agent-team-task.js');
+                    logger.info({ fromSlug, toSlug: profile.slug, path: 'runagent_team_task' }, 'Phase 4: routing team task through runAgentTeamTask');
+                    const result = await runAgentTeamTask({
+                        fromName,
+                        fromSlug,
+                        content,
+                        profile,
+                        agentManager: this.getAgentManager(),
+                        memoryStore: this.assistant.getMemoryStore?.() ?? null,
+                        abortSignal: abortController?.signal,
+                    });
+                    scanner.refreshIntegrity();
+                    logger.info({
+                        fromSlug,
+                        toSlug: profile.slug,
+                        cost: Number(result.totalCostUsd.toFixed(4)),
+                        numTurns: result.numTurns,
+                        composioConnected: result.composioConnected.length,
+                    }, 'runAgentTeamTask: team task complete');
+                    // Best-effort streaming: if a callback is provided, deliver
+                    // the final text in one chunk (the SDK already streamed it
+                    // internally to runAgent's onText, but we collected it).
+                    if (onText && result.text) {
+                        try {
+                            onText(result.text);
+                        }
+                        catch { /* ignore */ }
+                    }
+                    return result.text;
+                }
+                catch (err) {
+                    logger.warn({ err, fromSlug, toSlug: profile.slug }, 'runAgentTeamTask path failed — falling back to legacy team-task path');
+                    // Fall through to legacy.
+                }
+            }
             const response = await this.assistant.runTeamTask(fromName, fromSlug, content, profile, onText, abortController);
             scanner.refreshIntegrity();
             return response;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.18.46",
+  "version": "1.18.47",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",