@vascend/talos 0.1.0

package/dist/vascend/mandate.d.ts

@@ -0,0 +1,33 @@
+import type { CastlePlan, PlanTaskStatus, VascendPlanStore } from "./plan-store.js";
+export interface MandateRoom {
+    readonly ref: string;
+    readonly title: string;
+    readonly status: PlanTaskStatus;
+    readonly weight?: number;
+    readonly files?: readonly string[];
+    readonly skills?: readonly string[];
+}
+export interface CastleMandate {
+    readonly castle: string;
+    readonly title: string;
+    readonly rooms: readonly MandateRoom[];
+    readonly closed: readonly string[];
+    readonly after?: string;
+    readonly partial: boolean;
+    readonly skills?: readonly string[];
+}
+/** Mandato ricavato da un castello del piano. Null se non resta nulla da fare. */
+export declare function mandateFromCastle(castle: CastlePlan, refs?: readonly string[]): CastleMandate | null;
+/** Mandato per slug, letto dal piano della sessione. Null se il castello non c'e'. */
+export declare function mandateFor(store: VascendPlanStore, slug: string, refs?: readonly string[]): CastleMandate | null;
+/**
+ * Obiettivo derivato dal piano, per quando il collaboratore viene assegnato a un
+ * castello senza che nessuno riscriva a mano cosa deve fare.
+ */
+export declare function mandateGoal(mandate: CastleMandate): string;
+/**
+ * Blocco Danilov del mandato. Va PRIMA del marcatore OBIETTIVO_CASTELLO, cosi'
+ * chi legge il titolo della stanza continua a trovare il task vero dopo il
+ * marcatore e non questo preambolo.
+ */
+export declare function formatMandate(mandate: CastleMandate, canDelegate: boolean): string;

package/dist/vascend/mandate.js

@@ -0,0 +1,107 @@
+const OPEN_STATES = ["pending", "running", "failed"];
+function toRoom(task) {
+    return {
+        ref: task.id,
+        title: task.title,
+        status: task.status,
+        ...(task.weight ? { weight: task.weight } : {}),
+        ...(task.files?.length ? { files: [...task.files] } : {}),
+        ...(task.skills?.length ? { skills: [...task.skills] } : {}),
+    };
+}
+// Accetta il ref ("T01", case-insensitive) o il numero di bit ("0"), come i tool
+// del piano: il modello non deve indovinare quale delle due forme usare.
+function selects(refs, task) {
+    const wanted = refs.map((r) => r.trim().toLowerCase()).filter(Boolean);
+    return wanted.includes(task.id.toLowerCase()) || wanted.includes(String(task.bit));
+}
+/** Mandato ricavato da un castello del piano. Null se non resta nulla da fare. */
+export function mandateFromCastle(castle, refs) {
+    const wanted = (refs ?? []).map((r) => String(r).trim()).filter(Boolean);
+    const chosen = wanted.length ? castle.tasks.filter((t) => selects(wanted, t)) : castle.tasks;
+    const rooms = chosen.filter((t) => OPEN_STATES.includes(t.status)).map(toRoom);
+    if (!rooms.length)
+        return null;
+    const closed = chosen.filter((t) => t.status === "completed").map((t) => t.id);
+    return {
+        castle: castle.slug,
+        title: castle.title,
+        rooms,
+        closed,
+        ...(castle.after ? { after: castle.after } : {}),
+        partial: wanted.length > 0 && chosen.length < castle.tasks.length,
+        ...(castle.skills?.length ? { skills: [...castle.skills] } : {}),
+    };
+}
+/** Mandato per slug, letto dal piano della sessione. Null se il castello non c'e'. */
+export function mandateFor(store, slug, refs) {
+    const castle = store.castle(slug);
+    return castle ? mandateFromCastle(castle, refs) : null;
+}
+/**
+ * Obiettivo derivato dal piano, per quando il collaboratore viene assegnato a un
+ * castello senza che nessuno riscriva a mano cosa deve fare.
+ */
+export function mandateGoal(mandate) {
+    const rooms = mandate.rooms.map((r) => `${r.ref} ${r.title}`).join("; ");
+    return `Porta a termine il gruppo "${mandate.title}" del piano: ${rooms}.`;
+}
+function roomLine(room) {
+    const parts = [`  ${room.ref}`];
+    if (room.weight)
+        parts.push(`[w${room.weight}]`);
+    parts.push(room.title);
+    if (room.status === "running")
+        parts.push("· gia' aperta");
+    if (room.status === "failed")
+        parts.push("· fallita, da riprendere");
+    if (room.files?.length)
+        parts.push(`· file: ${room.files.join(", ")}`);
+    if (room.skills?.length)
+        parts.push(`· skill: ${room.skills.join(", ")}`);
+    return parts.join(" ");
+}
+/**
+ * Blocco Danilov del mandato. Va PRIMA del marcatore OBIETTIVO_CASTELLO, cosi'
+ * chi legge il titolo della stanza continua a trovare il task vero dopo il
+ * marcatore e non questo preambolo.
+ */
+export function formatMandate(mandate, canDelegate) {
+    const total = mandate.rooms.length;
+    const closed = mandate.closed.length
+        ? `@attivita[chiuse]: ${mandate.closed.join(", ")} (NON rifarle)`
+        : `@attivita[chiuse]: nessuna`;
+    const scope = mandate.partial
+        ? `@confine[attivita]: hai SOLO i ref elencati; le altre attivita del gruppo sono di qualcun altro`
+        : `@confine[attivita]: tutto il gruppo e' tuo`;
+    // Delegare e' possibile solo al primo livello: un'unita' di secondo livello
+    // che potesse spawnare ancora aprirebbe una ricorsione senza fondo.
+    const growth = canDelegate
+        ? `@crescita[scomposizione]: se una attivita si rivela grande, o vascend_addtasks(group="${mandate.castle}") per spezzarla in sotto-attivita, o team_engage per affidare le attivita a un tuo team (una voce per ref: slug="T01", goal=cosa fare); NON lavorare fuori dal piano`
+        : `@crescita[scomposizione]: nessuna ulteriore delega da qui; se la attivita e' troppo grande chiudi cio' che e' verificabile e dillo nel report`;
+    const growthRel = canDelegate
+        ? `@R3: @attivita[mie] -> @crescita[scomposizione]  [ scomponi o delega, non sforare ]`
+        : `@R3: @attivita[mie] -> @crescita[scomposizione]  [ niente delega: riporta il limite ]`;
+    return `MANDATO
+INDICE
+1 = gruppo
+2 = attivita
+3 = avanzamento
+4 = crescita
+
+DEFINIZIONI
+@gruppo[assegnato]: ${mandate.castle} "${mandate.title}"${mandate.after ? ` · dopo ${mandate.after}` : ""}
+@attivita[mie]: ${total} da chiudere
+${mandate.rooms.map(roomLine).join("\n")}
+${closed}
+${scope}
+@avanzamento[marcatura]: appena APRI una attivita vascend_mark(group="${mandate.castle}", task="<ref>", status="running"), appena la CHIUDI status="completed" con evidence concreta (file + test/comando + risultato), oppure "failed" col motivo in vascend_note. E' l'unico modo in cui l'utente ti vede avanzare
+${growth}${mandate.skills?.length ? `\n@skill[gruppo]: ${mandate.skills.join(", ")} (richiamale quando servono, non tutte subito)` : ""}
+
+RELAZIONI
+@R1: @gruppo[assegnato] -> @attivita[mie]  [ il piano e' il mandato: non re-inventarlo ]
+@R2: @attivita[mie] -> @avanzamento[marcatura]  [ una marcatura per attivita, in tempo reale ]
+${growthRel}
+
+OUTPUT: chiudi le tue attivita una per una marcandole; nel report finale elenca i ref chiusi, quelli falliti e i file toccati.`;
+}

package/dist/vascend/memory-packet.d.ts

@@ -0,0 +1,13 @@
+export interface MemoryPacketInput {
+    readonly sessionDir: string;
+    readonly scopeId: string;
+    readonly planScopeId?: string;
+    readonly maxChars?: number;
+    readonly recentLimit?: number;
+    readonly projectScopeLimit?: number;
+    readonly projectKey?: string;
+    /** Preselected dependencies supplied by a coherent snapshot. */
+    readonly projectScopes?: readonly string[];
+}
+export declare function buildMemoryPacket(input: MemoryPacketInput): string;
+export declare function clampMemoryPacket(value: string, max: number): string;

package/dist/vascend/memory-packet.js

@@ -0,0 +1,155 @@
+import { sanitizeText } from "../core/text-sanitize.js";
+import { listMemoryScopes, MemoryStore } from "./memory-store.js";
+import { VascendPlanStore } from "./plan-store.js";
+import { RoomMemory } from "./room-memory.js";
+import { VascendVisionStore, visionCompleteness } from "./vision.js";
+import { listContextMemoryScopes } from "./context-fabric.js";
+export function buildMemoryPacket(input) {
+    const maxChars = input.maxChars && input.maxChars > 0 ? input.maxChars : 12_000;
+    const recentLimit = input.recentLimit && input.recentLimit > 0 ? input.recentLimit : 10;
+    const projectScopeLimit = input.projectScopeLimit && input.projectScopeLimit > 0 ? input.projectScopeLimit : 6;
+    const rooms = safe(() => RoomMemory.open(input.sessionDir, input.scopeId).frontier(), []);
+    const castles = safe(() => VascendPlanStore.open(input.sessionDir, input.planScopeId ?? input.scopeId).castles(), []);
+    const visions = safe(() => VascendVisionStore.open(input.sessionDir, input.scopeId).all(), []);
+    const events = safe(() => recentEvents(MemoryStore.open(input.sessionDir, input.scopeId).all(), recentLimit).map((event) => ({ scopeId: input.scopeId, value: event })), []);
+    const allowedScopes = !input.projectScopes && input.projectKey
+        ? new Set(listContextMemoryScopes(input.sessionDir, input.projectKey))
+        : null;
+    const projectScopes = input.projectScopes ?? listMemoryScopes(input.sessionDir, {
+        excludeScope: input.scopeId,
+        limit: allowedScopes ? 10_000 : projectScopeLimit,
+    }).filter((scope) => !allowedScopes || allowedScopes.has(scope)).slice(0, projectScopeLimit);
+    const projectRooms = loadProjectFrontiers(input.sessionDir, projectScopes, 8);
+    const projectCastles = loadProjectCastles(input.sessionDir, projectScopes, 8);
+    const projectVisions = loadProjectVisions(input.sessionDir, projectScopes, 5);
+    const projectEvents = loadProjectEvents(input.sessionDir, projectScopes, recentLimit);
+    const hasProject = Boolean(projectRooms.length || projectCastles.length || projectVisions.length || projectEvents.length);
+    if (!rooms.length && !castles.length && !visions.length && !events.length && !hasProject)
+        return "";
+    const lines = [
+        "[TALOS_MEMORY_PACKET]",
+        "INDICE",
+        "1 = frontiera",
+        "2 = piano",
+        "3 = vision",
+        "4 = eventi",
+        "5 = working_set_progetto",
+        "",
+        "DEFINIZIONI",
+        ...frontierRows(rooms),
+        ...planRows(castles),
+        ...visionRows(visions),
+        ...projectRows(projectRooms, projectCastles, projectVisions),
+        ...eventRows([...events, ...projectEvents]),
+        "",
+        "RELAZIONI",
+        "@R-memory: @frontiera -> recall  [ dettaglio recuperabile via tool recall ]",
+        "@R-plan: @piano -> azione  [ usa lo stato del piano per non duplicare lavoro ]",
+        "@R-vision: @vision -> decisioni  [ ogni scelta deve restare allineata alla stella polare ]",
+        "@R-project: @working_set_progetto -> continuita  [ recupera il contesto operativo dalle sessioni recenti ]",
+        "",
+        "OUTPUT: contesto memoria unificato; usa recall per dettaglio e aggiorna piano/note/vision quando cambia lo stato.",
+    ];
+    return clampMemoryPacket(lines.filter(Boolean).join("\n"), maxChars);
+}
+function frontierRows(rooms) {
+    if (!rooms.length)
+        return ["@frontiera[vuota]: nessuna attivita indicizzata"];
+    // La frontiera e' ordinata vecchio->recente. Conserva un indice per livello
+    // ma dedica la maggior parte degli slot allo stato piu' recente: slice(0,10)
+    // nascondeva proprio le ultime stanze nei run lunghi.
+    const byLevel = new Map();
+    for (const room of rooms)
+        if (!byLevel.has(room.level))
+            byLevel.set(room.level, room);
+    const picked = [...byLevel.values(), ...rooms.slice(-8)];
+    const unique = [...new Map(picked.map((room) => [room.room, room])).values()].slice(-10);
+    return unique.map((r) => `@frontiera[${r.room}]: level=${r.level}, title="${q(r.title)}", termini=${r.terms.slice(0, 6).join(",")}`);
+}
+function planRows(castles) {
+    if (!castles.length)
+        return ["@piano[vuoto]: nessun gruppo attivo"];
+    const ordered = [...castles].sort((a, b) => Number(b.tasks.some((task) => task.status !== "completed")) - Number(a.tasks.some((task) => task.status !== "completed")));
+    return ordered.flatMap((castle) => {
+        const tasks = [...castle.tasks]
+            .sort((a, b) => Number(a.status === "completed") - Number(b.status === "completed") || a.bit - b.bit)
+            .slice(0, 8)
+            .map((t) => `@task[${castle.slug}/${t.id}]: status=${t.status}, title="${q(t.title)}"`);
+        return [`@plan[${castle.slug}]: title="${q(castle.title)}", target=${castle.maskTarget}, attivita=${castle.tasks.length}`, ...tasks];
+    }).slice(0, 32);
+}
+function visionRows(visions) {
+    if (!visions.length)
+        return ["@vision[vuota]: nessuna Vision persistita"];
+    return visions.slice(0, 5).map((v) => {
+        const c = visionCompleteness(v);
+        return `@vision[${v.taskId}]: goal="${q(v.goal)}", ready=${c.productionReady}, core=${c.coreBuilt}/${c.coreTotal}, readiness=${c.readinessMet}/${c.readinessTotal}`;
+    });
+}
+function projectRows(rooms, castles, visions) {
+    if (!rooms.length && !castles.length && !visions.length)
+        return ["@working_set_progetto[vuoto]: nessun contesto recente da altre sessioni"];
+    return [
+        "[WORKING_SET_PROGETTO]",
+        ...rooms.map((r) => `@project_frontiera[${r.scopeId}/${r.value.room}]: level=${r.value.level}, title="${q(r.value.title)}"`),
+        ...castles.flatMap((c) => [
+            `@project_plan[${c.scopeId}/${c.value.slug}]: title="${q(c.value.title)}", target=${c.value.maskTarget}, attivita=${c.value.tasks.length}`,
+            ...c.value.tasks.slice(0, 4).map((t) => `@project_task[${c.scopeId}/${c.value.slug}/${t.id}]: status=${t.status}, title="${q(t.title)}"`),
+        ]),
+        ...visions.map((v) => `@project_vision[${v.scopeId}/${v.value.taskId}]: goal="${q(v.value.goal)}"`),
+    ].slice(0, 48);
+}
+function eventRows(events) {
+    if (!events.length)
+        return ["@eventi[vuoti]: nessun evento recente"];
+    return events.map(({ scopeId, value: e }) => `@evento[${scopeId}/${e.id}]: type=${e.type}, domain=${e.domain}, subject=${q(e.subject, 80)}, summary="${q(e.summary, 160)}"`);
+}
+function recentEvents(events, limit) {
+    return [...events]
+        .filter((e) => !isSuperseded(e))
+        .sort((a, b) => b.createdAt - a.createdAt || b.id.localeCompare(a.id))
+        .slice(0, limit);
+}
+// Vero se l'evento e' stato superato/archiviato (grafo di supersessione): non
+// deve sporcare il contesto con memoria obsoleta.
+function isSuperseded(event) {
+    const status = typeof event.payload?.["status"] === "string" ? event.payload["status"] : "active";
+    return status === "superseded" || status === "archived" || typeof event.payload?.["supersededBy"] === "string";
+}
+function loadProjectFrontiers(sessionDir, scopes, limit) {
+    return scopes.flatMap((scopeId) => safe(() => RoomMemory.open(sessionDir, scopeId).frontier().slice(-2).map((value) => ({ scopeId, value })), [])).slice(0, limit);
+}
+function loadProjectCastles(sessionDir, scopes, limit) {
+    return scopes.flatMap((scopeId) => safe(() => VascendPlanStore.open(sessionDir, scopeId).castles().slice(0, 2).map((value) => ({ scopeId, value })), [])).slice(0, limit);
+}
+function loadProjectVisions(sessionDir, scopes, limit) {
+    return scopes.flatMap((scopeId) => safe(() => VascendVisionStore.open(sessionDir, scopeId).all().slice(0, 2).map((value) => ({ scopeId, value })), [])).slice(0, limit);
+}
+function loadProjectEvents(sessionDir, scopes, limit) {
+    const events = scopes.flatMap((scopeId) => safe(() => MemoryStore.open(sessionDir, scopeId).all().map((value) => ({ scopeId, value })), []));
+    return events
+        .filter((e) => !isSuperseded(e.value))
+        .sort((a, b) => b.value.createdAt - a.value.createdAt || b.value.id.localeCompare(a.value.id))
+        .slice(0, limit);
+}
+function safe(fn, fallback) {
+    try {
+        return fn();
+    }
+    catch {
+        return fallback;
+    }
+}
+function q(value, max = 120) {
+    const oneLine = sanitizeText(value).replace(/\s+/g, " ").trim().replace(/"/g, "'");
+    return oneLine.length > max ? oneLine.slice(0, max - 1).trimEnd() + "..." : oneLine;
+}
+export function clampMemoryPacket(value, max) {
+    if (value.length <= max)
+        return value;
+    const marker = "\n...[memory-packet-troncato]";
+    const target = Math.max(0, max - marker.length);
+    const prefix = value.slice(0, target);
+    const boundary = prefix.lastIndexOf("\n");
+    return `${boundary > target * 0.7 ? prefix.slice(0, boundary) : prefix}${marker}`;
+}

package/dist/vascend/memory-status.d.ts

@@ -0,0 +1,22 @@
+export interface MemoryFrontierNode {
+    readonly id: string;
+    readonly level: number;
+    readonly label: string;
+    readonly terms: readonly string[];
+    readonly rooms: number;
+    readonly recent: boolean;
+}
+export interface MemoryStatus {
+    readonly rooms: number;
+    readonly nodes: number;
+    readonly frontier: readonly MemoryFrontierNode[];
+    readonly indexTokens: number;
+    readonly graph: {
+        readonly files: number;
+        readonly edges: number;
+    };
+}
+export declare function memoryStatus(sessionDir: string, scopeId: string, opts?: {
+    readonly limit?: number;
+    readonly fanout?: number;
+}): MemoryStatus | null;

package/dist/vascend/memory-status.js

@@ -0,0 +1,73 @@
+// Stato leggibile della memoria, per gli host che vogliono MOSTRARLO.
+//
+// L'agente naviga la memoria col tool recall; una interfaccia umana ha bisogno
+// di un'altra cosa: sapere a colpo d'occhio cosa c'e' in frontiera, quanto
+// costa l'indice vivo, quanto e' fitto il grafo. Questo modulo produce quella
+// vista, senza esporre gli store interni.
+//
+// Legge solo `<scope>.rooms.jsonl` (piccolo e gia' indicizzato): non tocca il
+// file di sessione, che su conversazioni lunghe pesa megabyte. Lo stato della
+// compattazione arriva invece all'host per evento, mentre accade.
+import { RoomMemory } from "./room-memory.js";
+import { filesOf } from "./room-graph.js";
+const DEFAULT_LIMIT = 6;
+// Stato della memoria di uno scope. Ritorna null se non c'e' nulla di
+// archiviato: l'host non deve mostrare una sezione vuota.
+export function memoryStatus(sessionDir, scopeId, opts = {}) {
+    let mem;
+    try {
+        mem = opts.fanout ? RoomMemory.open(sessionDir, scopeId, opts.fanout) : RoomMemory.open(sessionDir, scopeId);
+    }
+    catch {
+        return null;
+    }
+    if (!mem.count())
+        return null;
+    const all = mem.all();
+    const byId = new Map(all.map((r) => [r.room, r]));
+    const frontier = mem.frontier();
+    const limit = Math.max(1, opts.limit ?? DEFAULT_LIMIT);
+    // Si mostrano gli ULTIMI: la coda e' il lavoro recente, la testa e' storia
+    // gia' compattata in nodi di livello superiore.
+    const shown = frontier.slice(-limit);
+    const last = frontier[frontier.length - 1];
+    const files = new Set();
+    let edges = 0;
+    for (const record of all) {
+        if (record.level !== 0)
+            continue;
+        for (const file of filesOf(record)) {
+            files.add(file);
+            edges += 1;
+        }
+    }
+    return {
+        rooms: all.filter((r) => r.level === 0).length,
+        nodes: all.length,
+        frontier: shown.map((record) => ({
+            id: record.room,
+            level: record.level,
+            label: record.title,
+            terms: record.terms.slice(0, 6),
+            rooms: countRooms(record, byId),
+            recent: record.room === last?.room,
+        })),
+        indexTokens: Math.ceil(mem.indexBlock().length / 4),
+        graph: { files: files.size, edges },
+    };
+}
+// Stanze contenute da un nodo, scendendo la gerarchia. Un ciclo nei figli
+// (store corrotto) non deve mandare in ricorsione infinita.
+function countRooms(record, byId, seen = new Set()) {
+    if (record.level === 0)
+        return 1;
+    if (seen.has(record.room))
+        return 0;
+    seen.add(record.room);
+    let total = 0;
+    for (const childId of record.children) {
+        const child = byId.get(childId);
+        total += child ? countRooms(child, byId, seen) : 1;
+    }
+    return total;
+}

package/dist/vascend/memory-store.d.ts

@@ -0,0 +1,62 @@
+export type MemoryDomain = "rooms" | "plan" | "vision" | "notes" | "skills" | "assets" | "decisions" | "kingdom" | "system" | "files" | "code" | string;
+export interface MemoryLink {
+    readonly rel: string;
+    readonly target: string;
+    readonly domain?: MemoryDomain;
+}
+export interface MemoryEvent {
+    readonly id: string;
+    readonly type: string;
+    readonly domain: MemoryDomain;
+    readonly subject: string;
+    readonly summary: string;
+    readonly body: string;
+    readonly terms: readonly string[];
+    readonly links: readonly MemoryLink[];
+    readonly payload: Readonly<Record<string, unknown>>;
+    readonly createdAt: number;
+}
+export type MemoryEventInput = Partial<Pick<MemoryEvent, "id" | "body" | "terms" | "links" | "payload" | "createdAt">> & Pick<MemoryEvent, "type" | "domain" | "subject" | "summary">;
+export interface MemoryQuery {
+    readonly domain?: MemoryDomain;
+    readonly type?: string;
+    readonly subject?: string;
+    readonly limit?: number;
+}
+export interface MemorySearchOptions {
+    readonly domain?: MemoryDomain;
+    readonly type?: string;
+    readonly limit?: number;
+}
+export interface MemorySearchHit {
+    readonly event: MemoryEvent;
+    readonly score: number;
+}
+export interface ListMemoryScopesOptions {
+    readonly excludeScope?: string;
+    readonly limit?: number;
+}
+export declare function listMemoryScopes(sessionDir: string, opts?: ListMemoryScopesOptions): readonly string[];
+export declare class MemoryStore {
+    private readonly file;
+    private events;
+    private readonly ids;
+    private maxNumericId;
+    private loadedBytes;
+    private partialLine;
+    private docTokens;
+    private readonly globalDf;
+    private constructor();
+    static open(sessionDir: string, scopeId: string): MemoryStore;
+    count(): number;
+    all(): readonly MemoryEvent[];
+    append(input: MemoryEventInput): MemoryEvent;
+    query(q?: MemoryQuery): readonly MemoryEvent[];
+    byIds(ids: readonly string[]): readonly MemoryEvent[];
+    search(query: string, opts?: MemorySearchOptions): readonly MemorySearchHit[];
+    private nextId;
+    private reloadFromDisk;
+    private reloadTailFromDisk;
+    private resetIndexes;
+    private addEvent;
+}