@voybio/ace-swarm 2.4.8 → 2.4.10

package/dist/learning-controls.d.ts

@@ -0,0 +1,142 @@
+import { type LearnedArtifact } from './learned-artifacts.js';
+export declare function listLearning(root: string): {
+    lessons: import("./store/repositories/playbook-repository.js").PlaybookBullet[];
+    artifacts: LearnedArtifact[];
+};
+export declare function showLearning(root: string, id: string): import("./store/repositories/playbook-repository.js").PlaybookBullet | LearnedArtifact | undefined;
+export declare function approveLearning(root: string, id: string): Promise<void>;
+export declare function retireLearning(root: string, id: string, reason: string): Promise<void>;
+export { approvedInstructionText, approvedDistillerText } from './learning-overlays.js';
+export declare function learningReport(root: string): {
+    scorecard: {
+        active_learned_artifacts: {
+            lessons: number;
+            skills: number;
+            approved_instructions: number;
+        };
+        repeat_failure_rate: {
+            signatures_served: number;
+            signatures_recurred: number;
+            rate: number | null;
+            missing_context_attempts: number;
+            interpretation: string;
+        };
+        first_attempt_success_by_scope: {
+            scope: string;
+            before: ReturnType<() => {
+                done: number;
+                steps: number;
+                rate: number | null;
+            }>;
+            after: ReturnType<() => {
+                done: number;
+                steps: number;
+                rate: number | null;
+            }>;
+            unclassified: ReturnType<() => {
+                done: number;
+                steps: number;
+                rate: number | null;
+            }>;
+            unexposed: ReturnType<() => {
+                done: number;
+                steps: number;
+                rate: number | null;
+            }>;
+        }[];
+        first_attempt_coverage: {
+            missing_first_attempts: number;
+            reconstructed_scopes: number;
+            interpretation: string;
+        };
+        served_helpfulness: {
+            helpful: number;
+            harmful: number;
+            ratio: number | null;
+            counter_scope: string;
+        };
+        distill_acceptance: {
+            checked: number;
+            submitted: number;
+            rate: number | null;
+            demonstrated_current_artifacts: number;
+        };
+        learning_overhead: {
+            learning_steps: number;
+            all_steps: number;
+            ratio: number | null;
+            opportunistic_payload_steps: number;
+            assignments: {
+                episode_id: string;
+                utf8_bytes: number;
+                token_upper_bound: number;
+            }[];
+            max_served_token_upper_bound: number | null;
+            token_method: string;
+        };
+        retirement_health: {
+            window_days: number;
+            retired: number;
+            ever_active: number;
+            ratio: number | null;
+            unknown_history: number;
+        };
+        distillation_steps: {
+            goal_id: string;
+            step_id: string;
+            checked: boolean;
+            items_after_20_serves: number;
+            mean_strong_helpfulness: number | null;
+        }[];
+        coverage: string;
+    };
+    enabled: boolean;
+    policy_issue: string | null;
+    observation: string;
+    episodes: number;
+    attempts: number;
+    first_attempts_done: number;
+    steps_with_outcomes: number;
+    artifacts: {
+        lessons: number;
+        skills: number;
+        quarantined: number;
+    };
+    instructions: {
+        active: number;
+        proposed: number;
+    };
+    served: number;
+    used: number;
+    helpful: number;
+    harmful: number;
+    weak_outcomes: {
+        done_first_attempt: number;
+        failed_same_signature: number;
+        other: number;
+    };
+    repeat_signatures: {
+        signature: string;
+        count: number;
+    }[];
+    distillation: {
+        submitted: number;
+        checked: number;
+        acceptance_rate: number | null;
+        demonstrated: number;
+        helpfulness_after_20_serves: {
+            id: unknown;
+            helpful: number;
+            harmful: number;
+            used: number;
+        }[];
+    };
+    limitations: string[];
+};
+export declare function exportLearning(root: string, to: string): Promise<{
+    files: string[];
+    unexported: string[];
+}>;
+/** Open the next useful proposal, never a coordinator or automatic approval. */
+export declare function advanceLearning(root: string): Promise<void>;
+//# sourceMappingURL=learning-controls.d.ts.map

package/dist/learning-controls.js

@@ -0,0 +1,135 @@
+import { buildLearningScorecard } from './learning-scorecard.js';
+/** Explicit operator controls and reports over existing learning records. */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { GoalRepository, defaultGoalBudgets } from './store/repositories/goal-repository.js';
+import { amendTaskPlan, createTaskPlan } from './orchestrator-supervisor.js';
+import { PlaybookRepository, withPlaybookTransaction } from './store/repositories/playbook-repository.js';
+import { listLearnedArtifacts, saveLearnedArtifact, regenerateLearnedProjection, withLearnedStore } from './learned-artifacts.js';
+import { withStoreWriteCoordinator } from './store/write-coordinator.js';
+import { readLearningPolicy } from './learning-policy.js';
+import { ContentSource } from './store/types.js';
+import { listEpisodes } from './host-learning.js';
+export function listLearning(root) { return { lessons: new PlaybookRepository(root).listBulletsReadOnly(), artifacts: listLearnedArtifacts(root) }; }
+export function showLearning(root, id) { const all = listLearning(root); return all.lessons.find(b => b.bullet_id === id) ?? all.artifacts.find(a => a.id === id); }
+export async function approveLearning(root, id) {
+    const a = listLearnedArtifacts(root).find(a => a.id === id);
+    if (!a || a.status !== 'proposed' || !['instruction', 'distiller'].includes(a.kind))
+        throw Error('Choose an existing proposed instruction or distiller overlay. Lessons and skills do not need operator approval.');
+    const sourceKey = a.key, canonical = a.kind === 'instruction' ? `knowledge/agents/${a.scope.role}/LEARNED.md` : 'knowledge/skills/learn-from-work/LEARNED.md';
+    await withLearnedStore(root, async (store) => {
+        const prior = await store.getBlob(canonical);
+        if (prior) {
+            const name = `references/history/${new Date().toISOString().replace(/[^0-9]/g, '')}.md`;
+            if (a.kind === 'instruction')
+                await store.setAgentInstruction(a.scope.role, name, prior, ContentSource.User);
+            else
+                await store.setSkillContent('learn-from-work', name, prior, ContentSource.User);
+        }
+    });
+    if (sourceKey !== canonical)
+        await saveLearnedArtifact(root, { ...a, id: a.id + ':proposal-record', status: 'retired', retired_reason: 'Approved into ' + canonical });
+    a.status = 'active';
+    a.approved_at = new Date().toISOString();
+    a.approval = 'explicit ace learn approve';
+    a.key = canonical;
+    await saveLearnedArtifact(root, a);
+    await regenerateLearnedProjection(root);
+}
+export async function retireLearning(root, id, reason) {
+    if (!reason.trim())
+        throw Error('Retirement needs a reason.');
+    const a = listLearnedArtifacts(root).find(a => a.id === id);
+    if (a) {
+        await saveLearnedArtifact(root, { ...a, status: 'retired', retired_reason: reason });
+    }
+    else
+        await withPlaybookTransaction(root, repo => {
+            const b = repo.getBullet(id);
+            if (!b)
+                throw Error('Learning item not found: ' + id);
+            repo.saveBullet({ ...b, status: 'retired', retired_reason: reason });
+        });
+    await regenerateLearnedProjection(root);
+}
+export { approvedInstructionText, approvedDistillerText } from './learning-overlays.js';
+export function learningReport(root) {
+    const all = listLearning(root), repo = new GoalRepository(root), steps = repo.listGoals().flatMap(g => (repo.getPlan(g.goal_id)?.steps ?? []).map(s => ({ goal: g.goal_id, step: s }))), episodes = listEpisodes(root);
+    const logs = steps.flatMap(({ goal, step }) => (step.attempts_log ?? []).map(a => ({ ...a, goal, step_id: step.step_id })));
+    const distill = steps.filter(({ step }) => step.learning_payload && step.learning_result), skills = all.artifacts.filter(a => a.kind === 'skill'), instructions = all.artifacts.filter(a => a.kind === 'instruction'), served = [...all.lessons, ...skills];
+    const signatureCounts = new Map();
+    for (const ep of episodes)
+        if (ep.failure_signature)
+            signatureCounts.set(ep.failure_signature, (signatureCounts.get(ep.failure_signature) ?? 0) + 1);
+    return { scorecard: buildLearningScorecard(steps, episodes, all.lessons, all.artifacts), enabled: readLearningPolicy(root).enabled, policy_issue: readLearningPolicy(root).issue ?? null, observation: 'unavailable unless a qualified Vericify adapter supplied Linked records', episodes: episodes.length, attempts: logs.length, first_attempts_done: logs.filter(a => a.attempt === 1 && a.status === 'done').length, steps_with_outcomes: new Set(logs.map(a => `${a.goal}:${a.step_id}`)).size, artifacts: { lessons: all.lessons.filter(b => b.status === 'active').length, skills: skills.filter(a => a.status === 'active').length, quarantined: all.lessons.filter(b => b.status === 'quarantined').length + all.artifacts.filter(a => a.status === 'quarantined').length }, instructions: { active: instructions.filter(a => a.status === 'active').length, proposed: instructions.filter(a => a.status === 'proposed').length }, served: served.reduce((sum, b) => sum + (b.served_count ?? 0), 0), used: served.reduce((sum, b) => sum + (b.used_count ?? 0), 0), helpful: served.reduce((sum, b) => sum + b.helpful_count, 0), harmful: served.reduce((sum, b) => sum + b.harmful_count, 0), weak_outcomes: served.reduce((sum, b) => ({ done_first_attempt: sum.done_first_attempt + (b.served_outcomes?.done_first_attempt ?? 0), failed_same_signature: sum.failed_same_signature + (b.served_outcomes?.failed_same_signature ?? 0), other: sum.other + (b.served_outcomes?.other ?? 0) }), { done_first_attempt: 0, failed_same_signature: 0, other: 0 }), repeat_signatures: [...signatureCounts.entries()].filter(([, count]) => count > 1).map(([signature, count]) => ({ signature, count })), distillation: { submitted: distill.length, checked: distill.filter(({ step }) => step.learning_result?.ok).length, acceptance_rate: distill.length ? distill.filter(({ step }) => step.learning_result?.ok).length / distill.length : null, demonstrated: all.artifacts.filter(a => a.label === 'demonstrated').length + all.lessons.filter(b => b.label === 'demonstrated').length, helpfulness_after_20_serves: served.filter(a => (a.served_count ?? 0) >= 20).map(a => ({ id: 'bullet_id' in a ? a.bullet_id : a.id, helpful: a.helpful_count, harmful: a.harmful_count, used: a.used_count ?? 0 })) }, limitations: ['Attempt context retains five entries; pinned citations preserve cited earlier episodes.', 'No provider quality, causal benefit or unavailable external observation is inferred from these counters.'] };
+}
+export async function exportLearning(root, to) {
+    const all = listLearning(root), files = [], unexported = [];
+    const target = resolve(root, to);
+    const emit = (path, text) => { const file = join(target, path); mkdirSync(dirname(file), { recursive: true }); const marker = '<!-- Generated by ace learn export; review changes before committing. -->\n'; const output = text.startsWith('---\n') ? text.replace(/\n---\n/, '\n---\n' + marker) : marker + text; writeFileSync(file, output.endsWith('\n') ? output : output + '\n'); files.push(file); };
+    const grouped = new Map();
+    for (const b of all.lessons.filter(b => b.status === 'active')) {
+        if (!b.evidence_snapshots?.length) {
+            unexported.push(`${b.bullet_id}: no ACE episode citation`);
+            continue;
+        }
+        const key = createHash('sha256').update(JSON.stringify(b.scope)).digest('hex').slice(0, 8);
+        grouped.set(key, [...(grouped.get(key) ?? []), b]);
+    }
+    for (const [key, items] of grouped)
+        emit(`lessons/${key}.md`, '# Learned lessons\n\n' + items.map(b => `## ${b.bullet_id} (${b.label ?? 'checked'})\n\n${b.content}\n\nEpisodes: ${b.evidence_snapshots.map(e => e.id).join(', ')}\n\nScope: ${JSON.stringify(b.scope)}`).join('\n\n'));
+    for (const a of all.artifacts.filter(a => a.status === 'active')) {
+        if (!a.episodes.length) {
+            unexported.push(`${a.id}: no episode citation`);
+            continue;
+        }
+        const name = a.kind === 'skill' ? `skills/${a.id.replace(/^learned\//, '')}/SKILL.md` : a.kind === 'instruction' ? `agents/${a.scope.role}/LEARNED.md` : 'skills/learn-from-work/LEARNED.md';
+        const front = a.kind === 'skill' ? `---\nname: ${JSON.stringify(a.id.replace(/^learned\//, ''))}\ndescription: ${JSON.stringify(a.description ?? 'Use for ' + JSON.stringify(a.scope))}\nscope: ${JSON.stringify(a.scope)}\norigin: learned\nlabel: ${a.label}\nepisodes: ${JSON.stringify(a.episodes)}\n---\n` : '';
+        emit(name, front + (a.kind === 'skill' ? a.body : `# ${a.id}\n\nLabel: ${a.label}\n\nEpisodes: ${a.episodes.join(', ')}\n\n${a.body}`));
+        for (const [name, body] of Object.entries(a.references ?? {}))
+            emit(`skills/${a.id.replace(/^learned\//, '')}/references/${name}`, `Episodes: ${a.episodes.join(', ')}\n\n${body}`);
+        if (a.kind === 'skill')
+            emit(`skills/${a.id.replace(/^learned\//, '')}/references/episodes.md`, a.evidence_snapshots.map(e => { const current = listEpisodes(root).find(item => item.id === e.id) ?? e; return `## ${e.id}\n\n${JSON.stringify(current, null, 2)}`; }).join('\n\n'));
+    }
+    return { files, unexported };
+}
+/** Open the next useful proposal, never a coordinator or automatic approval. */
+export async function advanceLearning(root) {
+    const policy = readLearningPolicy(root);
+    if (!policy.enabled)
+        return;
+    const repo = new GoalRepository(root), catalog = listLearnedArtifacts(root), eligible = catalog.filter(a => a.kind === 'skill' && a.status === 'active' && a.label === 'demonstrated' && a.helpful_count >= 10 && a.harmful_count === 0 && (a.used_goals?.length ?? 0) >= 3);
+    const prior = repo.getPlan('G-learning');
+    if (prior?.steps.some(s => ['planned', 'running', 'blocked'].includes(s.status)))
+        return;
+    const priorBase = (prior?.steps ?? []).filter(s => s.learning_payload && s.learning_result && s.learning_kind !== 'meta').slice(-10);
+    if (!eligible.length && !(priorBase.length === 10 && priorBase.filter(s => s.learning_result.ok).length < 5))
+        return;
+    await withStoreWriteCoordinator(repo.planPath('G-learning'), async () => {
+        let g = repo.getGoal('G-learning'), p = repo.getPlan('G-learning');
+        if (p?.steps.some(s => ['planned', 'running', 'blocked'].includes(s.status)))
+            return;
+        const base = (p?.steps ?? []).filter(s => s.learning_payload && s.learning_result && s.learning_kind !== 'meta').slice(-10), trigger = base.map(s => s.step_id).join(',');
+        const coolingMeta = (p?.steps ?? []).some(s => s.learning_kind === 'meta' && Date.now() - Date.parse(s.learning_opened_at ?? new Date().toISOString()) < policy.distill_cooldown_days * 86400000);
+        const meta = !coolingMeta && base.length === 10 && base.filter(s => s.learning_result.ok).length < 5 && !(p?.steps ?? []).some(s => s.learning_kind === 'meta' && s.learning_trigger === trigger);
+        const candidate = eligible.find(a => !p?.steps.some(s => s.learning_kind === 'graduation' && s.learning_source === a.id));
+        const graduate = !!candidate;
+        if (!meta && !graduate)
+            return;
+        const now = new Date().toISOString();
+        const body = meta ? 'Propose one depth-one revision to the learn-from-work distillation skill. Use outcome.learned.skill with slug learn-from-work. Keep it proposed for operator approval. Never propose a revision about this overlay itself. Inspect the referenced rejected base payloads and acceptance errors.' : 'Propose the role-level rule this demonstrated skill implies, if any. Submit outcome.learned.instruction; it remains proposed until an operator approves it. Inspect the referenced demonstrated skill.';
+        const learning_inputs = meta ? { rejected_steps: base.map(s => s.step_id) } : { artifacts: [candidate.id] };
+        if (!p) {
+            p = createTaskPlan({ task: 'Keep this workspace\'s learned artifacts current', steps: [] });
+            g = { goal_id: 'G-learning', objective: p.task, status: 'executing', executor: 'host', plan_id: p.plan_id, success_contract: { expected_artifacts: [], required_evidence_refs: [], verification_commands: [], gate_ids: [], uncompilable_criteria: [] }, budgets: defaultGoalBudgets(), created_at: now, updated_at: now, tick_count: 0, replan_count: 0, stop_requested: false, escalations: [] };
+        }
+        p = amendTaskPlan(p, { append_steps: [{ role: 'coders', task: body, learning_inputs, learning_scope: meta ? 'distiller-depth-1' : `graduate:${candidate.id}`, learning_kind: meta ? 'meta' : 'graduation', learning_source: meta ? undefined : candidate.id, learning_trigger: meta ? trigger : undefined, learning_opened_at: now }] });
+        if (g.status === 'done' || !g.started_at)
+            g.started_at = now;
+        g.status = 'executing';
+        repo.savePlan('G-learning', p);
+        repo.saveGoal(g);
+    }, { operation_label: 'learning_proposal' });
+}
+//# sourceMappingURL=learning-controls.js.map

package/dist/learning-input-context.d.ts

@@ -0,0 +1,9 @@
+/** Bounded derived context. The existing plans/knowledge retain every full input. */
+import type { TaskStep } from './orchestrator-supervisor.js';
+export interface LearningInputRefs {
+    episodes?: string[];
+    artifacts?: string[];
+    rejected_steps?: string[];
+}
+export declare function renderLearningTask(root: string, goalId: string, step: TaskStep): string;
+//# sourceMappingURL=learning-input-context.d.ts.map

package/dist/learning-input-context.js

@@ -0,0 +1,62 @@
+import { GoalRepository } from './store/repositories/goal-repository.js';
+import { PlaybookRepository } from './store/repositories/playbook-repository.js';
+import { listEpisodes } from './host-learning.js';
+import { listLearnedArtifacts } from './learned-artifacts.js';
+import { utf8Prefix } from './task-plan-context.js';
+const MAX_CONTEXT_BYTES = 8000;
+export function renderLearningTask(root, goalId, step) {
+    if (!step.learning_scope)
+        return step.task;
+    const source = `agent-state/goals/${goalId}.plan.json#${step.step_id}`;
+    const refs = step.learning_inputs;
+    if (!refs) {
+        if (Buffer.byteLength(step.task) <= MAX_CONTEXT_BYTES)
+            return step.task;
+        return `${utf8Prefix(step.task, 7400)}\n[Legacy learning input preview; full retained text is at the source below.]\nFull learning inputs: ${source}.task`;
+    }
+    const rows = [];
+    const episodes = new Map(listEpisodes(root).map(e => [e.id, e]));
+    const groups = new Map();
+    for (const id of refs.episodes ?? []) {
+        const group = episodes.get(id)?.goal_id ?? 'unavailable';
+        groups.set(group, [...(groups.get(group) ?? []), id]);
+    }
+    const selected = [];
+    while (selected.length < 8 && [...groups.values()].some(ids => ids.length)) {
+        for (const ids of groups.values()) {
+            if (ids.length && selected.length < 8)
+                selected.push(ids.shift());
+        }
+    }
+    for (const id of selected) {
+        const e = episodes.get(id);
+        rows.push({ id, text: e ? `${e.status}: ${utf8Prefix(e.failure_excerpt ?? '', 220)}\nSummary: ${utf8Prefix(e.summary, 300)}\nEvidence: ${e.evidence_refs.slice(0, 2).join(', ')}` : 'Source unavailable; retain this identity and inspect the referenced plan or pinned knowledge.' });
+    }
+    const artifacts = new Map([
+        ...new PlaybookRepository(root).listBulletsReadOnly().map(b => [b.bullet_id, b]),
+        ...listLearnedArtifacts(root).map(a => [a.id, a]),
+    ]);
+    for (const id of (refs.artifacts ?? []).slice(0, 4)) {
+        const a = artifacts.get(id);
+        rows.push({ id, text: a ? `${a.status}: ${a.content ?? a.body ?? ''}` : 'Artifact unavailable; preserve its reference.' });
+    }
+    const plan = new GoalRepository(root).getPlan(goalId);
+    for (const id of (refs.rejected_steps ?? []).slice(-10)) {
+        const s = plan?.steps.find(s => s.step_id === id);
+        rows.push({ id: `${goalId}/${id}`, text: s ? `Acceptance errors: ${(s.learning_result?.errors ?? []).join('; ')}\nPayload preview: ${JSON.stringify(s.learning_payload)}` : 'Rejected work record unavailable; inspect its retained source.' });
+    }
+    const count = (refs.episodes?.length ?? 0) + (refs.artifacts?.length ?? 0) + (refs.rejected_steps?.length ?? 0);
+    const footer = `\nInput selection: ${rows.length} of ${count} records previewed. Summaries are excerpts; no source record is deleted.\nFull learning inputs: ${source}.learning_inputs\nRead the referenced goal plans, pinned episodes and knowledge with the host's tools or existing ACE read tools when more detail is needed.`;
+    const prefix = `${step.task}\n\nRetained input previews:\n`;
+    let remaining = MAX_CONTEXT_BYTES - Buffer.byteLength(prefix + footer);
+    const blocks = rows.map((row, index) => {
+        const budget = Math.max(0, Math.floor(remaining / (rows.length - index)));
+        const header = `[${row.id}]\n`;
+        const text = utf8Prefix(row.text, Math.max(0, budget - Buffer.byteLength(header) - 45));
+        const block = `${header}${text}${text.length < row.text.length ? '\n[excerpt; full source referenced below]' : ''}\n`;
+        remaining -= Buffer.byteLength(block);
+        return block;
+    });
+    return prefix + blocks.join('\n') + footer;
+}
+//# sourceMappingURL=learning-input-context.js.map

package/dist/learning-lifecycle.d.ts

@@ -0,0 +1,10 @@
+/** State transition dates on the artifact itself; no separate activity log. */
+export interface LearningLifecycle {
+    status: string;
+    ever_active?: boolean;
+    activated_at?: string;
+    last_active_at?: string;
+    retired_at?: string;
+}
+export declare function learningLifecycle(next: LearningLifecycle, previous: LearningLifecycle | undefined, at: string): Omit<LearningLifecycle, 'status'>;
+//# sourceMappingURL=learning-lifecycle.d.ts.map

package/dist/learning-lifecycle.js

@@ -0,0 +1,11 @@
+export function learningLifecycle(next, previous, at) {
+    const active = next.status === 'active';
+    const ever = active || previous?.status === 'active' ? true : next.ever_active ?? previous?.ever_active ?? (previous ? undefined : false);
+    return {
+        ever_active: ever,
+        activated_at: next.activated_at ?? previous?.activated_at ?? (active && previous?.status !== 'active' ? at : undefined),
+        last_active_at: active || previous?.status === 'active' ? at : next.last_active_at ?? previous?.last_active_at,
+        retired_at: next.status === 'retired' ? next.retired_at ?? (previous?.status !== 'retired' ? at : previous?.retired_at) : undefined,
+    };
+}
+//# sourceMappingURL=learning-lifecycle.js.map

package/dist/learning-overlays.d.ts

@@ -0,0 +1,3 @@
+export declare function approvedInstructionText(root: string, role: string): string;
+export declare function approvedDistillerText(root: string): string;
+//# sourceMappingURL=learning-overlays.d.ts.map

package/dist/learning-overlays.js

@@ -0,0 +1,17 @@
+/** Read approved canonical overlays without importing execution/runtime owners. */
+import { readLearningPolicy } from './learning-policy.js';
+import { readStoreBlobSync } from './store/store-snapshot.js';
+import { decodeLearned } from './learning-records.js';
+export function approvedInstructionText(root, role) {
+    if (!readLearningPolicy(root).enabled)
+        return '';
+    const key = `knowledge/agents/${role}/LEARNED.md`, a = decodeLearned(readStoreBlobSync(root, key) ?? '', key);
+    return a?.kind === 'instruction' && a.status === 'active' && a.scope.role === role ? `\n\n## Learned in this workspace\n[${a.id}] ${a.body}\nEpisodes: ${a.episodes.join(', ')}` : '';
+}
+export function approvedDistillerText(root) {
+    if (!readLearningPolicy(root).enabled)
+        return '';
+    const key = 'knowledge/skills/learn-from-work/LEARNED.md', a = decodeLearned(readStoreBlobSync(root, key) ?? '', key);
+    return a?.kind === 'distiller' && a.status === 'active' ? `\n\n## Approved workspace distillation guidance\n[${a.id}] ${a.body}\nEpisodes: ${a.episodes.join(', ')}` : '';
+}
+//# sourceMappingURL=learning-overlays.js.map

package/dist/learning-policy.d.ts

@@ -0,0 +1,40 @@
+/** The learning block of the existing ACE_WORKFLOW profile. No load events on reads. */
+import { z } from 'zod';
+export declare const DEFAULT_LEARNING_POLICY: {
+    enabled: boolean;
+    distill_min_items: number;
+    distill_min_goals: number;
+    max_open_learning_steps: 1;
+    distill_cooldown_days: number;
+    max_learned_skills: number;
+    serve_max_lessons: number;
+    serve_max_skills: number;
+    serve_max_tokens: number;
+    retire_unhelpful_after_serves: number;
+    instructions_require_approval: true;
+};
+export declare const learningPolicySchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    distill_min_items: z.ZodDefault<z.ZodNumber>;
+    distill_min_goals: z.ZodDefault<z.ZodNumber>;
+    max_open_learning_steps: z.ZodDefault<z.ZodLiteral<1>>;
+    distill_cooldown_days: z.ZodDefault<z.ZodNumber>;
+    max_learned_skills: z.ZodDefault<z.ZodNumber>;
+    serve_max_lessons: z.ZodDefault<z.ZodNumber>;
+    serve_max_skills: z.ZodDefault<z.ZodNumber>;
+    serve_max_tokens: z.ZodDefault<z.ZodNumber>;
+    retire_unhelpful_after_serves: z.ZodDefault<z.ZodNumber>;
+    instructions_require_approval: z.ZodDefault<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+export type LearningPolicy = z.infer<typeof learningPolicySchema> & {
+    issue?: string;
+};
+export declare function readLearningPolicy(root: string): LearningPolicy;
+/** One identity for threshold and re-distillation cooldown decisions. */
+export declare function learningScopeKey(scope: {
+    role?: string;
+    paths?: string[];
+    task_tags?: string[];
+}): string;
+export declare function canonicalLearningScopeKey(value: string): string;
+//# sourceMappingURL=learning-policy.d.ts.map

package/dist/learning-policy.js

@@ -0,0 +1,38 @@
+/** The learning block of the existing ACE_WORKFLOW profile. No load events on reads. */
+import { z } from 'zod';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readStoreBlobSync } from './store/store-snapshot.js';
+import { extractFrontMatter, parseYamlFrontMatter } from './runtime-profile-syntax.js';
+export const DEFAULT_LEARNING_POLICY = { enabled: true, distill_min_items: 3, distill_min_goals: 2, max_open_learning_steps: 1, distill_cooldown_days: 7, max_learned_skills: 30, serve_max_lessons: 3, serve_max_skills: 2, serve_max_tokens: 600, retire_unhelpful_after_serves: 40, instructions_require_approval: true };
+export const learningPolicySchema = z.object({ enabled: z.boolean().default(true), distill_min_items: z.number().int().positive().default(3), distill_min_goals: z.number().int().min(2).default(2), max_open_learning_steps: z.literal(1).default(1), distill_cooldown_days: z.number().positive().default(7), max_learned_skills: z.number().int().min(1).max(30).default(30), serve_max_lessons: z.number().int().min(0).max(3).default(3), serve_max_skills: z.number().int().min(0).max(2).default(2), serve_max_tokens: z.number().int().min(1).max(600).default(600), retire_unhelpful_after_serves: z.number().int().positive().default(40), instructions_require_approval: z.literal(true).default(true) }).strict();
+export function readLearningPolicy(root) {
+    let result = { ...DEFAULT_LEARNING_POLICY };
+    const file = join(root, 'agent-state/ACE_WORKFLOW.md');
+    const raw = readStoreBlobSync(root, 'knowledge/runtime/ACE_WORKFLOW.md') ?? readStoreBlobSync(root, 'state/artifacts/agent-state/ACE_WORKFLOW.md') ?? (existsSync(file) ? readFileSync(file, 'utf8') : undefined);
+    if (raw)
+        try {
+            const front = parseYamlFrontMatter(extractFrontMatter(raw).front_matter);
+            result = learningPolicySchema.parse(front.learning ?? {});
+        }
+        catch (error) {
+            result = { ...result, enabled: false, issue: `Learning profile invalid: ${String(error)}` };
+        }
+    if (process.env.ACE_LEARN === '0')
+        result.enabled = false;
+    return result;
+}
+/** One identity for threshold and re-distillation cooldown decisions. */
+export function learningScopeKey(scope) {
+    const path = (scope.paths?.[0] ?? '').replace(/\\/g, '/').replace(/^\.\//, '').split('/').slice(0, 2).join('/');
+    return `${scope.role ?? ''}|${path}|${scope.task_tags?.[0] ?? ''}`;
+}
+export function canonicalLearningScopeKey(value) {
+    try {
+        if (value.startsWith('{'))
+            return learningScopeKey(JSON.parse(value));
+    }
+    catch { }
+    return value;
+}
+//# sourceMappingURL=learning-policy.js.map

package/dist/learning-records.d.ts

@@ -0,0 +1,35 @@
+import type { Episode } from './host-learning.js';
+import type { PlaybookScope } from './store/repositories/playbook-repository.js';
+export interface LearnedArtifact {
+    id: string;
+    key: string;
+    kind: 'skill' | 'instruction' | 'distiller';
+    status: 'active' | 'quarantined' | 'proposed' | 'retired';
+    label: 'checked' | 'demonstrated';
+    episodes: string[];
+    evidence_snapshots: Episode[];
+    scope: PlaybookScope;
+    body: string;
+    acceptance_errors: string[];
+    checked_at: string;
+    proposal_id: string;
+    helpful_count: number;
+    harmful_count: number;
+    references?: Record<string, string>;
+    retired_reason?: string;
+    ever_active?: boolean;
+    activated_at?: string;
+    last_active_at?: string;
+    retired_at?: string;
+    used_goals?: string[];
+    served_count?: number;
+    used_count?: number;
+    served_outcomes?: {
+        done_first_attempt: number;
+        failed_same_signature: number;
+        other: number;
+    };
+    [key: string]: unknown;
+}
+export declare function decodeLearned(text: string, key: string): LearnedArtifact | undefined;
+//# sourceMappingURL=learning-records.d.ts.map

package/dist/learning-records.js

@@ -0,0 +1,17 @@
+/** Shared learned-knowledge metadata codec; no runtime, helper or goal imports. */
+import { parse } from 'yaml';
+export function decodeLearned(text, key) {
+    try {
+        const m = text.match(/^---\n([\s\S]*?)\n---\n/);
+        if (!m)
+            return;
+        const front = parse(m[1]);
+        if (!front.ace_learning)
+            return;
+        return { ...front.ace_learning, key, body: text.slice(m[0].length), description: front.description };
+    }
+    catch {
+        return;
+    }
+}
+//# sourceMappingURL=learning-records.js.map

package/dist/learning-scorecard.d.ts

@@ -0,0 +1,82 @@
+/** The declared scorecard, derived from retained work and artifact state. */
+import type { TaskStep } from './orchestrator-supervisor.js';
+import type { Episode } from './host-learning.js';
+import type { PlaybookBullet } from './store/repositories/playbook-repository.js';
+import type { LearnedArtifact } from './learning-records.js';
+type Work = {
+    goal: string;
+    step: TaskStep;
+};
+declare const phase: () => {
+    done: number;
+    steps: number;
+    rate: number | null;
+};
+export declare function buildLearningScorecard(steps: Work[], episodes: Episode[], lessons: PlaybookBullet[], artifacts: LearnedArtifact[], now?: number): {
+    active_learned_artifacts: {
+        lessons: number;
+        skills: number;
+        approved_instructions: number;
+    };
+    repeat_failure_rate: {
+        signatures_served: number;
+        signatures_recurred: number;
+        rate: number | null;
+        missing_context_attempts: number;
+        interpretation: string;
+    };
+    first_attempt_success_by_scope: {
+        scope: string;
+        before: ReturnType<typeof phase>;
+        after: ReturnType<typeof phase>;
+        unclassified: ReturnType<typeof phase>;
+        unexposed: ReturnType<typeof phase>;
+    }[];
+    first_attempt_coverage: {
+        missing_first_attempts: number;
+        reconstructed_scopes: number;
+        interpretation: string;
+    };
+    served_helpfulness: {
+        helpful: number;
+        harmful: number;
+        ratio: number | null;
+        counter_scope: string;
+    };
+    distill_acceptance: {
+        checked: number;
+        submitted: number;
+        rate: number | null;
+        demonstrated_current_artifacts: number;
+    };
+    learning_overhead: {
+        learning_steps: number;
+        all_steps: number;
+        ratio: number | null;
+        opportunistic_payload_steps: number;
+        assignments: {
+            episode_id: string;
+            utf8_bytes: number;
+            token_upper_bound: number;
+        }[];
+        max_served_token_upper_bound: number | null;
+        token_method: string;
+    };
+    retirement_health: {
+        window_days: number;
+        retired: number;
+        ever_active: number;
+        ratio: number | null;
+        unknown_history: number;
+    };
+    distillation_steps: {
+        goal_id: string;
+        step_id: string;
+        checked: boolean;
+        items_after_20_serves: number;
+        mean_strong_helpfulness: number | null;
+    }[];
+    coverage: string;
+};
+export {};
+//# sourceMappingURL=learning-scorecard.d.ts.map