@ashlr/hub 2.2.0

package/dist/core/learn/playbooks.d.ts

@@ -0,0 +1,84 @@
+/**
+ * playbooks.ts — M26 playbook distillation from SUCCESSFUL past swarms.
+ *
+ * Distills recurring patterns from `done` swarms into playbook entries and
+ * persists them via the genome (appendHubEntry, hubOnly) so they auto-inject
+ * into future agents. An OPTIONAL local-model narrative may polish the playbook
+ * text — but the default path is deterministic and makes ZERO cloud calls.
+ *
+ * HARD SAFETY INVARIANTS (M26):
+ *  - READ-ONLY over history: reads listSwarms() only. The ONLY write is
+ *    appendHubEntry({ hubOnly: true }) into ~/.ashlr/genome/hub.jsonl — an
+ *    APPEND to the genome hub. With hubOnly:true it NEVER drops a file into a
+ *    user repo working tree (see appendHubEntry's contract). It NEVER writes
+ *    CONFIG_PATH / router policy / prompts.
+ *  - LOCAL-FIRST: narrative text routes through getActiveClient(cfg,
+ *    { allowCloud }) EXACTLY as M25 ask.ts — local Ollama/LM Studio only unless
+ *    the caller passes allowCloud AND a key is present. Default path is local
+ *    and the deterministic fallback needs no model at all.
+ *  - BOUNDED: analyzes at most `maxRuns` recent done swarms; caps emitted
+ *    playbooks.
+ *  - NEVER THROWS: degrades to the deterministic synthesis / a no-op persist.
+ *
+ * METADATA ONLY — never persists secret values or raw payloads.
+ */
+import type { AshlrConfig, GenomeEntry, SwarmRun } from '../types.js';
+/** One distilled playbook before persistence. */
+export interface DistilledPlaybook {
+    /** Coarse category / goal-cluster this playbook generalizes. */
+    category: string;
+    /** Short title used as the genome entry heading. */
+    title: string;
+    /** The playbook body (deterministic synthesis, optionally LLM-polished). */
+    text: string;
+    /** Tags attached to the persisted genome entry. */
+    tags: string[];
+    /** Number of successful swarms that informed this playbook. */
+    supportCount: number;
+}
+/** Result of a distill+persist pass. */
+export interface PlaybookResult {
+    /** The distilled playbooks (whether or not persistence succeeded). */
+    playbooks: DistilledPlaybook[];
+    /** Genome entries actually appended (one per persisted playbook). Empty when
+     *  persistence was not requested (the default report-only mode). */
+    persisted: GenomeEntry[];
+    /** True when the narrative text was produced by a LOCAL model (or no model). */
+    local: boolean;
+    /** Whether the genome hub was actually written (true only with persist:true). */
+    didPersist: boolean;
+}
+/**
+ * Distill recurring SUCCESSFUL patterns from `done` swarms into playbook
+ * candidates. Pure over the provided swarms; never throws.
+ *
+ * Filters to status==='done', clusters by coarse goal category, and for each
+ * cluster with >= MIN_SUPPORT support synthesizes a deterministic "what worked"
+ * body from the swarms' goals/results. Capped at MAX_PLAYBOOKS, sorted by
+ * supportCount desc.
+ */
+export declare function distillPlaybooks(swarms: SwarmRun[]): DistilledPlaybook[];
+/**
+ * Distill playbooks from recent SUCCESSFUL swarms. Persisting them to the
+ * genome hub (appendHubEntry, hubOnly:true) — which auto-injects them into
+ * future agents — happens ONLY when `opts.persist` is true. By DEFAULT this is
+ * report-only: it distills and returns the playbooks but writes NOTHING, so a
+ * genome write that changes future-agent behaviour never happens without an
+ * explicit opt-in (the CLI's `--persist` flag).
+ *
+ * When `opts.narrative` is requested, each playbook body is optionally polished
+ * by a model via getActiveClient(cfg, { allowCloud: opts.allowCloud }) —
+ * LOCAL-ONLY unless allowCloud AND a key exist (getActiveClient throws
+ * otherwise; we then fall back to the deterministic body). The default path
+ * (no narrative) makes ZERO non-localhost connections.
+ *
+ * Never throws. MUST NOT call saveConfig() or write CONFIG_PATH / router policy.
+ */
+export declare function distillAndPersist(cfg: AshlrConfig, opts?: {
+    maxRuns?: number;
+    narrative?: boolean;
+    allowCloud?: boolean;
+    /** When true, persist distilled playbooks to the genome hub. Default false
+     *  (report-only — no genome write, no future-agent behaviour change). */
+    persist?: boolean;
+}): Promise<PlaybookResult>;

package/dist/core/learn/playbooks.js

@@ -0,0 +1,241 @@
+/**
+ * playbooks.ts — M26 playbook distillation from SUCCESSFUL past swarms.
+ *
+ * Distills recurring patterns from `done` swarms into playbook entries and
+ * persists them via the genome (appendHubEntry, hubOnly) so they auto-inject
+ * into future agents. An OPTIONAL local-model narrative may polish the playbook
+ * text — but the default path is deterministic and makes ZERO cloud calls.
+ *
+ * HARD SAFETY INVARIANTS (M26):
+ *  - READ-ONLY over history: reads listSwarms() only. The ONLY write is
+ *    appendHubEntry({ hubOnly: true }) into ~/.ashlr/genome/hub.jsonl — an
+ *    APPEND to the genome hub. With hubOnly:true it NEVER drops a file into a
+ *    user repo working tree (see appendHubEntry's contract). It NEVER writes
+ *    CONFIG_PATH / router policy / prompts.
+ *  - LOCAL-FIRST: narrative text routes through getActiveClient(cfg,
+ *    { allowCloud }) EXACTLY as M25 ask.ts — local Ollama/LM Studio only unless
+ *    the caller passes allowCloud AND a key is present. Default path is local
+ *    and the deterministic fallback needs no model at all.
+ *  - BOUNDED: analyzes at most `maxRuns` recent done swarms; caps emitted
+ *    playbooks.
+ *  - NEVER THROWS: degrades to the deterministic synthesis / a no-op persist.
+ *
+ * METADATA ONLY — never persists secret values or raw payloads.
+ */
+import { listSwarms } from '../swarm/store.js';
+import { appendHubEntry } from '../genome/store.js';
+import { getActiveClient } from '../run/provider-client.js';
+import { classifyGoal } from './reflect.js';
+// ---------------------------------------------------------------------------
+// Bounds
+// ---------------------------------------------------------------------------
+/** Default cap on how many recent swarms to mine for patterns. */
+const DEFAULT_MAX_RUNS = 100;
+/** Max playbook entries distilled+persisted per invocation. */
+const MAX_PLAYBOOKS = 5;
+/** Minimum successful swarms in a category before it becomes a playbook. */
+const MIN_SUPPORT = 2;
+/** Hard cap on the narrative-synthesis prompt fed to the local model (chars). */
+const SYNTHESIS_PROMPT_MAX_CHARS = 4000;
+// ---------------------------------------------------------------------------
+// Pure distillation (exported for testing) — NO I/O, NO LLM
+// ---------------------------------------------------------------------------
+/** Collapse a result/goal string into a short, single-line excerpt. Pure. */
+function excerpt(s, max = 140) {
+    if (!s)
+        return '';
+    return s.replace(/\s+/g, ' ').trim().slice(0, max);
+}
+/**
+ * Distill recurring SUCCESSFUL patterns from `done` swarms into playbook
+ * candidates. Pure over the provided swarms; never throws.
+ *
+ * Filters to status==='done', clusters by coarse goal category, and for each
+ * cluster with >= MIN_SUPPORT support synthesizes a deterministic "what worked"
+ * body from the swarms' goals/results. Capped at MAX_PLAYBOOKS, sorted by
+ * supportCount desc.
+ */
+export function distillPlaybooks(swarms) {
+    try {
+        if (!Array.isArray(swarms))
+            return [];
+        const done = swarms.filter((s) => s && s.status === 'done');
+        const byCat = new Map();
+        for (const s of done) {
+            const cat = classifyGoal(s.goal ?? '');
+            const arr = byCat.get(cat) ?? [];
+            arr.push(s);
+            byCat.set(cat, arr);
+        }
+        const playbooks = [];
+        for (const [category, group] of byCat) {
+            if (group.length < MIN_SUPPORT)
+                continue;
+            // Deterministic "what worked" body: a few representative goals + outcomes.
+            const samples = group.slice(0, 3).map((s) => {
+                const goal = excerpt(s.goal, 100) || '(no goal)';
+                const seq = phasePattern(s);
+                const phaseStr = seq ? ` [phases: ${seq}]` : '';
+                const result = excerpt(s.result, 100);
+                return `- ${goal}${phaseStr}${result ? ` -> ${result}` : ''}`;
+            });
+            // The most common phase pattern across the cluster (e.g. "plan -> build").
+            const dominant = dominantPhasePattern(group);
+            const text = `Playbook: ${category} work that succeeded\n\n` +
+                `Across ${group.length} successful '${category}' swarm(s), the following approaches ` +
+                `completed first-pass. ` +
+                (dominant
+                    ? `The recurring phase pattern was: ${dominant}. `
+                    : `No consistent phase pattern was recorded. `) +
+                `Reuse the phase structure and framing below for similar goals:\n\n` +
+                samples.join('\n');
+            playbooks.push({
+                category,
+                title: `What works for ${category} swarms`,
+                text,
+                tags: ['m26', 'playbook', `cat:${category}`],
+                supportCount: group.length,
+            });
+        }
+        playbooks.sort((a, b) => b.supportCount - a.supportCount ||
+            (a.category < b.category ? -1 : a.category > b.category ? 1 : 0));
+        return playbooks.slice(0, MAX_PLAYBOOKS);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Derive a swarm's de-duplicated phase sequence from its executed tasks,
+ * rendered as "plan -> build -> verify". Empty string when no phases. Pure.
+ */
+function phasePattern(s) {
+    const tasks = Array.isArray(s?.tasks) ? s.tasks : [];
+    const phases = [];
+    for (const t of tasks) {
+        const ph = t?.phase ? String(t.phase) : '';
+        if (ph && phases[phases.length - 1] !== ph)
+            phases.push(ph);
+    }
+    return phases.join(' -> ');
+}
+/** The most frequent phase pattern across a cluster of swarms. Pure. */
+function dominantPhasePattern(group) {
+    const counts = new Map();
+    for (const s of group) {
+        const ptn = phasePattern(s);
+        if (!ptn)
+            continue;
+        counts.set(ptn, (counts.get(ptn) ?? 0) + 1);
+    }
+    let best = '';
+    let bestN = 0;
+    for (const [ptn, n] of counts) {
+        if (n > bestN || (n === bestN && (best === '' || ptn < best))) {
+            best = ptn;
+            bestN = n;
+        }
+    }
+    return best;
+}
+/**
+ * Build the OPTIONAL narrative-synthesis prompt for a playbook candidate.
+ * Pure; capped at SYNTHESIS_PROMPT_MAX_CHARS. Never throws.
+ */
+function buildNarrativePrompt(pb) {
+    const prompt = `You are distilling a reusable engineering playbook from past SUCCESSFUL runs. ` +
+        `Rewrite the notes below into a concise, actionable playbook (max ~120 words). ` +
+        `Do NOT invent facts; only generalize what is present.\n\n` +
+        `Category: ${pb.category}\nSupport: ${pb.supportCount} successful swarm(s)\n\n` +
+        `Notes:\n${pb.text}`;
+    return prompt.slice(0, SYNTHESIS_PROMPT_MAX_CHARS);
+}
+// ---------------------------------------------------------------------------
+// Public: distill + persist
+// ---------------------------------------------------------------------------
+/**
+ * Distill playbooks from recent SUCCESSFUL swarms. Persisting them to the
+ * genome hub (appendHubEntry, hubOnly:true) — which auto-injects them into
+ * future agents — happens ONLY when `opts.persist` is true. By DEFAULT this is
+ * report-only: it distills and returns the playbooks but writes NOTHING, so a
+ * genome write that changes future-agent behaviour never happens without an
+ * explicit opt-in (the CLI's `--persist` flag).
+ *
+ * When `opts.narrative` is requested, each playbook body is optionally polished
+ * by a model via getActiveClient(cfg, { allowCloud: opts.allowCloud }) —
+ * LOCAL-ONLY unless allowCloud AND a key exist (getActiveClient throws
+ * otherwise; we then fall back to the deterministic body). The default path
+ * (no narrative) makes ZERO non-localhost connections.
+ *
+ * Never throws. MUST NOT call saveConfig() or write CONFIG_PATH / router policy.
+ */
+export async function distillAndPersist(cfg, opts = {}) {
+    // 1. Read recent swarms (READ-ONLY, BOUNDED).
+    let swarms = [];
+    try {
+        swarms = listSwarms().slice(0, Math.max(0, opts.maxRuns ?? DEFAULT_MAX_RUNS));
+    }
+    catch {
+        swarms = [];
+    }
+    // 2. Deterministic distillation.
+    const playbooks = distillPlaybooks(swarms);
+    // 3. OPTIONAL narrative polish — LOCAL-FIRST, mirrors M25 ask.ts.
+    //    Default path (no narrative) never touches a model at all.
+    let local = true;
+    if (opts.narrative && playbooks.length > 0) {
+        try {
+            const client = await getActiveClient(cfg, { allowCloud: opts.allowCloud ?? false });
+            // ALLOWLIST (not denylist): only the known local providers count as local.
+            local = client.id === 'ollama' || client.id === 'lmstudio';
+            for (const pb of playbooks) {
+                try {
+                    const res = await client.chat([
+                        {
+                            role: 'system',
+                            content: 'You distill reusable engineering playbooks from successful past runs. ' +
+                                'Be concise and never invent facts.',
+                        },
+                        { role: 'user', content: buildNarrativePrompt(pb) },
+                    ]);
+                    const polished = (res.content ?? '').trim();
+                    if (polished)
+                        pb.text = polished;
+                }
+                catch {
+                    // Keep the deterministic body for this playbook on any model error.
+                }
+            }
+        }
+        catch {
+            // getActiveClient threw (no local provider, or cloud refused without key).
+            // Keep deterministic bodies; the local-first refusal is treated as a local
+            // attempt that simply didn't produce narrative.
+            local = true;
+        }
+    }
+    // 4. Persist each via the genome hub (hubOnly:true => never writes a repo
+    //    file) — ONLY when explicitly opted in via persist:true. By default this
+    //    is report-only: NO genome write, so future-agent behaviour is unchanged
+    //    until a human runs `reflect playbooks --persist`.
+    const persisted = [];
+    const didPersist = opts.persist === true;
+    if (didPersist) {
+        for (const pb of playbooks) {
+            try {
+                const entry = appendHubEntry({
+                    text: pb.text,
+                    title: pb.title,
+                    tags: pb.tags,
+                    hubOnly: true,
+                });
+                persisted.push(entry);
+            }
+            catch {
+                // Append failed — still return the distilled playbook to the caller.
+            }
+        }
+    }
+    return { playbooks, persisted, local, didPersist };
+}
+//# sourceMappingURL=playbooks.js.map

package/dist/core/learn/playbooks.js.map

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

package/dist/core/learn/reflect.d.ts

@@ -0,0 +1,87 @@
+/**
+ * reflect.ts — M26 deterministic reflection metrics engine.
+ *
+ * Scores the org's OWN past swarms/usage/genome and computes a ReflectionReport:
+ * success rate, avg cost & tokens per swarm, local-vs-cloud share, clustered
+ * top failure modes, slowest/most-expensive goal categories, and week-over-week
+ * deltas vs the prior persisted snapshot.
+ *
+ * HARD SAFETY INVARIANTS (M26):
+ *  1. READ-ONLY over history. Reads listSwarms() / genomeHubHealth /
+ *     collectUsageEvents() ONLY — the HUB-ONLY genome reader (no portfolio
+ *     disk scan). Writes nothing here (the CLI persists the snapshot via
+ *     learn/store.ts under ~/.ashlr/learn/).
+ *  2. NO TUNING. This module never proposes or applies anything — pure metrics.
+ *  3. LOCAL-FIRST / NO LLM. buildReflection is DETERMINISTIC and makes ZERO
+ *     network connections. No getActiveClient, no fetch. Narrative generation
+ *     lives in playbooks.ts, never here.
+ *  4. BOUNDED. Reads at most `maxRuns` recent swarms (default DEFAULT_MAX_RUNS)
+ *     and/or those within `sinceMs`. listSwarms() is itself capped at 200.
+ *  5. NEVER THROWS. Degrades to a zeroed report on any failure.
+ *
+ * METADATA ONLY — never reads/retains secret values or raw code/payloads.
+ */
+import type { AshlrConfig, FailureMode, GoalCategoryStat, ReflectionDelta, ReflectionOptions, ReflectionReport, SwarmRun } from '../types.js';
+/** Default cap on how many recent swarms to analyze (bounds work). */
+export declare const DEFAULT_MAX_RUNS = 100;
+/**
+ * Default usage-window lookback (ms) applied when NO --since window is given.
+ * Bounds collectUsageEvents() so the default path never streams the entire
+ * historical transcript corpus — it matches the report's week-over-week
+ * framing. `--since all` (sinceMs explicitly 0) is the opt-in to scan all
+ * history (still bounded by the per-file caps in usage-source.ts).
+ */
+export declare const DEFAULT_USAGE_LOOKBACK_MS: number;
+/** Coarse goal categories (keyword heuristic; deterministic). */
+declare const GOAL_CATEGORIES: readonly ["feature", "bugfix", "refactor", "test", "docs", "chore", "other"];
+/**
+ * Bucket a swarm goal string into one coarse GOAL_CATEGORIES label using a
+ * deterministic keyword heuristic. Pure; never throws.
+ *
+ * Order matters: the first matching category wins (most-specific verbs first).
+ */
+export declare function classifyGoal(goal: string): (typeof GOAL_CATEGORIES)[number];
+/**
+ * Normalize a raw task.error string into a stable cluster key (lowercase,
+ * stripped of ids/paths/numbers/hashes) so similar errors cluster together.
+ * Pure; never throws.
+ */
+export declare function normalizeErrorKey(error: string): string;
+/**
+ * Cluster failed tasks across swarms into the top FailureMode buckets, most
+ * frequent first, capped at MAX_FAILURE_MODES. Pure over the provided swarms;
+ * never throws.
+ */
+export declare function clusterFailures(swarms: SwarmRun[]): FailureMode[];
+/**
+ * Aggregate per-goal-category cost/token/success stats over the swarms,
+ * most-expensive (avgCostUsd) first. Pure; never throws.
+ */
+export declare function summarizeGoalCategories(swarms: SwarmRun[]): GoalCategoryStat[];
+/**
+ * Compute week-over-week deltas vs a prior snapshot. Pure; never throws.
+ * When `previous` is null, returns a no-prior delta (all numeric fields null).
+ *
+ * `currentWindow` (the window/scope label of the CURRENT report) is compared
+ * against `previous.window`. When they differ, the metrics were computed over
+ * DIFFERENT populations, so the headline is annotated '(windows differ)' to
+ * flag that the delta is apples-to-oranges. Omitting it (or passing the same
+ * label) leaves the headline unannotated.
+ */
+export declare function computeDelta(current: Pick<ReflectionReport, 'successRate' | 'avgCostUsd' | 'localShare'>, previous: ReflectionReport | null, currentWindow?: string | null): ReflectionDelta;
+/**
+ * Build a ReflectionReport from the user's OWN local history.
+ *
+ * Reads (READ-ONLY):
+ *  - listSwarms() — capped to the most-recent `maxRuns` and/or `sinceMs` window.
+ *  - collectUsageEvents(sinceMs) — for the local-vs-cloud token share.
+ *  - genomeHubHealth — HUB-ONLY entry counts (no portfolio disk scan).
+ *
+ * Computes: success rate, avg cost & tokens per swarm, local share, top failure
+ * modes, goal-category stats, and week-over-week deltas vs loadPreviousReport().
+ *
+ * DETERMINISTIC: makes ZERO network connections and uses NO LLM. Never throws —
+ * returns a zeroed report on any failure.
+ */
+export declare function buildReflection(_cfg: AshlrConfig, opts?: ReflectionOptions): ReflectionReport;
+export {};