@0xmaxma/claude-gateway 1.6.8 → 1.7.0

package/dist/agent/skill-learning/index.js

@@ -0,0 +1,308 @@
+"use strict";
+/**
+ * SkillLearningManager — the only export the runner/index wire to.
+ *
+ * Owns the closed loop: cheap per-turn telemetry capture (always-on), a
+ * debounced session-idle review trigger, the print-only reviewer, the
+ * provenance-guarded writer, and the daily curator. All turn-lifecycle methods
+ * are best-effort and MUST never throw into the runner's hot path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillLearningManager = exports.REVIEW_IDLE_DEBOUNCE_MS = void 0;
+const loader_1 = require("../../skills/loader");
+const parser_1 = require("../../skills/parser");
+const config_1 = require("./config");
+const telemetry_1 = require("./telemetry");
+const trigger_1 = require("./trigger");
+const reviewer_1 = require("./reviewer");
+const writer_1 = require("./writer");
+const curator_1 = require("./curator");
+const metrics_1 = require("./metrics");
+const notifier_1 = require("./notifier");
+/** Debounce: fire the review this long after the last turn ends (session-idle proxy). */
+exports.REVIEW_IDLE_DEBOUNCE_MS = 20000;
+/** Heuristic: a user message that reads like a correction of the agent's last action. */
+const CORRECTION_RE = /^\s*(no\b|not\b|wrong\b|that'?s not|nope\b|ไม่ใช่|ผิด|บ่ใช่)/i;
+class SkillLearningManager {
+    constructor(opts) {
+        this.accum = new Map();
+        this.reviewInFlight = new Set();
+        this.idleTimers = new Map();
+        this.db = opts.db;
+        this.agentId = opts.agentId;
+        this.workspaceDir = opts.workspaceDir;
+        this.mcpToolsDir = opts.mcpToolsDir;
+        this.sharedSkillsDir = opts.sharedSkillsDir;
+        this.logger = opts.logger;
+        this.reviewSpawn = opts.reviewSpawn;
+        this.now = opts.now ?? Date.now;
+        this.cfg = (0, config_1.resolveSkillLearningConfig)(opts.agentCfg, opts.globalCfg);
+        this.notifier =
+            opts.notifier ??
+                new notifier_1.SkillNotifier({
+                    workspaceDir: this.workspaceDir,
+                    notify: this.cfg.notify,
+                    send: (0, notifier_1.buildChannelSend)(this.workspaceDir, opts.channels ?? {}, opts.logger),
+                    logger: opts.logger,
+                });
+    }
+    isEnabled() {
+        return this.cfg.enabled;
+    }
+    // ---- Turn lifecycle (called by the runner; all best-effort) ----------------
+    /** A user turn begins. `invokedSkills` = skills detected in the incoming message. */
+    onTurnStart(mapKey, sessionId, firstUserMessage, invokedSkills = []) {
+        try {
+            let a = this.accum.get(mapKey);
+            if (!a || a.sessionId !== sessionId) {
+                a = this.freshAccum(sessionId);
+            }
+            else {
+                a.turnIdx += 1;
+            }
+            a.startedAt = this.now();
+            a.toolUseIds.clear();
+            a.toolCalls = 0;
+            a.tokensIn = 0;
+            a.tokensOut = 0;
+            a.recoveryFired = false;
+            a.skillsLoaded = new Set(invokedSkills.filter(Boolean));
+            a.firstUserMsg = firstUserMessage ?? '';
+            if (CORRECTION_RE.test(a.firstUserMsg))
+                a.sigCorrection = true;
+            this.accum.set(mapKey, a);
+        }
+        catch {
+            /* never break the turn */
+        }
+    }
+    /** A tool_use block streamed by. Deduped by block id (cumulative snapshots). */
+    onToolUse(mapKey, toolUseId) {
+        const a = this.accum.get(mapKey);
+        if (!a)
+            return;
+        if (toolUseId) {
+            if (a.toolUseIds.has(toolUseId))
+                return;
+            a.toolUseIds.add(toolUseId);
+        }
+        a.toolCalls += 1;
+    }
+    onTokenUsage(mapKey, inputTokens, totalTokens) {
+        const a = this.accum.get(mapKey);
+        if (!a)
+            return;
+        if (inputTokens > a.tokensIn)
+            a.tokensIn = inputTokens; // peak context
+        a.tokensOut += Math.max(0, totalTokens); // accumulated work
+    }
+    onRecoveryFired(mapKey) {
+        const a = this.accum.get(mapKey);
+        if (!a)
+            return;
+        a.recoveryFired = true;
+        a.sigRecovery = true;
+    }
+    /** A user turn ended. Persist the metric row + arm the idle-review debounce. */
+    onTurnEnd(mapKey, sessionId) {
+        try {
+            const a = this.accum.get(mapKey);
+            if (!a || a.sessionId !== sessionId)
+                return;
+            const ts = this.now();
+            const skills = [...a.skillsLoaded];
+            this.db.insertTurnMetric({
+                sessionId,
+                turnIdx: a.turnIdx,
+                ts,
+                toolCalls: a.toolCalls,
+                durationMs: Math.max(0, ts - a.startedAt),
+                tokensIn: a.tokensIn,
+                tokensOut: a.tokensOut,
+                recoveryFired: a.recoveryFired ? 1 : 0,
+                skillsLoaded: skills.length ? JSON.stringify(skills) : null,
+                intentHash: (0, telemetry_1.intentHash)(a.firstUserMsg),
+                enabled: this.cfg.enabled ? 1 : 0,
+            });
+            for (const name of skills)
+                this.db.bumpSkillLoaded(name, ts);
+            a.sigMaxToolCalls = Math.max(a.sigMaxToolCalls, a.toolCalls);
+            this.scheduleIdleReview(mapKey, sessionId);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    // ---- Review path -----------------------------------------------------------
+    scheduleIdleReview(mapKey, sessionId) {
+        if (!this.cfg.enabled)
+            return; // capture still ran above; review is the gated part
+        const existing = this.idleTimers.get(mapKey);
+        if (existing)
+            clearTimeout(existing);
+        const t = setTimeout(() => {
+            this.idleTimers.delete(mapKey);
+            void this.runReviewNow(mapKey, sessionId);
+        }, exports.REVIEW_IDLE_DEBOUNCE_MS);
+        if (typeof t.unref === 'function')
+            t.unref();
+        this.idleTimers.set(mapKey, t);
+    }
+    /**
+     * The gated review entry (also the direct test seam). Reads session signals,
+     * checks the daily budget, and — if the gate passes — runs the reviewer and
+     * applies the proposal. Never throws.
+     */
+    async runReviewNow(mapKey, sessionId) {
+        if (!this.cfg.enabled)
+            return;
+        if (this.reviewInFlight.has(sessionId))
+            return;
+        const a = this.accum.get(mapKey);
+        if (!a || a.sessionId !== sessionId)
+            return;
+        const signals = {
+            toolCalls: a.sigMaxToolCalls,
+            recoveryFired: a.sigRecovery,
+            userCorrection: a.sigCorrection,
+        };
+        const dayStart = (0, telemetry_1.startOfDayMs)(this.now(), this.cfg.pruneTimezone);
+        const spent = this.db.countReviewRunsSince(dayStart);
+        const decision = (0, trigger_1.shouldReview)(signals, this.cfg, { spent, cap: this.cfg.maxReviewsPerDay });
+        if (!decision.review)
+            return;
+        this.reviewInFlight.add(sessionId);
+        try {
+            const transcript = this.gatherTranscript(sessionId);
+            if (!transcript.trim())
+                return;
+            const existing = this.loadExistingSkills();
+            const { proposal, tokensSpent } = await (0, reviewer_1.runReviewer)({ transcript, existingSkills: existing.map((s) => ({ name: s.name, description: s.description })) }, this.cfg, this.reviewSpawn);
+            const outcome = (0, writer_1.applyProposal)(proposal, {
+                workspaceDir: this.workspaceDir,
+                sessionId,
+                now: this.now(),
+                mode: this.cfg.mode,
+                existing,
+            });
+            // Record provenance only on a genuine create — an edit's skill_stats row
+            // already exists (from the original create), so re-recording would reset
+            // its created_at (age clock) and usage counters.
+            if (outcome.written && !outcome.queued && outcome.action === 'create' && outcome.name) {
+                this.db.recordSkillCreated({
+                    name: outcome.name,
+                    origin: 'auto',
+                    createdAt: this.now(),
+                    createdFromSession: sessionId,
+                    pinned: 0,
+                });
+            }
+            this.db.insertReviewRun({
+                sessionId,
+                ts: this.now(),
+                triggerReason: decision.reason,
+                outcome: outcome.written ? outcome.action : proposal.action === 'none' ? 'none' : 'error',
+                tokensSpent,
+            });
+            // Tell the operator a skill changed — diary (always) + throttled channel
+            // push. Only for a genuine live write (not the propose review queue).
+            if (outcome.written && !outcome.queued && outcome.name &&
+                (outcome.action === 'create' || outcome.action === 'edit')) {
+                this.notifier.onSkillWritten({
+                    name: outcome.name,
+                    action: outcome.action,
+                    sessionId,
+                    now: this.now(),
+                });
+            }
+            this.logger?.info(`[skill-learning:${this.agentId}] review (${decision.reason}) → ${outcome.written ? `${outcome.action}:${outcome.name}${outcome.queued ? ' (queued)' : ''}` : `no-write (${outcome.reason ?? proposal.action})`} tokens=${tokensSpent}`);
+        }
+        catch (err) {
+            this.logger?.warn?.(`[skill-learning:${this.agentId}] review failed: ${err.message}`);
+        }
+        finally {
+            this.reviewInFlight.delete(sessionId);
+            // Reset session signals so the next batch of turns re-qualifies from scratch.
+            a.sigMaxToolCalls = 0;
+            a.sigRecovery = false;
+            a.sigCorrection = false;
+        }
+    }
+    // ---- Curator ---------------------------------------------------------------
+    /** Start the daily curator scheduler. Returns a canceller. */
+    startCurator() {
+        return (0, curator_1.startCurator)(() => ({
+            db: this.db,
+            workspaceDir: this.workspaceDir,
+            agentId: this.agentId,
+            cfg: this.cfg,
+            logger: this.logger,
+        }), this.cfg);
+    }
+    /** Run one curation sweep immediately (test/ops seam). */
+    curateNow() {
+        return (0, curator_1.curateOnce)({
+            db: this.db,
+            workspaceDir: this.workspaceDir,
+            agentId: this.agentId,
+            cfg: this.cfg,
+            now: this.now(),
+            logger: this.logger,
+        });
+    }
+    /** The effectiveness rollup (REST/MCP read side). */
+    rollup() {
+        return (0, metrics_1.computeRollup)(this.db, this.agentId, this.now());
+    }
+    // ---- Internals -------------------------------------------------------------
+    freshAccum(sessionId) {
+        return {
+            sessionId,
+            turnIdx: 0,
+            startedAt: this.now(),
+            toolUseIds: new Set(),
+            toolCalls: 0,
+            tokensIn: 0,
+            tokensOut: 0,
+            recoveryFired: false,
+            skillsLoaded: new Set(),
+            firstUserMsg: '',
+            sigMaxToolCalls: 0,
+            sigRecovery: false,
+            sigCorrection: false,
+        };
+    }
+    gatherTranscript(sessionId) {
+        const rows = this.db.getSessionTranscript(sessionId, 200);
+        return rows
+            .map((r) => `${r.role === 'assistant' ? 'assistant' : 'user'}: ${r.content}`)
+            .join('\n')
+            .slice(-20000); // bound the reviewer prompt
+    }
+    /** All loaded skills with resolved provenance + path (for dedup + guards). */
+    loadExistingSkills() {
+        try {
+            const registry = (0, loader_1.loadSkills)({
+                workspaceDir: this.workspaceDir,
+                mcpToolsDir: this.mcpToolsDir,
+                sharedSkillsDir: this.sharedSkillsDir,
+            });
+            const out = [];
+            for (const skill of registry.skills.values()) {
+                let origin = 'user';
+                // Only workspace skills can ever be origin:auto; trust the on-disk FM.
+                if (skill.source === 'workspace') {
+                    const fm = (0, parser_1.extractFrontmatter)(skill.content)?.frontmatter;
+                    origin = fm && fm['origin'] === 'auto' ? 'auto' : (0, writer_1.readSkillOrigin)(skill.filePath);
+                }
+                out.push({ name: skill.name, description: skill.description, origin, filePath: skill.filePath });
+            }
+            return out;
+        }
+        catch {
+            return [];
+        }
+    }
+}
+exports.SkillLearningManager = SkillLearningManager;
+//# sourceMappingURL=index.js.map

package/dist/agent/skill-learning/index.js.map

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

package/dist/agent/skill-learning/metrics.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Metrics (read side) — the 5 effectiveness measures, all derived from
+ * turn_metrics + skill_stats + skill_review_runs. This is the concrete
+ * "measurable effectiveness" surface (planning-62 §Measurement).
+ *
+ * All measures are directional/heuristic by design; the causal signal is the
+ * `enabled` on/off cohort (measure 4) and the net-token ledger (measure 5).
+ */
+import type { HistoryDB } from '../../history/db';
+import type { SkillMetricsRollup } from './types';
+/** Compute the full effectiveness rollup for an agent. */
+export declare function computeRollup(db: HistoryDB, agentId: string, now: number): SkillMetricsRollup;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/agent/skill-learning/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../src/agent/skill-learning/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAiB,MAAM,kBAAkB,CAAC;AACjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AA4BlD,0DAA0D;AAC1D,wBAAgB,aAAa,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAqD7F"}

package/dist/agent/skill-learning/metrics.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Metrics (read side) — the 5 effectiveness measures, all derived from
+ * turn_metrics + skill_stats + skill_review_runs. This is the concrete
+ * "measurable effectiveness" surface (planning-62 §Measurement).
+ *
+ * All measures are directional/heuristic by design; the causal signal is the
+ * `enabled` on/off cohort (measure 4) and the net-token ledger (measure 5).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeRollup = computeRollup;
+function median(values) {
+    if (values.length === 0)
+        return 0;
+    const s = values.slice().sort((a, b) => a - b);
+    const mid = Math.floor(s.length / 2);
+    return s.length % 2 ? s[mid] : Math.round((s[mid - 1] + s[mid]) / 2);
+}
+/** Median for display, or `null` when there is no data (distinct from a real 0). */
+function medianOrNull(values) {
+    return values.length === 0 ? null : median(values);
+}
+function turnTokens(r) {
+    return r.tokensIn + r.tokensOut;
+}
+function hasSkill(r) {
+    if (!r.skillsLoaded)
+        return false;
+    try {
+        const arr = JSON.parse(r.skillsLoaded);
+        return Array.isArray(arr) && arr.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Compute the full effectiveness rollup for an agent. */
+function computeRollup(db, agentId, now) {
+    const stats = db.listSkillStats();
+    const autoStats = stats.filter((s) => s.origin === 'auto');
+    const turns = db.listTurnMetrics(0);
+    const reviews = db.listReviewRuns(0);
+    // ---- Measure 1: adoption funnel ----
+    const autoSkills = autoStats.length;
+    const loadedAtLeast1 = autoStats.filter((s) => s.timesLoaded >= 1).length;
+    const loadedAtLeast3 = autoStats.filter((s) => s.timesLoaded >= 3).length;
+    const stickyPct = autoSkills > 0 ? (loadedAtLeast3 / autoSkills) * 100 : 0;
+    // ---- Measure 2: cost-to-complete delta (skill-loaded turns vs not) ----
+    const before = turns.filter((t) => !hasSkill(t));
+    const after = turns.filter((t) => hasSkill(t));
+    const clusters = new Set(turns.map((t) => t.intentHash ?? 'misc')).size;
+    // ---- Measure 3: recovery-rate trend (earlier half vs recent half by ts) ----
+    const byTs = turns.slice().sort((a, b) => a.ts - b.ts);
+    const half = Math.floor(byTs.length / 2);
+    const earlier = byTs.slice(0, half);
+    const recent = byTs.slice(half);
+    const rate = (rows) => rows.length ? (rows.filter((r) => r.recoveryFired).length / rows.length) * 100 : 0;
+    // ---- Measure 4: cohort A/B by the `enabled` column ----
+    const enabledTurns = turns.filter((t) => t.enabled === 1);
+    const disabledTurns = turns.filter((t) => t.enabled === 0);
+    // ---- Measure 5: net token economics ----
+    const spentReviewing = reviews.reduce((n, r) => n + r.tokensSpent, 0);
+    const savedByReuse = estimateSaved(turns);
+    return {
+        agentId,
+        generatedAt: now,
+        adoption: { autoSkills, loadedAtLeast1, loadedAtLeast3, stickyPct },
+        costDelta: {
+            clusters,
+            medianToolCallsBefore: medianOrNull(before.map((t) => t.toolCalls)),
+            medianToolCallsAfter: medianOrNull(after.map((t) => t.toolCalls)),
+            medianTokensBefore: medianOrNull(before.map(turnTokens)),
+            medianTokensAfter: medianOrNull(after.map(turnTokens)),
+        },
+        recovery: { ratePctRecent: rate(recent), ratePctEarlier: rate(earlier) },
+        cohort: {
+            enabledTurns: enabledTurns.length,
+            disabledTurns: disabledTurns.length,
+            enabledMedianToolCalls: medianOrNull(enabledTurns.map((t) => t.toolCalls)),
+            disabledMedianToolCalls: medianOrNull(disabledTurns.map((t) => t.toolCalls)),
+        },
+        netTokens: { savedByReuse, spentReviewing, net: savedByReuse - spentReviewing },
+    };
+}
+/**
+ * Estimate tokens saved by reuse: per intent cluster, take the median token cost
+ * of "before" (no-skill) turns as the counterfactual, and credit each "after"
+ * (skill-loaded) turn the positive difference. Sum across clusters.
+ */
+function estimateSaved(turns) {
+    const byCluster = new Map();
+    for (const t of turns) {
+        const k = t.intentHash ?? 'misc';
+        (byCluster.get(k) ?? byCluster.set(k, []).get(k)).push(t);
+    }
+    let saved = 0;
+    for (const rows of byCluster.values()) {
+        const before = rows.filter((r) => !hasSkill(r));
+        const after = rows.filter((r) => hasSkill(r));
+        if (!before.length || !after.length)
+            continue;
+        const baseline = median(before.map(turnTokens));
+        for (const a of after) {
+            saved += Math.max(0, baseline - turnTokens(a));
+        }
+    }
+    return saved;
+}
+//# sourceMappingURL=metrics.js.map

package/dist/agent/skill-learning/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../../src/agent/skill-learning/metrics.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAgCH,sCAqDC;AAhFD,SAAS,MAAM,CAAC,MAAgB;IAC9B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAClC,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AACvE,CAAC;AAED,oFAAoF;AACpF,SAAS,YAAY,CAAC,MAAgB;IACpC,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,UAAU,CAAC,CAAgB;IAClC,OAAO,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,SAAS,CAAC;AAClC,CAAC;AAED,SAAS,QAAQ,CAAC,CAAgB;IAChC,IAAI,CAAC,CAAC,CAAC,YAAY;QAAE,OAAO,KAAK,CAAC;IAClC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAc,CAAC;QACpD,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,0DAA0D;AAC1D,SAAgB,aAAa,CAAC,EAAa,EAAE,OAAe,EAAE,GAAW;IACvE,MAAM,KAAK,GAAG,EAAE,CAAC,cAAc,EAAE,CAAC;IAClC,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;IAC3D,MAAM,KAAK,GAAG,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAErC,uCAAuC;IACvC,MAAM,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC;IACpC,MAAM,cAAc,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;IAC1E,MAAM,cAAc,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;IAC1E,MAAM,SAAS,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,GAAG,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAE3E,0EAA0E;IAC1E,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,IAAI,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IAExE,+EAA+E;IAC/E,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IACvD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACpC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,IAAI,GAAG,CAAC,IAAqB,EAAU,EAAE,CAC7C,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAErF,0DAA0D;IAC1D,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC;IAC1D,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC;IAE3D,2CAA2C;IAC3C,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IACtE,MAAM,YAAY,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAE1C,OAAO;QACL,OAAO;QACP,WAAW,EAAE,GAAG;QAChB,QAAQ,EAAE,EAAE,UAAU,EAAE,cAAc,EAAE,cAAc,EAAE,SAAS,EAAE;QACnE,SAAS,EAAE;YACT,QAAQ;YACR,qBAAqB,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YACnE,oBAAoB,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YACjE,kBAAkB,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YACxD,iBAAiB,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;SACvD;QACD,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,cAAc,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE;QACxE,MAAM,EAAE;YACN,YAAY,EAAE,YAAY,CAAC,MAAM;YACjC,aAAa,EAAE,aAAa,CAAC,MAAM;YACnC,sBAAsB,EAAE,YAAY,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YAC1E,uBAAuB,EAAE,YAAY,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;SAC7E;QACD,SAAS,EAAE,EAAE,YAAY,EAAE,cAAc,EAAE,GAAG,EAAE,YAAY,GAAG,cAAc,EAAE;KAChF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,KAAsB;IAC3C,MAAM,SAAS,GAAG,IAAI,GAAG,EAA2B,CAAC;IACrD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,IAAI,MAAM,CAAC;QACjC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAChD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9C,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM;YAAE,SAAS;QAC9C,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;QAChD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/agent/skill-learning/notifier.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Skill notifier — tells the operator when the closed loop writes a skill.
+ *
+ * Two independent surfaces (per user request, 2026-08-17):
+ *   1. **Diary** (`SKILLS_LEARNED.md` in the workspace) — ALWAYS appended, an
+ *      immutable audit log of every auto-write. Cheap, offline, never throttled.
+ *   2. **Channel push** (Telegram) — a short "learned a skill" ping, gated by
+ *      `cfg.notify`. Throttled: up to NOTIFY_THROTTLE_MAX immediate pings per
+ *      rolling window, then further writes coalesce into one digest so a burst
+ *      cannot spam the chat.
+ *
+ * Everything here is best-effort and MUST NOT throw into the review path.
+ * The channel transport (`send`) is injected — the manager builds the real
+ * Telegram sender; tests pass a capturing stub. Diary + throttle logic are
+ * transport-agnostic and fully unit-testable with an injected clock.
+ */
+export declare const DIARY_FILENAME = "SKILLS_LEARNED.md";
+/** Rolling window for the burst throttle. */
+export declare const NOTIFY_THROTTLE_WINDOW_MS: number;
+/** Immediate pings allowed per window before writes coalesce into a digest. */
+export declare const NOTIFY_THROTTLE_MAX = 3;
+/** A channel transport: deliver one plain-text message. Never expected to throw. */
+export type SendFn = (text: string) => void | Promise<void>;
+export interface SkillWriteEvent {
+    name: string;
+    action: 'create' | 'edit';
+    sessionId: string;
+    /** Timestamp (ms) — injected clock so tests are deterministic. */
+    now: number;
+}
+export interface SkillNotifierOpts {
+    workspaceDir: string;
+    /** Channel push on/off. The diary is written regardless. */
+    notify: boolean;
+    /** Channel transport. `undefined` ⇒ no channel wired (diary-only). */
+    send?: SendFn;
+    logger?: {
+        info: (msg: string) => void;
+        warn?: (msg: string) => void;
+    };
+}
+/**
+ * Read the Telegram allowlist for a workspace — the chat_ids authorized to talk
+ * to this agent, which are exactly the right recipients for its notifications
+ * (Telegram DM chat_id == user_id). Best-effort: any error ⇒ no recipients.
+ */
+export declare function readTelegramRecipients(workspaceDir: string): string[];
+/** POST a Telegram sendMessage. Throws on HTTP failure so the caller can log it. */
+export declare function pushTelegram(botToken: string, chatId: string, text: string): Promise<void>;
+/**
+ * Build the channel `send` transport for an agent from its Telegram bot token.
+ * Returns `undefined` when no token is configured (diary-only). The returned fn
+ * resolves recipients fresh on each call (allowlist may change at runtime) and
+ * fans out best-effort — one failed recipient never blocks the others.
+ */
+export declare function buildTelegramSend(workspaceDir: string, botToken: string | undefined, logger?: SkillNotifierOpts['logger']): SendFn | undefined;
+/** Per-agent channel credentials available at gateway boot (from AgentConfig). */
+export interface ChannelTokens {
+    telegramBotToken?: string;
+    discordBotToken?: string;
+    /** LINE channel access token. Present ⇒ the LINE transport self-activates. */
+    lineAccessToken?: string;
+}
+/** Discord recipients: user_ids from `.discord-state/access.json` `allowFrom`. */
+export declare function readDiscordRecipients(workspaceDir: string): string[];
+/** DM a Discord user (open DM channel, then post chunked). Throws on HTTP failure. */
+export declare function pushDiscordDM(botToken: string, userId: string, text: string): Promise<void>;
+/** Build the Discord `send` transport. undefined when no bot token is configured. */
+export declare function buildDiscordSend(workspaceDir: string, botToken: string | undefined, logger?: SkillNotifierOpts['logger']): SendFn | undefined;
+/** LINE recipients: user_ids from `.line-state/access.json` `allowFrom`. */
+export declare function readLineRecipients(workspaceDir: string): string[];
+/** Push a LINE text message to a user. Throws on HTTP failure so the caller can log it. */
+export declare function pushLine(accessToken: string, to: string, text: string): Promise<void>;
+/**
+ * Build the LINE `send` transport. undefined when no channel access token is
+ * configured — so LINE stays dormant until an agent has LINE set up, at which
+ * point it self-activates with no code change ("just open it": the token flows
+ * in from AgentConfig.line.channelAccessToken at boot).
+ */
+export declare function buildLineSend(workspaceDir: string, accessToken: string | undefined, logger?: SkillNotifierOpts['logger']): SendFn | undefined;
+/**
+ * Build a single fan-out `send` across every configured channel transport.
+ * Returns undefined when the agent has no push channel wired (diary-only).
+ * Fan-out is best-effort and concurrent — one channel failing never blocks the
+ * others, and no rejection escapes into the review path.
+ */
+export declare function buildChannelSend(workspaceDir: string, tokens: ChannelTokens, logger?: SkillNotifierOpts['logger']): SendFn | undefined;
+export declare class SkillNotifier {
+    private readonly workspaceDir;
+    private readonly notify;
+    private readonly send?;
+    private readonly logger?;
+    /** Timestamps of immediate pings still inside the current window. */
+    private recent;
+    /** Coalesced writes awaiting a digest flush. */
+    private buffer;
+    private flushTimer?;
+    constructor(opts: SkillNotifierOpts);
+    /**
+     * Record a live skill write. Appends the diary (always) and, if channel push
+     * is on, either pings immediately or buffers for a digest. Never throws.
+     */
+    onSkillWritten(ev: SkillWriteEvent): void;
+    /** Emit any buffered digest now (shutdown / test seam / timer callback). */
+    flushPending(): void;
+    private pushThrottled;
+    private armFlush;
+    private safeSend;
+    private appendDiary;
+}
+//# sourceMappingURL=notifier.d.ts.map

package/dist/agent/skill-learning/notifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifier.d.ts","sourceRoot":"","sources":["../../../src/agent/skill-learning/notifier.ts"],"names":[],"mappings":"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"}