@vascend/talos 0.1.0

package/dist/core/file-lease-store.d.ts

@@ -0,0 +1,14 @@
+import type { FileLease, FilePresence } from "./file-coordination.js";
+import { type ExecutionTarget } from "./execution-target.js";
+export declare function workspaceLeaseDirectory(cwd: string, target?: ExecutionTarget): string;
+/** Short record transactions; the write lease itself lasts until release or owner death. */
+export declare class FileLeaseStore {
+    private readonly path;
+    constructor(directory: string);
+    acquire(lease: FileLease): readonly FilePresence[];
+    validate(lease: FileLease): readonly FilePresence[];
+    release(lease: FileLease): void;
+    list(path?: string): readonly FilePresence[];
+    private transaction;
+    private read;
+}

package/dist/core/file-lease-store.js

@@ -0,0 +1,89 @@
+import { readFileSync, writeFileSync, renameSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { withLockSync } from "../vascend/file-lock.js";
+import { executionTargetKey, localExecutionTarget } from "./execution-target.js";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+export function workspaceLeaseDirectory(cwd, target = localExecutionTarget()) {
+    let root = resolve(cwd);
+    try {
+        root = realpathSync(root);
+    }
+    catch { /* workspace may be created later */ }
+    const workspace = createHash("sha256").update(process.platform === "win32" ? root.toLowerCase() : root).digest("hex");
+    return join(tmpdir(), "talos-file-leases", workspace, createHash("sha256").update(executionTargetKey(target)).digest("hex").slice(0, 24));
+}
+/** Short record transactions; the write lease itself lasts until release or owner death. */
+export class FileLeaseStore {
+    path;
+    constructor(directory) { this.path = join(directory, "leases.json"); }
+    acquire(lease) {
+        return this.transaction((records) => {
+            const current = records[lease.path];
+            if (current)
+                return [presence(current)];
+            records[lease.path] = { ...lease, pid: process.pid, at: Date.now() };
+            return [];
+        });
+    }
+    validate(lease) {
+        const current = this.read()[lease.path];
+        return current?.id === lease.id && current.pid === process.pid ? []
+            : current ? [presence(current)] : [{ path: lease.path, mode: "writing", updatedAt: Date.now(),
+                    actor: { id: "lease-lost", label: "lease di scrittura non piu' valida", kind: "external" } }];
+    }
+    release(lease) {
+        this.transaction((records) => {
+            if (records[lease.path]?.id === lease.id)
+                delete records[lease.path];
+        });
+    }
+    list(path) {
+        return Object.values(this.read()).filter((record) => (!path || record.path === path) && alive(record.pid)).map(presence);
+    }
+    transaction(fn) {
+        return withLockSync(this.path, () => {
+            const records = this.read();
+            for (const [key, record] of Object.entries(records))
+                if (!alive(record.pid))
+                    delete records[key];
+            const value = fn(records);
+            const temp = this.path + "." + randomUUID() + ".tmp";
+            writeFileSync(temp, JSON.stringify(records), "utf8");
+            renameSync(temp, this.path);
+            return value;
+        });
+    }
+    read() {
+        try {
+            const value = JSON.parse(readFileSync(this.path, "utf8"));
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                throw new Error("registro lease non valido");
+            const records = value;
+            for (const [key, row] of Object.entries(records)) {
+                if (!row || row.path !== key || !row.id || !Number.isInteger(row.pid) || row.pid <= 0 || !row.actor?.id) {
+                    throw new Error("registro lease non valido");
+                }
+            }
+            return records;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return {};
+            throw error;
+        }
+    }
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+function presence(record) {
+    return { path: record.path, actor: record.actor, mode: "writing", updatedAt: record.at };
+}

package/dist/core/image-limits.d.ts

@@ -0,0 +1,26 @@
+export declare const MAX_LATO_PX = 8000;
+export declare const LATO_CONSIGLIATO_PX = 1568;
+export declare const MAX_BYTES: number;
+export interface Dimensioni {
+    readonly larghezza: number;
+    readonly altezza: number;
+    readonly formato: "png" | "jpeg" | "gif" | "webp";
+}
+export declare function dimensioni(bytes: Uint8Array | null | undefined): Dimensioni | null;
+export declare function dimensioniDaBase64(data: string | null | undefined): Dimensioni | null;
+export declare function fattoreDiRiduzione(d: Dimensioni, latoMax?: number): number;
+export declare function ridimensionaA(d: Dimensioni, latoMax?: number): {
+    larghezza: number;
+    altezza: number;
+};
+export interface Verdetto {
+    readonly ok: boolean;
+    readonly spiegazione?: string;
+    readonly dimensioni?: Dimensioni;
+}
+export declare function verifica(bytesBase64: string, opts?: {
+    readonly nome?: string;
+    readonly latoMax?: number;
+}): Verdetto;
+export declare function spiegaErroreImmagine(dettaglio: string): string | null;
+export declare function messaggioErroreTurno(etichettaProvider: string, status: number, dettaglio: string): string;

package/dist/core/image-limits.js

@@ -0,0 +1,205 @@
+// Quanto e' grande davvero un'immagine, e cosa farne prima di spedirla.
+//
+// PERCHE' ESISTE. Anthropic rifiuta con un 400 le immagini che superano gli
+// 8000 pixel per lato, e il messaggio che torna e' questo:
+//
+//   messages.0.content.1.image.source.base64.data: At least one of the image
+//   dimensions exceed max allowed size: 8000 pixels
+//
+// L'utente non ha idea di cosa sia `messages.0.content.1`, e soprattutto: il
+// turno INTERO fallisce per un allegato. Non e' un errore da mostrare, e' un
+// errore da non far succedere.
+//
+// Qui si leggono le dimensioni dall'INTESTAZIONE del file, senza decodificare
+// l'immagine: bastano i primi byte, quindi costa niente anche su un file da
+// venti megabyte, e non serve nessuna dipendenza.
+//
+// Il ridimensionamento vero non sta qui: richiede API grafiche che Node non ha.
+// Lo fa chi le possiede (Horizon, tramite Electron nativeImage) prima ancora di
+// allegare. Questo modulo e' la rete di sicurezza per tutto il resto — immagini
+// che arrivano dagli strumenti, da un CLI, da una sessione ripristinata.
+// Il limite duro dell'API: oltre, la richiesta viene rifiutata.
+export const MAX_LATO_PX = 8000;
+// Il lato lungo consigliato. Oltre questa soglia l'immagine viene comunque
+// ridimensionata dal server, quindi i pixel in piu' non aggiungono dettaglio:
+// si pagano soltanto in tempo di caricamento.
+export const LATO_CONSIGLIATO_PX = 1568;
+// Tetto pratico per singola immagine in base64. L'API ne accetta di piu', ma
+// oltre questa soglia il turno diventa lento senza che il modello veda meglio.
+export const MAX_BYTES = 5 * 1024 * 1024;
+function leggiPng(b) {
+    // Firma PNG + primo chunk IHDR: larghezza e altezza sono due interi a 32 bit
+    // big-endian a offset fisso. Se non c'e' IHDR non e' un PNG valido.
+    if (b.length < 24)
+        return null;
+    const firma = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+    if (!firma.every((v, i) => b[i] === v))
+        return null;
+    if (String.fromCharCode(b[12], b[13], b[14], b[15]) !== "IHDR")
+        return null;
+    const leggi32 = (o) => ((b[o] << 24) | (b[o + 1] << 16) | (b[o + 2] << 8) | b[o + 3]) >>> 0;
+    return { larghezza: leggi32(16), altezza: leggi32(20), formato: "png" };
+}
+function leggiGif(b) {
+    // GIF87a/89a: dimensioni a 16 bit little-endian subito dopo la firma.
+    if (b.length < 10)
+        return null;
+    const testa = String.fromCharCode(...b.slice(0, 6));
+    if (testa !== "GIF87a" && testa !== "GIF89a")
+        return null;
+    return { larghezza: b[6] | (b[7] << 8), altezza: b[8] | (b[9] << 8), formato: "gif" };
+}
+function leggiJpeg(b) {
+    // JPEG e' una sequenza di segmenti: si salta di lunghezza in lunghezza fino a
+    // un marcatore SOF (Start Of Frame), che porta le dimensioni. Non si puo'
+    // leggere a offset fisso perche' prima ci sono EXIF, miniature, commenti.
+    if (b.length < 4 || b[0] !== 0xff || b[1] !== 0xd8)
+        return null;
+    let i = 2;
+    while (i + 9 < b.length) {
+        if (b[i] !== 0xff) {
+            i += 1;
+            continue;
+        } // riallineamento su padding
+        const marcatore = b[i + 1];
+        if (marcatore === 0xff) {
+            i += 1;
+            continue;
+        }
+        // SOF0..SOF15 tranne DHT (c4), JPG (c8) e DAC (cc), che non sono frame.
+        if (marcatore >= 0xc0 && marcatore <= 0xcf && marcatore !== 0xc4 && marcatore !== 0xc8 && marcatore !== 0xcc) {
+            return { altezza: (b[i + 5] << 8) | b[i + 6], larghezza: (b[i + 7] << 8) | b[i + 8], formato: "jpeg" };
+        }
+        const lunghezza = (b[i + 2] << 8) | b[i + 3];
+        if (lunghezza < 2)
+            return null; // segmento corrotto
+        i += 2 + lunghezza;
+    }
+    return null;
+}
+function leggiWebp(b) {
+    // RIFF....WEBP, poi un chunk VP8 (lossy), VP8L (lossless) o VP8X (esteso):
+    // tre formati diversi con tre codifiche diverse delle dimensioni.
+    if (b.length < 30)
+        return null;
+    if (String.fromCharCode(...b.slice(0, 4)) !== "RIFF")
+        return null;
+    if (String.fromCharCode(...b.slice(8, 12)) !== "WEBP")
+        return null;
+    const chunk = String.fromCharCode(...b.slice(12, 16));
+    if (chunk === "VP8 ") {
+        // Frame key: 3 byte di tag, poi la firma 9d 01 2a, poi 14 bit per lato.
+        if (b[23] !== 0x9d || b[24] !== 0x01 || b[25] !== 0x2a)
+            return null;
+        return {
+            larghezza: ((b[27] << 8) | b[26]) & 0x3fff,
+            altezza: ((b[29] << 8) | b[28]) & 0x3fff,
+            formato: "webp",
+        };
+    }
+    if (chunk === "VP8L") {
+        // 14 bit per lato impacchettati, meno uno.
+        const bits = b[21] | (b[22] << 8) | (b[23] << 16) | (b[24] << 24);
+        return { larghezza: (bits & 0x3fff) + 1, altezza: ((bits >> 14) & 0x3fff) + 1, formato: "webp" };
+    }
+    if (chunk === "VP8X") {
+        // Canvas esteso: 24 bit per lato, little-endian, meno uno.
+        const dim = (o) => (b[o] | (b[o + 1] << 8) | (b[o + 2] << 16)) + 1;
+        return { larghezza: dim(24), altezza: dim(27), formato: "webp" };
+    }
+    return null;
+}
+// Le dimensioni di un'immagine dai suoi primi byte, o null se il formato non e'
+// riconosciuto. Non lancia mai: un'immagine illeggibile non deve rompere un
+// turno, e in dubbio si lascia passare (sara' il server a dire la sua).
+export function dimensioni(bytes) {
+    if (!bytes || bytes.length < 10)
+        return null;
+    try {
+        return leggiPng(bytes) ?? leggiJpeg(bytes) ?? leggiGif(bytes) ?? leggiWebp(bytes);
+    }
+    catch {
+        return null;
+    }
+}
+export function dimensioniDaBase64(data) {
+    const testo = String(data ?? "").replace(/\s+/g, "");
+    if (!testo)
+        return null;
+    try {
+        // Bastano i primi byte: si decodifica solo la testa, non tutta l'immagine.
+        // 64 KB coprono anche i JPEG con EXIF e miniature prima del frame.
+        return dimensioni(Buffer.from(testo.slice(0, 87400), "base64"));
+    }
+    catch {
+        return null;
+    }
+}
+// Il fattore per rientrare in un lato massimo, oppure 1 se ci sta gia'.
+export function fattoreDiRiduzione(d, latoMax = LATO_CONSIGLIATO_PX) {
+    const lungo = Math.max(d.larghezza, d.altezza);
+    if (lungo <= latoMax || lungo <= 0)
+        return 1;
+    return latoMax / lungo;
+}
+// Le dimensioni dopo la riduzione, mai sotto un pixel.
+export function ridimensionaA(d, latoMax = LATO_CONSIGLIATO_PX) {
+    const f = fattoreDiRiduzione(d, latoMax);
+    return {
+        larghezza: Math.max(1, Math.round(d.larghezza * f)),
+        altezza: Math.max(1, Math.round(d.altezza * f)),
+    };
+}
+// Si puo' spedire? In caso contrario, la spiegazione dice cosa e' successo e
+// cosa fare — non "content.1.image.source.base64.data".
+export function verifica(bytesBase64, opts = {}) {
+    const latoMax = opts.latoMax ?? MAX_LATO_PX;
+    const d = dimensioniDaBase64(bytesBase64);
+    // Formato non riconosciuto: si lascia passare. Rifiutare cio' che non si sa
+    // leggere farebbe piu' danni del 400 che si vuole evitare.
+    if (!d)
+        return { ok: true };
+    const lungo = Math.max(d.larghezza, d.altezza);
+    if (lungo > latoMax) {
+        const nome = opts.nome ? `"${opts.nome}"` : "L'immagine";
+        return {
+            ok: false,
+            dimensioni: d,
+            spiegazione: `${nome} e' ${d.larghezza}×${d.altezza} pixel e non puo' essere letta dal modello: `
+                + `il limite e' ${latoMax} pixel per lato. `
+                + `Ridimensionala (il lato lungo entro ${LATO_CONSIGLIATO_PX} px va benissimo) e riprova.`,
+        };
+    }
+    return { ok: true, dimensioni: d };
+}
+// Il messaggio da mostrare all'utente quando l'API rifiuta comunque per via di
+// un'immagine. Riconosce la risposta di Anthropic e la traduce; se non e' quel
+// caso ritorna null e chi chiama mostra l'errore originale.
+export function spiegaErroreImmagine(dettaglio) {
+    return riconosci(dettaglio);
+}
+// L'errore da mostrare per un turno fallito: se riguarda un'immagine diventa
+// una frase in italiano, altrimenti resta quello del provider con il suo
+// codice. Un `400` grezzo con dentro `messages.0.content.1.image.source` non
+// dice a nessuno cosa fare.
+export function messaggioErroreTurno(etichettaProvider, status, dettaglio) {
+    const spiegazione = riconosci(dettaglio);
+    if (spiegazione)
+        return spiegazione;
+    return `Errore ${etichettaProvider} (${status}): ${dettaglio}`;
+}
+function riconosci(dettaglio) {
+    const testo = String(dettaglio ?? "");
+    if (/image dimensions exceed max allowed size/i.test(testo)) {
+        const px = /(\d{3,5})\s*pixels/i.exec(testo)?.[1] ?? String(MAX_LATO_PX);
+        return `Un'immagine allegata supera i ${px} pixel per lato, il massimo che il modello accetta. `
+            + `Ridimensionala (lato lungo entro ${LATO_CONSIGLIATO_PX} px) e rimandala.`;
+    }
+    if (/image exceeds \d+\s*MB|image.*too large/i.test(testo)) {
+        return "Un'immagine allegata e' troppo pesante per il modello. Riducila di dimensione e rimandala.";
+    }
+    if (/could not process image|unsupported image|invalid image/i.test(testo)) {
+        return "Un'immagine allegata non e' in un formato leggibile dal modello (servono PNG, JPEG, WebP o GIF).";
+    }
+    return null;
+}

package/dist/core/interruptible-completion.d.ts

@@ -0,0 +1,3 @@
+import type { CompletionRequest, ModelTurn, Provider } from "./types.js";
+import type { UserInbox } from "./user-inbox.js";
+export declare function completeWithSteering(provider: Provider, request: CompletionRequest, inbox?: UserInbox): Promise<ModelTurn | null>;

package/dist/core/interruptible-completion.js

@@ -0,0 +1,42 @@
+// Interrompe solo la richiesta al modello. I tool gia' avviati terminano con
+// il proprio risultato prima di consumare l'inbox nel loop dell'agente.
+export async function completeWithSteering(provider, request, inbox) {
+    if (!inbox?.onImmediate)
+        return provider.complete(request);
+    const controller = new AbortController();
+    let active = true;
+    let interrupt;
+    const interrupted = new Promise(resolve => { interrupt = resolve; });
+    const stop = () => {
+        interrupt({ text: "interrotto", toolCalls: [], stopReason: "error" });
+        controller.abort();
+    };
+    request.signal.addEventListener("abort", stop, { once: true });
+    const unsubscribe = inbox.onImmediate(() => {
+        interrupt(null);
+        controller.abort();
+    });
+    if (request.signal.aborted)
+        stop();
+    try {
+        if (controller.signal.aborted)
+            return await interrupted;
+        return await Promise.race([interrupted, provider.complete({
+                ...request,
+                signal: controller.signal,
+                onDelta: delta => { if (active && !controller.signal.aborted)
+                    request.onDelta?.(delta); },
+                onToolDelta: delta => { if (active && !controller.signal.aborted)
+                    request.onToolDelta?.(delta); },
+                onReasoning: delta => { if (active && !controller.signal.aborted)
+                    request.onReasoning?.(delta); },
+                onActivity: label => { if (active && !controller.signal.aborted)
+                    request.onActivity?.(label); },
+            })]);
+    }
+    finally {
+        active = false;
+        unsubscribe();
+        request.signal.removeEventListener("abort", stop);
+    }
+}

package/dist/core/kingdoms-mode-state.d.ts

@@ -0,0 +1,24 @@
+export declare const KINGDOMS_TRIGGER_KEYWORD = "ultracheck";
+export type KingdomsModeSource = "default" | "keyword" | "manual" | "stored";
+export interface KingdomsModeState {
+    readonly enabled: boolean;
+    readonly source: KingdomsModeSource;
+    readonly updatedAt: string;
+}
+export declare const DEFAULT_KINGDOMS_MODE_STATE: KingdomsModeState;
+export interface KingdomsTriggerOptions {
+    readonly detect?: (text: string) => boolean;
+    readonly keyword?: string;
+}
+export declare function kingdomsModeFile(env: NodeJS.ProcessEnv): string;
+export declare function readKingdomsModeState(env: NodeJS.ProcessEnv): KingdomsModeState;
+export declare function writeKingdomsModeState(env: NodeJS.ProcessEnv, state: KingdomsModeState): KingdomsModeState;
+export declare function isKingdomsModeEnabled(state: KingdomsModeState): boolean;
+export declare function enableKingdomsMode(state: KingdomsModeState, source?: KingdomsModeSource, now?: () => string): KingdomsModeState;
+export declare function disableKingdomsMode(state: KingdomsModeState, source?: KingdomsModeSource, now?: () => string): KingdomsModeState;
+export declare function toggleKingdomsMode(state: KingdomsModeState, now?: () => string): KingdomsModeState;
+export declare function promptHasTrigger(text: string, opts?: KingdomsTriggerOptions): boolean;
+export declare function applyPromptTrigger(state: KingdomsModeState, prompt: string, opts?: KingdomsTriggerOptions, now?: () => string): KingdomsModeState;
+export declare function setKingdomsModeEnabled(env: NodeJS.ProcessEnv, enabled: boolean, source?: KingdomsModeSource): KingdomsModeState;
+export declare function toggleKingdomsModePersisted(env: NodeJS.ProcessEnv): KingdomsModeState;
+export declare function applyPromptTriggerPersisted(env: NodeJS.ProcessEnv, prompt: string, opts?: KingdomsTriggerOptions): KingdomsModeState;

package/dist/core/kingdoms-mode-state.js

@@ -0,0 +1,139 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+// Stato applicativo + toggle "Kingdoms Mode".
+//
+// La modalita' Kingdoms si ATTIVA quando il prompt dell'utente contiene la
+// parola chiave 'ultracheck' (vedi applyPromptTrigger). Questo modulo possiede
+// SOLO lo stato e le sue transizioni (abilitazione/disabilitazione/persistenza):
+// la RILEVAZIONE della keyword puo' arrivare da un detector esterno (peer
+// keyword-detector) passato come predicate opzionale; in sua assenza si usa un
+// matcher interno di default.
+//
+// Lo stato e' persistito come JSON in ~/.talos/agent/kingdoms-mode.json (stesso
+// pattern di trust.ts: directory di config overridabile via TALOS_CONFIG_DIR).
+// Tutte le transizioni sono IMMUTABILI: si crea un nuovo stato, non si muta.
+// Parola chiave che, presente nel prompt, attiva la modalita'.
+export const KINGDOMS_TRIGGER_KEYWORD = "ultracheck";
+// Stato iniziale: modalita' spenta.
+export const DEFAULT_KINGDOMS_MODE_STATE = {
+    enabled: false,
+    source: "default",
+    updatedAt: "",
+};
+// Path del file di stato persistito. Override della dir via TALOS_CONFIG_DIR
+// (parita' con trust.ts), altrimenti ~/.talos/agent.
+export function kingdomsModeFile(env) {
+    const override = env["TALOS_CONFIG_DIR"];
+    const base = override ? override : join(homedir(), ".talos", "agent");
+    return join(base, "kingdoms-mode.json");
+}
+function coerceSource(value) {
+    return value === "keyword" || value === "manual" || value === "stored" || value === "default"
+        ? value
+        : "stored";
+}
+// Normalizza un oggetto sconosciuto in uno stato valido (difensivo verso JSON
+// corrotti o di versioni precedenti).
+function coerceState(raw, source) {
+    if (typeof raw !== "object" || raw === null)
+        return DEFAULT_KINGDOMS_MODE_STATE;
+    const obj = raw;
+    return {
+        enabled: obj["enabled"] === true,
+        source: coerceSource(obj["source"]),
+        updatedAt: typeof obj["updatedAt"] === "string" ? obj["updatedAt"] : "",
+    };
+}
+// Legge lo stato persistito. Ritorna lo stato di default se assente/illeggibile.
+export function readKingdomsModeState(env) {
+    const file = kingdomsModeFile(env);
+    if (!existsSync(file))
+        return DEFAULT_KINGDOMS_MODE_STATE;
+    try {
+        const raw = JSON.parse(readFileSync(file, "utf8"));
+        return coerceState(raw, "stored");
+    }
+    catch {
+        return DEFAULT_KINGDOMS_MODE_STATE;
+    }
+}
+// Persiste lo stato su disco (crea la directory se serve). Ritorna lo stato
+// scritto (per concatenare). Operazione idempotente.
+export function writeKingdomsModeState(env, state) {
+    const file = kingdomsModeFile(env);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(state, null, 2) + "\n", "utf8");
+    return state;
+}
+// --- Query -----------------------------------------------------------------
+export function isKingdomsModeEnabled(state) {
+    return state.enabled;
+}
+// --- Transizioni immutabili (puro stato, niente I/O) -----------------------
+function transition(state, enabled, source, now) {
+    // Se non cambia nulla, ritorna lo stato invariato (idempotenza, nessun
+    // aggiornamento spurio del timestamp).
+    if (state.enabled === enabled)
+        return state;
+    return { enabled, source, updatedAt: now() };
+}
+const isoNow = () => new Date().toISOString();
+// Abilita la modalita'. `source` distingue keyword vs manuale (default manuale).
+export function enableKingdomsMode(state, source = "manual", now = isoNow) {
+    return transition(state, true, source, now);
+}
+// Disabilita la modalita'.
+export function disableKingdomsMode(state, source = "manual", now = isoNow) {
+    return transition(state, false, source, now);
+}
+// Inverte lo stato corrente (toggle esplicito).
+export function toggleKingdomsMode(state, now = isoNow) {
+    return transition(state, !state.enabled, "manual", now);
+}
+// --- Trigger da keyword nel prompt -----------------------------------------
+// True se il testo contiene la keyword di attivazione. Usa il detector esterno
+// se fornito, altrimenti un confronto case-insensitive sulla parola.
+export function promptHasTrigger(text, opts = {}) {
+    if (opts.detect)
+        return opts.detect(text);
+    const keyword = (opts.keyword ?? KINGDOMS_TRIGGER_KEYWORD).toLowerCase();
+    if (!keyword)
+        return false;
+    return text.toLowerCase().includes(keyword);
+}
+// Applica il trigger al prompt: se il prompt contiene la keyword, ATTIVA la
+// modalita' (source="keyword"); altrimenti lascia lo stato invariato. Il
+// trigger non disattiva mai (la presenza/assenza della parola non spegne una
+// modalita' gia' accesa): la disattivazione e' un'azione esplicita.
+export function applyPromptTrigger(state, prompt, opts = {}, now = isoNow) {
+    if (!promptHasTrigger(prompt, opts))
+        return state;
+    return enableKingdomsMode(state, "keyword", now);
+}
+// --- Helper con persistenza (I/O) ------------------------------------------
+// Comodi per i consumer (TUI/agent): leggono, transizionano e ripersistono.
+export function setKingdomsModeEnabled(env, enabled, source = "manual") {
+    const current = readKingdomsModeState(env);
+    const next = transition(current, enabled, source, isoNow);
+    if (next === current)
+        return current;
+    return writeKingdomsModeState(env, next);
+}
+export function toggleKingdomsModePersisted(env) {
+    const current = readKingdomsModeState(env);
+    const next = toggleKingdomsMode(current);
+    if (next === current)
+        return current;
+    return writeKingdomsModeState(env, next);
+}
+// Legge lo stato, applica il trigger sul prompt e — se cambia — lo persiste.
+// Ritorna lo stato risultante. Usalo nel flusso del turno per "accendere"
+// Kingdoms Mode appena l'utente scrive 'ultracheck'.
+export function applyPromptTriggerPersisted(env, prompt, opts = {}) {
+    const current = readKingdomsModeState(env);
+    const next = applyPromptTrigger(current, prompt, opts);
+    if (next === current)
+        return current;
+    return writeKingdomsModeState(env, next);
+}

package/dist/core/licenza.d.ts

@@ -0,0 +1,38 @@
+export declare const CHIAVE_PUBBLICA: string;
+export declare const EMITTENTE = "vascend";
+export declare const SCOPO = "offline-entitlement";
+export interface ClaimsProva {
+    readonly purpose?: string;
+    readonly iss?: string;
+    readonly exp?: number;
+    readonly nbf?: number;
+    readonly email?: string;
+    readonly tier?: string;
+}
+export type EsitoProva = {
+    readonly ok: true;
+    readonly claims: ClaimsProva;
+} | {
+    readonly ok: false;
+    readonly motivo: string;
+};
+export declare function verificaProva(token: string, chiavePubblicaPem?: string, opts?: {
+    adesso?: number;
+    emittente?: string;
+}): EsitoProva;
+export declare const TOLLERANZA_INDIETRO_S: number;
+export declare function orologioAttendibile(adesso: number, massimoVisto: number, tolleranza?: number): boolean;
+export declare function nuovoMassimo(adesso: number, massimoVisto: number): number;
+export interface ValutazioneProva {
+    readonly ok: boolean;
+    readonly motivo?: string;
+    readonly claims?: ClaimsProva;
+    readonly massimoVisto: number;
+}
+export declare function valuta(p: {
+    token: string;
+    chiavePubblicaPem?: string;
+    adesso?: number;
+    massimoVisto?: number;
+    emittente?: string;
+}): ValutazioneProva;