@vascend/talos 0.1.0

package/dist/vascend/team-session.js

@@ -0,0 +1,142 @@
+// Squadre VIVE: chi sta lavorando adesso, per sessione.
+//
+// Il problema che risolve. Finora ingaggiare dei collaboratori voleva dire
+// restare fermi dentro la tool call finche' l'ultimo non aveva finito: l'agente
+// principale era parcheggiato, e "farsi dare una mano DURANTE la conversazione"
+// era inesprimibile — non per una scelta di prodotto, per come era scritto il
+// codice. Qui la promessa del lavoro viene messa da parte invece che attesa, e
+// il turno continua: si puo' parlare con chi lavora, correggerlo, e raccogliere
+// i risultati quando ha senso.
+//
+// Registro di processo, non persistenza: una squadra vive quanto il processo
+// che la esegue. Cio' che deve sopravvivere alla sessione sta nel piano a rami
+// e nella memoria, non qui.
+import { setTimeout as delay } from "node:timers/promises";
+import { saveTeamHandoff } from "./team-handoff.js";
+const teams = new Map();
+function key(sessionId, teamId) {
+    return `${sessionId}\u0000${teamId}`;
+}
+function snapshot(team) {
+    return {
+        revision: team.revision,
+        ...(team.persistenceError ? { persistenceError: team.persistenceError } : {}),
+        id: team.id,
+        sessionId: team.sessionId,
+        members: team.members,
+        startedAt: team.startedAt,
+        work: team.work,
+        done: team.done,
+        report: team.report,
+        failed: team.failed,
+    };
+}
+// Registra una squadra appena avviata. La promessa NON viene attesa qui: le si
+// attacca solo come finira', cosi' il registro sa dire "hanno finito" senza che
+// nessuno sia rimasto ad aspettare.
+export function registerTeam(input) {
+    const team = {
+        sessionDir: input.sessionDir,
+        revision: 0,
+        id: input.id,
+        sessionId: input.sessionId,
+        members: input.members.map((member) => ({ ...member, status: member.status ?? "queued" })),
+        startedAt: input.at,
+        work: input.work,
+        done: false,
+        report: "",
+        failed: false,
+    };
+    teams.set(key(input.sessionId, input.id), team);
+    checkpoint(team);
+    void input.work.then((report) => {
+        team.done = true;
+        team.report = String(report ?? "");
+        team.failed = team.members.some((member) => member.status === "failed");
+        team.members = team.members.map((member) => ({ ...member,
+            status: member.status === "failed" ? "failed" : "completed" }));
+        checkpoint(team);
+    }, (error) => {
+        team.done = true;
+        team.failed = true;
+        team.report = error instanceof Error ? error.message : String(error);
+        team.members = team.members.map((member) => member.status === "completed" ? member
+            : { ...member, status: "failed", error: team.report });
+        checkpoint(team);
+    });
+    return snapshot(team);
+}
+// La squadra piu' recente di questa sessione. E' quella con cui si parla quando
+// non se ne indica una: nella pratica ce n'e' una sola per volta.
+export function teamForSession(sessionId) {
+    let ultima = null;
+    for (const team of teams.values()) {
+        if (team.sessionId !== sessionId)
+            continue;
+        if (!ultima || team.startedAt >= ultima.startedAt)
+            ultima = team;
+    }
+    return ultima ? snapshot(ultima) : null;
+}
+export function teamById(sessionId, teamId) {
+    const team = teams.get(key(sessionId, teamId));
+    return team ? snapshot(team) : null;
+}
+// Quelli che stanno ancora lavorando, per dirlo a chi chiede.
+export function pendingMembers(team) {
+    return team.done ? [] : team.members.filter((member) => member.status !== "completed" && member.status !== "failed").map((m) => m.slug);
+}
+export function teamByKingdom(teamId) {
+    for (const team of teams.values())
+        if (team.id === teamId)
+            return snapshot(team);
+    return null;
+}
+export function updateTeamMember(teamId, slug, patch) {
+    for (const team of teams.values()) {
+        if (team.id !== teamId)
+            continue;
+        team.members = team.members.map((member) => member.slug === slug ? { ...member, ...patch } : member);
+        team.failed = team.members.some((member) => member.status === "failed");
+        checkpoint(team);
+    }
+}
+function checkpoint(team) {
+    if (!team.sessionDir) {
+        team.revision++;
+        return;
+    }
+    try {
+        const saved = saveTeamHandoff(team.sessionDir, { id: team.id, sessionId: team.sessionId,
+            members: team.members, done: team.done, failed: team.failed, report: team.report });
+        team.revision = saved.revision;
+        delete team.persistenceError;
+    }
+    catch (error) {
+        team.persistenceError = error instanceof Error ? error.message : String(error);
+    }
+}
+export async function waitForTeamChange(team, signal, interrupted) {
+    const signature = (current) => JSON.stringify(current.members.map((member) => [member.slug, member.status]));
+    const before = signature(team);
+    const deadline = Date.now() + 30_000;
+    while (!signal.aborted && !interrupted() && Date.now() < deadline) {
+        const current = teamById(team.sessionId, team.id);
+        if (!current || current.done || signature(current) !== before)
+            return;
+        try {
+            await delay(100, undefined, { signal });
+        }
+        catch {
+            return;
+        }
+    }
+}
+export function forgetTeam(sessionId, teamId) {
+    teams.delete(key(sessionId, teamId));
+}
+// Solo per i test: il registro e' di processo e non deve travasare da un test
+// all'altro.
+export function __resetTeams() {
+    teams.clear();
+}

package/dist/vascend/test-failure-memory.d.ts

@@ -0,0 +1,76 @@
+import { type RoomRecord } from "./room-memory.js";
+export type FailureStatus = "open" | "fixed" | "superseded";
+export type TestEventType = "test.failed" | "test.fixed" | "test.superseded";
+export interface TestFailureInput {
+    readonly file: string;
+    readonly testName?: string;
+    readonly command?: string;
+    readonly error: string;
+    readonly stack?: string;
+    readonly suspectedCause?: string;
+    readonly fixedBy?: string;
+}
+export interface FailureRecord {
+    readonly id: string;
+    readonly file: string;
+    readonly testName?: string;
+    readonly command?: string;
+    readonly error: string;
+    readonly stack?: string;
+    readonly suspectedCause?: string;
+    readonly fixedBy?: string;
+    readonly status: FailureStatus;
+    readonly openedAt: number;
+    readonly updatedAt: number;
+}
+export interface TestFailureEvent {
+    readonly type: TestEventType;
+    readonly id: string;
+    readonly file: string;
+    readonly testName?: string;
+    readonly command?: string;
+    readonly error: string;
+    readonly stack?: string;
+    readonly suspectedCause?: string;
+    readonly fixedBy?: string;
+    readonly status: FailureStatus;
+    readonly at: number;
+}
+export interface TestEventSink {
+    emit(event: TestFailureEvent): void;
+}
+export declare function failureId(file: string, testName?: string, command?: string): string;
+export declare function formatTestFailureRecord(room: string, event: TestFailureEvent): RoomRecord;
+export declare class RoomMemoryTestSink implements TestEventSink {
+    private readonly sessionDir;
+    private readonly storeId;
+    private readonly namespace;
+    private constructor();
+    static open(sessionDir: string, storeId: string, namespace?: string): RoomMemoryTestSink;
+    emit(event: TestFailureEvent): void;
+}
+export declare class InMemoryTestSink implements TestEventSink {
+    private readonly events;
+    emit(event: TestFailureEvent): void;
+    all(): readonly TestFailureEvent[];
+    ofType(type: TestEventType): readonly TestFailureEvent[];
+}
+export declare class TestFailureMemory {
+    private readonly file;
+    private readonly sink;
+    private events;
+    private constructor();
+    static open(sessionDir: string, storeId: string, sink?: TestEventSink): TestFailureMemory;
+    private load;
+    private writeEvent;
+    record(input: TestFailureInput, at?: number): FailureRecord;
+    markFixed(id: string, fixedBy?: string, at?: number): FailureRecord | undefined;
+    markSuperseded(id: string, at?: number): FailureRecord | undefined;
+    allEvents(): readonly TestFailureEvent[];
+    records(): readonly FailureRecord[];
+    byId(id: string): FailureRecord | undefined;
+    byFile(file: string): readonly FailureRecord[];
+    byTestName(testName: string): readonly FailureRecord[];
+    open(): readonly FailureRecord[];
+    query(file: string, testName?: string): readonly FailureRecord[];
+}

package/dist/vascend/test-failure-memory.js

@@ -0,0 +1,354 @@
+// Dominio EVENTI TEST FALLITI: TestFailureMemory salva ogni fallimento di
+// test o typecheck come evento del dominio "test.*" e lo rende richiamabile
+// via il tool `recall`, cosi' l'agente non ripete fix gia' tentati e falliti.
+//
+//   test.failed      — un test/typecheck e' fallito (apertura: status=open)
+//   test.fixed       — il fallimento e' stato risolto (status=fixed, fixedBy)
+//   test.superseded  — il fallimento e' stato rimpiazzato da uno piu' recente
+//                      o non e' piu' rilevante (status=superseded)
+//
+// Ogni fallimento e' un FailureRecord con id stabile (derivato da file +
+// testName + command). Il ciclo di vita e' open -> fixed | superseded.
+// Lo store e' un log append-only (JSONL): lo stato corrente di ogni fallimento
+// si DERIVA riducendo gli eventi in ordine (event sourcing leggero, coerente
+// con MemoryStore). Ogni evento e' anche indicizzato come stanza Danilov
+// (RoomRecord livello 0) cosi' una query recall "questo test e' gia' fallito?"
+// trova causa sospetta e fix gia' tentato.
+//
+// Filosofia del progetto: zero dipendenze a runtime, immutabilita', il sink
+// recall e' una primitiva iniettabile (non hardcoded), nessun throw che possa
+// rompere la pipeline di test che alimenta la memoria.
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join } from "node:path";
+import { RoomMemory } from "./room-memory.js";
+import { withLockSync } from "./file-lock.js";
+// Id STABILE di un fallimento: stessa coppia (file, testName, command) ->
+// stesso id, cosi' un re-run dello stesso fallimento lo riconosce e non crea
+// duplicati. Hash corto, deterministico, indipendente dal messaggio d'errore
+// (che puo' variare leggermente tra run).
+export function failureId(file, testName, command) {
+    const key = `${norm(file)}\u0000${norm(testName)}\u0000${norm(command)}`;
+    return "tf_" + createHash("sha1").update(key).digest("hex").slice(0, 12);
+}
+function norm(v) {
+    return (v ?? "").trim().toLowerCase();
+}
+// Etichetta umana breve del tipo evento (per titolo/azione Danilov).
+function actionLabel(type) {
+    switch (type) {
+        case "test.failed": return "fallito";
+        case "test.fixed": return "risolto";
+        case "test.superseded": return "superato";
+    }
+}
+// Tokenizza valori in termini per l'indice recall: token interi + sotto-parole
+// (split su -, ., _, /, spazi) cosi' un fallimento e' richiamabile cercando
+// anche una sola parola del nome file o del test.
+function terms(...values) {
+    const out = new Set();
+    for (const v of values) {
+        if (!v)
+            continue;
+        for (const whole of v.toLowerCase().match(/[a-z0-9_./-]{2,}/g) ?? []) {
+            const t = whole.replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, "");
+            if (t.length >= 2)
+                out.add(t);
+            for (const part of whole.split(/[-._/\s]+/)) {
+                if (part.length >= 2)
+                    out.add(part);
+            }
+        }
+    }
+    return [...out].filter((t) => t.length >= 2);
+}
+function escapeValue(value) {
+    return value.replace(/\s+/g, " ").trim().replace(/"/g, "'");
+}
+// Costruisce il RoomRecord Danilov di un evento test (stanza livello 0).
+// `room` e' l'id assegnato dallo store (namespaced, es. "testfail-R1"). Il body
+// e' un blocco INDICE/DEFINIZIONI/RELAZIONI/OUTPUT, coerente con la memoria,
+// cosi' la ricerca BM25 di RoomMemory lo trova per termini.
+export function formatTestFailureRecord(room, event) {
+    const action = actionLabel(event.type);
+    const where = event.testName ? `${event.file} :: ${event.testName}` : event.file;
+    const title = `${event.type}: ${where}`;
+    const indexTerms = [
+        ...terms(event.file, event.testName, event.command),
+        ...terms(event.error, event.suspectedCause, event.fixedBy),
+        "test",
+        "failure",
+        "fallimento",
+        action,
+        event.status,
+    ];
+    const uniqTerms = [...new Set(indexTerms)].filter(Boolean).slice(0, 24);
+    const def = [
+        `@evento[${room}]: type=${event.type}, action=${action}, status=${event.status}, at=${event.at}`,
+        `@fallimento[${event.id}]: file="${escapeValue(event.file)}"${event.testName ? `, test="${escapeValue(event.testName)}"` : ""}${event.command ? `, command="${escapeValue(event.command)}"` : ""}`,
+        `@errore[${event.id}]: "${escapeValue(event.error).slice(0, 600)}"`,
+    ];
+    if (event.stack) {
+        def.push(`@stack[${event.id}]: "${escapeValue(event.stack).slice(0, 800)}"`);
+    }
+    if (event.suspectedCause) {
+        def.push(`@causa_sospetta[${event.id}]: "${escapeValue(event.suspectedCause).slice(0, 400)}"`);
+    }
+    if (event.fixedBy) {
+        def.push(`@risolto_da[${event.id}]: "${escapeValue(event.fixedBy).slice(0, 400)}"`);
+    }
+    const rel = `@R: ${room} -> ${event.type} -> fallimento:${event.id} -> status:${event.status}  [ ${action} ]`;
+    const lesson = event.type === "test.failed"
+        ? `fix gia' tentato registrato; PRIMA di ritentare consulta causa sospetta e fixedBy per non ripetere un fix fallito`
+        : event.type === "test.fixed"
+            ? `risolto da: ${escapeValue(event.fixedBy ?? "(non indicato)")}`
+            : `superato da un fallimento piu' recente o non piu' rilevante`;
+    const body = `INDICE
+${uniqTerms.map((t, i) => `${i + 1} = ${t}`).join("\n")}
+
+DEFINIZIONI
+${def.join("\n")}
+
+RELAZIONI
+${rel}
+
+OUTPUT: ${where} ${action} (status=${event.status}); ${lesson}; richiamabile via recall.`;
+    return {
+        room,
+        level: 0,
+        title: escapeValue(title).slice(0, 160),
+        terms: uniqTerms,
+        body,
+        children: [],
+        parent: null,
+        createdAt: event.at,
+    };
+}
+// Sink concreto su RoomMemory: indicizza ogni evento test come stanza
+// richiamabile via recall. Usa il namespace "testfail" per gli id
+// (testfail-R1, ...) cosi' gli eventi test non collidono con le stanze
+// conversazionali e sono filtrabili. Non lancia mai (best-effort).
+export class RoomMemoryTestSink {
+    sessionDir;
+    storeId;
+    namespace;
+    constructor(sessionDir, storeId, namespace) {
+        this.sessionDir = sessionDir;
+        this.storeId = storeId;
+        this.namespace = namespace;
+    }
+    // `storeId` e' l'id dello store stanze (sessionId o id regno in Kingdoms).
+    static open(sessionDir, storeId, namespace = "testfail") {
+        return new RoomMemoryTestSink(sessionDir, storeId, namespace);
+    }
+    emit(event) {
+        try {
+            const mem = RoomMemory.open(this.sessionDir, this.storeId);
+            // Scrittura sicura cross-processo: id monotono su vista fresca.
+            mem.appendRoomNamespaced((room) => formatTestFailureRecord(room, event), this.namespace);
+        }
+        catch {
+            // L'indicizzazione recall e' best-effort: non deve rompere la pipeline.
+        }
+    }
+}
+// Sink in-memory per i test/uso programmatico: tiene gli eventi e li espone.
+export class InMemoryTestSink {
+    events = [];
+    emit(event) {
+        this.events.push(event);
+    }
+    all() {
+        return this.events;
+    }
+    ofType(type) {
+        return this.events.filter((e) => e.type === type);
+    }
+}
+// Riduce un evento sul record corrente di un fallimento (event sourcing).
+function reduceEvent(prev, event) {
+    if (!prev) {
+        return {
+            id: event.id,
+            file: event.file,
+            testName: event.testName,
+            command: event.command,
+            error: event.error,
+            stack: event.stack,
+            suspectedCause: event.suspectedCause,
+            fixedBy: event.fixedBy,
+            status: event.status,
+            openedAt: event.at,
+            updatedAt: event.at,
+        };
+    }
+    return {
+        ...prev,
+        // Un nuovo test.failed riapre/aggiorna error e stack; gli altri eventi
+        // preservano i dati di apertura ma aggiornano lo stato e le annotazioni.
+        error: event.type === "test.failed" ? event.error : prev.error,
+        stack: event.type === "test.failed" ? (event.stack ?? prev.stack) : prev.stack,
+        suspectedCause: event.suspectedCause ?? prev.suspectedCause,
+        fixedBy: event.fixedBy ?? prev.fixedBy,
+        status: event.status,
+        updatedAt: event.at,
+    };
+}
+// TestFailureMemory: registro append-only dei fallimenti di test/typecheck.
+// Persiste gli eventi in <sessionDir>/<storeId>.test-failures.jsonl e deriva
+// lo stato corrente di ogni fallimento riducendo gli eventi in ordine. Emette
+// ogni evento anche al sink recall (RoomMemory) per renderlo richiamabile.
+export class TestFailureMemory {
+    file;
+    sink;
+    events = [];
+    constructor(file, sink) {
+        this.file = file;
+        this.sink = sink;
+    }
+    // Apre/crea il registro. `sink` di default indicizza su RoomMemory (recall);
+    // passare un InMemoryTestSink per test/uso programmatico senza side-effect.
+    static open(sessionDir, storeId, sink) {
+        const file = join(sessionDir, `${storeId}.test-failures.jsonl`);
+        const effectiveSink = sink ?? RoomMemoryTestSink.open(sessionDir, storeId);
+        const mem = new TestFailureMemory(file, effectiveSink);
+        mem.load();
+        return mem;
+    }
+    load() {
+        this.events = [];
+        if (!existsSync(this.file))
+            return;
+        const raw = readFileSync(this.file, "utf8");
+        for (const line of raw.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                this.events.push(JSON.parse(line));
+            }
+            catch {
+                // riga corrotta: ignorata
+            }
+        }
+    }
+    writeEvent(event) {
+        this.events.push(event);
+        mkdirSync(dirname(this.file), { recursive: true });
+        withLockSync(this.file, () => {
+            appendFileSync(this.file, JSON.stringify(event) + "\n", "utf8");
+        });
+        this.sink.emit(event);
+    }
+    // Registra un fallimento di test/typecheck. Apre (o riapre) il fallimento
+    // con status=open e ritorna il record corrente. Id stabile su (file,
+    // testName, command): un re-run dello stesso fallimento non duplica l'id.
+    record(input, at = Date.now()) {
+        const id = failureId(input.file, input.testName, input.command);
+        const event = {
+            type: "test.failed",
+            id,
+            file: input.file,
+            testName: input.testName,
+            command: input.command,
+            error: input.error,
+            stack: input.stack,
+            suspectedCause: input.suspectedCause,
+            fixedBy: input.fixedBy,
+            status: "open",
+            at,
+        };
+        this.writeEvent(event);
+        return this.byId(id);
+    }
+    // Segna un fallimento come risolto (status=fixed). `fixedBy` documenta il fix
+    // applicato (cosi' un recall futuro sa cosa ha funzionato). Ritorna il record
+    // aggiornato, o undefined se l'id non esiste.
+    markFixed(id, fixedBy, at = Date.now()) {
+        const cur = this.byId(id);
+        if (!cur)
+            return undefined;
+        const event = {
+            ...toEventBase(cur),
+            type: "test.fixed",
+            fixedBy: fixedBy ?? cur.fixedBy,
+            status: "fixed",
+            at,
+        };
+        this.writeEvent(event);
+        return this.byId(id);
+    }
+    // Segna un fallimento come superato (status=superseded): non piu' rilevante
+    // o rimpiazzato da uno piu' recente. Ritorna il record aggiornato o undefined.
+    markSuperseded(id, at = Date.now()) {
+        const cur = this.byId(id);
+        if (!cur)
+            return undefined;
+        const event = {
+            ...toEventBase(cur),
+            type: "test.superseded",
+            status: "superseded",
+            at,
+        };
+        this.writeEvent(event);
+        return this.byId(id);
+    }
+    // Tutti gli eventi grezzi, in ordine cronologico (log append-only).
+    allEvents() {
+        return this.events;
+    }
+    // Vista derivata: lo stato corrente di OGNI fallimento noto (uno per id),
+    // ordinato per ultimo aggiornamento (piu' recente prima).
+    records() {
+        const byId = new Map();
+        for (const event of this.events) {
+            byId.set(event.id, reduceEvent(byId.get(event.id), event));
+        }
+        return [...byId.values()].sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    // Record corrente di un fallimento per id (undefined se sconosciuto).
+    byId(id) {
+        let acc;
+        for (const event of this.events) {
+            if (event.id === id)
+                acc = reduceEvent(acc, event);
+        }
+        return acc;
+    }
+    // Fallimenti per file (match esatto, normalizzato). Utile per "questo file
+    // ha gia' rotto dei test?".
+    byFile(file) {
+        const key = norm(file);
+        return this.records().filter((r) => norm(r.file) === key);
+    }
+    // Fallimenti per nome del test (match esatto, normalizzato).
+    byTestName(testName) {
+        const key = norm(testName);
+        return this.records().filter((r) => norm(r.testName) === key);
+    }
+    // I fallimenti ancora APERTI (status=open): quelli su cui c'e' un fix da
+    // trovare o da non ripetere.
+    open() {
+        return this.records().filter((r) => r.status === "open");
+    }
+    // "Questo test/file e' gia' fallito prima?" — match per file (+ testName se
+    // dato), per evitare di ritentare un fix gia' fallito. Ritorna i record che
+    // matchano, piu' recente prima.
+    query(file, testName) {
+        const fkey = norm(file);
+        const tkey = testName ? norm(testName) : undefined;
+        return this.records().filter((r) => norm(r.file) === fkey && (tkey === undefined || norm(r.testName) === tkey));
+    }
+}
+// Estrae la base evento dai dati correnti di un record (per markFixed/Superseded).
+function toEventBase(r) {
+    return {
+        id: r.id,
+        file: r.file,
+        testName: r.testName,
+        command: r.command,
+        error: r.error,
+        stack: r.stack,
+        suspectedCause: r.suspectedCause,
+        fixedBy: r.fixedBy,
+    };
+}

package/dist/vascend/token-market.d.ts

@@ -0,0 +1,42 @@
+import { type BestExpansionOptions } from "./expansion-levels.js";
+import { type ContextCapsule, type ExpansionLevel } from "./context-capsule.js";
+export interface CapsuleBid {
+    readonly id: string;
+    readonly relevance: number;
+    readonly dependency: number;
+    readonly riskReduction: number;
+    readonly novelty: number;
+    readonly trust: number;
+    readonly tokenCost: number;
+    readonly bid: number;
+    readonly desiredLevel: ExpansionLevel;
+}
+export interface MarketContext {
+    readonly relevance?: ReadonlyMap<string, number>;
+    readonly novelty?: ReadonlyMap<string, number>;
+    readonly tokenBudget: number;
+    readonly expansion?: BestExpansionOptions;
+}
+export declare function computeBid(c: ContextCapsule, ctx: MarketContext): CapsuleBid;
+export interface MarketAllocation {
+    readonly capsule: ContextCapsule;
+    readonly bid: CapsuleBid;
+    readonly level: ExpansionLevel | "drop";
+    readonly tokensUsed: number;
+}
+export interface MarketResult {
+    readonly admitted: readonly MarketAllocation[];
+    readonly dropped: readonly MarketAllocation[];
+    readonly tokensUsed: number;
+    readonly tokenBudget: number;
+}
+export declare function runTokenMarket(capsules: readonly ContextCapsule[], ctx: MarketContext): MarketResult;
+export interface ZonePricingInput {
+    readonly congestion: number;
+    readonly stalePenalty: number;
+    readonly missionNeed: number;
+}
+export declare function zonePrice(input: ZonePricingInput): number;
+export declare function formatMarketResult(r: MarketResult, opts?: {
+    readonly top?: number;
+}): string;