@voybio/ace-swarm 2.4.9 → 2.4.10

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

package/dist/learning-scorecard.js

@@ -0,0 +1,86 @@
+import { learningScopeKey } from './learning-policy.js';
+const ratio = (n, d) => d ? n / d : null;
+const phase = () => ({ done: 0, steps: 0, rate: null });
+function match(scope, e) {
+    return (scope.role === e.role ? 2 : 0) +
+        (scope.paths?.some(p => e.paths.some(q => q === p || q.startsWith(p + '/') || p.startsWith(q + '/'))) ? 3 : 0) +
+        (scope.task_tags?.filter(t => e.tags.includes(t)).length ?? 0) +
+        (scope.failure_signature && scope.failure_signature === e.failure_signature ? 5 : 0);
+}
+export function buildLearningScorecard(steps, episodes, lessons, artifacts, now = Date.now()) {
+    const skills = artifacts.filter(a => a.kind === 'skill');
+    const known = [...lessons, ...skills];
+    const byId = new Map(known.map(a => ['bullet_id' in a ? a.bullet_id : a.id, a]));
+    const work = new Map(steps.map(s => [`${s.goal}:${s.step.step_id}`, s.step]));
+    const signatures = new Set(), recurring = new Set();
+    const servedSizes = [];
+    let missingContext = 0;
+    for (const ep of episodes) {
+        const step = work.get(`${ep.goal_id}:${ep.step_id}`);
+        const attempt = ep.attempt ?? Number(ep.id.split(':').at(-1));
+        const fallback = step && step.attempt === attempt && step.served_learning ? {
+            items: step.served_learning.items,
+            rendered_bytes: Buffer.byteLength(step.served_learning.text),
+        } : undefined;
+        const context = ep.served_context ?? fallback;
+        if (!context) {
+            if (ep.served?.length)
+                missingContext++;
+            continue;
+        }
+        if (context.items.length)
+            servedSizes.push({ episode_id: ep.id, utf8_bytes: context.rendered_bytes, token_upper_bound: context.rendered_bytes });
+        for (const item of context.items.filter(i => i.kind === 'lesson' && i.scope.failure_signature)) {
+            signatures.add(item.scope.failure_signature);
+            if (ep.failure_signature === item.scope.failure_signature)
+                recurring.add(item.scope.failure_signature);
+        }
+    }
+    const scopes = new Map();
+    let missingFirst = 0, reconstructedScopes = 0;
+    const episodeMap = new Map(episodes.map(e => [`${e.goal_id}:${e.step_id}:${e.attempt ?? Number(e.id.split(':').at(-1))}`, e]));
+    for (const { goal, step } of steps) {
+        const first = episodeMap.get(`${goal}:${step.step_id}:1`);
+        if (!first) {
+            missingFirst++;
+            continue;
+        }
+        if (!first.scope_snapshot)
+            reconstructedScopes++;
+        const key = learningScopeKey({ role: first.role, paths: first.paths, task_tags: first.tags });
+        const group = scopes.get(key) ?? { scope: key, before: phase(), after: phase(), unclassified: phase(), unexposed: phase() };
+        const relevant = known.filter(a => a.ever_active !== false && (a.status === 'active' || a.ever_active) && match(a.scope, first) >= 3);
+        const dates = relevant.flatMap(a => a.activated_at && Number.isFinite(Date.parse(a.activated_at)) ? [Date.parse(a.activated_at)] : []);
+        const kind = !Number.isFinite(Date.parse(first.at)) ? 'unclassified' : !relevant.length ? 'unexposed' : dates.length !== relevant.length ? 'unclassified' : Date.parse(first.at) < Math.min(...dates) ? 'before' : 'after';
+        group[kind].steps++;
+        if (first.status === 'done')
+            group[kind].done++;
+        for (const p of [group.before, group.after, group.unclassified, group.unexposed])
+            p.rate = ratio(p.done, p.steps);
+        scopes.set(key, group);
+    }
+    const learning = steps.filter(({ step }) => !!step.learning_scope);
+    const submissions = steps.filter(({ step }) => !!step.learning_payload && !!step.learning_result);
+    const checked = submissions.filter(({ step }) => step.learning_result.ok);
+    const helpful = known.reduce((n, a) => n + a.helpful_count, 0), harmful = known.reduce((n, a) => n + a.harmful_count, 0);
+    const since = now - 30 * 86400000;
+    const recentActive = known.filter(a => a.status === 'active' || (a.ever_active && !!a.last_active_at && Date.parse(a.last_active_at) >= since));
+    const retired = recentActive.filter(a => a.status === 'retired' && !!a.retired_at && Date.parse(a.retired_at) >= since);
+    const unknownHistory = known.filter(a => a.status !== 'active' && (a.ever_active === undefined || (a.ever_active && !a.last_active_at)));
+    return {
+        active_learned_artifacts: { lessons: lessons.filter(a => a.status === 'active').length, skills: skills.filter(a => a.status === 'active').length, approved_instructions: artifacts.filter(a => a.kind === 'instruction' && a.status === 'active').length },
+        repeat_failure_rate: { signatures_served: signatures.size, signatures_recurred: recurring.size, rate: ratio(recurring.size, signatures.size), missing_context_attempts: missingContext, interpretation: 'Recurrence after serving is correlational; it is not proof the item was used or caused the outcome.' },
+        first_attempt_success_by_scope: [...scopes.values()],
+        first_attempt_coverage: { missing_first_attempts: missingFirst, reconstructed_scopes: reconstructedScopes, interpretation: 'Before/after uses known activation timestamps and retained first attempts. Unknown activation history stays unclassified.' },
+        served_helpfulness: { helpful, harmful, ratio: ratio(helpful, helpful + harmful), counter_scope: 'Existing artifact counters; legacy producer history is not retrospectively re-attributed.' },
+        distill_acceptance: { checked: checked.length, submitted: submissions.length, rate: ratio(checked.length, submissions.length), demonstrated_current_artifacts: known.filter(a => a.status === 'active' && a.label === 'demonstrated').length },
+        learning_overhead: { learning_steps: learning.length, all_steps: steps.length, ratio: ratio(learning.length, steps.length), opportunistic_payload_steps: submissions.filter(({ step }) => !step.learning_scope).length, assignments: servedSizes, max_served_token_upper_bound: servedSizes.length ? Math.max(...servedSizes.map(s => s.token_upper_bound)) : null, token_method: 'UTF-8 byte count is a conservative upper bound; no provider tokenizer count is claimed.' },
+        retirement_health: { window_days: 30, retired: retired.length, ever_active: recentActive.length, ratio: ratio(retired.length, recentActive.length), unknown_history: unknownHistory.length },
+        distillation_steps: submissions.map(({ goal, step }) => {
+            const eligible = (step.learning_result.ids ?? []).flatMap(id => { const a = byId.get(id); return a && (a.served_count ?? 0) >= 20 && a.helpful_count + a.harmful_count > 0 ? [a.helpful_count / (a.helpful_count + a.harmful_count)] : []; });
+            return { goal_id: goal, step_id: step.step_id, checked: step.learning_result.ok, items_after_20_serves: eligible.length, mean_strong_helpfulness: eligible.length ? eligible.reduce((sum, v) => sum + v, 0) / eligible.length : null };
+        }),
+        coverage: 'Retained plans, pinned episodes and existing artifacts only; missing history and insufficient samples are not treated as success.',
+    };
+}
+//# sourceMappingURL=learning-scorecard.js.map

package/dist/learning-serving.d.ts

@@ -0,0 +1,29 @@
+/** Match learning at assignment time; score only consequence with evidence of use. */
+import type { TaskPlan, TaskStep } from './orchestrator-supervisor.js';
+import type { GoalRecord } from './store/repositories/goal-repository.js';
+import { type PlaybookScope } from './store/repositories/playbook-repository.js';
+import type { StepOutcome } from './host-goal-engine.js';
+export interface ServedLearningItem {
+    id: string;
+    kind: 'lesson' | 'skill' | 'packaged';
+    scope: PlaybookScope;
+    text: string;
+    check?: string;
+    checks?: string[];
+    helpful: number;
+    harmful: number;
+    score: number;
+}
+export interface ServedLearning {
+    text: string;
+    items: ServedLearningItem[];
+}
+export declare function selectLearning(root: string, plan: TaskPlan, step: TaskStep): ServedLearning;
+export declare function recordSkillUse(root: string, ref: {
+    goal_id: string;
+    step_id: string;
+    attempt: number;
+    agent: string;
+}, id: string): Promise<void>;
+export declare function scoreLearning(root: string, goal: GoalRecord, step: TaskStep, outcome: StepOutcome): Promise<void>;
+//# sourceMappingURL=learning-serving.d.ts.map

package/dist/learning-serving.js

@@ -0,0 +1,134 @@
+import { readLearningPolicy } from './learning-policy.js';
+import { GoalRepository } from './store/repositories/goal-repository.js';
+import { PlaybookRepository, withPlaybookTransaction } from './store/repositories/playbook-repository.js';
+import { listLearnedArtifacts, updateLearnedArtifact, ensureLearningStep } from './learned-artifacts.js';
+import { listSkillCatalogEntries } from './skill-catalog.js';
+import { withWorkspaceRoot } from './helpers/workspace-root.js';
+import { withStoreWriteCoordinator } from './store/write-coordinator.js';
+import { failureSignature, learningTaskText } from './experience-reflector.js';
+import { curate } from './playbook-curator.js';
+const tags = ['test', 'build', 'store', 'todo', 'handoff', 'scheduler', 'migration', 'docs', 'release', 'mcp', 'hook', 'schema'];
+export function selectLearning(root, plan, step) {
+    const policy = readLearningPolicy(root);
+    if (!policy.enabled || step.learning_scope)
+        return { text: '', items: [] };
+    const all = [step, ...plan.steps.filter(s => step.depends_on?.includes(s.step_id))];
+    const signatures = new Set(all.flatMap(s => s.attempts_log?.flatMap(a => a.failure_signature ? [a.failure_signature] : []) ?? []));
+    const paths = all.flatMap(s => [...(s.expected_artifacts ?? []).map(a => a.path), ...(s.evidence_refs ?? [])]).map(p => p.replace(/\\/g, '/').replace(/^\.\//, ''));
+    const taskTags = tags.filter(tag => learningTaskText(step).toLowerCase().includes(tag));
+    const score = (scope, helpful, harmful) => (scope.failure_signature && signatures.has(scope.failure_signature) ? 5 : 0) + (scope.paths?.some(p => paths.some(q => q === p || q.startsWith(p + '/') || p.startsWith(q + '/'))) ? 3 : 0) + (scope.role === step.role ? 2 : 0) + (scope.task_tags?.filter(t => taskTags.includes(t)).length ?? 0) - (harmful > helpful ? 3 : 0);
+    const candidates = new PlaybookRepository(root).listBulletsReadOnly({ status: 'active' }).map(b => ({ id: b.bullet_id, kind: 'lesson', scope: b.scope, text: `[${b.bullet_id}] (learned, ${b.label ?? 'checked'}) ${b.content} (helped ${b.helpful_count}×; harmful ${b.harmful_count}×)`, check: b.content.match(/Check:\s*(.+)$/)?.[1]?.trim(), helpful: b.helpful_count, harmful: b.harmful_count, score: score(b.scope, b.helpful_count, b.harmful_count) }));
+    for (const a of listLearnedArtifacts(root).filter(a => a.kind === 'skill' && a.status === 'active'))
+        candidates.push({ id: a.id, kind: 'skill', scope: a.scope, text: `[${a.id}] (${a.label}) ${typeof a.description === 'string' ? a.description : 'Use for ' + JSON.stringify(a.scope)}`, checks: [...(a.body.match(/^## Validation[^\n]*\n([\s\S]*?)(?=^## |$(?![\s\S]))/m)?.[1] ?? '').matchAll(/```bash\s*\n([\s\S]*?)```/g)].map(m => m[1].replace(/\n$/, '')), helpful: a.helpful_count, harmful: a.harmful_count, score: score(a.scope, a.helpful_count, a.harmful_count) });
+    const packaged = withWorkspaceRoot(root, () => listSkillCatalogEntries()).filter(s => s.source === 'package-defaults');
+    for (const skill of packaged) {
+        const scope = { task_tags: tags.filter(t => skill.description.toLowerCase().includes(t)) };
+        candidates.push({ id: skill.name, kind: 'packaged', scope, text: `[${skill.name}] ${skill.description} — load with get_skill_instructions`, helpful: 0, harmful: 0, score: score(scope, 0, 0) });
+    }
+    const picked = [];
+    let text = '';
+    for (const item of candidates.filter(c => c.score >= 3).sort((a, b) => b.score - a.score || b.helpful - a.helpful || a.id.localeCompare(b.id))) {
+        if (picked.filter(i => i.kind === 'lesson').length >= policy.serve_max_lessons && item.kind === 'lesson')
+            continue;
+        if (picked.filter(i => i.kind !== 'lesson').length >= policy.serve_max_skills && item.kind !== 'lesson')
+            continue;
+        const rendered = text + (text ? '\n' : 'Known pitfalls and relevant skills (load when useful):\n') + item.text;
+        if (Buffer.byteLength(rendered, 'utf8') > policy.serve_max_tokens)
+            continue;
+        picked.push(item);
+        text = rendered;
+    }
+    return { text, items: picked };
+}
+export async function recordSkillUse(root, ref, id) {
+    if (!readLearningPolicy(root).enabled)
+        return;
+    const repo = new GoalRepository(root);
+    await withStoreWriteCoordinator(repo.planPath(ref.goal_id), async () => {
+        const p = repo.getPlan(ref.goal_id), s = p?.steps.find(s => s.step_id === ref.step_id);
+        if (!p || !s || s.status !== 'running' || s.attempt !== ref.attempt || s.assignee !== ref.agent || !s.served_learning?.items.some(i => i.id === id && i.kind !== 'lesson'))
+            return;
+        s.loaded_learning ??= [];
+        if (!s.loaded_learning.some(i => i.id === id)) {
+            s.loaded_learning.push({ id, at: new Date().toISOString() });
+            repo.savePlan(ref.goal_id, p);
+        }
+    }, { operation_label: 'served_skill_use' });
+}
+export async function scoreLearning(root, goal, step, outcome) {
+    const policy = readLearningPolicy(root);
+    if (!policy.enabled || !step.served_learning?.items.length)
+        return;
+    const episode = step.attempts_log?.at(-1);
+    if (!episode || episode.attempt !== step.attempt)
+        return;
+    const key = `${goal.goal_id}:${step.step_id}:${episode.attempt}`, runs = episode.observed_runs ?? [], forces = [];
+    for (const served of step.served_learning.items) {
+        if (served.kind === 'packaged')
+            continue;
+        const feedback = step.learning_feedback?.find(f => f.id === served.id);
+        const checkRuns = runs.filter(r => r.attribution === 'Linked' && (r.command === served.check || served.checks?.includes(r.command)));
+        const loaded = step.loaded_learning?.find(i => i.id === served.id);
+        const used = feedback !== undefined || !!loaded || (served.kind === 'lesson' && checkRuns.length > 0);
+        const usedAt = loaded?.at ?? checkRuns[0]?.at;
+        const recurrence = !!served.scope.failure_signature && (runs.some(r => r.attribution === 'Linked' && r.outcome === 'failed' && failureSignature(r.output_tail ?? '') === served.scope.failure_signature && (!usedAt || r.at >= usedAt)) || (!runs.length && episode.status !== 'done' && episode.failure_signature === served.scope.failure_signature));
+        const commands = served.check ? [served.check] : (served.checks ?? []);
+        const passed = episode.status === 'done' && commands.length > 0 && commands.every(command => checkRuns.some(r => r.command === command && r.outcome === 'ok' && r.exit_code === 0));
+        const tag = feedback ? (feedback.helpful ? 'helpful' : 'harmful') : used && recurrence ? 'harmful' : used && passed ? 'helpful' : undefined;
+        const weak = !used ? (episode.status === 'done' && episode.attempt === 1 ? 'done_first_attempt' : recurrence ? 'failed_same_signature' : 'other') : undefined;
+        if (served.kind === 'lesson') {
+            await withPlaybookTransaction(root, async (repo) => {
+                let b = repo.getBullet(served.id);
+                if (!b || b.scored_attempts?.includes(key))
+                    return;
+                if (tag) {
+                    await curate(repo, [{ type: 'TAG', bullet_id: b.bullet_id, tag }], { quarantine_harmful_min: 2, emitEvent: false });
+                    b = repo.getBullet(served.id);
+                }
+                const counts = b.served_outcomes ?? { done_first_attempt: 0, failed_same_signature: 0, other: 0 };
+                if (weak)
+                    counts[weak]++;
+                const next = { ...b, served_count: (b.served_count ?? 0) + 1, used_count: (b.used_count ?? 0) + (used ? 1 : 0), served_outcomes: counts, scored_attempts: [...(b.scored_attempts ?? []), key], used_goals: used ? [...new Set([...(b.used_goals ?? []), goal.goal_id])] : b.used_goals };
+                if (next.served_count >= policy.retire_unhelpful_after_serves && !next.used_count) {
+                    next.status = 'retired';
+                    next.retired_reason = 'Served at least 40 times without evidence of use.';
+                }
+                repo.saveBullet(next);
+                if (tag === 'harmful' && recurrence)
+                    forces.push(b.scope);
+            });
+        }
+        else {
+            const found = listLearnedArtifacts(root).find(a => a.id === served.id && a.kind === 'skill');
+            if (!found)
+                continue;
+            await updateLearnedArtifact(root, found.key, a => {
+                if (a.scored_attempts?.includes(key))
+                    return;
+                a.served_count = (a.served_count ?? 0) + 1;
+                a.used_count = (a.used_count ?? 0) + (used ? 1 : 0);
+                a.scored_attempts = [...(a.scored_attempts ?? []), key];
+                a.used_goals = used ? [...new Set([...(a.used_goals ?? []), goal.goal_id])] : a.used_goals;
+                if (tag === 'helpful')
+                    a.helpful_count++;
+                if (tag === 'harmful')
+                    a.harmful_count++;
+                a.served_outcomes ??= { done_first_attempt: 0, failed_same_signature: 0, other: 0 };
+                if (weak)
+                    a.served_outcomes[weak]++;
+                if (a.harmful_count >= 2 && a.harmful_count > a.helpful_count)
+                    a.status = 'quarantined';
+                if (a.served_count >= policy.retire_unhelpful_after_serves && !a.used_count) {
+                    a.status = 'retired';
+                    a.retired_reason = 'Served at least 40 times without evidence of use.';
+                }
+                if (tag === 'harmful' && recurrence)
+                    forces.push(a.scope);
+                return a;
+            });
+        }
+    }
+    for (const scope of forces)
+        await ensureLearningStep(root, { scope, reason: 'An applied artifact\'s own failure recurred. Compare the served attempts and repair the advice.' });
+}
+//# sourceMappingURL=learning-serving.js.map

package/dist/linked-work.d.ts

@@ -0,0 +1,9 @@
+import type { TodoNode } from './store/repositories/todo-repository.js';
+import type { TaskPlan } from './orchestrator-supervisor.js';
+export declare function deriveLinkedTodo<T extends TodoNode>(todo: T, root: string, snapshot?: {
+    goal: {
+        goal_id: string;
+    };
+    plan: TaskPlan;
+}): T;
+//# sourceMappingURL=linked-work.d.ts.map

package/dist/linked-work.js

@@ -0,0 +1,28 @@
+/** Read-only derivation: a linked todo is a view of its existing goal step. */
+import { GoalRepository } from './store/repositories/goal-repository.js';
+export function deriveLinkedTodo(todo, root, snapshot) {
+    const repo = new GoalRepository(root);
+    let ref = todo.step_ref;
+    if (!ref) {
+        const current = snapshot?.plan.steps.find(s => s.todo_id === todo.id);
+        if (current)
+            ref = { goal_id: snapshot.goal.goal_id, step_id: current.step_id };
+        else
+            for (const goal of repo.listGoals()) {
+                const linked = repo.getPlan(goal.goal_id)?.steps.find(s => s.todo_id === todo.id);
+                if (linked) {
+                    ref = { goal_id: goal.goal_id, step_id: linked.step_id };
+                    break;
+                }
+            }
+    }
+    if (!ref)
+        return todo;
+    const plan = snapshot?.goal.goal_id === ref.goal_id ? snapshot.plan : repo.getPlan(ref.goal_id);
+    const step = plan?.steps.find(s => s.step_id === ref.step_id);
+    if (!step)
+        return todo;
+    const status = step.status === 'running' ? 'in_progress' : step.status === 'done' || step.status === 'skipped' ? 'done' : step.status === 'failed' || step.status === 'blocked' ? 'blocked' : 'pending';
+    return { ...todo, step_ref: ref, status, ...(step.assignee ? { assigned_to: step.assignee } : {}) };
+}
+//# sourceMappingURL=linked-work.js.map

package/dist/local-model-runtime.js

@@ -159,7 +159,7 @@ export async function runLocalModelTask(options) {
         requested_tier: options.tier,
         requested_model_class: options.modelClass,
     });
-    const maxTurns = options.maxTurns ?? defaultTurnsForPolicy(role, policy);
+    const maxTurns = options.maxTurns ?? (runtime.executionEngine === 'hermes_local' ? defaultTurnsForPolicy(role, policy) : 0);
     const requestedToolScope = options.toolScope ?? defaultToolScopeForPolicy(role, policy);
     const filteredToolCatalog = buildFilteredToolCatalog(policy.model_class, requestedToolScope, {
         mutation_lane: policy.mutation_lane,