@vascend/talos 0.1.0

package/dist/core/cli-args.js

@@ -0,0 +1,282 @@
+import { parseVibeMode } from "./vibe-modes.js";
+import { SessionIdError, validateSessionId } from "./session.js";
+export class CliArgumentError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "CliArgumentError";
+    }
+}
+export function parseCliArgs(argv) {
+    const args = {
+        mode: "tui",
+        json: false,
+        yolo: false,
+        addDirs: [],
+        promptTemplates: [],
+        skills: [],
+        noSkills: false,
+        excludeTools: [],
+        help: false,
+        version: false,
+        extensionFlags: [],
+    };
+    const positional = [];
+    let explicitMode = null;
+    let afterDoubleDash = false;
+    const requireValue = (index, flag) => {
+        const value = argv[index + 1];
+        if (!value || value.startsWith("-"))
+            throw new CliArgumentError(`${flag} richiede un valore`);
+        return value;
+    };
+    const requirePositive = (index, flag) => {
+        const raw = Number(requireValue(index, flag));
+        if (!Number.isFinite(raw) || raw <= 0)
+            throw new CliArgumentError(`${flag} richiede un numero maggiore di zero`);
+        return Math.trunc(raw);
+    };
+    const setMode = (mode, flag) => {
+        if (explicitMode && explicitMode !== mode) {
+            throw new CliArgumentError(`${flag} e la modalita' ${explicitMode} non possono essere usati insieme`);
+        }
+        explicitMode = mode;
+        args.mode = mode;
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (afterDoubleDash) {
+            positional.push(token);
+            continue;
+        }
+        if (token === "--") {
+            afterDoubleDash = true;
+            continue;
+        }
+        switch (token) {
+            case "-h":
+            case "--help":
+                args.help = true;
+                break;
+            case "-V":
+            case "--version":
+                args.version = true;
+                break;
+            case "-p":
+            case "--print":
+                setMode("print", token);
+                break;
+            case "--rpc":
+                setMode("rpc", token);
+                break;
+            case "--doctor":
+                setMode("doctor", token);
+                break;
+            // Lavoro autonomo: il ciclo fuori dalla conversazione.
+            case "--work":
+                setMode("work", token);
+                break;
+            case "--work-list":
+                setMode("work", token);
+                args.workList = true;
+                break;
+            case "--work-scope":
+                setMode("work", token);
+                args.workScope = requireValue(i, token);
+                i += 1;
+                break;
+            case "--work-verify":
+                setMode("work", token);
+                args.workVerify = requireValue(i, token);
+                i += 1;
+                break;
+            case "--work-max":
+                setMode("work", token);
+                args.workMax = requirePositive(i, token);
+                i += 1;
+                break;
+            case "--work-minutes":
+                setMode("work", token);
+                args.workMinutes = requirePositive(i, token);
+                i += 1;
+                break;
+            case "--json":
+                args.json = true;
+                break;
+            case "--yolo":
+                args.yolo = true;
+                break;
+            case "-m":
+            case "--model":
+                args.model = requireValue(i, token);
+                i += 1;
+                break;
+            case "-C":
+            case "--cwd":
+                args.cwd = requireValue(i, token);
+                i += 1;
+                break;
+            case "--add-dir":
+                args.addDirs.push(requireValue(i, token));
+                i += 1;
+                break;
+            case "--config":
+                args.config = requireValue(i, token);
+                i += 1;
+                break;
+            case "--prompt-template":
+                args.promptTemplates.push(requireValue(i, token));
+                i += 1;
+                break;
+            case "--skill":
+                args.skills.push(requireValue(i, token));
+                i += 1;
+                break;
+            case "--no-skills":
+                args.noSkills = true;
+                break;
+            case "--approve":
+                args.approve = true;
+                break;
+            case "--no-approve":
+                args.noApprove = true;
+                break;
+            case "--session-id":
+                args.sessionId = requireValue(i, token);
+                i += 1;
+                break;
+            case "-c":
+            case "--continue":
+                args.continueLast = true;
+                break;
+            case "--resume": {
+                const next = argv[i + 1];
+                if (next && !next.startsWith("-")) {
+                    args.sessionId = next;
+                    i += 1;
+                }
+                else {
+                    args.resumePicker = true;
+                }
+                break;
+            }
+            case "--name":
+                args.name = requireValue(i, token);
+                i += 1;
+                break;
+            case "--exclude-tools":
+                args.excludeTools.push(...requireValue(i, token).split(",").map((value) => value.trim()).filter(Boolean));
+                i += 1;
+                break;
+            case "--vibe":
+            case "--mode": {
+                const raw = requireValue(i, token);
+                const parsed = parseVibeMode(raw);
+                if (!parsed)
+                    throw new CliArgumentError(`modalita' vibe sconosciuta: ${raw}`);
+                args.vibeMode = parsed;
+                i += 1;
+                break;
+            }
+            default: {
+                if (token.startsWith("--")) {
+                    // Le estensioni vengono caricate dopo il parsing core. I flag custom
+                    // con valore usano --nome=valore, evitando ambiguita' col prompt.
+                    const eq = token.indexOf("=");
+                    args.extensionFlags.push(eq > 2
+                        ? { name: token.slice(0, eq), value: token.slice(eq + 1) }
+                        : { name: token });
+                }
+                else if (token.startsWith("-")) {
+                    throw new CliArgumentError(`flag sconosciuto: ${token}`);
+                }
+                else {
+                    positional.push(token);
+                }
+            }
+        }
+    }
+    if (args.help || args.version)
+        return Object.freeze({ ...args });
+    if (args.sessionId) {
+        try {
+            args.sessionId = validateSessionId(args.sessionId);
+        }
+        catch (err) {
+            if (err instanceof SessionIdError)
+                throw new CliArgumentError(err.message);
+            throw err;
+        }
+    }
+    if (args.approve && args.noApprove)
+        throw new CliArgumentError("--approve e --no-approve sono incompatibili");
+    if (args.continueLast && (args.sessionId || args.resumePicker)) {
+        throw new CliArgumentError("--continue non puo' essere combinato con --resume/--session-id");
+    }
+    if (args.resumePicker && args.mode !== "tui") {
+        throw new CliArgumentError("--resume senza id richiede la TUI");
+    }
+    if (args.json && args.mode === "tui") {
+        throw new CliArgumentError("--json richiede --print, --rpc, --doctor o --work");
+    }
+    if (positional.length) {
+        if (args.mode !== "print") {
+            throw new CliArgumentError("un prompt posizionale richiede --print (-p)");
+        }
+        args.prompt = positional.join(" ");
+    }
+    return Object.freeze({ ...args });
+}
+export function cliHelp() {
+    return `Horizon - agente Vascend da terminale
+
+USO
+  horizon [opzioni]
+  horizon --print [opzioni] "prompt"
+  horizon --rpc [opzioni]
+  horizon --doctor
+  horizon --work [--work-verify "npm test"] [--work-max N] [--work-minutes N]
+
+MODALITA'
+  -p, --print                 esegue un prompt one-shot
+      --rpc                   protocollo JSONL su stdin/stdout
+      --doctor                diagnostica ambiente (provider, modello, sessioni)
+      --json                  emette AgentEvent JSONL (print/RPC/work) o il report doctor
+
+LAVORO AUTONOMO (il ciclo sta fuori dalla conversazione)
+      --work                  prende le unita' dalla coda, una per agente NUOVO
+      --work-list             mostra la coda (stati, lease, tentativi) e esce
+      --work-scope <nome>     coda e memoria condivisa del progetto (default: default)
+      --work-verify <cmd>     comando che decide se un'unita' e' fatta (exit code)
+      --work-max <N>          quante unita' al massimo in questo giro (default 25)
+      --work-minutes <N>      smette di rivendicare dopo N minuti
+
+MODELLO E CONTESTO
+  -m, --model <provider/id>   seleziona provider e modello
+  -C, --cwd <path>            workspace seguito
+      --add-dir <path>        aggiunge una root allo stesso workspace (ripetibile)
+      --vibe <modalita>       auto, flow, debug, architect, ui, ship,
+                             migrate, security, swarm, ultracheck, ...
+      --config <path>         config esplicita
+      --prompt-template <p>   directory/file template aggiuntivo (ripetibile)
+      --skill <path>          skill aggiuntiva (ripetibile)
+      --no-skills             disabilita discovery skill
+
+SESSIONE E SICUREZZA
+  -c, --continue              riprende l'ultima sessione
+      --resume [id]           riprende id; senza id apre il picker TUI
+      --session-id <id>       usa una sessione specifica
+      --name <nome>           assegna un nome alla sessione
+      --approve               considera fidate le risorse locali
+      --no-approve            nega le risorse locali
+      --yolo                  auto-approva i tool (anche in TUI; usare con cautela)
+      --exclude-tools <a,b>   rimuove tool dal registry
+
+ALTRO
+  -h, --help                  mostra questo aiuto
+  -V, --version               mostra la versione
+      --                      termina il parsing delle opzioni
+
+I flag delle estensioni sono accettati dopo il bootstrap. Per un valore usa
+la forma non ambigua --nome=valore.`;
+}

package/dist/core/collapsible-output.d.ts

@@ -0,0 +1,38 @@
+export type CollapsibleState = "open" | "closed";
+export type ContentSource = string | (() => string);
+export interface CollapsibleOptions {
+    readonly summary: string;
+    readonly content: ContentSource;
+    readonly open?: boolean;
+    readonly onCleanup?: (id: string) => void;
+}
+export interface Collapsible {
+    readonly id: string;
+    summary: string;
+    state: CollapsibleState;
+    readonly createdAt: number;
+    readonly source: ContentSource;
+    materialized: string | null;
+    readonly onCleanup?: (id: string) => void;
+}
+export declare class CollapsibleRegistry {
+    private readonly items;
+    private readonly order;
+    private seq;
+    private readonly changeCbs;
+    register(opts: CollapsibleOptions): string;
+    get(id: string): Collapsible | undefined;
+    list(): readonly Collapsible[];
+    isOpen(id: string): boolean;
+    render(id: string): string;
+    open(id: string): boolean;
+    close(id: string): boolean;
+    toggle(id: string): CollapsibleState | null;
+    updateSummary(id: string, summary: string): boolean;
+    remove(id: string): boolean;
+    closeAll(): number;
+    size(): number;
+    onChange(cb: () => void): () => void;
+    private emitChange;
+}
+export declare const collapsibleRegistry: CollapsibleRegistry;

package/dist/core/collapsible-output.js

@@ -0,0 +1,143 @@
+// Utility riutilizzabile per OUTPUT COLLASSABILI/ESPANDIBILI in chat.
+//
+// Modella un blocco di output (es. il risultato di un comando) che puo' essere
+// mostrato in forma compatta (solo una riga di sintesi) oppure espanso (con il
+// contenuto completo). Lo stato e' apri/chiudi (open/closed) e quando il blocco
+// e' CHIUSO il suo contenuto pesante viene rilasciato (cleanup automatico), per
+// non trattenere stringhe enormi in memoria piu' del necessario.
+//
+// E' deliberatamente DISACCOPPIATA da qualunque comando o dalla TUI: non importa
+// nulla del rendering. Chi consuma (la TUI, un comando, un test) registra un
+// blocco, riceve un id stabile e poi lo apre/chiude/interroga. Un callback
+// onChange permette al consumatore di ri-renderizzare quando lo stato cambia.
+// Stesso stile di BackgroundManager: classe pura, zero dipendenze a runtime.
+// Registry dei blocchi collassabili. Gestisce id stabili, ordine d'inserimento,
+// transizioni di stato con cleanup e notifiche di cambiamento. Riutilizzabile:
+// se ne possono creare istanze separate (una per chat) o usarne una condivisa.
+export class CollapsibleRegistry {
+    items = new Map();
+    order = [];
+    seq = 0;
+    changeCbs = new Set();
+    // Registra un nuovo blocco e ne ritorna l'id stabile.
+    register(opts) {
+        this.seq += 1;
+        const id = `co${this.seq}`;
+        const open = opts.open === true;
+        const item = {
+            id,
+            summary: opts.summary,
+            state: open ? "open" : "closed",
+            createdAt: Date.now(),
+            source: opts.content,
+            materialized: open ? resolveSource(opts.content) : null,
+            onCleanup: opts.onCleanup,
+        };
+        this.items.set(id, item);
+        this.order.push(id);
+        this.emitChange();
+        return id;
+    }
+    get(id) { return this.items.get(id); }
+    // Blocchi in ordine d'inserimento.
+    list() {
+        return this.order.map((id) => this.items.get(id)).filter((x) => Boolean(x));
+    }
+    // true se il blocco esiste ed e' aperto.
+    isOpen(id) { return this.items.get(id)?.state === "open"; }
+    // Contenuto da mostrare: la sintesi se chiuso, il contenuto completo se aperto.
+    // Materializza il contenuto lazy alla prima apertura.
+    render(id) {
+        const it = this.items.get(id);
+        if (!it)
+            return "";
+        if (it.state === "closed")
+            return it.summary;
+        if (it.materialized === null)
+            it.materialized = resolveSource(it.source);
+        return it.materialized;
+    }
+    // Apre (espande) un blocco. No-op se gia' aperto o inesistente. Ritorna true
+    // se lo stato e' cambiato.
+    open(id) {
+        const it = this.items.get(id);
+        if (!it || it.state === "open")
+            return false;
+        it.state = "open";
+        it.materialized = resolveSource(it.source);
+        this.emitChange();
+        return true;
+    }
+    // Chiude (collassa) un blocco: rilascia il contenuto materializzato (cleanup
+    // automatico della memoria) e invoca onCleanup. No-op se gia' chiuso. Ritorna
+    // true se lo stato e' cambiato.
+    close(id) {
+        const it = this.items.get(id);
+        if (!it || it.state === "closed")
+            return false;
+        it.state = "closed";
+        it.materialized = null; // cleanup: non trattenere il contenuto pesante
+        this.emitChange();
+        it.onCleanup?.(it.id);
+        return true;
+    }
+    // Inverte lo stato del blocco. Ritorna il nuovo stato, o null se inesistente.
+    toggle(id) {
+        const it = this.items.get(id);
+        if (!it)
+            return null;
+        if (it.state === "open") {
+            this.close(id);
+            return "closed";
+        }
+        this.open(id);
+        return "open";
+    }
+    // Aggiorna la riga di sintesi (es. mentre l'output cresce). No-op se assente.
+    updateSummary(id, summary) {
+        const it = this.items.get(id);
+        if (!it)
+            return false;
+        it.summary = summary;
+        this.emitChange();
+        return true;
+    }
+    // Rimuove un blocco dal registry. Se era aperto, scatta prima il cleanup.
+    remove(id) {
+        const it = this.items.get(id);
+        if (!it)
+            return false;
+        if (it.state === "open") {
+            it.state = "closed";
+            it.materialized = null;
+            it.onCleanup?.(it.id);
+        }
+        this.items.delete(id);
+        const i = this.order.indexOf(id);
+        if (i >= 0)
+            this.order.splice(i, 1);
+        this.emitChange();
+        return true;
+    }
+    // Chiude tutti i blocchi aperti (cleanup di massa). Ritorna quanti ne ha chiusi.
+    closeAll() {
+        let n = 0;
+        for (const id of this.order)
+            if (this.close(id))
+                n += 1;
+        return n;
+    }
+    // Numero di blocchi registrati.
+    size() { return this.items.size; }
+    // Sottoscrive ai cambi di stato. Ritorna una funzione di unsubscribe.
+    onChange(cb) { this.changeCbs.add(cb); return () => this.changeCbs.delete(cb); }
+    emitChange() { for (const cb of this.changeCbs)
+        cb(); }
+}
+// Risolve una ContentSource al suo valore stringa (invoca la funzione se lazy).
+function resolveSource(src) {
+    return typeof src === "function" ? src() : src;
+}
+// Istanza condivisa di processo (comoda per la TUI; i test possono crearne di
+// proprie per isolamento).
+export const collapsibleRegistry = new CollapsibleRegistry();

package/dist/core/compaction-checkpoint.d.ts

@@ -0,0 +1,9 @@
+import type { PiConfig } from "./config.js";
+import type { Message } from "./types.js";
+import { type PlanTask } from "../vascend/plan-store.js";
+export interface CheckpointTask extends PlanTask {
+    readonly ref: string;
+}
+export declare function checkpointTasks(config: PiConfig, sessionId: string, owner?: string): readonly CheckpointTask[] | null;
+export declare function completedWaypoints(before: readonly CheckpointTask[], after: readonly CheckpointTask[]): readonly CheckpointTask[];
+export declare function compactionCheckpoint(tasks: readonly CheckpointTask[] | null, messages: readonly Message[], cutIndex: number): string;

package/dist/core/compaction-checkpoint.js

@@ -0,0 +1,58 @@
+import { VascendPlanStore } from "../vascend/plan-store.js";
+import { hasTaskEvidence } from "../vascend/plan-progress.js";
+// Read the same authoritative scope as the tool executor, including delegated
+// task ownership. A failed read is not evidence that work has been completed.
+export function checkpointTasks(config, sessionId, owner) {
+    try {
+        const scope = config.planStoreId ?? config.roomStoreId ?? sessionId;
+        const group = config.planCastle ?? owner?.trim();
+        return VascendPlanStore.open(config.sessionDir, scope, { strict: true }).castles()
+            .filter(plan => !group || plan.slug === group)
+            .flatMap(plan => plan.tasks
+            .filter(task => !config.planTasks?.length || config.planTasks.includes(task.id))
+            .map(task => ({ ...task, ref: `${plan.slug}/${task.id}` })));
+    }
+    catch {
+        return null;
+    }
+}
+export function completedWaypoints(before, after) {
+    const previous = new Map(before.map(task => [task.ref, task]));
+    return after.filter(task => {
+        const old = previous.get(task.ref);
+        return task.status === "completed" && hasTaskEvidence(task)
+            && (old?.status !== "completed" || old.title !== task.title);
+    });
+}
+const MAX_STATE_CHARS = 16_000;
+const clip = (text, max) => text.length <= max ? text : `${text.slice(0, max - 3)}...`;
+// Persist a small, deterministic continuation state alongside the model's
+// summary. This is data, never a claim that unchecked work has been verified.
+export function compactionCheckpoint(tasks, messages, cutIndex) {
+    const lines = [];
+    const requestIndex = messages.findLastIndex(message => message.role === "user"
+        && !message.content.some(part => part.type === "tool_result"));
+    if (requestIndex >= 0 && requestIndex < cutIndex) {
+        const request = messages[requestIndex].content.filter(part => part.type === "text").map(part => part.text).join("\n");
+        if (request)
+            lines.push(`Richiesta utente in corso: ${JSON.stringify(clip(request, 8_000))}`);
+    }
+    if (tasks?.length) {
+        lines.push("Stato del piano al checkpoint; prima di agire verifica lo stato corrente con vascend_status.");
+        const priority = { running: 0, failed: 1, pending: 2, completed: 3 };
+        const open = tasks.filter(task => task.status !== "completed")
+            .sort((a, b) => priority[a.status] - priority[b.status]);
+        const done = tasks.filter(task => task.status === "completed").slice(-8);
+        for (const task of [...open, ...done]) {
+            const line = JSON.stringify({ ref: task.ref, status: task.status, title: clip(task.title, 180),
+                ...(task.evidence?.length ? { evidence: clip(task.evidence.at(-1), 240) } : {}),
+                ...(task.notes?.length ? { notes: clip(task.notes.slice(-3).join(" | "), 480) } : {}), });
+            if (lines.join("\n").length + line.length > MAX_STATE_CHARS) {
+                lines.push("Altre attivita nel piano persistito: usa vascend_status con paginazione.");
+                break;
+            }
+            lines.push(line);
+        }
+    }
+    return lines.length ? `STATO DI RIPRESA (dati della sessione)\n${lines.join("\n")}` : "";
+}

package/dist/core/compaction.d.ts

@@ -0,0 +1,42 @@
+import type { Message, Provider, ToolDef } from "./types.js";
+export interface CompactionConfig {
+    readonly enabled: boolean;
+    readonly reserveTokens: number;
+    readonly keepRecentTokens: number;
+    readonly perRoom: boolean;
+    readonly roomFanout: number;
+}
+export declare const DEFAULT_COMPACTION: CompactionConfig;
+export declare function estimateTokens(text: string): number;
+export declare const IMAGE_TOKEN_ESTIMATE = 1400;
+export declare function estimateMessagesTokens(messages: readonly Message[]): number;
+export declare function estimateToolDefinitionTokens(tools: readonly ToolDef[]): number;
+export declare function contextWindowFor(model: string, override?: number): number;
+export declare function shouldCompact(contextTokens: number, contextWindow: number, reserveTokens: number): boolean;
+export type CompactionMove = "none" | "speculative" | "await" | "now";
+export declare const SPECULATIVE_FRACTION = 0.8;
+export declare function planCompactionMove(input: {
+    readonly enabled: boolean;
+    readonly tokens: number;
+    readonly contextWindow: number;
+    readonly reserveTokens: number;
+    readonly inFlight: boolean;
+    readonly speculativeFraction?: number;
+}): CompactionMove;
+export interface CompactionPlan {
+    readonly cutIndex: number;
+    readonly toSummarize: readonly Message[];
+    readonly toKeep: readonly Message[];
+}
+export declare function planCompaction(messages: readonly Message[], keepRecentTokens: number): CompactionPlan | null;
+export declare function verifySummary(summary: string, anchors: readonly string[], preservedMessages?: readonly Message[]): readonly string[];
+export declare function protectedExcerpts(messages: readonly Message[], anchors: readonly string[], maxChars?: number): readonly string[];
+export declare function withProtectedExcerpts(summary: string, excerpts: readonly string[]): string;
+export declare function repairInstructions(missing: readonly string[], base?: string): string;
+export declare function summarizeMessages(provider: Provider, toSummarize: readonly Message[], opts: {
+    readonly model: string;
+    readonly maxTokens: number;
+    readonly signal: AbortSignal;
+    readonly previousSummary?: string;
+    readonly instructions?: string;
+}): Promise<string>;