@vascend/talos 0.1.0

package/dist/vascend/runtime.d.ts

@@ -0,0 +1,84 @@
+import type { Message } from "../core/types.js";
+import { type VisionLike } from "./long-term-context.js";
+export type VascendMode = "off" | "sticky";
+export type VascendPromptMode = "one-shot" | "sticky";
+export type VascendTaskStatus = "pending" | "running" | "completed" | "failed";
+export interface VascendTask {
+    readonly id: string;
+    readonly bit: number;
+    readonly mask: string;
+    readonly title: string;
+    readonly status: VascendTaskStatus;
+    readonly tokens?: number;
+    readonly ms?: number;
+    readonly notes?: readonly string[];
+    readonly skills?: readonly string[];
+    readonly weight?: number;
+    readonly files?: readonly string[];
+    readonly evidence?: readonly string[];
+    readonly compact?: boolean;
+}
+export interface VascendCastle {
+    readonly slug: string;
+    readonly title: string;
+    readonly maskTarget: string;
+    readonly tasks: readonly VascendTask[];
+    readonly notes?: readonly string[];
+    readonly skills?: readonly string[];
+    readonly after?: string;
+}
+export interface VascendKingdom {
+    readonly castles: readonly VascendCastle[];
+}
+export interface VascendState {
+    readonly mode: VascendMode;
+    readonly goal: string | null;
+    readonly kingdom: VascendKingdom;
+    readonly vision?: VisionLike | null;
+}
+export interface PreparedVascendInput {
+    readonly active: boolean;
+    readonly input: string;
+}
+export type VascendCommandResult = {
+    readonly kind: "status";
+    readonly message: string;
+} | {
+    readonly kind: "input";
+    readonly message: string;
+    readonly input: string;
+};
+export interface VascendCheckpoint {
+    readonly path: string;
+    readonly text: string;
+}
+export declare const VASCEND_SYSTEM_BLOCK = "# Lista delle attivita\nComunica in italiano naturale, con spiegazioni chiare e Markdown leggibile.\nDescrivi il lavoro con una to-do list: attivita, gruppi, dipendenze e stati\nda fare, in corso, completata o fallita. I riepiloghi della memoria sono solo\ncontesto interno: all'utente mostra le attivita e i risultati pertinenti.\nPer lavori con piu passi usa vascend_plan: un piano contiene gruppi di attivita,\nogni gruppo contiene attivita con stato, dipendenze e prove di verifica.\nAggiorna gli stati con vascend_mark; completa solo dopo le verifiche.\nUsa vascend_note per decisioni e blocchi e recall per recuperare il passato.\nPer lavori indipendenti valuta collaboratori tramite gli strumenti del team.\nPer domande o richieste semplici non creare un piano inutile.";
+export interface VascendVerdict {
+    readonly ok: boolean;
+    readonly total: number;
+    readonly done: number;
+    readonly pending: readonly string[];
+    readonly failed: readonly string[];
+}
+export declare function validateKingdom(state: VascendState): VascendVerdict;
+export declare function buildValidationSteer(v: VascendVerdict): string;
+export declare function createVascendState(): VascendState;
+export declare function createVascendGoal(state: VascendState, goal: string): VascendState;
+export declare function setVascendMode(state: VascendState, mode: VascendMode): VascendState;
+export declare function setVascendVision(state: VascendState, vision: VisionLike | null): VascendState;
+export declare function wrapVascendPrompt(state: VascendState, userText: string, mode: VascendPromptMode, checkpoint?: string): string;
+export declare function formatVascendCompact(state: VascendState, messages?: readonly Message[]): string;
+export declare class VascendRuntime {
+    private readonly cwd;
+    private stateValue;
+    private customPlan;
+    constructor(cwd: string, initialMode?: VascendMode);
+    state(): VascendState;
+    hasCustomPlan(): boolean;
+    loadPlan(sessionDir: string, sessionId: string): boolean;
+    resetPlan(sessionDir: string, sessionId: string): void;
+    handleCommand(args: string): VascendCommandResult;
+    prepareUserInput(userText: string): PreparedVascendInput;
+    compact(messages: readonly Message[]): VascendCheckpoint;
+    private wrap;
+}

package/dist/vascend/runtime.js

@@ -0,0 +1,286 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { sanitizeText } from "../core/text-sanitize.js";
+import { VascendPlanStore } from "./plan-store.js";
+import { injectLongTermContext } from "./long-term-context.js";
+export const VASCEND_SYSTEM_BLOCK = `# Lista delle attivita
+Comunica in italiano naturale, con spiegazioni chiare e Markdown leggibile.
+Descrivi il lavoro con una to-do list: attivita, gruppi, dipendenze e stati
+da fare, in corso, completata o fallita. I riepiloghi della memoria sono solo
+contesto interno: all'utente mostra le attivita e i risultati pertinenti.
+Per lavori con piu passi usa vascend_plan: un piano contiene gruppi di attivita,
+ogni gruppo contiene attivita con stato, dipendenze e prove di verifica.
+Aggiorna gli stati con vascend_mark; completa solo dopo le verifiche.
+Usa vascend_note per decisioni e blocchi e recall per recuperare il passato.
+Per lavori indipendenti valuta collaboratori tramite gli strumenti del team.
+Per domande o richieste semplici non creare un piano inutile.`;
+export function validateKingdom(state) {
+    const castles = state.kingdom.castles;
+    const multi = castles.length > 1;
+    let total = 0;
+    let done = 0;
+    const pending = [];
+    const failed = [];
+    for (const c of castles) {
+        for (const t of c.tasks) {
+            total += 1;
+            const id = multi ? `${c.slug}/${t.id}` : t.id;
+            if (t.status === "completed")
+                done += 1;
+            else if (t.status === "failed")
+                failed.push(id);
+            else
+                pending.push(id);
+        }
+    }
+    return { ok: total > 0 && done === total, total, done, pending, failed };
+}
+// Messaggio di steering per svegliare l'agente sulle stanze da completare.
+export function buildValidationSteer(v) {
+    return `[VASCEND_VALIDAZIONE]
+INDICE
+1 = piano
+2 = aperto
+
+DEFINIZIONI
+@stato[piano]: completate=${v.done}/${v.total}
+@aperto[attivita]: ${v.pending.join(", ")} NON completate
+
+RELAZIONI
+@R: @aperto[attivita] -> @stato[piano]  [ il piano NON valida finché restano attivita da completare ]
+
+OUTPUT: completa le attivita non completate facendo il lavoro reale e segnandole con vascend_mark (status completed). Se una e' davvero impossibile, marcala failed indicando il motivo. Non concludere finché non sono tutte risolte.`;
+}
+export function createVascendState() {
+    return { mode: "off", goal: null, kingdom: { castles: [] } };
+}
+export function createVascendGoal(state, goal) {
+    const title = oneLine(goal) || "obiettivo";
+    // NIENTE castello automatico: il castello (con le sue stanze) si crea solo su
+    // richiesta (comando /castle) o quando l'agente pianifica con vascend_plan.
+    // Cosi' il riquadro non compare quando non serve (es. un saluto).
+    return { ...state, goal: title, kingdom: { castles: [] } };
+}
+export function setVascendMode(state, mode) {
+    return { ...state, mode };
+}
+// Imposta (o azzera con null) la VISION finale del task. Immutabile: crea un
+// nuovo stato. Il goal momentaneo resta indipendente e non viene toccato.
+export function setVascendVision(state, vision) {
+    return { ...state, vision };
+}
+export function wrapVascendPrompt(state, userText, mode, checkpoint) {
+    if (!state.goal)
+        return userText;
+    const checkpointBlock = checkpoint
+        ? `\nCHECKPOINT_PRECEDENTE\n${checkpoint.trim()}\n`
+        : "";
+    const immediatePrompt = `[VASCEND_GOAL]
+GOAL: ${state.goal}
+MODE: ${mode}
+${checkpointBlock}
+Piano di lavoro:
+- Comunica in modo naturale e leggibile, senza imporre notazioni speciali.
+- Per lavori con piu passi crea o riprendi il piano con vascend_plan e vascend_status.
+- Organizza il piano in gruppi e attivita; aggiorna gli stati con vascend_mark.
+- Completa le attivita solo dopo verifiche concrete; registra decisioni e blocchi.
+- Per lavori indipendenti valuta collaboratori; per domande semplici non serve un piano.
+
+INPUT_UTENTE
+${userText}`;
+    // Antepone il CONTESTO A LUNGO TERMINE (Vision finale) come piano SEPARATO
+    // dal goal immediato. Il goal corrente viene passato come "immediato" cosi'
+    // che il blocco espliciti la distinzione momentaneo/visione. Se non c'e'
+    // Vision con contenuto, injectLongTermContext ritorna il prompt invariato.
+    const currentCastle = state.kingdom.castles[0];
+    const currentRoom = currentCastle?.tasks.find((t) => t.status === "running");
+    return injectLongTermContext(immediatePrompt, {
+        vision: state.vision ?? null,
+        immediate: {
+            ...(state.goal ? { goal: state.goal } : {}),
+            ...(currentCastle ? { castle: currentCastle.title } : {}),
+            ...(currentRoom ? { room: currentRoom.title } : {}),
+        },
+    });
+}
+export function formatVascendCompact(state, messages = []) {
+    const castle = state.kingdom.castles[0];
+    const multi = state.kingdom.castles.length > 1;
+    const tasks = state.kingdom.castles.flatMap(group => group.tasks.map(task => ({ ...task,
+        id: multi ? `${group.slug}/${task.id}` : task.id,
+    })));
+    const groups = state.kingdom.castles.map(group => `@gruppo[${group.slug}]: titolo="${escapeValue(group.title)}", dipendenza=${group.after ?? "none"}`).join("\n");
+    const taskRows = tasks.length
+        ? tasks.map((task) => compactTaskRow(task)).join("\n")
+        : "@aperto[goal]: nessun_gruppo_attivo, blocco=none";
+    const recent = messagePreviews(messages)
+        .map((text, index) => `@stato[recent_${index + 1}]: ${text}`)
+        .join("\n");
+    const relations = tasks.length
+        ? tasks.map((task, index) => `@R${index + 1}: @stato[goal] -> @${task.status === "completed" ? "fatto" : "aperto"}[${task.id}], task`).join("\n")
+        : "@R1: @stato[goal] -> @aperto[goal], crea_gruppo";
+    // The synthetic summary is usually older than the last four messages.
+    // Keep it in the cold-start checkpoint, not just 140-character previews.
+    const summary = messages.flatMap(message => message.content
+        .filter(part => part.type === "text" && part.text.startsWith("[Riepilogo del contesto precedente]"))
+        .map(part => part.type === "text" ? part.text : "")).at(-1);
+    return `INDICE
+1 = goal
+2 = gruppo
+3 = task
+4 = file
+5 = contesto
+
+DEFINIZIONI
+@stato[goal]: valore="${escapeValue(state.goal ?? "nessun_goal")}", mode=${state.mode}
+@stato[gruppo]: slug=${castle?.slug ?? "none"}, mask=${castle?.maskTarget ?? "0x0000"}
+${groups}
+${taskRows}
+@file[checkpoint]: path=.vascend-compact.md, ruolo=checkpoint, stato=aggiornato${recent ? `\n${recent}` : ""}
+
+RELAZIONI
+${relations}
+@R99: @file[checkpoint] -> @stato[goal], ripresa
+
+OUTPUT: stato compatto della sessione, pronto a riprendere a freddo.${summary ? `\n\nCONTESTO DI RIPRESA\n${summary}` : ""}`;
+}
+export class VascendRuntime {
+    cwd;
+    stateValue;
+    customPlan = false;
+    // initialMode permette di rendere il metodo Vascend NATIVO (sticky) di
+    // default nella TUI, senza dover digitare /vascend on. Default "off" per
+    // mantenere puro il runtime fuori dalla TUI (test, print, SDK).
+    constructor(cwd, initialMode = "off") {
+        this.cwd = cwd;
+        this.stateValue = setVascendMode(createVascendState(), initialMode);
+    }
+    state() {
+        return this.stateValue;
+    }
+    hasCustomPlan() {
+        return this.customPlan;
+    }
+    // Carica il piano CUSTOM definito dall'agente (vascend_plan/vascend_mark) e lo
+    // riflette come castello master, con gli stati reali delle stanze. Ritorna
+    // true se esiste un piano custom: in tal caso la TUI mostra le stanze vere e
+    // si salta l'euristica di illuminazione (begin/record/finish).
+    loadPlan(sessionDir, sessionId) {
+        const planned = VascendPlanStore.open(sessionDir, sessionId).castles();
+        if (!planned.length) {
+            this.customPlan = false;
+            return false;
+        }
+        const castles = planned.map((c) => ({
+            slug: c.slug,
+            title: c.title,
+            maskTarget: c.maskTarget,
+            tasks: c.tasks.map((t) => ({
+                id: t.id, bit: t.bit, mask: t.mask, title: t.title, status: t.status,
+                ...(t.tokens !== undefined ? { tokens: t.tokens } : {}),
+                ...(t.ms !== undefined ? { ms: t.ms } : {}),
+                ...(t.notes ? { notes: t.notes } : {}),
+                ...(t.skills ? { skills: t.skills } : {}),
+                ...(t.weight ? { weight: t.weight } : {}),
+                ...(t.files ? { files: t.files } : {}),
+                ...(t.evidence ? { evidence: t.evidence } : {}),
+                ...(t.compact ? { compact: true } : {}),
+            })),
+            ...(c.notes ? { notes: c.notes } : {}),
+            ...(c.skills ? { skills: c.skills } : {}),
+            ...(c.after ? { after: c.after } : {}),
+        }));
+        this.stateValue = {
+            ...this.stateValue,
+            goal: this.stateValue.goal ?? castles[0]?.title ?? null,
+            kingdom: { castles },
+        };
+        this.customPlan = true;
+        return true;
+    }
+    // Azzera il piano custom del regno (nuovo obiettivo = regno pulito).
+    resetPlan(sessionDir, sessionId) {
+        VascendPlanStore.open(sessionDir, sessionId).clear();
+        this.customPlan = false;
+    }
+    handleCommand(args) {
+        const value = args.trim();
+        if (!value || value === "on") {
+            this.stateValue = setVascendMode(this.stateValue, "sticky");
+            return { kind: "status", message: "vascend sticky attivo" };
+        }
+        if (value === "off") {
+            this.stateValue = createVascendState();
+            return { kind: "status", message: "vascend spento; piano svuotato" };
+        }
+        if (value === "clear") {
+            this.stateValue = createVascendState();
+            return { kind: "status", message: "piano vascend svuotato" };
+        }
+        if (value === "status") {
+            return { kind: "status", message: this.stateValue.mode === "sticky" ? "vascend sticky attivo" : "vascend non sticky" };
+        }
+        this.stateValue = createVascendGoal(this.stateValue, value);
+        return {
+            kind: "input",
+            message: "goal vascend one-shot creato",
+            input: this.wrap(value, "one-shot"),
+        };
+    }
+    prepareUserInput(userText) {
+        if (this.stateValue.mode !== "sticky")
+            return { active: false, input: userText };
+        this.stateValue = createVascendGoal(this.stateValue, userText);
+        return { active: true, input: this.wrap(userText, "sticky") };
+    }
+    compact(messages) {
+        const text = formatVascendCompact(this.stateValue, messages);
+        const path = checkpointPath(this.cwd);
+        writeFileSync(path, text + "\n", "utf8");
+        return { path, text };
+    }
+    wrap(userText, mode) {
+        return wrapVascendPrompt(this.stateValue, userText, mode, readCheckpoint(this.cwd));
+    }
+}
+function compactTaskRow(task) {
+    const kind = task.status === "completed" ? "fatto" : "aperto";
+    const block = task.status === "failed" ? ", blocco=failed" : "";
+    const evidence = task.evidence?.length
+        ? `, prove="${escapeValue(task.evidence.slice(-3).join(" | "))}"`
+        : "";
+    return `@${kind}[${task.id}]: titolo="${escapeValue(task.title)}", bit=${task.bit}, mask=${task.mask}, esito=${task.status}${block}${evidence}`;
+}
+function messagePreviews(messages) {
+    return messages.slice(-4).flatMap((message) => {
+        const text = message.content
+            .map((part) => {
+            if (part.type === "text")
+                return part.text;
+            if (part.type === "tool_call")
+                return `${part.name} ${JSON.stringify(part.input)}`;
+            if (part.type === "image")
+                return `[immagine ${part.mime}]`;
+            return part.output;
+        })
+            .join(" ");
+        const compact = oneLine(text).slice(0, 140);
+        return compact ? [`role=${message.role}, text="${escapeValue(compact)}"`] : [];
+    });
+}
+function checkpointPath(cwd) {
+    return join(cwd, ".vascend-compact.md");
+}
+function readCheckpoint(cwd) {
+    const path = checkpointPath(cwd);
+    return existsSync(path) ? readFileSync(path, "utf8") : undefined;
+}
+function oneLine(value) {
+    return sanitizeText(value).replace(/\s+/g, " ").trim();
+}
+function escapeValue(value) {
+    return oneLine(value).replace(/"/g, "'");
+}
+function hexMask(value) {
+    return `0x${value.toString(16).padStart(4, "0")}`;
+}

package/dist/vascend/self-improve.d.ts

@@ -0,0 +1,104 @@
+import type { Harness } from "../core/bootstrap.js";
+export interface VisionFeatureLike {
+    readonly id?: string;
+    readonly title?: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly priority?: string;
+    readonly done?: boolean;
+}
+export interface ReadinessCriterionLike {
+    readonly id?: string;
+    readonly text?: string;
+    readonly description?: string;
+    readonly met?: boolean;
+}
+export interface VisionValueLike {
+    readonly statement?: string;
+    readonly text?: string;
+    readonly metrics?: readonly string[];
+}
+export interface VisionLike {
+    readonly id?: string;
+    readonly title?: string;
+    readonly finalGoal?: string;
+    readonly value?: VisionValueLike | string;
+    readonly features?: readonly VisionFeatureLike[];
+    readonly readinessCriteria?: readonly ReadinessCriterionLike[];
+    readonly summary?: string;
+}
+export type ImprovementCategory = "feature" | "quality" | "ux" | "robustness" | "performance" | "alignment";
+export type ImprovementPriority = "must" | "should" | "could";
+export interface ImprovementProposal {
+    readonly text: string;
+    readonly category: ImprovementCategory;
+    readonly priority: ImprovementPriority;
+    readonly impact: number;
+    readonly effort?: "small" | "medium" | "large";
+    readonly visionRef?: string;
+    readonly rationale?: string;
+}
+export interface SelfImproveReport {
+    readonly alignment: number;
+    readonly atVision: boolean;
+    readonly proposals: readonly ImprovementProposal[];
+    readonly summary: string;
+    readonly fallback: boolean;
+}
+export declare function selfImproveEnabled(env: NodeJS.ProcessEnv): boolean;
+export declare function selfImproveRounds(env: NodeJS.ProcessEnv): number;
+export declare function selfImproveThreshold(env: NodeJS.ProcessEnv): number;
+export declare function selfImproveMaxProposals(env: NodeJS.ProcessEnv): number;
+export interface SelfImproveOptions {
+    readonly enabled: boolean;
+    readonly rounds: number;
+    readonly threshold: number;
+    readonly maxProposals: number;
+}
+export declare function selfImproveOptions(env: NodeJS.ProcessEnv): SelfImproveOptions;
+export declare function aggregateProposals(opts: {
+    readonly proposals: readonly ImprovementProposal[];
+    readonly alignment?: number;
+    readonly threshold?: number;
+    readonly maxProposals?: number;
+    readonly fallback?: boolean;
+}): SelfImproveReport;
+export declare function visionToText(vision: VisionLike | string | undefined): string;
+interface RawProposal {
+    text?: unknown;
+    category?: unknown;
+    priority?: unknown;
+    impact?: unknown;
+    effort?: unknown;
+    visionRef?: unknown;
+    rationale?: unknown;
+}
+export declare function normalizeProposal(raw: RawProposal): ImprovementProposal | null;
+export declare function parseProposals(text: string): ImprovementProposal[];
+export declare function parseReport(text: string, opts?: {
+    readonly threshold?: number;
+    readonly maxProposals?: number;
+}): SelfImproveReport;
+export interface SelfImproveInput {
+    readonly harness: Harness;
+    readonly vision: VisionLike | string | undefined;
+    readonly evidence: string;
+    readonly goal?: string;
+    readonly signal: AbortSignal;
+    readonly threshold?: number;
+    readonly maxProposals?: number;
+}
+export declare function runSelfImprove(input: SelfImproveInput): Promise<SelfImproveReport>;
+export declare function buildSelfImproveSteer(goal: string, report: SelfImproveReport): string;
+export declare function selfImproveSummary(report: SelfImproveReport): string;
+export declare function formatSelfImproveReport(report: SelfImproveReport): string;
+interface RealVisionShape {
+    readonly id?: string;
+    readonly title?: string;
+    readonly finalGoal?: string;
+    readonly value?: VisionValueLike | string;
+    readonly features?: readonly VisionFeatureLike[];
+    readonly readinessCriteria?: readonly ReadinessCriterionLike[];
+}
+export declare function fromVision(vision: RealVisionShape | VisionLike, summary?: string): VisionLike;
+export {};