clementine-agent 1.18.45 → 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

@@ -0,0 +1,79 @@
+/**
+ * Clementine TypeScript — runAgent cron wrapper.
+ *
+ * Phase 3 of the SDK-canonical migration (see
+ * /Users/nathan.reynolds/.claude/plans/sdk-canonical-migration.md).
+ *
+ * Cron jobs need more than a bare runAgent() call: they get progress
+ * continuity, linked goals, delegated tasks, team context, success
+ * criteria, and matched skills injected ahead of the job prompt. This
+ * file owns that composition for the new (canonical SDK) path. The
+ * legacy assistant.ts:runCronJob keeps its inline equivalents so we
+ * can ship Phase 3 without touching legacy code.
+ *
+ * After Phase 3 verifies and we collapse the legacy path, the
+ * duplicated helpers here become the single source of truth.
+ */
+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;
+    /** Job prompt body (the user-defined "do this" text). */
+    jobPrompt: string;
+    /** Cron tier. Drives effort + budget. */
+    tier?: number;
+    /** Optional max-turns cap (the SDK runs until done otherwise, bounded by maxBudget). */
+    maxTurns?: number;
+    /** Profile of the hired agent running this job (Sasha/Ross/Nora/etc). null = Clementine. */
+    profile?: AgentProfile | null;
+    /** Hired-agent registry — passed through to runAgent so subagent delegation works. */
+    agentManager?: AgentManager | null;
+    /** Memory store for cost logging + skill use tracking. */
+    memoryStore?: MemoryStore | null;
+    /** Per-job success criteria from CRON.md frontmatter. */
+    successCriteria?: string[];
+    /** Optional model override (rare — most jobs let the SDK default decide). */
+    model?: string;
+    /** Optional max-budget override. Default: tier-1 = $1, tier-2+ = $3. */
+    maxBudgetUsd?: number;
+    /** Optional working directory override (project-scoped jobs). */
+    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).
+     *  Useful for cron diagnostics + debugging. */
+    builtPrompt: string;
+    /** Diagnostics: which Composio + external servers were live for this run. */
+    composioConnected: string[];
+    externalConnected: string[];
+}
+/**
+ * Run a cron job via the canonical SDK runAgent path.
+ *
+ * Composes the same context blocks the legacy runCronJob injects
+ * (progress, goals, delegation, team, criteria, skills, fanout
+ * directive), wires Composio + external MCP via the dedup-aware
+ * helper, then calls runAgent.
+ *
+ * The SDK handles the loop, compaction, subagent fanout, prompt
+ * caching, retries — none of which we wrap manually anymore.
+ */
+export declare function runAgentCron(opts: RunAgentCronOptions): Promise<RunAgentCronResult>;
+//# sourceMappingURL=run-agent-cron.d.ts.map

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

@@ -0,0 +1,335 @@
+/**
+ * Clementine TypeScript — runAgent cron wrapper.
+ *
+ * Phase 3 of the SDK-canonical migration (see
+ * /Users/nathan.reynolds/.claude/plans/sdk-canonical-migration.md).
+ *
+ * Cron jobs need more than a bare runAgent() call: they get progress
+ * continuity, linked goals, delegated tasks, team context, success
+ * criteria, and matched skills injected ahead of the job prompt. This
+ * file owns that composition for the new (canonical SDK) path. The
+ * legacy assistant.ts:runCronJob keeps its inline equivalents so we
+ * can ship Phase 3 without touching legacy code.
+ *
+ * After Phase 3 verifies and we collapse the legacy path, the
+ * duplicated helpers here become the single source of truth.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+import { BASE_DIR, VAULT_DIR, CRON_PROGRESS_DIR, } from '../config.js';
+import { runAgent } from './run-agent.js';
+import { buildExtraMcpForRunAgent } from './run-agent-mcp.js';
+import { buildFanoutDirectiveForText, buildAlwaysOnParallelizationHint } from './fanout-policy.js';
+import { listAllGoals } from '../tools/shared.js';
+const CRON_PROGRESS_PENDING_MAX_ITEMS = 20;
+const CRON_PROGRESS_NOTES_MAX_CHARS = 2000;
+const logger = pino({ name: 'clementine.run-agent-cron' });
+const CRON_CONTEXT_ITEM_MAX = 80;
+function capContextItem(s) {
+    if (!s)
+        return '';
+    return s.length <= CRON_CONTEXT_ITEM_MAX ? s : s.slice(0, CRON_CONTEXT_ITEM_MAX - 3) + '...';
+}
+function capContextBlock(s, max) {
+    if (!s)
+        return '';
+    return s.length <= max ? s : s.slice(0, max - 3) + '...';
+}
+/**
+ * Build the previous-progress block from the cron progress JSON file.
+ * Lets the agent continue where the prior run left off without re-doing
+ * work it already completed.
+ */
+function buildProgressContext(jobName) {
+    try {
+        const safeJob = jobName.replace(/[^a-zA-Z0-9_-]/g, '_');
+        const progressFile = path.join(CRON_PROGRESS_DIR, `${safeJob}.json`);
+        if (!fs.existsSync(progressFile))
+            return '';
+        const progress = JSON.parse(fs.readFileSync(progressFile, 'utf-8'));
+        const parts = [`## Previous Progress (run #${progress.runCount}, ${progress.lastRunAt})`];
+        if (progress.completedItems?.length > 0) {
+            parts.push(`Completed: ${progress.completedItems.slice(-10).map(capContextItem).join(', ')}`);
+        }
+        if (progress.pendingItems?.length > 0) {
+            const pendingItems = progress.pendingItems.slice(0, CRON_PROGRESS_PENDING_MAX_ITEMS).map(capContextItem);
+            const suffix = progress.pendingItems.length > CRON_PROGRESS_PENDING_MAX_ITEMS
+                ? ` (${progress.pendingItems.length - CRON_PROGRESS_PENDING_MAX_ITEMS} more omitted)`
+                : '';
+            parts.push(`Pending: ${pendingItems.join(', ')}${suffix}`);
+        }
+        if (progress.notes) {
+            parts.push(`Notes: ${capContextBlock(progress.notes, CRON_PROGRESS_NOTES_MAX_CHARS)}`);
+        }
+        return parts.join('\n') + '\n\n' +
+            'Continue from where you left off. Use `cron_progress_write` at the end to save what you completed and what\'s pending.\n\n';
+    }
+    catch {
+        return '';
+    }
+}
+/** Build the linked-goals block for jobs that contribute to active goals. */
+function buildGoalContext(jobName) {
+    try {
+        const linkedGoals = listAllGoals()
+            .map(({ goal }) => goal)
+            .filter(g => g && g.status === 'active' && g.linkedCronJobs?.includes(jobName));
+        if (linkedGoals.length === 0)
+            return '';
+        const goalLines = linkedGoals.map(g => {
+            const goalRecord = g;
+            const nextAct = goalRecord.nextActions?.length ? ` Next: ${goalRecord.nextActions[0]}` : '';
+            const recentProgress = goalRecord.progressNotes?.length
+                ? ` Last progress: ${goalRecord.progressNotes[goalRecord.progressNotes.length - 1]}`
+                : '';
+            return `- **${goalRecord.title}** (${goalRecord.id}): ${goalRecord.description.slice(0, 100)}${nextAct}${recentProgress}`;
+        });
+        return `## Active Goals Linked to This Job\n${goalLines.join('\n')}\n\n` +
+            'After completing your work, update goal progress with `goal_update` if you made meaningful progress.\n\n';
+    }
+    catch {
+        return '';
+    }
+}
+/** Build the delegated-tasks block for hired agents that have pending team requests. */
+function buildDelegationContext(agentSlug) {
+    if (!agentSlug)
+        return '';
+    try {
+        const tasksDir = path.join(VAULT_DIR, '00-System', 'agents', agentSlug, 'tasks');
+        if (!fs.existsSync(tasksDir))
+            return '';
+        const taskFiles = fs.readdirSync(tasksDir).filter(f => f.endsWith('.json'));
+        const pendingTasks = taskFiles
+            .map(f => {
+            try {
+                return JSON.parse(fs.readFileSync(path.join(tasksDir, f), 'utf-8'));
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((t) => t !== null && t.status === 'pending');
+        if (pendingTasks.length === 0)
+            return '';
+        const taskLines = pendingTasks.map(t => `- [${t.id}] From ${t.fromAgent}: ${t.task.slice(0, 150)} (expected: ${t.expectedOutput.slice(0, 80)})`);
+        return `## Delegated Tasks Waiting\n${taskLines.join('\n')}\n\n` +
+            'Work on these delegated tasks in addition to your scheduled task. ' +
+            'Mark them in_progress/completed by editing the task JSON when done.\n\n';
+    }
+    catch {
+        return '';
+    }
+}
+/** Build the team-comms block: pending requests + recent messages for this agent. */
+function buildTeamContext(agentSlug) {
+    if (!agentSlug)
+        return '';
+    try {
+        const teamLogPath = path.join(BASE_DIR, 'logs', 'team-comms.jsonl');
+        if (!fs.existsSync(teamLogPath))
+            return '';
+        const teamLines = fs.readFileSync(teamLogPath, 'utf-8').trim().split('\n').filter(Boolean);
+        const recentForAgent = teamLines
+            .slice(-50)
+            .map(l => { try {
+            return JSON.parse(l);
+        }
+        catch {
+            return null;
+        } })
+            .filter((m) => m !== null && (m.toAgent === agentSlug || m.fromAgent === agentSlug))
+            .slice(-5);
+        const pendingRequests = recentForAgent.filter(m => m.protocol === 'request' && m.toAgent === agentSlug && !m.response);
+        if (pendingRequests.length === 0 && recentForAgent.length === 0)
+            return '';
+        const parts = ['## Team Context'];
+        if (pendingRequests.length > 0) {
+            parts.push('### REPLY NEEDED — Pending Requests');
+            for (const r of pendingRequests) {
+                parts.push(`- From ${r.fromAgent}: ${r.content.slice(0, 200)}`);
+            }
+            parts.push('Address these requests before your main task.');
+        }
+        if (recentForAgent.length > 0) {
+            parts.push('### Recent Team Messages');
+            for (const m of recentForAgent) {
+                const dir = m.fromAgent === agentSlug ? 'sent to' : 'from';
+                const other = m.fromAgent === agentSlug ? m.toAgent : m.fromAgent;
+                parts.push(`- ${dir} ${other}: ${m.content.slice(0, 100)}`);
+            }
+        }
+        return parts.join('\n') + '\n\n';
+    }
+    catch {
+        return '';
+    }
+}
+/** Build the success-criteria block from job spec. */
+function buildCriteriaContext(successCriteria) {
+    if (!successCriteria?.length)
+        return '';
+    return `## Success Criteria\nYour output will be verified against these criteria:\n` +
+        successCriteria.map(c => `- ${c}`).join('\n') + '\n\n';
+}
+/** Build the matched-skills block (procedures learned from prior successful runs). */
+async function buildSkillContext(jobName, jobPrompt, agentSlug, memoryStore) {
+    try {
+        const { searchSkills, recordSkillUse } = await import('./skill-extractor.js');
+        const skillQuery = jobName + ' ' + jobPrompt.slice(0, 200);
+        const suppressedNamesRaw = memoryStore
+            ?.getSkillsToSuppress?.(agentSlug);
+        const suppressedNames = Array.isArray(suppressedNamesRaw)
+            ? new Set(suppressedNamesRaw)
+            : (suppressedNamesRaw ?? undefined);
+        const matchedSkills = searchSkills(skillQuery, 2, agentSlug, { suppressedNames });
+        if (matchedSkills.length === 0)
+            return '';
+        const skillLines = matchedSkills.map(s => {
+            recordSkillUse(s.name);
+            memoryStore?.logSkillUse?.({
+                skillName: s.name,
+                sessionKey: `cron:${agentSlug ?? 'clementine'}:${jobName}`,
+                queryText: skillQuery,
+                score: s.score,
+                agentSlug: agentSlug ?? null,
+            });
+            let block = `### ${s.title}\n${s.content}`;
+            if (s.toolsUsed.length > 0)
+                block += `\n**Tools:** ${s.toolsUsed.join(', ')}`;
+            if (s.attachments.length > 0) {
+                const attDir = path.join(s.skillDir, s.name + '.files');
+                for (const attName of s.attachments.slice(0, 3)) {
+                    const attPath = path.join(attDir, attName);
+                    if (fs.existsSync(attPath)) {
+                        try {
+                            const content = fs.readFileSync(attPath, 'utf-8').slice(0, 2000);
+                            block += `\n#### ${attName}\n\`\`\`\n${content}\n\`\`\``;
+                        }
+                        catch { /* skip */ }
+                    }
+                }
+            }
+            return block;
+        });
+        return `## Learned Procedures (from past successful executions)\nFollow these proven approaches when applicable:\n\n${skillLines.join('\n\n')}\n\n`;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Run a cron job via the canonical SDK runAgent path.
+ *
+ * Composes the same context blocks the legacy runCronJob injects
+ * (progress, goals, delegation, team, criteria, skills, fanout
+ * directive), wires Composio + external MCP via the dedup-aware
+ * helper, then calls runAgent.
+ *
+ * The SDK handles the loop, compaction, subagent fanout, prompt
+ * caching, retries — none of which we wrap manually anymore.
+ */
+export async function runAgentCron(opts) {
+    const tier = opts.tier ?? 1;
+    const agentSlug = opts.profile?.slug;
+    const ownerName = process.env.OWNER_NAME ?? 'the user';
+    // ── Compose context blocks (mirrors legacy runCronJob) ─────────────
+    const progressContext = buildProgressContext(opts.jobName);
+    const goalContext = buildGoalContext(opts.jobName);
+    const delegationContext = buildDelegationContext(agentSlug);
+    const teamContext = buildTeamContext(agentSlug);
+    const criteriaContext = buildCriteriaContext(opts.successCriteria);
+    const skillContext = await buildSkillContext(opts.jobName, opts.jobPrompt, agentSlug, opts.memoryStore);
+    // Sub-agent fanout directive — when the job description suggests
+    // multi-item work, prepend a hard-line fanout mandate.
+    const fanoutScope = `${opts.jobName}\n${opts.jobPrompt}\n${opts.profile?.description ?? ''}\n${opts.profile?.systemPromptBody ?? ''}`;
+    const { directive: fanoutDirective, report: fanoutReport } = buildFanoutDirectiveForText(fanoutScope);
+    if (fanoutReport.needsFanout) {
+        logger.info({
+            job: opts.jobName,
+            signals: fanoutReport.signals.map(s => s.pattern),
+        }, 'runAgentCron: fanout directive injected');
+    }
+    // Final prompt (matches legacy runCronJob's structure).
+    const builtPrompt = `[Scheduled task: ${opts.jobName}]\n\n` +
+        (fanoutDirective ? fanoutDirective + '\n\n' : '') +
+        buildAlwaysOnParallelizationHint() + '\n\n' +
+        progressContext +
+        goalContext +
+        skillContext +
+        delegationContext +
+        teamContext +
+        criteriaContext +
+        `${opts.jobPrompt}\n\n` +
+        `## How to respond\n` +
+        `You're sending this directly to ${ownerName} as a DM. ` +
+        `Write like you're texting a friend — casual, warm, concise. ` +
+        `Use their name naturally. No headers, bullet lists, or formal structure unless the content genuinely needs it. ` +
+        `Skip narrating your process ("I checked X, then Y..."). Just share the interesting stuff.\n\n` +
+        `If there's genuinely nothing worth mentioning (no new data, no changes, no alerts), ` +
+        `output ONLY: __NOTHING__\n` +
+        `But lean toward sharing something — a one-liner is better than silence. ` +
+        `"Quiet morning, inbox is clean" beats __NOTHING__ if you did check things.\n\n` +
+        `After finishing your work, you MUST write a final text response with your findings — ` +
+        `only that final message gets delivered.`;
+    // ── Wire Composio + external MCP servers (same dedup as legacy) ───
+    const mcp = await buildExtraMcpForRunAgent({
+        scopeText: [
+            opts.jobName,
+            opts.jobPrompt,
+            opts.profile?.description,
+            opts.profile?.systemPromptBody,
+        ].filter(Boolean).join('\n\n'),
+        profile: opts.profile,
+    });
+    // ── Run via canonical runAgent ────────────────────────────────────
+    const maxBudget = opts.maxBudgetUsd ?? (tier >= 2 ? 3.0 : 1.0);
+    const effort = tier >= 2 ? 'high' : 'medium';
+    logger.info({
+        job: opts.jobName,
+        tier,
+        profile: agentSlug,
+        composioConnected: mcp.composioConnected,
+        externalConnected: mcp.externalConnected,
+        droppedClaudeAi: mcp.droppedClaudeAi,
+        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',
+        profile: opts.profile,
+        agentManager: opts.agentManager,
+        memoryStore: opts.memoryStore,
+        model: opts.model,
+        effort,
+        maxBudgetUsd: maxBudget,
+        maxTurns: opts.maxTurns,
+        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,
+        composioConnected: mcp.composioConnected,
+        externalConnected: mcp.externalConnected,
+    };
+}
+//# sourceMappingURL=run-agent-cron.js.map

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-mcp.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Clementine TypeScript — MCP server wiring helper for runAgent.
+ *
+ * Phase 3 of the SDK-canonical migration (see
+ * /Users/nathan.reynolds/.claude/plans/sdk-canonical-migration.md).
+ *
+ * runAgent always wires the Clementine MCP server. This helper builds
+ * the EXTRA MCP servers callers may need (Composio toolkits, external
+ * claude.ai integrations, browser-harness, etc.), applying the same
+ * service dedup logic from 1.18.34 so we don't load duplicates of the
+ * same service from two providers.
+ *
+ * The legacy assistant.ts:buildOptions path does roughly the same
+ * thing for chat/cron — this is the standalone equivalent.
+ */
+import type { AgentProfile } from '../types.js';
+export interface BuildExtraMcpOptions {
+    /** The text we're routing on (job prompt, user message, etc). Used to pick which
+     *  Composio toolkits + external servers are relevant via the existing bundle router. */
+    scopeText?: string;
+    /** Active agent profile. When set, profile.allowedMcpServers and
+     *  profile.allowedComposioToolkits override the bundle router's choices. */
+    profile?: AgentProfile | null;
+    /** When true, build the FULL surface (no bundle filtering, no dedup).
+     *  Used by admin/debug callers; not the cron-path default. */
+    fullSurface?: boolean;
+}
+export interface BuildExtraMcpResult {
+    /** Map of additional MCP servers to merge into runAgent's mcpServers. */
+    servers: Record<string, Record<string, unknown>>;
+    /** Diagnostics: which Composio toolkits / external servers ended up live. */
+    composioConnected: string[];
+    externalConnected: string[];
+    /** Diagnostics: which services were de-duped (we kept Composio over claude.ai etc). */
+    droppedClaudeAi: string[];
+    droppedComposio: string[];
+}
+/**
+ * Build the extra MCP servers (Composio + external) for a runAgent call.
+ *
+ * Mirrors the legacy assistant.ts:buildOptions chain but as a standalone
+ * function so the runAgent path doesn't depend on PersonalAssistant
+ * instance state.
+ */
+export declare function buildExtraMcpForRunAgent(opts?: BuildExtraMcpOptions): Promise<BuildExtraMcpResult>;
+//# sourceMappingURL=run-agent-mcp.d.ts.map

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

@@ -0,0 +1,104 @@
+/**
+ * Clementine TypeScript — MCP server wiring helper for runAgent.
+ *
+ * Phase 3 of the SDK-canonical migration (see
+ * /Users/nathan.reynolds/.claude/plans/sdk-canonical-migration.md).
+ *
+ * runAgent always wires the Clementine MCP server. This helper builds
+ * the EXTRA MCP servers callers may need (Composio toolkits, external
+ * claude.ai integrations, browser-harness, etc.), applying the same
+ * service dedup logic from 1.18.34 so we don't load duplicates of the
+ * same service from two providers.
+ *
+ * The legacy assistant.ts:buildOptions path does roughly the same
+ * thing for chat/cron — this is the standalone equivalent.
+ */
+import pino from 'pino';
+import { routeToolSurface, applyServiceDedup } from './tool-router.js';
+import { loadClaudeIntegrations, getMcpServersForAgent } from './mcp-bridge.js';
+import { loadToolPreferences, KNOWN_SERVICES } from '../integrations/tool-preferences.js';
+const logger = pino({ name: 'clementine.run-agent-mcp' });
+/**
+ * Build the extra MCP servers (Composio + external) for a runAgent call.
+ *
+ * Mirrors the legacy assistant.ts:buildOptions chain but as a standalone
+ * function so the runAgent path doesn't depend on PersonalAssistant
+ * instance state.
+ */
+export async function buildExtraMcpForRunAgent(opts = {}) {
+    const result = {
+        servers: {},
+        composioConnected: [],
+        externalConnected: [],
+        droppedClaudeAi: [],
+        droppedComposio: [],
+    };
+    // 1. Route the tool surface based on scope text.
+    let route = opts.fullSurface
+        ? {
+            bundles: [],
+            externalMcpServers: undefined,
+            composioToolkits: undefined,
+            inheritFullClaudeEnv: true,
+            fullSurface: true,
+            reason: 'full_surface',
+        }
+        : routeToolSurface(opts.scopeText ?? '');
+    // 2. Build Composio MCP servers, honoring profile allowlist when set.
+    let composioMcpServers = {};
+    try {
+        const { buildComposioMcpServers } = await import('../integrations/composio/mcp-bridge.js');
+        const profileAllowList = opts.profile?.allowedComposioToolkits;
+        const composioAllow = Array.isArray(profileAllowList)
+            ? profileAllowList
+            : route.composioToolkits;
+        composioMcpServers = await buildComposioMcpServers(composioAllow);
+    }
+    catch (err) {
+        logger.debug({ err }, 'Composio MCP servers unavailable (non-fatal)');
+    }
+    // 3. Build external MCP servers (claude.ai integrations, etc).
+    let externalMcpServers = {};
+    try {
+        const profileAllowList = Array.isArray(opts.profile?.allowedMcpServers)
+            ? opts.profile?.allowedMcpServers
+            : undefined;
+        const externalAllow = profileAllowList ?? route.externalMcpServers;
+        externalMcpServers = getMcpServersForAgent(externalAllow);
+    }
+    catch (err) {
+        logger.debug({ err }, 'External MCP servers unavailable (non-fatal)');
+    }
+    // 4. Apply service dedup so Composio outlook + claude.ai Microsoft 365
+    //    don't both load (same logic as 1.18.34).
+    if (!opts.fullSurface) {
+        try {
+            const composioConnected = new Set(Object.keys(composioMcpServers));
+            const cdIntegrations = loadClaudeIntegrations();
+            const claudeDesktopActive = new Set(Object.values(cdIntegrations).filter(i => i.connected).map(i => i.name));
+            const prefs = loadToolPreferences();
+            const dedup = applyServiceDedup(route, {
+                composioConnected,
+                claudeDesktopActive,
+                preferences: prefs.preferences,
+                knownServices: KNOWN_SERVICES,
+            });
+            route = dedup.route;
+            result.droppedClaudeAi = dedup.droppedClaudeAi;
+            result.droppedComposio = dedup.droppedComposio;
+            for (const name of dedup.droppedClaudeAi)
+                delete externalMcpServers[name];
+            for (const slug of dedup.droppedComposio)
+                delete composioMcpServers[slug];
+        }
+        catch (err) {
+            logger.debug({ err }, 'Service dedup failed (non-fatal — using full surface)');
+        }
+    }
+    // 5. Merge into one map.
+    result.servers = { ...externalMcpServers, ...composioMcpServers };
+    result.composioConnected = Object.keys(composioMcpServers);
+    result.externalConnected = Object.keys(externalMcpServers);
+    return result;
+}
+//# sourceMappingURL=run-agent-mcp.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();
@@ -2602,6 +2638,57 @@ export class Gateway {
             const cronStart = Date.now();
             try {
                 let response;
+                // ── Phase 3: opt-in canonical SDK cron path ──────────────────
+                // CLEMENTINE_USE_RUNAGENT_CRON=1 routes the job through
+                // runAgentCron() — the canonical SDK pattern. Default OFF.
+                // Falls back to legacy on error so the job always completes.
+                const useRunAgentCron = process.env.CLEMENTINE_USE_RUNAGENT_CRON === '1';
+                if (useRunAgentCron && !opts?.disableAllTools) {
+                    try {
+                        const { runAgentCron } = await import('../agent/run-agent-cron.js');
+                        const profile = agentSlug && agentSlug !== 'clementine'
+                            ? this.getAgentManager().get(agentSlug) ?? null
+                            : null;
+                        logger.info({ jobName, agentSlug, tier, path: 'runagent_cron' }, 'Phase 3: routing cron through runAgentCron');
+                        const cronResult = await runAgentCron({
+                            jobName,
+                            jobPrompt,
+                            tier,
+                            maxTurns,
+                            profile,
+                            agentManager: this.getAgentManager(),
+                            memoryStore: this.assistant.getMemoryStore?.() ?? null,
+                            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();
+                        events.emit('cron:complete', {
+                            jobName,
+                            mode: 'runagent',
+                            durationMs: Date.now() - cronStart,
+                            responseLength: response?.length ?? 0,
+                        });
+                        logger.info({
+                            jobName,
+                            cost: Number(cronResult.totalCostUsd.toFixed(4)),
+                            numTurns: cronResult.numTurns,
+                            composioConnected: cronResult.composioConnected.length,
+                            externalConnected: cronResult.externalConnected.length,
+                            durationMs: Date.now() - cronStart,
+                        }, 'runAgentCron: cron job complete');
+                        return response;
+                    }
+                    catch (err) {
+                        logger.warn({ err, jobName }, 'runAgentCron path failed — falling back to legacy cron path');
+                        // Fall through to legacy below.
+                    }
+                }
                 if (mode === 'unleashed') {
                     response = await this.assistant.runUnleashedTask(jobName, jobPrompt, tier, maxTurns, model, workDir, maxHours, agentSlug);
                 }
@@ -2633,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.45",
+  "version": "1.18.47",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",