@vascend/talos 0.1.0

package/dist/extensions/loader.js

@@ -0,0 +1,474 @@
+import { readdirSync, existsSync } from "node:fs";
+import { join, resolve, basename } from "node:path";
+import { pathToFileURL } from "node:url";
+import { spawn } from "node:child_process";
+import { installCodeGraphRuntime } from "../vascend/code-graph-runtime.js";
+import { ExtensionSettingsStore } from "./settings.js";
+const headlessUi = {
+    confirm: async () => false,
+    select: async () => null,
+    input: async () => null,
+    notify: (message, type) => process.stderr.write(`[ext:${type ?? "info"}] ${message}\n`),
+    setStatus: () => { },
+    setWidget: () => { },
+};
+function messageText(content) {
+    if (typeof content === "string")
+        return content;
+    return content.filter((part) => part.type === "text").map((part) => part.text ?? "").join("\n");
+}
+function execForExtension(command, args, options = {}) {
+    return new Promise((done) => {
+        const child = spawn(command, [...args], {
+            cwd: options.cwd,
+            env: options.env ? { ...process.env, ...options.env } : process.env,
+            windowsHide: true,
+            signal: options.signal,
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const finish = (code, killed) => {
+            if (settled)
+                return;
+            settled = true;
+            done({ stdout, stderr, code, killed });
+        };
+        child.stdout?.on("data", (chunk) => { stdout += chunk.toString(); });
+        child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
+        child.on("error", (error) => { stderr += error.message; finish(-1, child.killed); });
+        child.on("close", (code) => finish(code ?? -1, child.killed));
+        if (options.timeout && options.timeout > 0) {
+            const timer = setTimeout(() => child.kill(), options.timeout);
+            child.once("close", () => clearTimeout(timer));
+        }
+    });
+}
+function emptyPerExt() {
+    return {
+        tools: new Set(),
+        commands: new Set(),
+        shortcuts: new Set(),
+        flags: new Set(),
+        renderers: new Set(),
+        providers: new Set(),
+        handlers: [],
+        systemHooks: [],
+    };
+}
+// Raccoglie cio' che le estensioni registrano ed espone un bus eventi che il
+// loop dell'agente interroga ai punti chiave (parita' Pi ExtensionApi).
+export class ExtensionHost {
+    tools;
+    cwd;
+    commands = new Map();
+    shortcuts = new Map();
+    flags = new Map();
+    renderers = new Map();
+    pendingUserMessages = [];
+    pendingMessages = [];
+    systemHooks = [];
+    systemAppends = [];
+    handlers = new Map();
+    piFlagValues = new Map();
+    sharedEvents = new Map();
+    bindings = {};
+    // Inventario per-estensione: id file -> cosa ha registrato. Vuoto finche' non
+    // si carica. Riempito quando `currentExt` e' impostato (durante loadModule).
+    perExt = new Map();
+    currentExt = null;
+    // Estensioni esistenti su disco (anche quelle disabilitate, non in perExt).
+    knownFiles = [];
+    settings;
+    constructor(tools, cwd) {
+        this.tools = tools;
+        this.cwd = cwd;
+        this.settings = ExtensionSettingsStore.open(cwd);
+        // Il grafo strutturale viene alimentato dai tool reali senza aggiungere
+        // logica al loop dell'agente. Il wrapper e' best-effort e idempotente.
+        installCodeGraphRuntime(tools);
+    }
+    bind(bindings) {
+        this.bindings = { ...this.bindings, ...bindings };
+    }
+    // Registrazioni dell'estensione corrente (durante il load). Fuori dal load
+    // ritorna un contenitore usa-e-getta non tracciato.
+    slot() {
+        if (!this.currentExt)
+            return emptyPerExt();
+        let s = this.perExt.get(this.currentExt);
+        if (!s) {
+            s = emptyPerExt();
+            this.perExt.set(this.currentExt, s);
+        }
+        return s;
+    }
+    ctx() {
+        const b = this.bindings;
+        const base = b.systemPrompt?.() ?? "";
+        return {
+            cwd: this.cwd,
+            mode: b.mode ?? "sdk",
+            hasUI: Boolean(b.ui),
+            isProjectTrusted: () => b.isProjectTrusted?.() ?? false,
+            getContextUsage: () => b.contextUsage?.() ?? { tokens: 0, window: 0 },
+            getSystemPrompt: () => base,
+            getSystemPromptOptions: () => ({ base, appended: [...this.systemAppends] }),
+            ui: b.ui ?? headlessUi,
+            sessionManager: {
+                entries: () => b.sessionEntries?.() ?? [],
+                getBranch: () => b.sessionEntries?.() ?? [],
+                getLeafId: () => b.sessionLeafId?.() ?? null,
+            },
+        };
+    }
+    adaptTool(definition) {
+        if ("handler" in definition)
+            return definition;
+        return {
+            name: definition.name,
+            title: definition.label ?? definition.title,
+            description: definition.description,
+            inputSchema: definition.parameters,
+            ...(definition.outputSchema ? { outputSchema: definition.outputSchema } : {}),
+            handler: async (input, toolCtx) => {
+                const result = await definition.execute(`talos-${Date.now().toString(36)}`, input, toolCtx.signal, () => { }, this.ctx());
+                if (typeof result === "string")
+                    return result;
+                if (result && typeof result === "object" && "details" in result && !("structuredContent" in result)) {
+                    const details = result.details;
+                    const structuredContent = details && typeof details === "object" && !Array.isArray(details)
+                        ? details
+                        : undefined;
+                    const normalized = {
+                        ...(result.content ? { content: result.content } : {}),
+                        ...(structuredContent ? { structuredContent } : {}),
+                        ...(result.isError !== undefined ? { isError: result.isError } : {}),
+                    };
+                    return normalized;
+                }
+                return result;
+            },
+        };
+    }
+    api() {
+        // Durante il caricamento `currentExt` e' impostato: ogni registrazione viene
+        // annotata nell'inventario per-estensione (per reload e gestione).
+        const slot = this.slot();
+        const extId = this.currentExt;
+        return {
+            cwd: this.cwd,
+            registerTool: (definition) => {
+                const tool = this.adaptTool(definition);
+                this.tools.register(tool);
+                slot.tools.add(tool.name);
+            },
+            registerCommand: (command, options) => {
+                const cmd = typeof command === "string"
+                    ? {
+                        name: command,
+                        description: options?.description ?? "",
+                        run: async (args) => {
+                            const value = await options?.handler(args, this.ctx());
+                            return typeof value === "string" ? value : null;
+                        },
+                    }
+                    : command;
+                this.commands.set(cmd.name, cmd);
+                slot.commands.add(cmd.name);
+            },
+            registerShortcut: (shortcut, options) => {
+                const s = typeof shortcut === "string"
+                    ? {
+                        key: shortcut,
+                        description: options?.description ?? "",
+                        run: (ctx) => options?.handler(ctx),
+                    }
+                    : shortcut;
+                this.shortcuts.set(s.key, s);
+                slot.shortcuts.add(s.key);
+            },
+            registerFlag: (flag, options) => {
+                const piName = typeof flag === "string" ? flag : null;
+                if (piName && options?.default !== undefined)
+                    this.piFlagValues.set(piName, options.default);
+                const f = typeof flag === "string"
+                    ? {
+                        name: flag.startsWith("--") ? flag : `--${flag}`,
+                        description: options?.description ?? "",
+                        hasValue: options?.type === "string",
+                        run: (value) => {
+                            this.piFlagValues.set(flag, options?.type === "string" ? value ?? "" : true);
+                        },
+                    }
+                    : flag;
+                this.flags.set(f.name, f);
+                slot.flags.add(f.name);
+            },
+            getFlag: (name) => this.piFlagValues.get(name),
+            getAllTools: () => this.tools.names().flatMap((name) => {
+                const tool = this.tools.get(name);
+                return tool ? [{
+                        name: tool.name,
+                        description: tool.description,
+                        parameters: tool.schema,
+                        sourceInfo: {
+                            path: slot.tools.has(name) ? `<extension:${extId ?? "runtime"}>` : `<builtin:${name}>`,
+                            source: slot.tools.has(name) ? "extension" : "builtin",
+                            scope: "temporary",
+                            origin: "top-level",
+                        },
+                    }] : [];
+            }),
+            getActiveTools: () => this.tools.activeNames(),
+            setActiveTools: (names) => this.tools.setActive(names),
+            exec: (command, args, options) => execForExtension(command, args, options),
+            events: {
+                on: (name, handler) => {
+                    const handlers = this.sharedEvents.get(name) ?? new Set();
+                    handlers.add(handler);
+                    this.sharedEvents.set(name, handlers);
+                },
+                off: (name, handler) => this.sharedEvents.get(name)?.delete(handler),
+                emit: (name, data) => {
+                    for (const handler of this.sharedEvents.get(name) ?? [])
+                        handler(data);
+                },
+            },
+            registerProvider: (name, config) => {
+                this.bindings.registerProvider?.(name, config);
+                slot.providers.add(name);
+            },
+            unregisterProvider: (name) => this.bindings.unregisterProvider?.(name),
+            registerMessageRenderer: (type, renderer) => {
+                this.renderers.set(type, renderer);
+                slot.renderers.add(type);
+            },
+            onSystemPrompt: (fn) => {
+                this.systemHooks.push(fn);
+                slot.systemHooks.push(fn);
+            },
+            on: (event, handler) => {
+                const list = this.handlers.get(event) ?? [];
+                list.push(handler);
+                this.handlers.set(event, list);
+                slot.handlers.push({ event, handler: handler });
+            },
+            sendMessage: (message, opts) => {
+                const content = typeof message === "string" ? message : messageText(message.content);
+                const display = typeof message === "string" ? opts?.display ?? true : message.display ?? opts?.display ?? true;
+                this.pendingMessages.push({ content, display });
+            },
+            sendUserMessage: (content) => this.pendingUserMessages.push(messageText(content)),
+            appendEntry: (type, data) => this.bindings.appendEntry?.(type, data),
+            setSessionName: (name) => this.bindings.setSessionName?.(name),
+            setLabel: (entryId, label) => this.bindings.setLabel?.(entryId, label),
+            log: (msg) => process.stderr.write(`[ext] ${msg}\n`),
+            reloadExtensions: () => this.reload(),
+            // Impostazioni dell'estensione corrente (lette dal file su disco).
+            getSettings: () => (extId ? this.settings.options(extId) : {}),
+            setSetting: (key, value) => {
+                if (extId)
+                    this.settings.setOption(extId, key, value);
+            },
+        };
+    }
+    // API pubblica per i comandi slash gestiti dal repl.
+    publicApi() {
+        return this.api();
+    }
+    // Esegue un flag CLI registrato da un'estensione nel suo vero contesto.
+    // Il parser core conserva i flag sconosciuti fino al bootstrap; qui diventano
+    // operativi invece di restare una API registrata ma mai consumata.
+    async runFlag(name, value) {
+        const flag = this.flags.get(name);
+        if (!flag)
+            return { ok: false, reason: `flag sconosciuto: ${name}` };
+        if (flag.hasValue && value === undefined) {
+            return { ok: false, reason: `${name} richiede un valore nella forma ${name}=valore` };
+        }
+        if (!flag.hasValue && value !== undefined) {
+            return { ok: false, reason: `${name} non accetta un valore` };
+        }
+        await flag.run(value, this.ctx());
+        return { ok: true };
+    }
+    // Emette un evento a tutti gli handler registrati, raccogliendo gli esiti.
+    hasHandlers(event) {
+        return (this.handlers.get(event)?.length ?? 0) > 0;
+    }
+    async emit(event, payload) {
+        const list = this.handlers.get(event);
+        if (!list || !list.length)
+            return [];
+        const ctx = this.ctx();
+        const outcomes = [];
+        for (const handler of list) {
+            try {
+                const out = await handler(payload, ctx);
+                if (out)
+                    outcomes.push(out);
+            }
+            catch (err) {
+                process.stderr.write(`[ext] handler ${event} errore: ${err.message}\n`);
+            }
+        }
+        return outcomes;
+    }
+    // Applica gli hook delle estensioni al system prompt di base.
+    applySystem(base) {
+        const withAppends = this.systemAppends.length ? `${base}\n\n${this.systemAppends.join("\n\n")}` : base;
+        return this.systemHooks.reduce((acc, fn) => fn(acc), withAppends);
+    }
+    async loadModule(spec, cacheBust = false) {
+        let url = pathToFileURL(resolve(this.cwd, spec)).href;
+        // Cache-bust: il loader di moduli ESM tiene una cache per URL, quindi un
+        // secondo import dello stesso file ritornerebbe la versione vecchia. Una
+        // query string univoca forza la rivalutazione del file dal disco.
+        if (cacheBust)
+            url += `?t=${Date.now()}`;
+        const mod = (await import(url));
+        if (typeof mod.default === "function") {
+            await mod.default(this.api());
+        }
+    }
+    // Carica tutte le estensioni da .talos/extensions/*.{ts,js,mjs}, saltando
+    // quelle disabilitate nei settings. Popola l'inventario per-estensione.
+    async loadDir(cacheBust = false) {
+        const dir = join(this.cwd, ".talos", "extensions");
+        if (!existsSync(dir)) {
+            this.knownFiles = [];
+            return;
+        }
+        const files = readdirSync(dir).filter((f) => /\.(ts|js|mjs)$/.test(f));
+        this.knownFiles = [...files].sort();
+        for (const f of files) {
+            if (!this.settings.isEnabled(f))
+                continue; // disabilitata: salta
+            this.currentExt = f;
+            try {
+                await this.loadModule(join(dir, f), cacheBust);
+            }
+            catch (err) {
+                process.stderr.write(`[ext] errore caricando ${f}: ${err.message}\n`);
+            }
+            finally {
+                this.currentExt = null;
+            }
+        }
+    }
+    // Annulla le registrazioni di UNA estensione (o di tutte). Lascia intatti i
+    // tool/comandi CORE (non in perExt). Idempotente.
+    unloadOne(id) {
+        const s = this.perExt.get(id);
+        if (!s)
+            return;
+        for (const name of s.tools)
+            this.tools.remove(name);
+        for (const name of s.commands)
+            this.commands.delete(name);
+        for (const key of s.shortcuts)
+            this.shortcuts.delete(key);
+        for (const name of s.flags)
+            this.flags.delete(name);
+        for (const type of s.renderers)
+            this.renderers.delete(type);
+        for (const name of s.providers)
+            this.bindings.unregisterProvider?.(name);
+        const toDrop = new Set(s.handlers.map((h) => h.handler));
+        for (const [event, list] of this.handlers) {
+            const kept = list.filter((h) => !toDrop.has(h));
+            if (kept.length)
+                this.handlers.set(event, kept);
+            else
+                this.handlers.delete(event);
+        }
+        const dropHooks = new Set(s.systemHooks);
+        let i = this.systemHooks.length;
+        while (i--)
+            if (dropHooks.has(this.systemHooks[i]))
+                this.systemHooks.splice(i, 1);
+        this.perExt.delete(id);
+    }
+    unloadAll() {
+        for (const id of [...this.perExt.keys()])
+            this.unloadOne(id);
+    }
+    allTools() {
+        const out = new Set();
+        for (const s of this.perExt.values())
+            for (const t of s.tools)
+                out.add(t);
+        return [...out].sort();
+    }
+    // Hot reload (parita' pi.dev): scarica le estensioni correnti e ricarica la
+    // dir da disco con cache-bust. Ritorna un diff dei tool per il feedback.
+    async reload() {
+        const before = this.allTools();
+        this.unloadAll();
+        this.settings = ExtensionSettingsStore.open(this.cwd); // rilegge i settings
+        await this.loadDir(true);
+        const after = this.allTools();
+        const beforeSet = new Set(before);
+        const afterSet = new Set(after);
+        return {
+            before,
+            after,
+            added: after.filter((t) => !beforeSet.has(t)),
+            removed: before.filter((t) => !afterSet.has(t)),
+        };
+    }
+    // --- Gestione/lista estensioni (esposta a tool agente e comando TUI) ---
+    // Inventario completo: tutte le estensioni note su disco con stato e
+    // registrazioni. Le disabilitate compaiono con loaded=false.
+    inventory() {
+        const ids = new Set([...this.knownFiles, ...this.perExt.keys()]);
+        const out = [];
+        for (const id of [...ids].sort()) {
+            const s = this.perExt.get(id);
+            out.push({
+                id,
+                enabled: this.settings.isEnabled(id),
+                loaded: Boolean(s),
+                tools: s ? [...s.tools].sort() : [],
+                commands: s ? [...s.commands].sort() : [],
+                shortcuts: s ? [...s.shortcuts].sort() : [],
+                flags: s ? [...s.flags].sort() : [],
+                renderers: s ? [...s.renderers].sort() : [],
+                providers: s ? [...s.providers].sort() : [],
+                events: s ? [...new Set(s.handlers.map((h) => h.event))].sort() : [],
+                systemHooks: s ? s.systemHooks.length : 0,
+                options: this.settings.options(id),
+            });
+        }
+        return out;
+    }
+    // Abilita/disabilita un'estensione: persiste il settaggio e ricarica.
+    async setEnabled(id, enabled) {
+        if (!this.knownFiles.includes(id) && !this.perExt.has(id)) {
+            return { ok: false, reason: `estensione '${id}' non trovata` };
+        }
+        this.settings.setEnabled(id, enabled);
+        await this.reload();
+        return { ok: true };
+    }
+    // Imposta un'opzione di un'estensione (persistita). Ricarica per applicarla.
+    async setOption(id, key, value) {
+        if (!this.knownFiles.includes(id) && !this.perExt.has(id)) {
+            return { ok: false, reason: `estensione '${id}' non trovata` };
+        }
+        this.settings.setOption(id, key, value);
+        await this.reload();
+        return { ok: true };
+    }
+    // Normalizza un id passato dall'utente (accetta nome senza estensione).
+    resolveId(input) {
+        const ids = new Set([...this.knownFiles, ...this.perExt.keys()]);
+        if (ids.has(input))
+            return input;
+        for (const id of ids)
+            if (basename(id).replace(/\.(ts|js|mjs)$/, "") === input)
+                return id;
+        return null;
+    }
+}

package/dist/extensions/settings.d.ts

@@ -0,0 +1,20 @@
+export interface ExtensionSetting {
+    enabled: boolean;
+    options: Record<string, unknown>;
+}
+type SettingsMap = Record<string, ExtensionSetting>;
+export declare class ExtensionSettingsStore {
+    private readonly file;
+    private cache;
+    private constructor();
+    static open(cwd: string): ExtensionSettingsStore;
+    get(id: string): ExtensionSetting;
+    isEnabled(id: string): boolean;
+    options(id: string): Record<string, unknown>;
+    all(): SettingsMap;
+    setEnabled(id: string, enabled: boolean): void;
+    setOption(id: string, key: string, value: unknown): void;
+    setOptions(id: string, options: Record<string, unknown>): void;
+    private persist;
+}
+export {};

package/dist/extensions/settings.js

@@ -0,0 +1,86 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+// Store JSON append/overwrite su .talos/extensions-settings.json. Immutabile
+// verso l'esterno: ogni mutazione riscrive il file e aggiorna la cache interna.
+export class ExtensionSettingsStore {
+    file;
+    cache;
+    constructor(file, initial) {
+        this.file = file;
+        this.cache = initial;
+    }
+    static open(cwd) {
+        const file = join(cwd, ".talos", "extensions-settings.json");
+        let data = {};
+        if (existsSync(file)) {
+            try {
+                const raw = JSON.parse(readFileSync(file, "utf8"));
+                if (raw && typeof raw === "object")
+                    data = normalize(raw);
+            }
+            catch {
+                // file corrotto: riparti da vuoto, non bloccare l'avvio.
+                data = {};
+            }
+        }
+        return new ExtensionSettingsStore(file, data);
+    }
+    // Stato di un'estensione (default: abilitata, opzioni vuote).
+    get(id) {
+        return this.cache[id] ?? { enabled: true, options: {} };
+    }
+    isEnabled(id) {
+        return this.get(id).enabled;
+    }
+    options(id) {
+        return { ...this.get(id).options };
+    }
+    // Tutte le impostazioni esplicite presenti sul disco.
+    all() {
+        const out = {};
+        for (const [k, v] of Object.entries(this.cache))
+            out[k] = { enabled: v.enabled, options: { ...v.options } };
+        return out;
+    }
+    setEnabled(id, enabled) {
+        const cur = this.get(id);
+        this.cache = { ...this.cache, [id]: { ...cur, enabled } };
+        this.persist();
+    }
+    // Aggiorna una singola opzione (merge). value undefined la rimuove.
+    setOption(id, key, value) {
+        const cur = this.get(id);
+        const options = { ...cur.options };
+        if (value === undefined)
+            delete options[key];
+        else
+            options[key] = value;
+        this.cache = { ...this.cache, [id]: { ...cur, options } };
+        this.persist();
+    }
+    // Sostituisce in blocco le opzioni di un'estensione.
+    setOptions(id, options) {
+        const cur = this.get(id);
+        this.cache = { ...this.cache, [id]: { ...cur, options: { ...options } } };
+        this.persist();
+    }
+    persist() {
+        const dir = dirname(this.file);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(this.file, JSON.stringify(this.cache, null, 2) + "\n", "utf8");
+    }
+}
+function normalize(raw) {
+    const out = {};
+    for (const [id, v] of Object.entries(raw)) {
+        if (!v || typeof v !== "object")
+            continue;
+        const rec = v;
+        out[id] = {
+            enabled: rec.enabled !== false,
+            options: rec.options && typeof rec.options === "object" ? rec.options : {},
+        };
+    }
+    return out;
+}