@vascend/talos 0.1.0

package/dist/core/session-usage.js

@@ -0,0 +1,74 @@
+import { appendFileSync, existsSync, lstatSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { validateSessionId } from "./session.js";
+function usagePath(base, sessionId, create = false) {
+    const id = validateSessionId(sessionId);
+    const directory = join(base, "usage");
+    if (create)
+        mkdirSync(directory, { recursive: true });
+    if (existsSync(directory) && lstatSync(directory).isSymbolicLink())
+        throw new Error("Usage directory is a link");
+    const file = join(directory, `${id}.jsonl`);
+    if (existsSync(file) && lstatSync(file).isSymbolicLink())
+        throw new Error("Usage file is a link");
+    return file;
+}
+// Metadati separati dalla cronologia: checkout e compattazione non riducono il consumo.
+export function saveSessionUsage(base, sessionId, record) {
+    try {
+        appendFileSync(usagePath(base, sessionId, true), JSON.stringify(record) + "\n", { encoding: "utf8", mode: 0o600 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function readSessionUsage(base, sessionId) {
+    const records = new Map();
+    let incomplete = false;
+    try {
+        const file = usagePath(base, sessionId);
+        if (!existsSync(file))
+            return { records: [], incomplete: false };
+        for (const line of readFileSync(file, "utf8").split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const r = JSON.parse(line);
+                if (typeof r.id !== "string" || typeof r.model !== "string" || typeof r.providerId !== "string" ||
+                    typeof r.sessionId !== "string" || !Number.isFinite(r.at))
+                    throw new Error("Invalid usage entry");
+                if (r.usage && ![r.usage.inputTokens, r.usage.outputTokens, r.usage.cacheReadTokens ?? 0,
+                    r.usage.cacheWriteTokens ?? 0].every(n => typeof n === "number" && Number.isFinite(n) && n >= 0))
+                    throw new Error("Invalid token count");
+                records.set(r.id, r);
+            }
+            catch {
+                incomplete = true;
+            }
+        }
+    }
+    catch {
+        incomplete = true;
+    }
+    return { records: [...records.values()], incomplete };
+}
+// Include anche le chiamate di compattazione effettuate con questo provider.
+const trackedProviders = new WeakMap();
+export function trackSessionUsage(provider, base, sessionId, sink) {
+    const scope = `${base}\n${sessionId}`;
+    if (trackedProviders.get(provider) === scope)
+        return provider;
+    const tracked = { ...provider, id: provider.id, models: provider.models, supportsFastMode: provider.supportsFastMode, complete: async (request) => {
+            const result = await provider.complete(request);
+            const record = { id: randomUUID(), sessionId, providerId: provider.id,
+                model: request.model.startsWith(`${provider.id}/`) ? request.model : `${provider.id}/${request.model}`,
+                at: Date.now(), ...(result.usage ? { usage: result.usage } : {}), ...(result.limits ? { limits: result.limits } : {}) };
+            const persisted = saveSessionUsage(base, sessionId, record);
+            sink({ type: "usage", record, persisted });
+            return result;
+        } };
+    trackedProviders.set(tracked, scope);
+    return tracked;
+}

package/dist/core/session.d.ts

@@ -0,0 +1,58 @@
+import type { Message } from "./types.js";
+export declare const SESSION_ID_MAX_LENGTH = 200;
+export declare class SessionIdError extends Error {
+    constructor(id: string, reason: string);
+}
+export declare function validateSessionId(id: string): string;
+export declare function sessionFilePath(baseDir: string, id: string): string;
+export interface SessionSummary {
+    readonly id: string;
+    readonly name: string | null;
+    readonly updatedAt: number;
+    readonly messages: number;
+    readonly preview: string;
+}
+export declare function listSessions(baseDir: string): SessionSummary[];
+export interface SessionNode {
+    readonly id: string;
+    readonly parentId: string | null;
+    readonly message: Message;
+    readonly ts: number;
+}
+export interface CompactionEntry {
+    readonly type: "compaction";
+    readonly summary: string;
+    readonly firstKeptId: string;
+    readonly tokensBefore: number;
+    readonly ts: number;
+}
+export interface MetaEntry {
+    readonly type: "meta";
+    readonly name: string;
+    readonly ts: number;
+}
+export type SessionEntry = SessionNode | CompactionEntry | MetaEntry;
+export declare class Session {
+    readonly id: string;
+    private readonly file;
+    private readonly nodes;
+    private headId;
+    private compaction;
+    private nameValue;
+    private historyCache;
+    private constructor();
+    static create(baseDir: string, id?: string): Session;
+    static load(baseDir: string, id: string): Session;
+    get head(): string | null;
+    get name(): string | null;
+    setName(name: string): void;
+    append(message: Message): SessionNode;
+    checkout(id: string): boolean;
+    nodeChain(): readonly SessionNode[];
+    history(): readonly Message[];
+    compact(summary: string, firstKeptId: string, tokensBefore: number): void;
+    get lastCompaction(): CompactionEntry | null;
+    commonAncestor(aId: string, bId: string): string | null;
+    branchMessages(leafId: string, ancestorId: string | null): readonly Message[];
+    tree(): readonly SessionNode[];
+}

package/dist/core/session.js

@@ -0,0 +1,296 @@
+import { appendFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep, posix, win32 } from "node:path";
+import { sessionTitle } from "./session-title.js";
+// Gli id Talos diventano nomi di file. La validazione e la risoluzione vivono
+// qui, nel confine dello store, cosi' CLI, TUI, backend ed SDK non possono
+// aggirarle chiamando Session direttamente.
+export const SESSION_ID_MAX_LENGTH = 200;
+export class SessionIdError extends Error {
+    constructor(id, reason) {
+        super(`ID sessione non valido ${JSON.stringify(id)}: ${reason}`);
+        this.name = "SessionIdError";
+    }
+}
+// Mantiene tutti gli id prodotti da Talos (s-..., kw-..., rev-..., slug con
+// lettere/numeri/._-) e anche nomi leggibili, ma rifiuta sintassi che su POSIX
+// o Windows puo' cambiare directory, volume o stream del file.
+export function validateSessionId(id) {
+    if (!id.length)
+        throw new SessionIdError(id, "l'ID non puo' essere vuoto");
+    if (id.length > SESSION_ID_MAX_LENGTH) {
+        throw new SessionIdError(id, `massimo ${SESSION_ID_MAX_LENGTH} caratteri`);
+    }
+    if (id !== id.trim())
+        throw new SessionIdError(id, "niente spazi iniziali o finali");
+    if (id === "." || id === "..")
+        throw new SessionIdError(id, "'.' e '..' non sono ammessi");
+    if (id.includes("/") || id.includes("\\")) {
+        throw new SessionIdError(id, "i separatori di percorso '/' e '\\' non sono ammessi");
+    }
+    if (posix.isAbsolute(id) || win32.isAbsolute(id)) {
+        throw new SessionIdError(id, "i percorsi assoluti non sono ammessi");
+    }
+    if (/[:*?"<>|\u0000-\u001f\u007f]/u.test(id)) {
+        throw new SessionIdError(id, "contiene caratteri non validi per un nome file portabile");
+    }
+    if (/[. ]$/u.test(id)) {
+        throw new SessionIdError(id, "un ID non puo' terminare con punto o spazio");
+    }
+    // Windows interpreta questi nomi come device anche quando hanno estensioni.
+    const firstComponent = id.split(".", 1)[0].toUpperCase();
+    if (/^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/u.test(firstComponent)) {
+        throw new SessionIdError(id, "nome riservato dal filesystem Windows");
+    }
+    return id;
+}
+function assertContained(baseDir, target, id) {
+    const rel = relative(baseDir, target);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new SessionIdError(id, "il file risolto uscirebbe dalla directory delle sessioni");
+    }
+}
+// Risoluzione lessicale pubblica per chi deve conoscere il file di una
+// sessione. Il risultato e' sempre un figlio diretto assoluto di baseDir.
+export function sessionFilePath(baseDir, id) {
+    const sid = validateSessionId(id);
+    const base = resolve(baseDir);
+    const target = resolve(base, `${sid}.jsonl`);
+    assertContained(base, target, sid);
+    return target;
+}
+// Verifica anche il filesystem reale: un file sessione gia' esistente non puo'
+// essere un symlink che reindirizza append/read fuori da sessionDir.
+function prepareSessionFile(baseDir, id) {
+    const sid = validateSessionId(id);
+    const file = sessionFilePath(baseDir, sid);
+    mkdirSync(resolve(baseDir), { recursive: true });
+    const realBase = realpathSync(resolve(baseDir));
+    const realParent = realpathSync(dirname(file));
+    assertContained(realBase, realParent, sid);
+    if (existsSync(file)) {
+        if (lstatSync(file).isSymbolicLink()) {
+            throw new SessionIdError(sid, "il file sessione non puo' essere un collegamento simbolico");
+        }
+        assertContained(realBase, realpathSync(file), sid);
+    }
+    return { id: sid, file };
+}
+// Testo leggibile di un messaggio (concatena le parti testo).
+function messageText(m) {
+    return m.content.filter((p) => p.type === "text").map((p) => p.text).join(" ").trim();
+}
+// Anteprima dell'obiettivo: primo messaggio utente, ripulito dai tag iniettati
+// ([VASCEND...], [Riepilogo...]) cosi' il picker mostra il vero prompt.
+function goalPreview(history) {
+    for (const m of history) {
+        if (m.role !== "user")
+            continue;
+        const title = sessionTitle(messageText(m));
+        if (title)
+            return title;
+    }
+    return "";
+}
+// Elenca le sessioni di baseDir, ordinate dalla piu' recente. Salta i file
+// corrotti o vuoti. Usata da `/resume`, `/sessions` e dal flag `--continue`.
+export function listSessions(baseDir) {
+    if (!existsSync(baseDir))
+        return [];
+    const out = [];
+    for (const f of readdirSync(baseDir)) {
+        if (!f.endsWith(".jsonl"))
+            continue;
+        const id = f.replace(/\.jsonl$/, "");
+        try {
+            const s = Session.load(baseDir, id);
+            const chain = s.nodeChain();
+            if (!chain.length)
+                continue;
+            out.push({
+                id,
+                name: s.name,
+                updatedAt: chain[chain.length - 1].ts,
+                messages: chain.length,
+                preview: goalPreview(chain.map(node => node.message)),
+            });
+        }
+        catch { /* file corrotto/illeggibile: salta */ }
+    }
+    return out.sort((a, b) => b.updatedAt - a.updatedAt);
+}
+let counter = 0;
+function nodeId() {
+    counter += 1;
+    return `${Date.now().toString(36)}-${counter.toString(36)}`;
+}
+export class Session {
+    id;
+    file;
+    nodes = new Map();
+    headId = null;
+    compaction = null;
+    nameValue = null;
+    historyCache = null;
+    constructor(id, file) {
+        this.id = id;
+        this.file = file;
+    }
+    // Crea una nuova sessione persistita sotto baseDir/<id>.jsonl
+    static create(baseDir, id) {
+        const sid = id ?? `s-${Date.now().toString(36)}`;
+        const safe = prepareSessionFile(baseDir, sid);
+        return new Session(safe.id, safe.file);
+    }
+    // Carica una sessione esistente ricostruendo l'albero e l'eventuale
+    // compattazione (l'ultima entry vince).
+    static load(baseDir, id) {
+        // Garantisce la dir: con --session-id su un workspace nuovo il file non
+        // esiste ancora e il primo append fallirebbe con ENOENT.
+        const safe = prepareSessionFile(baseDir, id);
+        const s = new Session(safe.id, safe.file);
+        if (existsSync(s.file)) {
+            const raw = readFileSync(s.file, "utf8");
+            for (const line of raw.split("\n")) {
+                if (!line.trim())
+                    continue;
+                const parsed = JSON.parse(line);
+                if (parsed.type === "compaction") {
+                    s.compaction = parsed;
+                    continue;
+                }
+                if (parsed.type === "meta") {
+                    s.nameValue = parsed.name;
+                    continue;
+                }
+                const node = parsed;
+                s.nodes.set(node.id, node);
+                s.headId = node.id;
+            }
+        }
+        return s;
+    }
+    get head() {
+        return this.headId;
+    }
+    get name() {
+        return this.nameValue;
+    }
+    // Nome leggibile della sessione, persistito come entry meta.
+    setName(name) {
+        const entry = { type: "meta", name, ts: Date.now() };
+        appendFileSync(this.file, JSON.stringify(entry) + "\n", "utf8");
+        this.nameValue = name;
+    }
+    // Aggiunge un messaggio come figlio della testa corrente.
+    append(message) {
+        const node = {
+            id: nodeId(),
+            parentId: this.headId,
+            message,
+            ts: Date.now(),
+        };
+        appendFileSync(this.file, JSON.stringify(node) + "\n", "utf8");
+        this.nodes.set(node.id, node);
+        this.headId = node.id;
+        this.historyCache = null;
+        return node;
+    }
+    // Sposta la testa su un nodo esistente: i prossimi append creano un branch.
+    checkout(id) {
+        if (!this.nodes.has(id))
+            return false;
+        this.headId = id;
+        this.historyCache = null;
+        return true;
+    }
+    // Catena di nodi dalla radice alla testa.
+    nodeChain() {
+        const chain = [];
+        let cur = this.headId;
+        while (cur) {
+            const node = this.nodes.get(cur);
+            if (!node)
+                break;
+            chain.push(node);
+            cur = node.parentId;
+        }
+        return chain.reverse();
+    }
+    // Ricostruisce la cronologia lineare, applicando la compattazione: il
+    // prefisso fino a firstKeptId viene sostituito dal riassunto.
+    history() {
+        if (this.historyCache)
+            return this.historyCache;
+        const messages = [];
+        let cur = this.headId;
+        while (cur) {
+            const node = this.nodes.get(cur);
+            if (!node)
+                break;
+            messages.push(node.message);
+            // Il prefisso archiviato non serve per proiettare la finestra viva.
+            // Un checkout su un altro ramo non incontra firstKeptId e resta integro.
+            if (node.id === this.compaction?.firstKeptId && node.parentId && this.nodes.has(node.parentId)) {
+                messages.push({
+                    role: "user",
+                    content: [{ type: "text", text: `[Riepilogo del contesto precedente]\n\n${this.compaction.summary}` }],
+                });
+                break;
+            }
+            cur = node.parentId;
+        }
+        this.historyCache = Object.freeze(messages.reverse());
+        return this.historyCache;
+    }
+    // Registra una compattazione: riassunto + primo nodo da mantenere.
+    compact(summary, firstKeptId, tokensBefore) {
+        const entry = {
+            type: "compaction",
+            summary,
+            firstKeptId,
+            tokensBefore,
+            ts: Date.now(),
+        };
+        appendFileSync(this.file, JSON.stringify(entry) + "\n", "utf8");
+        this.compaction = entry;
+        this.historyCache = null;
+    }
+    get lastCompaction() {
+        return this.compaction;
+    }
+    // Antenato comune tra due nodi: serve alla summarization di branch quando si
+    // naviga via /tree (si riassume cio' che si abbandona).
+    commonAncestor(aId, bId) {
+        const ancestors = new Set();
+        let cur = aId;
+        while (cur) {
+            ancestors.add(cur);
+            cur = this.nodes.get(cur)?.parentId ?? null;
+        }
+        cur = bId;
+        while (cur) {
+            if (ancestors.has(cur))
+                return cur;
+            cur = this.nodes.get(cur)?.parentId ?? null;
+        }
+        return null;
+    }
+    // Messaggi sul percorso da `leafId` (incluso) risalendo fino a `ancestorId`
+    // (escluso): il ramo che viene abbandonato.
+    branchMessages(leafId, ancestorId) {
+        const out = [];
+        let cur = leafId;
+        while (cur && cur !== ancestorId) {
+            const node = this.nodes.get(cur);
+            if (!node)
+                break;
+            out.push(node.message);
+            cur = node.parentId;
+        }
+        return out.reverse();
+    }
+    // Vista ad albero per il comando /tree.
+    tree() {
+        return [...this.nodes.values()].sort((a, b) => a.ts - b.ts);
+    }
+}

package/dist/core/settings.d.ts

@@ -0,0 +1,17 @@
+export interface PersistableProvider {
+    readonly apiKey?: string;
+    readonly baseUrl?: string;
+}
+export interface PersistableSettings {
+    readonly model?: string;
+    readonly ui?: {
+        readonly theme?: string;
+    };
+    readonly effort?: string;
+    readonly fast?: boolean;
+    readonly permMode?: string;
+    readonly vibeMode?: string;
+    readonly providers?: Readonly<Record<string, PersistableProvider>>;
+}
+export declare function globalSettingsPath(env: NodeJS.ProcessEnv): string | null;
+export declare function saveGlobalSettings(env: NodeJS.ProcessEnv, patch: PersistableSettings): boolean;

package/dist/core/settings.js

@@ -0,0 +1,107 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { talosConfigDir } from "./env-paths.js";
+// Posizione del file globale. null se la config globale e' disattivata.
+export function globalSettingsPath(env) {
+    if (env["TALOS_NO_GLOBAL_CONFIG"] === "1")
+        return null;
+    return join(talosConfigDir(env), "config.json");
+}
+function readJson(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+    }
+    catch {
+        return {};
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Fonde le credenziali provider del patch nel blocco "providers" esistente,
+// preservando i provider non toccati e i campi non sovrascritti. Un campo a
+// stringa vuota cancella quel campo; una credenziale senza campi viene rimossa.
+function mergeProviders(current, patch) {
+    const base = {};
+    if (isRecord(current)) {
+        for (const [id, value] of Object.entries(current)) {
+            if (isRecord(value)) {
+                const cred = {};
+                if (typeof value["apiKey"] === "string")
+                    cred.apiKey = value["apiKey"];
+                if (typeof value["baseUrl"] === "string")
+                    cred.baseUrl = value["baseUrl"];
+                if (cred.apiKey !== undefined || cred.baseUrl !== undefined)
+                    base[id] = cred;
+            }
+        }
+    }
+    for (const [id, cred] of Object.entries(patch)) {
+        const next = { ...base[id] };
+        if (cred.apiKey !== undefined) {
+            if (cred.apiKey.trim())
+                next.apiKey = cred.apiKey.trim();
+            else
+                delete next.apiKey;
+        }
+        if (cred.baseUrl !== undefined) {
+            if (cred.baseUrl.trim())
+                next.baseUrl = cred.baseUrl.trim();
+            else
+                delete next.baseUrl;
+        }
+        if (next.apiKey === undefined && next.baseUrl === undefined)
+            delete base[id];
+        else
+            base[id] = next;
+    }
+    return base;
+}
+// Merge immutabile del patch sul contenuto esistente, preservando le altre
+// chiavi (e fondendo ui.* / providers.* senza azzerare il resto).
+function mergeSettings(current, patch) {
+    const next = { ...current };
+    if (patch.model !== undefined)
+        next["model"] = patch.model;
+    if (patch.effort !== undefined)
+        next["effort"] = patch.effort;
+    if (patch.fast !== undefined)
+        next["fast"] = patch.fast;
+    if (patch.permMode !== undefined)
+        next["permMode"] = patch.permMode;
+    if (patch.vibeMode !== undefined)
+        next["vibeMode"] = patch.vibeMode;
+    if (patch.ui) {
+        const baseUi = current["ui"] && typeof current["ui"] === "object" && !Array.isArray(current["ui"])
+            ? current["ui"]
+            : {};
+        next["ui"] = { ...baseUi, ...patch.ui };
+    }
+    if (patch.providers) {
+        const merged = mergeProviders(current["providers"], patch.providers);
+        if (Object.keys(merged).length > 0)
+            next["providers"] = merged;
+        else
+            delete next["providers"];
+    }
+    return next;
+}
+// Legge-modifica-scrive il file globale. Best effort: un errore di scrittura
+// (permessi, disco) non deve mai interrompere la sessione interattiva.
+export function saveGlobalSettings(env, patch) {
+    const path = globalSettingsPath(env);
+    if (!path)
+        return false;
+    try {
+        const merged = mergeSettings(readJson(path), patch);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(merged, null, 2) + "\n", "utf8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/storage-retention.d.ts

@@ -0,0 +1,21 @@
+export interface RetentionPolicy {
+    readonly days: number;
+    readonly maxBytes: number;
+}
+export interface RetentionReport {
+    readonly beforeBytes: number;
+    readonly afterBytes: number;
+    readonly removedGroups: number;
+    readonly removedFiles: number;
+    readonly protectedBytes: number;
+    readonly overBudget: boolean;
+}
+export declare function storageRetentionPolicy(env: NodeJS.ProcessEnv): RetentionPolicy;
+export declare function cleanSessionStorage(env: NodeJS.ProcessEnv, options?: {
+    readonly now?: number;
+    readonly dryRun?: boolean;
+    readonly force?: boolean;
+    readonly cwd?: string;
+}): RetentionReport | null;
+export declare function protectSessionStorage(store: string, owners: readonly string[], env: NodeJS.ProcessEnv, cwd?: string): () => void;
+export declare function maintainSessionStorage(env: NodeJS.ProcessEnv, cwd?: string): void;