clementine-agent 1.0.27 → 1.0.28

package/dist/agent/assistant.d.ts

@@ -79,6 +79,13 @@ export declare class PersonalAssistant {
     /** Inject a background work result into the session so the next chat naturally references it. */
     injectPendingContext(sessionKey: string, userPrompt: string, result: string): void;
     private initMemoryStore;
+    /**
+     * Seed the in-memory hotCorrections ring buffer from persisted behavioral
+     * patterns (corrections that recurred across ≥2 sessions in the last 30d).
+     * Without this, daemon restarts would wipe the prompt-injected corrections
+     * until they reoccurred live.
+     */
+    private primeHotCorrections;
     private loadSessions;
     /**
      * Schedule a debounced session persist. Multiple calls within 500ms collapse

package/dist/agent/assistant.js

@@ -15,7 +15,7 @@ import { query as rawQuery, listSubagents, getSubagentMessages, } from '@anthrop
 import pino from 'pino';
 import { BASE_DIR, PKG_DIR, VAULT_DIR, DAILY_NOTES_DIR, SOUL_FILE, AGENTS_FILE, MEMORY_FILE, PROFILES_DIR, AGENTS_DIR, ASSISTANT_NAME, OWNER_NAME, MODEL, MODELS, HEARTBEAT_MAX_TURNS, SEARCH_CONTEXT_LIMIT, SEARCH_RECENCY_LIMIT, SYSTEM_PROMPT_MAX_CONTEXT_CHARS, SESSION_EXCHANGE_HISTORY_SIZE, SESSION_EXCHANGE_MAX_CHARS, INJECTED_CONTEXT_MAX_CHARS, UNLEASHED_PHASE_TURNS, UNLEASHED_DEFAULT_MAX_HOURS, UNLEASHED_MAX_PHASES, PROJECTS_META_FILE, CRON_PROGRESS_DIR, CRON_REFLECTIONS_DIR, HANDOFFS_DIR, BUDGET, ENABLE_1M_CONTEXT, IDENTITY_FILE, CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY as CONFIG_ANTHROPIC_API_KEY, } from '../config.js';
 import { DEFAULT_CHANNEL_CAPABILITIES } from '../types.js';
-import { enforceToolPermissions, getSecurityPrompt, getHeartbeatSecurityPrompt, getCronSecurityPrompt, getHeartbeatDisallowedTools, logToolUse, setProfileTier, setProfileAllowedTools, setAgentDir, setSendPolicy, setInteractionSource, } from './hooks.js';
+import { enforceToolPermissions, getSecurityPrompt, getHeartbeatSecurityPrompt, getCronSecurityPrompt, getHeartbeatDisallowedTools, logToolUse, setProfileTier, setProfileAllowedTools, setAgentDir, setSendPolicy, setInteractionSource, logAuditJsonl, } from './hooks.js';
 import { scanner } from '../security/scanner.js';
 import { agentWorkingMemoryFile, listAllGoals } from '../tools/shared.js';
 import { AgentManager } from './agent-manager.js';
@@ -84,6 +84,64 @@ function formatCapabilities(caps) {
         features.push(`max ${caps.maxMessageLength} chars/message`);
     return features.length > 0 ? features.join(', ') : 'text only';
 }
+/** Derive the human-readable channel label from a session key. */
+function deriveChannel(opts) {
+    const { sessionKey, isAutonomous, cronTier } = opts;
+    if (isAutonomous)
+        return cronTier != null ? 'cron' : 'heartbeat';
+    if (!sessionKey)
+        return 'unknown';
+    if (sessionKey.startsWith('discord:user:'))
+        return 'Discord DM';
+    if (sessionKey.startsWith('discord:channel:'))
+        return 'Discord channel';
+    if (sessionKey.startsWith('slack:'))
+        return 'Slack';
+    if (sessionKey.startsWith('telegram:'))
+        return 'Telegram';
+    if (sessionKey.startsWith('whatsapp:'))
+        return 'WhatsApp';
+    if (sessionKey.startsWith('webhook:'))
+        return 'webhook';
+    return 'direct';
+}
+/**
+ * Per-channel tool deny list. Narrows what the agent can invoke based on the
+ * surface area of the channel — e.g. a public Discord channel shouldn't execute
+ * shell commands on the owner's box, and SMS/WhatsApp shouldn't touch the
+ * filesystem. Owner-direct surfaces (Discord DM, dashboard, direct CLI) get the
+ * full toolset.
+ *
+ * Returned tools are added to the SDK's `disallowedTools`. Denial is strict —
+ * it overrides the positive allowlist in buildOptions.
+ */
+function getChannelToolDenyList(channel) {
+    const CODE_EXEC = ['Bash', 'Write', 'Edit'];
+    const SHARED_DENY = [...CODE_EXEC];
+    const SMS_DENY = [
+        ...CODE_EXEC,
+        mcpTool('browser_screenshot'),
+        mcpTool('github_prs'),
+        mcpTool('rss_fetch'),
+        mcpTool('web_search'),
+        mcpTool('analyze_image'),
+        mcpTool('self_restart'),
+        mcpTool('update_self'),
+    ];
+    switch (channel) {
+        case 'Discord channel':
+        case 'Slack':
+            return SHARED_DENY;
+        case 'WhatsApp':
+        case 'Telegram':
+            return SMS_DENY;
+        case 'webhook':
+            return SMS_DENY;
+        default:
+            // Discord DM (owner), direct, dashboard:web, autonomous, unknown → full tools.
+            return [];
+    }
+}
 // ── Token estimation & context window guard ─────────────────────────
 /**
  * Estimate token count using a weighted heuristic.
@@ -575,6 +633,19 @@ export class PersonalAssistant {
     // ── Shared stream helpers ──────────────────────────────────────────
     /** Log SDK result metrics and store usage. Shared across all query methods. */
     logQueryResult(result, source, sessionKey, label, agentSlug) {
+        // Aggregate cache stats across all models used this turn
+        let cacheRead = 0;
+        let cacheCreation = 0;
+        let inputTokens = 0;
+        if (result.modelUsage) {
+            for (const usage of Object.values(result.modelUsage)) {
+                cacheRead += usage.cacheReadInputTokens ?? 0;
+                cacheCreation += usage.cacheCreationInputTokens ?? 0;
+                inputTokens += usage.inputTokens ?? 0;
+            }
+        }
+        const cacheDenominator = inputTokens + cacheRead + cacheCreation;
+        const cacheHitRate = cacheDenominator > 0 ? cacheRead / cacheDenominator : 0;
         if ('total_cost_usd' in result) {
             logger.info({
                 ...(label ? { job: label } : {}),
@@ -582,7 +653,23 @@ export class PersonalAssistant {
                 cost_usd: result.total_cost_usd,
                 num_turns: result.num_turns,
                 duration_ms: result.duration_ms,
+                cache_read_tokens: cacheRead,
+                cache_creation_tokens: cacheCreation,
+                cache_hit_rate: Number(cacheHitRate.toFixed(3)),
             }, `${source} query completed`);
+            logAuditJsonl({
+                event_type: 'query_complete',
+                source,
+                agent_slug: agentSlug,
+                job: label,
+                cost_usd: result.total_cost_usd,
+                num_turns: result.num_turns,
+                duration_ms: result.duration_ms,
+                tokens_in: inputTokens,
+                cache_read_tokens: cacheRead,
+                cache_creation_tokens: cacheCreation,
+                cache_hit_rate: Number(cacheHitRate.toFixed(3)),
+            });
         }
         if (this.memoryStore && result.modelUsage) {
             try {
@@ -638,11 +725,39 @@ export class PersonalAssistant {
             const { MEMORY_DB_PATH } = await import('../config.js');
             this.memoryStore = new MemoryStore(MEMORY_DB_PATH, VAULT_DIR);
             this.memoryStore.initialize();
+            this.primeHotCorrections();
         }
         catch (err) {
             logger.warn({ err }, 'Memory store init failed — falling back to static prompts');
         }
     }
+    /**
+     * Seed the in-memory hotCorrections ring buffer from persisted behavioral
+     * patterns (corrections that recurred across ≥2 sessions in the last 30d).
+     * Without this, daemon restarts would wipe the prompt-injected corrections
+     * until they reoccurred live.
+     */
+    primeHotCorrections() {
+        if (!this.memoryStore)
+            return;
+        try {
+            const patterns = this.memoryStore.getBehavioralPatterns(2);
+            const now = new Date().toISOString();
+            for (const p of patterns.slice(0, 10)) {
+                this.hotCorrections.push({
+                    correction: p.correction,
+                    category: p.category,
+                    timestamp: now,
+                });
+            }
+            if (patterns.length > 0) {
+                logger.info({ primed: Math.min(patterns.length, 10) }, 'Primed hot corrections from behavioral patterns');
+            }
+        }
+        catch (err) {
+            logger.warn({ err }, 'Priming hot corrections failed');
+        }
+    }
     // ── Session Persistence ───────────────────────────────────────────
     loadSessions() {
         if (!fs.existsSync(SESSIONS_FILE))
@@ -864,40 +979,6 @@ export class PersonalAssistant {
                 }
             }
         }
-        const now = new Date();
-        // Derive channel label from session key
-        let channel = 'unknown';
-        if (isAutonomous) {
-            channel = cronTier !== null ? 'cron' : 'heartbeat';
-        }
-        else if (sessionKey) {
-            if (sessionKey.startsWith('discord:user:'))
-                channel = 'Discord DM';
-            else if (sessionKey.startsWith('discord:channel:'))
-                channel = 'Discord channel';
-            else if (sessionKey.startsWith('slack:'))
-                channel = 'Slack';
-            else if (sessionKey.startsWith('telegram:'))
-                channel = 'Telegram';
-            else if (sessionKey.startsWith('whatsapp:'))
-                channel = 'WhatsApp';
-            else if (sessionKey.startsWith('webhook:'))
-                channel = 'webhook';
-            else
-                channel = 'direct';
-        }
-        const resolvedModel = resolveModel(model) ?? MODEL;
-        const modelLabel = Object.entries(MODELS).find(([, v]) => v === resolvedModel)?.[0] ?? resolvedModel;
-        const caps = !isAutonomous ? getChannelCapabilities(channel) : null;
-        parts.push(`## Current Context
-
-- **Date:** ${formatDate(now)}
-- **Time:** ${formatTime(now)}
-- **Timezone:** ${Intl.DateTimeFormat().resolvedOptions().timeZone}
-- **Channel:** ${channel}${caps ? ` (${formatCapabilities(caps)})` : ''}
-- **Model:** ${modelLabel} (${resolvedModel})
-- **Vault:** ${vault}
-`);
         if (isAutonomous) {
             // Minimal vault reference for heartbeats/cron — they know their tools
             parts.push(`Vault: \`${vault}\`. Key files: MEMORY.md, ${todayISO()}.md (today), TASKS.md. Use MCP tools (memory_read/write, task_list/add/update, note_take).`);
@@ -979,7 +1060,8 @@ Never spawn a sub-agent with vague instructions like "handle this brief" — tel
         // Proactive skill injection: match user message against skill triggers
         if (this._lastUserMessage && !isAutonomous) {
             try {
-                const matchedSkills = searchSkillsSync(this._lastUserMessage, 1, profile?.slug);
+                const suppressedNames = this.memoryStore?.getSkillsToSuppress?.(profile?.slug);
+                const matchedSkills = searchSkillsSync(this._lastUserMessage, 1, profile?.slug, { suppressedNames });
                 if (matchedSkills.length > 0 && matchedSkills[0].score >= 4) {
                     const skill = matchedSkills[0];
                     this.memoryStore?.logSkillUse?.({
@@ -1153,6 +1235,21 @@ If you're stuck after reading several files, tell ${owner} what's blocking you.
 You have a cost budget per message — not a hard turn limit. Work until the task is done. For long tasks (10+ tool calls), narrate progress as you go so ${owner} can see you're making headway. If a task needs many database queries, keep result sets small (LIMIT 20) to avoid filling context.`);
         }
         // Security rules are now appended to systemPrompt in buildOptions()
+        // Volatile suffix — put last so the stable prefix above stays cache-friendly.
+        const channel = deriveChannel({ sessionKey, isAutonomous, cronTier });
+        const resolvedModel = resolveModel(model) ?? MODEL;
+        const modelLabel = Object.entries(MODELS).find(([, v]) => v === resolvedModel)?.[0] ?? resolvedModel;
+        const caps = !isAutonomous ? getChannelCapabilities(channel) : null;
+        const now = new Date();
+        parts.push(`## Current Context
+
+- **Date:** ${formatDate(now)}
+- **Time:** ${formatTime(now)}
+- **Timezone:** ${Intl.DateTimeFormat().resolvedOptions().timeZone}
+- **Channel:** ${channel}${caps ? ` (${formatCapabilities(caps)})` : ''}
+- **Model:** ${modelLabel} (${resolvedModel})
+- **Vault:** ${vault}
+`);
         return parts.join('\n\n---\n\n');
     }
     // ── Build SDK Options ─────────────────────────────────────────────
@@ -1271,8 +1368,18 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
         // Cron tier 1 gets heartbeat restrictions (read-only + vault writes).
         const isCron = cronTier !== null;
         const disallowed = isHeartbeat && (!isCron || (cronTier ?? 0) < 2)
-            ? getHeartbeatDisallowedTools()
+            ? [...getHeartbeatDisallowedTools()]
             : [];
+        // Per-channel tool scoping: narrow tools for surfaces where destructive
+        // operations shouldn't happen (public Discord/Slack channels, SMS-like
+        // channels, webhooks). Owner DMs + dashboard keep the full toolset.
+        const channelForScoping = deriveChannel({ sessionKey, isAutonomous: isHeartbeat || isCron, cronTier });
+        const channelDeny = getChannelToolDenyList(channelForScoping);
+        if (channelDeny.length > 0) {
+            for (const t of channelDeny)
+                if (!disallowed.includes(t))
+                    disallowed.push(t);
+        }
         // Cron/heartbeat get turn limits. Interactive chat has no turn cap —
         // cost budget (maxBudgetUsd) is the primary guardrail.
         const effectiveMaxTurns = maxTurns
@@ -1426,7 +1533,8 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
                 (async () => {
                     try {
                         const { searchSkills, recordSkillUse } = await import('./skill-extractor.js');
-                        const matchedSkills = searchSkills(enrichedQuery, 2, agentSlug || undefined);
+                        const suppressedNames = this.memoryStore?.getSkillsToSuppress?.(agentSlug || undefined);
+                        const matchedSkills = searchSkills(enrichedQuery, 2, agentSlug || undefined, { suppressedNames });
                         if (matchedSkills.length > 0) {
                             return `## Relevant Procedures (from past successful executions)\n\n` +
                                 matchedSkills.map(s => {
@@ -1913,6 +2021,7 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
                 let responseText = '';
                 let sessionId = '';
                 let hitRateLimit = false;
+                let rateLimitRetryAfterMs = null;
                 let staleSession = false;
                 let contextRecovery = false;
                 let lastAssistantBlocks = [];
@@ -2083,6 +2192,16 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
                     }
                     else if (errStr.includes('rate') && (errStr.includes('limit') || errStr.includes('rate_limit'))) {
                         hitRateLimit = true;
+                        // Try to respect any retry hint the server surfaced in the error text.
+                        // Matches: "retry-after: 30", "retry after 30 seconds", "retry in 30s".
+                        const m = errStr.match(/retry[-\s]?(?:after|in)[:\s]*(\d+)\s*(ms|s|seconds?|milliseconds?)?/);
+                        if (m) {
+                            const n = Number(m[1]);
+                            if (Number.isFinite(n) && n > 0) {
+                                const unit = (m[2] ?? 's').toLowerCase();
+                                rateLimitRetryAfterMs = unit.startsWith('ms') || unit.startsWith('milli') ? n : n * 1000;
+                            }
+                        }
                     }
                     else if (errStr.includes('autocompact') || errStr.includes('thrash') || errStr.includes('context refilled to the limit')) {
                         // SDK autocompact thrashing — tool outputs are too large for the context window.
@@ -2166,8 +2285,14 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
                     continue;
                 }
                 if (hitRateLimit && attempt < PersonalAssistant.RATE_LIMIT_MAX_RETRIES) {
-                    const wait = PersonalAssistant.RATE_LIMIT_BACKOFF[Math.min(attempt, PersonalAssistant.RATE_LIMIT_BACKOFF.length - 1)];
+                    const base = rateLimitRetryAfterMs
+                        ?? PersonalAssistant.RATE_LIMIT_BACKOFF[Math.min(attempt, PersonalAssistant.RATE_LIMIT_BACKOFF.length - 1)];
+                    // ±25% jitter so concurrent retries don't align and re-collide.
+                    const jitter = 1 + (Math.random() - 0.5) * 0.5;
+                    const wait = Math.max(500, Math.round(base * jitter));
+                    logger.info({ sessionKey, attempt, waitMs: wait, hintedRetryAfterMs: rateLimitRetryAfterMs }, 'Rate-limited — waiting before retry');
                     await new Promise((r) => setTimeout(r, wait));
+                    rateLimitRetryAfterMs = null; // hint is per-attempt
                     continue;
                 }
                 if (hitRateLimit && !responseText) {
@@ -3149,7 +3274,8 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
             const { searchSkills, recordSkillUse } = await import('./skill-extractor.js');
             const cronAgentSlug = sdkOptions.env?.CLEMENTINE_TEAM_AGENT;
             const skillQuery = jobName + ' ' + jobPrompt.slice(0, 200);
-            const matchedSkills = searchSkills(skillQuery, 2, cronAgentSlug || undefined);
+            const suppressedNames = this.memoryStore?.getSkillsToSuppress?.(cronAgentSlug || undefined);
+            const matchedSkills = searchSkills(skillQuery, 2, cronAgentSlug || undefined, { suppressedNames });
             if (matchedSkills.length > 0) {
                 const skillLines = matchedSkills.map(s => {
                     recordSkillUse(s.name);
@@ -3511,7 +3637,8 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
                     const { searchSkills, recordSkillUse } = await import('./skill-extractor.js');
                     const unleashedAgentSlug = jobName.includes(':') ? jobName.split(':')[0] : undefined;
                     const unleashedSkillQuery = jobName + ' ' + jobPrompt.slice(0, 200);
-                    const matchedSkills = searchSkills(unleashedSkillQuery, 2, unleashedAgentSlug);
+                    const suppressedNames = this.memoryStore?.getSkillsToSuppress?.(unleashedAgentSlug);
+                    const matchedSkills = searchSkills(unleashedSkillQuery, 2, unleashedAgentSlug, { suppressedNames });
                     if (matchedSkills.length > 0) {
                         unleashedSkillContext = `\n\n## Learned Procedures\nFollow these proven approaches when applicable:\n\n` +
                             matchedSkills.map(s => {

package/dist/agent/hooks.d.ts

@@ -9,6 +9,44 @@
  *   - Audit logging: persistent file + in-memory buffer
  */
 import type { SendPolicy } from '../types.js';
+export interface TraceContext {
+    trace_id: string;
+    session_id?: string;
+    channel?: string;
+    agent_slug?: string;
+    span_stack: string[];
+}
+/**
+ * Run `fn` inside a trace context. Creates a new trace_id if none is supplied
+ * and inherited from an outer context. Nested calls push a span_id onto the
+ * stack so parent/child relationships survive async hops.
+ */
+export declare function runWithTrace<T>(ctx: {
+    trace_id?: string;
+    session_id?: string;
+    channel?: string;
+    agent_slug?: string;
+}, fn: () => Promise<T> | T): Promise<T> | T;
+export declare function getTraceContext(): TraceContext | undefined;
+export interface AuditEvent {
+    event_type: string;
+    tool_name?: string;
+    duration_ms?: number;
+    tokens_in?: number;
+    tokens_out?: number;
+    cache_read_tokens?: number;
+    cache_creation_tokens?: number;
+    cost_usd?: number;
+    num_turns?: number;
+    error?: string;
+    [key: string]: unknown;
+}
+/**
+ * Append a structured event to audit.jsonl with the current trace context.
+ * Runs alongside (not in place of) the legacy text audit.log so existing
+ * consumers keep working.
+ */
+export declare function logAuditJsonl(event: AuditEvent): void;
 export declare function setHeartbeatMode(active: boolean, tier2Allowed?: boolean): void;
 export declare function setApprovalCallback(cb: ((desc: string) => Promise<boolean>) | null): void;
 export declare function setProfileTier(tier: number | null): void;

package/dist/agent/hooks.js

@@ -10,6 +10,8 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
 import { OWNER_NAME, BASE_DIR, TIMEZONE } from '../config.js';
 // ── Shared state ───────────────────────────────────────────────────────
 let heartbeatActive = false;
@@ -34,19 +36,27 @@ let interactionSource = 'autonomous';
 const logsDir = path.join(BASE_DIR, 'logs');
 fs.mkdirSync(logsDir, { recursive: true });
 const auditLogPath = path.join(logsDir, 'audit.log');
+const auditJsonlPath = path.join(logsDir, 'audit.jsonl');
 const MAX_AUDIT_SIZE = 5 * 1024 * 1024; // 5 MB
+function rotateIfLarge(filePath) {
+    try {
+        if (!fs.existsSync(filePath))
+            return;
+        const stat = fs.statSync(filePath);
+        if (stat.size <= MAX_AUDIT_SIZE)
+            return;
+        const backup = filePath + '.1';
+        if (fs.existsSync(backup))
+            fs.unlinkSync(backup);
+        fs.renameSync(filePath, backup);
+    }
+    catch {
+        // Non-fatal
+    }
+}
 function appendAuditFile(line) {
     try {
-        // Simple rotation: if file exceeds max size, rename to .log.1 and start fresh
-        if (fs.existsSync(auditLogPath)) {
-            const stat = fs.statSync(auditLogPath);
-            if (stat.size > MAX_AUDIT_SIZE) {
-                const backup = auditLogPath + '.1';
-                if (fs.existsSync(backup))
-                    fs.unlinkSync(backup);
-                fs.renameSync(auditLogPath, backup);
-            }
-        }
+        rotateIfLarge(auditLogPath);
         const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 19);
         fs.appendFileSync(auditLogPath, `${timestamp} ${line}\n`);
     }
@@ -54,6 +64,57 @@ function appendAuditFile(line) {
         // Non-fatal — audit logging should never crash the assistant
     }
 }
+const traceStorage = new AsyncLocalStorage();
+function shortId() {
+    // 8-char id — collision-resistant enough for per-session correlation and
+    // much easier to eyeball in logs than a full UUID.
+    return randomUUID().replace(/-/g, '').slice(0, 8);
+}
+/**
+ * Run `fn` inside a trace context. Creates a new trace_id if none is supplied
+ * and inherited from an outer context. Nested calls push a span_id onto the
+ * stack so parent/child relationships survive async hops.
+ */
+export function runWithTrace(ctx, fn) {
+    const existing = traceStorage.getStore();
+    const trace_id = ctx.trace_id ?? existing?.trace_id ?? shortId();
+    const store = {
+        trace_id,
+        session_id: ctx.session_id ?? existing?.session_id,
+        channel: ctx.channel ?? existing?.channel,
+        agent_slug: ctx.agent_slug ?? existing?.agent_slug,
+        span_stack: [shortId(), ...(existing?.span_stack ?? [])],
+    };
+    return traceStorage.run(store, fn);
+}
+export function getTraceContext() {
+    return traceStorage.getStore();
+}
+/**
+ * Append a structured event to audit.jsonl with the current trace context.
+ * Runs alongside (not in place of) the legacy text audit.log so existing
+ * consumers keep working.
+ */
+export function logAuditJsonl(event) {
+    try {
+        rotateIfLarge(auditJsonlPath);
+        const ctx = traceStorage.getStore();
+        const payload = {
+            ts: new Date().toISOString(),
+            trace_id: ctx?.trace_id,
+            span_id: ctx?.span_stack[0],
+            parent_span_id: ctx?.span_stack[1],
+            session_id: ctx?.session_id,
+            channel: ctx?.channel,
+            agent_slug: ctx?.agent_slug,
+            ...event,
+        };
+        fs.appendFileSync(auditJsonlPath, JSON.stringify(payload) + '\n');
+    }
+    catch {
+        // Non-fatal — audit logging should never crash the assistant
+    }
+}
 // ── State accessors ──────────────────────────────────────────────────
 export function setHeartbeatMode(active, tier2Allowed = false) {
     heartbeatActive = active;
@@ -99,6 +160,11 @@ export function logToolUse(toolName, toolInput) {
     const entry = `- \`${timestamp}\` **${toolName}** — ${summary}`;
     auditLog.push(entry);
     appendAuditFile(`${toolName} — ${summary}`);
+    logAuditJsonl({
+        event_type: 'tool_use',
+        tool_name: toolName,
+        summary,
+    });
 }
 // ── Heartbeat tool restrictions ─────────────────────────────────────
 // These apply to actual heartbeats and tier-1 cron jobs (read-only).

package/dist/agent/skill-extractor.d.ts

@@ -57,7 +57,9 @@ export interface SkillMatch {
     attachments: string[];
     skillDir: string;
 }
-export declare function searchSkills(query: string, limit?: number, agentSlug?: string): SkillMatch[];
+export declare function searchSkills(query: string, limit?: number, agentSlug?: string, opts?: {
+    suppressedNames?: Set<string>;
+}): SkillMatch[];
 /** Record that a skill was used (bump use count). */
 export declare function recordSkillUse(skillName: string, agentSlug?: string): void;
 /** List all active skills (global + all agent-scoped). */

package/dist/agent/skill-extractor.js

@@ -316,7 +316,7 @@ async function mergeSkill(assistant, existing, incoming) {
         return null;
     }
 }
-export function searchSkills(query, limit = 3, agentSlug) {
+export function searchSkills(query, limit = 3, agentSlug, opts) {
     const dirs = [];
     // Agent-scoped skills get priority (boost=2)
     if (agentSlug) {
@@ -332,6 +332,7 @@ export function searchSkills(query, limit = 3, agentSlug) {
     const queryWords = query.toLowerCase().split(/\s+/).filter(w => w.length > 2);
     const results = [];
     const seen = new Set();
+    const suppressed = opts?.suppressedNames;
     for (const { dir, boost } of dirs) {
         const files = readdirSync(dir).filter(f => f.endsWith('.md'));
         for (const file of files) {
@@ -339,6 +340,10 @@ export function searchSkills(query, limit = 3, agentSlug) {
             if (seen.has(name))
                 continue;
             seen.add(name);
+            // Feedback-gated: skip skills that have been repeatedly associated with
+            // negative user feedback (see store.getSkillsToSuppress).
+            if (suppressed?.has(name))
+                continue;
             try {
                 const raw = readFileSync(path.join(dir, file), 'utf-8');
                 const parsed = matter(raw);
@@ -346,8 +351,13 @@ export function searchSkills(query, limit = 3, agentSlug) {
                 const title = parsed.data.title ?? '';
                 const description = parsed.data.description ?? '';
                 // Score: trigger matches (high weight) + title/description word overlap + agent boost
+                // Filter non-string triggers defensively — YAML quirks like leading "##"
+                // parse as null and would crash toLowerCase(), causing the entire skill
+                // to be silently dropped by the outer catch. Skip them instead.
                 let score = 0;
-                const triggerLower = triggers.map(t => t.toLowerCase());
+                const triggerLower = triggers
+                    .filter((t) => typeof t === 'string' && t.length > 0)
+                    .map(t => t.toLowerCase());
                 for (const word of queryWords) {
                     for (const trigger of triggerLower) {
                         if (trigger.includes(word) || word.includes(trigger))

package/dist/gateway/delivery-queue.d.ts

@@ -5,16 +5,36 @@
  * Retries up to 3 times on a 5-minute interval, then logs as permanently failed.
  */
 import type { NotificationContext } from '../types.js';
+interface QueuedMessage {
+    text: string;
+    context?: NotificationContext;
+    attempts: number;
+    firstAttempt: string;
+    lastAttempt: string;
+}
+interface DlqEntry extends QueuedMessage {
+    failedAt: string;
+    reason: string;
+}
 type SendFn = (text: string, context?: NotificationContext) => Promise<{
     delivered: boolean;
 }>;
+type PermanentFailureFn = (entry: DlqEntry) => void | Promise<void>;
 export declare class DeliveryQueue {
     private queue;
+    private dlq;
     private timer;
     private sendFn;
+    private onPermanentFailure;
     constructor();
     /** Register the send function (from NotificationDispatcher). */
     setSender(fn: SendFn): void;
+    /**
+     * Register a callback invoked once per permanent failure (after MAX_ATTEMPTS).
+     * Wire this to an owner-alerting channel (Discord DM, email, etc.) so drops
+     * don't stay hidden in daily notes.
+     */
+    setOnPermanentFailure(fn: PermanentFailureFn): void;
     /** Start the retry drain loop. */
     start(): void;
     stop(): void;
@@ -23,8 +43,18 @@ export declare class DeliveryQueue {
     /** Drain the queue: retry each message, remove successes and expired items. */
     private drain;
     get size(): number;
+    /** Read-only snapshot of the DLQ (most recent first). */
+    getDlq(): DlqEntry[];
+    get dlqSize(): number;
+    /**
+     * Move DLQ entries back to the retry queue for another attempt. Returns the
+     * number of entries requeued. Intended for a dashboard "replay" button.
+     */
+    replayDlq(filter?: (entry: DlqEntry) => boolean): number;
     private load;
     private save;
+    private loadDlq;
+    private saveDlq;
 }
 export {};
 //# sourceMappingURL=delivery-queue.d.ts.map

package/dist/gateway/delivery-queue.js

@@ -11,19 +11,32 @@ import { BASE_DIR } from '../config.js';
 import { logToDailyNote } from './cron-scheduler.js';
 const logger = pino({ name: 'clementine.delivery-queue' });
 const QUEUE_FILE = path.join(BASE_DIR, 'delivery-queue.json');
+const DLQ_FILE = path.join(BASE_DIR, 'delivery-dlq.json');
+const DLQ_MAX_ENTRIES = 500;
 const MAX_ATTEMPTS = 3;
 const RETRY_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
 export class DeliveryQueue {
     queue = [];
+    dlq = [];
     timer = null;
     sendFn = null;
+    onPermanentFailure = null;
     constructor() {
         this.load();
+        this.loadDlq();
     }
     /** Register the send function (from NotificationDispatcher). */
     setSender(fn) {
         this.sendFn = fn;
     }
+    /**
+     * Register a callback invoked once per permanent failure (after MAX_ATTEMPTS).
+     * Wire this to an owner-alerting channel (Discord DM, email, etc.) so drops
+     * don't stay hidden in daily notes.
+     */
+    setOnPermanentFailure(fn) {
+        this.onPermanentFailure = fn;
+    }
     /** Start the retry drain loop. */
     start() {
         if (this.timer)
@@ -73,11 +86,28 @@ export class DeliveryQueue {
                 logger.debug({ err }, 'Retry delivery attempt failed');
             }
             if (msg.attempts >= MAX_ATTEMPTS) {
-                // Permanently failed — log to daily note so the user can find it
+                // Permanently failed — persist to DLQ for dashboard replay + surface to owner
                 const preview = msg.text.slice(0, 100).replace(/\n/g, ' ');
+                const entry = {
+                    ...msg,
+                    failedAt: new Date().toISOString(),
+                    reason: 'max_attempts_exceeded',
+                };
+                this.dlq.push(entry);
+                if (this.dlq.length > DLQ_MAX_ENTRIES)
+                    this.dlq = this.dlq.slice(-DLQ_MAX_ENTRIES);
+                this.saveDlq();
                 logToDailyNote(`**[Delivery permanently failed]** (${msg.attempts} attempts): ${preview}`);
-                logger.warn({ attempts: msg.attempts, preview }, 'Message permanently failed delivery — logged to daily note');
-                continue; // drop from queue
+                logger.warn({ attempts: msg.attempts, preview, dlqSize: this.dlq.length }, 'Message permanently failed delivery — moved to DLQ');
+                if (this.onPermanentFailure) {
+                    try {
+                        await this.onPermanentFailure(entry);
+                    }
+                    catch (err) {
+                        logger.debug({ err }, 'Permanent-failure hook threw');
+                    }
+                }
+                continue; // drop from retry queue
             }
             remaining.push(msg);
         }
@@ -87,6 +117,37 @@ export class DeliveryQueue {
     get size() {
         return this.queue.length;
     }
+    /** Read-only snapshot of the DLQ (most recent first). */
+    getDlq() {
+        return [...this.dlq].reverse();
+    }
+    get dlqSize() {
+        return this.dlq.length;
+    }
+    /**
+     * Move DLQ entries back to the retry queue for another attempt. Returns the
+     * number of entries requeued. Intended for a dashboard "replay" button.
+     */
+    replayDlq(filter) {
+        if (this.dlq.length === 0)
+            return 0;
+        const now = new Date().toISOString();
+        const toReplay = filter ? this.dlq.filter(filter) : [...this.dlq];
+        for (const entry of toReplay) {
+            this.queue.push({
+                text: entry.text,
+                context: entry.context,
+                attempts: 0,
+                firstAttempt: now,
+                lastAttempt: now,
+            });
+        }
+        this.dlq = filter ? this.dlq.filter(e => !filter(e)) : [];
+        this.save();
+        this.saveDlq();
+        logger.info({ replayed: toReplay.length, queueSize: this.queue.length }, 'DLQ entries replayed');
+        return toReplay.length;
+    }
     load() {
         if (!existsSync(QUEUE_FILE))
             return;
@@ -106,5 +167,24 @@ export class DeliveryQueue {
             logger.debug({ err }, 'Failed to persist delivery queue');
         }
     }
+    loadDlq() {
+        if (!existsSync(DLQ_FILE))
+            return;
+        try {
+            this.dlq = JSON.parse(readFileSync(DLQ_FILE, 'utf-8'));
+        }
+        catch {
+            logger.warn('Failed to parse DLQ file — starting fresh');
+            this.dlq = [];
+        }
+    }
+    saveDlq() {
+        try {
+            writeFileSync(DLQ_FILE, JSON.stringify(this.dlq, null, 2));
+        }
+        catch (err) {
+            logger.debug({ err }, 'Failed to persist DLQ');
+        }
+    }
 }
 //# sourceMappingURL=delivery-queue.js.map

package/dist/gateway/router.d.ts

@@ -143,6 +143,7 @@ export declare class Gateway {
      */
     private acquireSessionLock;
     handleMessage(sessionKey: string, text: string, onText?: OnTextCallback, model?: string, maxTurns?: number, onToolActivity?: OnToolActivityCallback): Promise<string>;
+    private _handleMessageInner;
     handleHeartbeat(standingInstructions: string, changesSummary?: string, timeContext?: string, dedupContext?: string, profile?: import('../types.js').AgentProfile | null): Promise<string>;
     handleCronJob(jobName: string, jobPrompt: string, tier?: number, maxTurns?: number, model?: string, workDir?: string, mode?: 'standard' | 'unleashed', maxHours?: number, timeoutMs?: number, successCriteria?: string[], agentSlug?: string): Promise<string>;
     /**

package/dist/gateway/router.js

@@ -8,6 +8,7 @@ import path from 'node:path';
 import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import pino from 'pino';
 import { PersonalAssistant } from '../agent/assistant.js';
+import { runWithTrace, logAuditJsonl } from '../agent/hooks.js';
 import { SelfImproveLoop } from '../agent/self-improve.js';
 import { MODELS, PROFILES_DIR, AGENTS_DIR, TEAM_COMMS_LOG, BASE_DIR, SEEN_CHANNELS_FILE } from '../config.js';
 import { scanner } from '../security/scanner.js';
@@ -681,6 +682,43 @@ export class Gateway {
         if (this.draining) {
             return "I'm restarting momentarily — your message will be processed after I'm back online.";
         }
+        // Derive channel label for the trace tag. Mirrors deriveChannel() in the
+        // agent layer but kept small here so the router stays independent.
+        const channelForTrace = sessionKey.startsWith('discord:user:') ? 'Discord DM'
+            : sessionKey.startsWith('discord:channel:') ? 'Discord channel'
+                : sessionKey.startsWith('slack:') ? 'Slack'
+                    : sessionKey.startsWith('telegram:') ? 'Telegram'
+                        : sessionKey.startsWith('whatsapp:') ? 'WhatsApp'
+                            : sessionKey.startsWith('webhook:') ? 'webhook'
+                                : sessionKey.startsWith('dashboard:') ? 'dashboard'
+                                    : 'direct';
+        const traceStart = Date.now();
+        return runWithTrace({ session_id: sessionKey, channel: channelForTrace }, async () => {
+            logAuditJsonl({
+                event_type: 'message_received',
+                text_preview: text.slice(0, 120),
+                text_len: text.length,
+            });
+            try {
+                const result = await this._handleMessageInner(sessionKey, text, onText, model, maxTurns, onToolActivity);
+                logAuditJsonl({
+                    event_type: 'message_completed',
+                    duration_ms: Date.now() - traceStart,
+                    response_len: result.length,
+                });
+                return result;
+            }
+            catch (err) {
+                logAuditJsonl({
+                    event_type: 'message_failed',
+                    duration_ms: Date.now() - traceStart,
+                    error: String(err).slice(0, 300),
+                });
+                throw err;
+            }
+        });
+    }
+    async _handleMessageInner(sessionKey, text, onText, model, maxTurns, onToolActivity) {
         // ── Auth circuit breaker — stop spamming error messages ────────
         if (this.authCircuitOpen) {
             if (!this.shouldProbeAuth()) {

package/dist/memory/store.d.ts

@@ -252,6 +252,13 @@ export declare class MemoryStore {
      * Get recent feedback entries.
      */
     getRecentFeedback(limit?: number): Feedback[];
+    /**
+     * Skills to suppress from retrieval: those that coincide with negative feedback
+     * in ≥3 sessions and whose negative rate exceeds 50% of rated sessions.
+     * Attribution is by session_key join; a feedback entry is credited to every
+     * skill retrieved in that session. Window: last 60 days.
+     */
+    getSkillsToSuppress(agentSlug?: string): Set<string>;
     /**
      * Get aggregate feedback statistics.
      */

package/dist/memory/store.js

@@ -1465,6 +1465,37 @@ export class MemoryStore {
             createdAt: row.created_at,
         }));
     }
+    /**
+     * Skills to suppress from retrieval: those that coincide with negative feedback
+     * in ≥3 sessions and whose negative rate exceeds 50% of rated sessions.
+     * Attribution is by session_key join; a feedback entry is credited to every
+     * skill retrieved in that session. Window: last 60 days.
+     */
+    getSkillsToSuppress(agentSlug) {
+        const suppressed = new Set();
+        try {
+            const sql = `
+        SELECT su.skill_name,
+               SUM(CASE WHEN f.rating = 'negative' THEN 1 ELSE 0 END) AS negative,
+               SUM(CASE WHEN f.rating = 'positive' THEN 1 ELSE 0 END) AS positive,
+               COUNT(DISTINCT f.id) AS total
+        FROM skill_usage su
+        JOIN feedback f ON f.session_key = su.session_key
+        WHERE su.retrieved_at >= datetime('now', '-60 days')
+          AND f.created_at >= su.retrieved_at
+          ${agentSlug ? 'AND su.agent_slug = ?' : ''}
+        GROUP BY su.skill_name
+        HAVING negative >= 3 AND negative * 2 > total
+      `;
+            const rows = this.conn.prepare(sql).all(...(agentSlug ? [agentSlug] : []));
+            for (const r of rows)
+                suppressed.add(r.skill_name);
+        }
+        catch {
+            // skill_usage or feedback tables may be empty / legacy — return empty set
+        }
+        return suppressed;
+    }
     /**
      * Get aggregate feedback statistics.
      */

package/package.json

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