@vascend/talos 0.1.4 → 0.1.6

package/dist/remote/relay-client.d.ts

@@ -0,0 +1,58 @@
+export type StatoRelay = "connessione" | "collegato" | "attesa" | "chiuso";
+export type CodiceRelay = "piano" | "token" | "troppe_sessioni" | "occupato" | "rete" | "risposta" | "finita";
+export declare class RelayError extends Error {
+    readonly code: CodiceRelay;
+    readonly status?: number | undefined;
+    constructor(code: CodiceRelay, status?: number | undefined);
+}
+export interface ComandoRelay {
+    readonly id: string;
+    readonly cid: string;
+    readonly k: string;
+    readonly b?: string;
+}
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+type SocketCtor = new (url: string) => WebSocket;
+export interface RelayDeps {
+    readonly token: () => Promise<string>;
+    readonly fetchImpl?: FetchLike;
+    readonly WebSocketImpl?: SocketCtor;
+    readonly wait?: (ms: number) => Promise<void>;
+    readonly onStato?: (stato: StatoRelay, motivo?: string) => void;
+    readonly onComando?: (comando: ComandoRelay) => Promise<void>;
+    readonly onPresenza?: (viewer: number) => void;
+}
+export declare const RELAY_URL = "https://relay.vascend.it";
+export declare function relayOf(env: NodeJS.ProcessEnv): string;
+export interface MetaSessione {
+    readonly title: string;
+    readonly agent: string;
+    readonly device: string;
+}
+export declare class RelayHost {
+    private readonly base;
+    readonly sessione: string;
+    private readonly deps;
+    private ws;
+    private stato;
+    private prossimo;
+    private readonly inAttesa;
+    private readonly eseguiti;
+    private catenaComandi;
+    private chiuso;
+    private tentativi;
+    private constructor();
+    static apri(base: string, meta: MetaSessione, deps: RelayDeps): Promise<RelayHost>;
+    statoAttuale(): StatoRelay;
+    invia(k: string, b?: string): boolean;
+    chiudi(attesaMs?: number): Promise<void>;
+    private cambiaStato;
+    private connetti;
+    private riconnetti;
+    private spedisci;
+    private daRelay;
+    private ciao;
+    private conferma;
+    private comando;
+}
+export {};

package/dist/remote/relay-client.js

@@ -0,0 +1,315 @@
+// Talos come host del relay delle sessioni (relay.vascend.it): possiede la
+// sessione, trasmette gli eventi e riceve i comandi dei dispositivi abbinati.
+// Protocollo: vascend-streaming/services/relay/src/protocollo.ts.
+//
+//   - HTTP: POST /v1/sessions crea la sessione e da' un ticket da host;
+//     POST /v1/sessions/:id/tickets ne da' uno nuovo a ogni riconnessione.
+//   - WebSocket /v1/connect?ticket=...: il ticket vale 30 s e una volta sola,
+//     il token non finisce mai in un URL.
+//   - seq contigui da last_seq+1 (arriva nel hello), conferma cumulativa
+//     (ack). Gli eventi non confermati restano qui e si rimandano dopo una
+//     riconnessione; il relay scarta i doppioni.
+//   - i comandi si confermano (cmd_ack) dopo averli eseguiti: dopo una
+//     riconnessione il relay rimanda quelli non confermati, e qui si
+//     scartano per cid.
+export class RelayError extends Error {
+    code;
+    status;
+    constructor(code, status) {
+        super(code);
+        this.code = code;
+        this.status = status;
+    }
+}
+export const RELAY_URL = "https://relay.vascend.it";
+const TIMEOUT_MS = 12_000;
+const ID_SESSIONE = /^s_[0-9a-f]{32}$/;
+const TICKET = /^[0-9a-f]{64}$/;
+const ID_STREAM = /^\d{1,15}-\d{1,10}$/;
+const CID = /^[A-Za-z0-9_-]{8,64}$/;
+// Oltre questi eventi non confermati si smette di mandare i delta (effimeri);
+// gli eventi durevoli restano tutti, e si scarta solo sopra il tetto massimo.
+const TETTO_DELTA = 2_000;
+const TETTO_EVENTI = 20_000;
+// Codici di chiusura del relay (connessioni.ts) dopo cui riprovare non serve.
+const CHIUSURE_DEFINITIVE = {
+    4001: "accesso non valido",
+    4003: "accesso negato",
+    4009: "sessione aperta da un altro dispositivo",
+    4400: "messaggi non validi",
+    4404: "sessione chiusa",
+};
+function urlValido(url) {
+    try {
+        const u = new URL(url);
+        if (u.username || u.password || u.search || u.hash)
+            return false;
+        if (u.protocol === "https:")
+            return true;
+        return u.protocol === "http:" && (u.hostname === "localhost" || u.hostname === "127.0.0.1");
+    }
+    catch {
+        return false;
+    }
+}
+// Override solo per sviluppo/collaudo (stesse regole dell'issuer di Vascend ID).
+export function relayOf(env) {
+    const override = String(env["TALOS_RELAY_URL"] ?? "").trim();
+    return (override && urlValido(override) ? override : RELAY_URL).replace(/\/+$/, "");
+}
+export class RelayHost {
+    base;
+    sessione;
+    deps;
+    ws = null;
+    stato = "connessione";
+    prossimo = 1;
+    inAttesa = [];
+    eseguiti = new Set();
+    catenaComandi = Promise.resolve();
+    chiuso = false;
+    tentativi = 0;
+    constructor(base, sessione, deps) {
+        this.base = base;
+        this.sessione = sessione;
+        this.deps = deps;
+    }
+    // Crea la sessione sul relay e apre il collegamento.
+    static async apri(base, meta, deps) {
+        const data = await richiesta(base, deps, "POST", "/v1/sessions", meta);
+        const sessione = data["session"]?.["id"];
+        const ticket = data["ticket"];
+        if (typeof sessione !== "string" || !ID_SESSIONE.test(sessione) || typeof ticket !== "string" || !TICKET.test(ticket)) {
+            throw new RelayError("risposta");
+        }
+        const host = new RelayHost(base, sessione, deps);
+        host.connetti(ticket);
+        return host;
+    }
+    statoAttuale() { return this.stato; }
+    // Evento da trasmettere; `b` e' gia' cifrato. Falso se non e' stato accodato.
+    invia(k, b) {
+        if (this.chiuso)
+            return false;
+        if (this.inAttesa.length >= TETTO_EVENTI || (k === "delta" && this.inAttesa.length >= TETTO_DELTA))
+            return false;
+        const voce = { seq: this.prossimo++, k, b };
+        this.inAttesa.push(voce);
+        if (this.stato === "collegato")
+            this.spedisci(voce);
+        return true;
+    }
+    // Chiude per tutti: ultimi eventi (breve attesa della conferma), poi la
+    // sessione sul relay e il WebSocket.
+    async chiudi(attesaMs = 1_500) {
+        if (this.chiuso)
+            return;
+        const fine = Date.now() + attesaMs;
+        const wait = this.deps.wait ?? ((ms) => new Promise(r => setTimeout(r, ms)));
+        while (this.inAttesa.length > 0 && this.stato === "collegato" && Date.now() < fine)
+            await wait(50);
+        this.chiuso = true;
+        this.cambiaStato("chiuso");
+        try {
+            this.ws?.close(1000, "fine");
+        }
+        catch { /* gia' chiuso */ }
+        this.ws = null;
+        try {
+            await richiesta(this.base, this.deps, "DELETE", `/v1/sessions/${this.sessione}`);
+        }
+        catch { /* best-effort */ }
+    }
+    // --- collegamento -----------------------------------------------------------
+    cambiaStato(stato, motivo) {
+        if (this.stato === stato && !motivo)
+            return;
+        this.stato = stato;
+        this.deps.onStato?.(stato, motivo);
+    }
+    connetti(ticket) {
+        if (this.chiuso)
+            return;
+        const Ctor = this.deps.WebSocketImpl ?? globalThis.WebSocket;
+        if (!Ctor) {
+            this.chiuso = true;
+            this.cambiaStato("chiuso", "WebSocket non disponibile in questo runtime");
+            return;
+        }
+        const ws = new Ctor(`${this.base.replace(/^http/, "ws")}/v1/connect?ticket=${ticket}`);
+        this.ws = ws;
+        ws.addEventListener("message", (ev) => {
+            if (this.ws === ws && typeof ev.data === "string")
+                this.daRelay(ev.data);
+        });
+        ws.addEventListener("close", (ev) => {
+            if (this.ws !== ws)
+                return;
+            this.ws = null;
+            if (this.chiuso)
+                return;
+            const definitiva = CHIUSURE_DEFINITIVE[ev.code];
+            if (definitiva) {
+                this.chiuso = true;
+                this.cambiaStato("chiuso", definitiva);
+                return;
+            }
+            this.cambiaStato("attesa");
+            void this.riconnetti();
+        });
+        ws.addEventListener("error", () => { });
+    }
+    async riconnetti() {
+        const wait = this.deps.wait ?? ((ms) => new Promise(r => setTimeout(r, ms)));
+        while (!this.chiuso) {
+            const attesa = Math.min(30_000, 1_000 * 2 ** Math.min(this.tentativi, 5));
+            this.tentativi++;
+            await wait(attesa);
+            if (this.chiuso)
+                return;
+            try {
+                const data = await richiesta(this.base, this.deps, "POST", `/v1/sessions/${this.sessione}/tickets`, { role: "host" });
+                const ticket = data["ticket"];
+                if (typeof ticket !== "string" || !TICKET.test(ticket))
+                    throw new RelayError("risposta");
+                this.cambiaStato("connessione");
+                this.connetti(ticket);
+                return;
+            }
+            catch (e) {
+                const code = e instanceof RelayError ? e.code : "rete";
+                // Sessione chiusa o piano scaduto: inutile riprovare.
+                if (code === "finita" || code === "piano" || code === "token") {
+                    this.chiuso = true;
+                    this.cambiaStato("chiuso", code);
+                    return;
+                }
+            }
+        }
+    }
+    spedisci(voce) {
+        try {
+            this.ws?.send(JSON.stringify({ t: "ev", seq: voce.seq, k: voce.k, b: voce.b }));
+        }
+        catch { /* ripreso al prossimo hello */ }
+    }
+    daRelay(raw) {
+        let f;
+        try {
+            f = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (!f || typeof f !== "object")
+            return;
+        switch (f["t"]) {
+            case "hello": return this.ciao(Number(f["last_seq"]));
+            case "ack": return this.conferma(Number(f["seq"]));
+            case "cmd": return this.comando(f);
+            case "presence":
+                this.deps.onPresenza?.(Number(f["viewers"]) || 0);
+                return;
+            default: return;
+        }
+    }
+    ciao(ultimo) {
+        const salvato = Number.isSafeInteger(ultimo) && ultimo >= 0 ? ultimo : 0;
+        this.conferma(salvato);
+        // Il relay ha perso degli eventi (es. Redis svuotato): si rinumera da li'
+        // invece di restare fuori sequenza per sempre.
+        if (this.inAttesa.length > 0 && this.inAttesa[0].seq !== salvato + 1) {
+            this.inAttesa.forEach((v, i) => { v.seq = salvato + 1 + i; });
+        }
+        this.prossimo = Math.max(this.prossimo, salvato + 1 + this.inAttesa.length);
+        if (this.inAttesa.length === 0)
+            this.prossimo = Math.max(salvato + 1, this.prossimo);
+        this.tentativi = 0;
+        this.cambiaStato("collegato");
+        for (const v of this.inAttesa)
+            this.spedisci(v);
+    }
+    conferma(seq) {
+        if (!Number.isSafeInteger(seq))
+            return;
+        while (this.inAttesa.length > 0 && this.inAttesa[0].seq <= seq)
+            this.inAttesa.shift();
+    }
+    comando(f) {
+        const id = f["id"], cid = f["cid"], k = f["k"], b = f["b"];
+        if (typeof id !== "string" || !ID_STREAM.test(id) || typeof cid !== "string" || !CID.test(cid) || typeof k !== "string")
+            return;
+        const ws = this.ws;
+        const ack = () => { try {
+            if (this.ws === ws)
+                ws?.send(JSON.stringify({ t: "cmd_ack", id }));
+        }
+        catch { /* rimandato dal relay */ } };
+        if (this.eseguiti.has(cid)) {
+            ack();
+            return;
+        }
+        // In ordine, uno alla volta: un "stop" dopo un messaggio deve arrivare dopo.
+        this.catenaComandi = this.catenaComandi.then(async () => {
+            if (this.eseguiti.has(cid))
+                return ack();
+            this.eseguiti.add(cid);
+            if (this.eseguiti.size > 5_000)
+                this.eseguiti.delete(this.eseguiti.values().next().value);
+            try {
+                await this.deps.onComando?.({ id, cid, k, b: typeof b === "string" ? b : undefined });
+            }
+            catch { /* un comando rotto non ferma gli altri */ }
+            ack();
+        });
+    }
+}
+// --- HTTP ---------------------------------------------------------------------
+async function richiesta(base, deps, method, path, body) {
+    const token = await deps.token();
+    const f = deps.fetchImpl ?? fetch;
+    let response;
+    let raw;
+    try {
+        response = await f(base + path, {
+            method,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: "application/json",
+                ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            redirect: "error",
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        raw = await response.text();
+    }
+    catch {
+        throw new RelayError("rete");
+    }
+    if (raw.length > 65_536)
+        throw new RelayError("risposta", response.status);
+    if (!response.ok) {
+        const s = response.status;
+        if (s === 401)
+            throw new RelayError("token", s);
+        if (s === 402)
+            throw new RelayError("piano", s);
+        if (s === 404 || s === 409)
+            throw new RelayError("finita", s);
+        if (s === 429)
+            throw new RelayError("troppe_sessioni", s);
+        if (s === 503)
+            throw new RelayError("occupato", s);
+        throw new RelayError(s >= 500 ? "rete" : "risposta", s);
+    }
+    if (!raw)
+        return {};
+    try {
+        const data = JSON.parse(raw);
+        if (data && typeof data === "object" && !Array.isArray(data))
+            return data;
+    }
+    catch { /* sotto */ }
+    throw new RelayError("risposta", response.status);
+}

package/dist/remote/sessione-remota.d.ts

@@ -0,0 +1,60 @@
+import type { AgentEvent } from "../core/types.js";
+import { type RelayDeps, type StatoRelay } from "./relay-client.js";
+export declare const VIEWER_URL = "https://vascend.it/remoto";
+export interface ManiRemote {
+    readonly invia: (testo: string, subito: boolean) => boolean;
+    readonly ferma: () => boolean;
+}
+export interface AvvioRemoto {
+    readonly base: string;
+    readonly cwd: string;
+    readonly mani: ManiRemote;
+    readonly token: RelayDeps["token"];
+    readonly onStato?: (stato: StatoRelay, motivo?: string) => void;
+    readonly onPresenza?: (viewer: number) => void;
+    readonly relayDeps?: Omit<RelayDeps, "token" | "onStato" | "onComando" | "onPresenza">;
+    readonly now?: () => number;
+}
+export declare class SessioneRemota {
+    private readonly relay;
+    private readonly chiave;
+    readonly link: string;
+    private readonly mani;
+    private readonly now;
+    private catena;
+    private delta;
+    private timerDelta;
+    private risposta;
+    private viewer;
+    private readonly permessi;
+    private constructor();
+    static avvia(opts: AvvioRemoto): Promise<SessioneRemota>;
+    get id(): string;
+    statoRelay(): StatoRelay;
+    dispositivi(): number;
+    osserva(event: AgentEvent): void;
+    testo(delta: string): void;
+    rispostaCompleta(): void;
+    chiamataTool(c: {
+        readonly id: string;
+        readonly name: string;
+        readonly input: unknown;
+        readonly parent?: string;
+    }): void;
+    risultatoTool(r: {
+        readonly id: string;
+        readonly error: boolean;
+        readonly output: string;
+        readonly parent?: string;
+    }): void;
+    statoAgente(state: "thinking" | "working" | "waiting" | "idle" | "error", label?: string): void;
+    messaggioUtente(testo: string): void;
+    permessoConGara(azione: string, dettaglio: string, signal: AbortSignal, tui: (signal: AbortSignal) => Promise<boolean>): Promise<boolean>;
+    chiudi(): Promise<void>;
+    private comando;
+    private svuotaDelta;
+    private chiudiRisposta;
+    private stato;
+    private evento;
+    private accoda;
+}