@vascend/talos 0.1.0

package/dist/vascend/granular-kingdom.js

@@ -0,0 +1,259 @@
+import { runTurn } from "../core/agent.js";
+import { Session } from "../core/session.js";
+import { createUserInbox } from "../core/user-inbox.js";
+import { kingdomLive } from "./kingdom-live.js";
+import { disjointAreas } from "./team-areas.js";
+import { fileActor, withFileActor } from "../core/file-coordination.js";
+import { launchGranular, granularConcurrency, formatGranularReport, } from "./granular-launcher.js";
+const REF_RE = /^t\d{1,2}$/i;
+function nestedUnits(specs) {
+    const seen = new Set();
+    return specs.slice(0, 32).flatMap((spec, index) => {
+        const id = String(spec.slug || `expert-${index + 1}`).trim()
+            .replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || `expert-${index + 1}`;
+        const goal = String(spec.goal || "").trim();
+        if (!goal || seen.has(id.toLowerCase()))
+            return [];
+        seen.add(id.toLowerCase());
+        return [{
+                id,
+                goal,
+                assignment: spec,
+                ...(spec.after?.length ? { deps: [...spec.after] } : {}),
+            }];
+    });
+}
+function maxTeamDepth(opts) {
+    if (Number.isInteger(opts.maxDepth) && Number(opts.maxDepth) > 0)
+        return Math.min(5, Number(opts.maxDepth));
+    const configured = Number(process.env["TALOS_KINGDOM_MAX_DEPTH"]);
+    return Number.isInteger(configured) && configured > 0 ? Math.min(5, configured) : 3;
+}
+function nestedTaskFields(slug) {
+    const parts = slug.split("/").filter(Boolean);
+    return {
+        ...(parts[0] ? { workstreamId: parts[0] } : {}),
+        ...(parts[1] ? { taskRefs: [parts[1]], parentTaskRef: parts[1] } : {}),
+    };
+}
+function nestedActivity(slug, event) {
+    if (event.type === "kingdom")
+        return event;
+    if (event.type === "turn_start")
+        return {
+            type: "kingdom", phase: "vassal", slug, state: "active", label: "Pianifica il task", ...nestedTaskFields(slug),
+        };
+    if (event.type === "tool_call" && event.call.name === "team_say") {
+        const rawTo = String(event.call.input["to"] ?? "tutti").trim() || "tutti";
+        const parts = slug.split("/").filter(Boolean);
+        const parent = parts.slice(0, -1).join("/");
+        const knownPrefix = parts.includes(rawTo);
+        const to = rawTo === "tutti" || rawTo === "orchestratore" || rawTo.includes("/") || knownPrefix
+            ? rawTo
+            : (parent ? `${parent}/${rawTo}` : rawTo);
+        return {
+            type: "kingdom",
+            phase: "message",
+            from: slug,
+            to,
+            kind: "message",
+            text: String(event.call.input["text"] ?? "").slice(0, 900),
+            ...(parts[0] ? { workstreamId: parts[0] } : {}),
+            ...(parts[1] ? { taskRef: parts[1] } : {}),
+        };
+    }
+    if (event.type === "tool_call")
+        return {
+            type: "kingdom", phase: "vassal", slug, state: "active", label: event.call.name, ...nestedTaskFields(slug),
+        };
+    if (event.type === "done")
+        return {
+            type: "kingdom", phase: "vassal", slug, state: "done", ...nestedTaskFields(slug),
+        };
+    if (event.type === "error")
+        return {
+            type: "kingdom", phase: "vassal", slug, state: "error", label: event.message, ...nestedTaskFields(slug),
+        };
+    return null;
+}
+// Regola di marcatura per una unita' che coincide con una stanza del piano.
+// Senza questa, il lavoro piu' granulare e' anche l'unico invisibile all'utente.
+function markRule(unit, castle) {
+    if (!castle || !REF_RE.test(unit.id))
+        return "";
+    return `\n@attivita[mia]: ${unit.id} del gruppo ${castle}: marcala con vascend_mark(group="${castle}", task="${unit.id}", status="running") all'apertura e "completed" (o "failed") alla chiusura`;
+}
+// Preambolo (notazione Danilov) di una UNITA' granulare: piu' stretto di quello
+// del castello: una sola unita', niente sotto-scomposizione, resta nel confine.
+function unitSteer(unit, peers, castle) {
+    const others = peers.filter((p) => p !== unit.id);
+    return `[UNITA' ${unit.id}]
+INDICE
+1 = ruolo
+2 = dipendenze
+3 = confine
+
+DEFINIZIONI
+@ruolo[unita]: id=${unit.id}, granularita=fine, peer=[${others.join(", ") || "nessuno"}]
+@dipendenze[done]: ${(unit.deps ?? []).join(", ") || "nessuna (gia' soddisfatte: parti subito)"}
+@confine[regola]: esegui SOLO questa unita', NON scomporla ulteriormente, NON toccare il lavoro delle altre unita'${markRule(unit, castle)}
+
+RELAZIONI
+@R1: @ruolo[unita] -> @confine[regola]  [ una sola unita', niente sovrapposizioni ]
+
+OUTPUT: esegui l'unita' e basta; le dipendenze sono gia' completate.
+
+OBIETTIVO_UNITA'
+`;
+}
+// Costruisce il TaskRunner che esegue una unita' come sessione di agente.
+export function makeAgentUnitRunner(opts) {
+    const { harness, kingdomId, castleSlug, signal, confirm, cwd, isolated } = opts;
+    const peers = opts.units.map((u) => u.id);
+    const depth = opts.depth ?? 2;
+    const maxDepth = maxTeamDepth(opts);
+    return async (unit, ctx) => {
+        const workerPool = Array.isArray(harness.config.workerModelPool)
+            ? harness.config.workerModelPool : undefined;
+        const unitIndex = Math.max(0, opts.units.findIndex((item) => item.id === unit.id));
+        const selected = unit.assignment?.model || (workerPool && workerPool.length
+            ? workerPool[unitIndex % workerPool.length]
+            : harness.config.model);
+        if (workerPool && (!workerPool.length || !workerPool.includes(selected))) {
+            throw new Error(`modello collaboratore non autorizzato: ${selected}`);
+        }
+        const resolved = harness.providers.resolve(selected);
+        if (!resolved)
+            throw new Error("modello non configurato");
+        const storageSlug = `${castleSlug}-${unit.id}`.replace(/[^a-zA-Z0-9_.-]+/g, "-");
+        const session = Session.create(harness.config.sessionDir, `${kingdomId}-${storageSlug}`);
+        const planCastle = unit.assignment?.castle ?? (opts.markCastle && REF_RE.test(unit.id) ? opts.markCastle : undefined);
+        const planTasks = unit.assignment?.tasks ?? (planCastle ? [unit.id] : undefined);
+        const workerTools = harness.tools.scoped(unit.assignment?.tools);
+        for (const name of ["team_say", "team_inbox", "team_wait", "team_report", "vascend_status"])
+            workerTools.promote(name);
+        const runConfig = {
+            ...harness.config,
+            model: resolved.modelId,
+            roomStoreId: kingdomId,
+            roomNamespace: storageSlug,
+            ...(opts.planStoreId ? { planStoreId: opts.planStoreId } : {}),
+            planCastle, planTasks,
+            ...(unit.assignment?.effort && ["low", "medium", "high", "max"].includes(unit.assignment.effort)
+                ? { effort: unit.assignment.effort } : {}),
+            ...(cwd ? { cwd } : {}),
+        };
+        const self = `${castleSlug}/${unit.id}`;
+        const spawnKingdom = depth < maxDepth ? async (specs) => {
+            const units = nestedUnits(specs);
+            if (!units.length)
+                return "team non avviato: nessun task valido";
+            for (const child of units) {
+                const slug = `${self}/${child.id}`;
+                const route = slug.split("/").filter(Boolean);
+                ctx.emit({
+                    type: "kingdom",
+                    phase: "vassal",
+                    slug,
+                    parent: self,
+                    role: "collaboratore",
+                    goal: child.goal,
+                    state: "start",
+                    ...(route[0] ? { workstreamId: route[0] } : {}),
+                    ...(route[1] ? { taskRefs: [route[1]], parentTaskRef: route[1] } : {}),
+                });
+                ctx.emit({
+                    type: "kingdom",
+                    phase: "message",
+                    kind: "assignment",
+                    from: self,
+                    to: slug,
+                    text: `Task assegnato: ${child.goal.slice(0, 900)}`,
+                    ...(route[0] ? { workstreamId: route[0] } : {}),
+                    ...(route[1] ? { taskRef: route[1] } : {}),
+                });
+            }
+            const report = await launchGranularKingdom({
+                ...opts,
+                harness: { ...harness, config: runConfig, tools: workerTools },
+                castleSlug: self,
+                units,
+                depth: depth + 1,
+                maxDepth,
+                markCastle: undefined,
+                onEvent: (id, event) => {
+                    const mapped = nestedActivity(`${self}/${id}`, event);
+                    if (mapped)
+                        ctx.emit(mapped);
+                },
+                onNotice: (text) => ctx.emit({ type: "kingdom", phase: "notice", text: `[${self}] ${text}` }),
+            });
+            return formatGranularReport(report);
+        } : undefined;
+        // Anche il sotto-collaboratore ha la sua casella: la scheda laterale non
+        // distingue i livelli, e nemmeno chi ci scrive dentro deve farlo.
+        const inbox = createUserInbox();
+        kingdomLive.register(kingdomId, self, inbox);
+        const deps = {
+            provider: resolved.provider,
+            tools: workerTools,
+            session,
+            config: runConfig,
+            confirm,
+            ask: opts.ask,
+            host: undefined,
+            inbox,
+            ...(opts.fileCoordination ? {
+                fileCoordination: withFileActor(opts.fileCoordination, fileActor(`${opts.fileCoordination.actor.id}:${self}`, self, "subagent")),
+            } : {}),
+            ...(spawnKingdom ? { spawnKingdom } : {}),
+            kingdom: { id: kingdomId, self, isolated: Boolean(isolated), peers: [castleSlug, ...peers.map((peer) => `${castleSlug}/${peer}`)] },
+        };
+        let summary = "";
+        let runError = "";
+        let completed = false;
+        const sink = (event) => {
+            if (event.type === "text")
+                summary += event.delta;
+            if (event.type === "error")
+                runError = event.message;
+            if (event.type === "done")
+                completed = true;
+            ctx.emit(event);
+        };
+        const input = unitSteer(unit, peers, opts.markCastle)
+            + (planCastle ? `\nPIANO_ASSEGNATO: ${planCastle}; task: ${(planTasks ?? []).join(", ")}. Consulta vascend_status e aggiorna solo queste attivita.\n` : "")
+            + (unit.assignment?.area?.length ? `\nAREA_ASSEGNATA: ${unit.assignment.area.join(", ")}\n` : "")
+            + (unit.assignment?.instructions ? `\nISTRUZIONI_AGGIUNTIVE\n${unit.assignment.instructions}\n` : "")
+            + (ctx.prerequisites?.length ? "\nPREREQUISITI_COMPLETATI (risultati da verificare)\n"
+                + ctx.prerequisites.map((result) => `[${result.id}] ${result.summary}`).join("\n").slice(0, 6000) + "\n" : "") + unit.goal;
+        try {
+            await runTurn(deps, input, sink, ctx.signal);
+        }
+        finally {
+            deps.fileCoordination?.hub.clearActor(deps.fileCoordination.actor.id);
+            kingdomLive.release(kingdomId, self);
+        }
+        if (ctx.signal.aborted)
+            throw new Error("interrotta");
+        if (runError || !completed)
+            throw new Error(runError || "unita' terminata senza completamento verificato");
+        return { summary: summary.trim() };
+    };
+}
+// Endpoint completo: lancia le unita' granulari di un castello in parallelo.
+export async function launchGranularKingdom(opts) {
+    const runner = makeAgentUnitRunner(opts);
+    return launchGranular({
+        units: opts.units,
+        runner,
+        signal: opts.signal,
+        concurrency: opts.concurrency ?? granularConcurrency(process.env),
+        // Children share their parent's directory, including within a worktree.
+        compatible: (left, right) => disjointAreas([
+            { slug: left.id, area: left.assignment?.area }, { slug: right.id, area: right.assignment?.area },
+        ], opts.cwd ?? opts.harness.config.cwd).disjoint,
+        ...(opts.onEvent ? { onEvent: opts.onEvent } : {}),
+        ...(opts.onNotice ? { onNotice: opts.onNotice } : {}),
+    });
+}

package/dist/vascend/granular-launcher.d.ts

@@ -0,0 +1,48 @@
+import type { AgentEvent, SpawnAgentSpec } from "../core/types.js";
+export type TaskUnitStatus = "pending" | "running" | "done" | "failed" | "skipped";
+export interface TaskUnit {
+    readonly id: string;
+    readonly goal: string;
+    readonly deps?: readonly string[];
+    readonly weight?: number;
+    readonly assignment?: SpawnAgentSpec;
+}
+export interface TaskUnitResult {
+    readonly id: string;
+    readonly status: TaskUnitStatus;
+    readonly summary: string;
+    readonly error?: string;
+    readonly blockedBy?: readonly string[];
+    readonly startedAt?: number;
+    readonly endedAt?: number;
+}
+export interface TaskRunResult {
+    readonly summary: string;
+}
+export type TaskRunner = (unit: TaskUnit, ctx: {
+    readonly signal: AbortSignal;
+    readonly emit: (event: AgentEvent) => void;
+    readonly prerequisites?: readonly TaskUnitResult[];
+}) => Promise<TaskRunResult>;
+export interface GranularLaunchSpec {
+    readonly units: readonly TaskUnit[];
+    readonly runner: TaskRunner;
+    readonly signal: AbortSignal;
+    readonly concurrency?: number;
+    readonly onEvent?: (id: string, event: AgentEvent) => void;
+    readonly onNotice?: (text: string) => void;
+    readonly compatible?: (left: TaskUnit, right: TaskUnit) => boolean;
+}
+export interface GranularLaunchReport {
+    readonly results: readonly TaskUnitResult[];
+    readonly ok: boolean;
+    readonly done: number;
+    readonly failed: number;
+    readonly skipped: number;
+}
+export declare class GraphError extends Error {
+}
+export declare function topoOrder(units: readonly TaskUnit[]): string[];
+export declare function granularConcurrency(env: NodeJS.ProcessEnv, fallback?: number): number;
+export declare function launchGranular(spec: GranularLaunchSpec): Promise<GranularLaunchReport>;
+export declare function formatGranularReport(report: GranularLaunchReport): string;

package/dist/vascend/granular-launcher.js

@@ -0,0 +1,202 @@
+// Errore di validazione del grafo (dipendenze mancanti o cicli): meglio fallire
+// subito e chiaro che lanciare un DAG malformato.
+export class GraphError extends Error {
+}
+// Valida il grafo: id unici, dipendenze esistenti, nessun ciclo. Ritorna un
+// ordine topologico (solo per diagnostica/test; lo scheduler usa la prontezza
+// dinamica, non quest'ordine fisso).
+export function topoOrder(units) {
+    const ids = new Set();
+    for (const u of units) {
+        if (ids.has(u.id))
+            throw new GraphError(`id duplicato: ${u.id}`);
+        ids.add(u.id);
+    }
+    for (const u of units) {
+        for (const d of u.deps ?? []) {
+            if (!ids.has(d))
+                throw new GraphError(`dipendenza inesistente: ${u.id} -> ${d}`);
+            if (d === u.id)
+                throw new GraphError(`auto-dipendenza: ${u.id}`);
+        }
+    }
+    // Kahn: rimuovi iterativamente i nodi senza dipendenze residue.
+    const indeg = new Map();
+    const dependents = new Map();
+    for (const u of units)
+        indeg.set(u.id, (u.deps ?? []).length);
+    for (const u of units) {
+        for (const d of u.deps ?? []) {
+            const arr = dependents.get(d) ?? [];
+            arr.push(u.id);
+            dependents.set(d, arr);
+        }
+    }
+    const ready = units.filter((u) => (indeg.get(u.id) ?? 0) === 0).map((u) => u.id);
+    ready.sort();
+    const order = [];
+    while (ready.length) {
+        const id = ready.shift();
+        order.push(id);
+        for (const dep of dependents.get(id) ?? []) {
+            const n = (indeg.get(dep) ?? 0) - 1;
+            indeg.set(dep, n);
+            if (n === 0) {
+                ready.push(dep);
+                ready.sort();
+            }
+        }
+    }
+    if (order.length !== units.length) {
+        const cyc = units.map((u) => u.id).filter((id) => !order.includes(id));
+        throw new GraphError(`ciclo nel grafo delle dipendenze: ${cyc.join(", ")}`);
+    }
+    return order;
+}
+// Concorrenza del granular launcher (override via env). Indipendente dalla
+// concorrenza dei castelli (TALOS_KINGDOM_CONCURRENCY): si possono volere molte
+// unita' piccole in volo anche con pochi castelli.
+export function granularConcurrency(env, fallback = 4) {
+    const n = Number(env["TALOS_GRANULAR_CONCURRENCY"]);
+    return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+// launchGranular: ENDPOINT di lancio granulare. Avvia ogni TaskUnit come unita'
+// separata (via il runner), rispettando il DAG delle dipendenze, con un pool di
+// concorrenza. Un fallimento NON abbatte il lancio: le unita' indipendenti
+// proseguono; i discendenti dell'unita' fallita vengono SKIPPATI (segnalati come
+// bloccati). Ritorna un report aggregato. Deterministico nell'ordine dei
+// risultati (= ordine delle unita' in input).
+export async function launchGranular(spec) {
+    const { units, runner, signal, onEvent, onNotice } = spec;
+    // Valida subito: un grafo malformato fa fallire l'intero lancio in modo netto.
+    topoOrder(units);
+    const limit = Math.max(1, spec.concurrency ?? granularConcurrency(process.env));
+    const byId = new Map(units.map((u) => [u.id, u]));
+    const status = new Map();
+    const result = new Map();
+    for (const u of units)
+        status.set(u.id, "pending");
+    // Una unita' e' PRONTA se e' pending e tutte le sue deps sono "done". Se una
+    // dep e' failed/skipped, l'unita' va a sua volta SKIPPATA (a cascata).
+    const readyOrSkip = () => {
+        const ready = [];
+        const skipped = [];
+        for (const u of units) {
+            if (status.get(u.id) !== "pending")
+                continue;
+            const deps = u.deps ?? [];
+            const bad = deps.filter((d) => {
+                const s = status.get(d);
+                return s === "failed" || s === "skipped";
+            });
+            if (bad.length) {
+                skipped.push(u);
+                continue;
+            }
+            const allDone = deps.every((d) => status.get(d) === "done");
+            if (allDone)
+                ready.push(u);
+        }
+        // A parita' di prontezza, pesi piu' alti (e id, per determinismo) per primi.
+        ready.sort((a, b) => (b.weight ?? 0) - (a.weight ?? 0) || a.id.localeCompare(b.id));
+        return { ready, skipped };
+    };
+    const launchOne = async (unit) => {
+        status.set(unit.id, "running");
+        onNotice?.(`[${unit.id}] avviata`);
+        const startedAt = Date.now();
+        const emit = (event) => onEvent?.(unit.id, event);
+        try {
+            const r = await runner(unit, { signal, emit, prerequisites: (unit.deps ?? []).map((id) => result.get(id)) });
+            status.set(unit.id, "done");
+            result.set(unit.id, { id: unit.id, status: "done", summary: r.summary.trim(), startedAt, endedAt: Date.now() });
+            onNotice?.(`[${unit.id}] completata`);
+        }
+        catch (err) {
+            status.set(unit.id, "failed");
+            result.set(unit.id, { id: unit.id, status: "failed", summary: "", error: err.message, startedAt, endedAt: Date.now() });
+            onNotice?.(`[${unit.id}] FALLITA: ${err.message}`);
+        }
+    };
+    // Scheduler a pool: a ogni giro marca gli skip a cascata, riempie il pool con
+    // le unita' pronte fino al limite, attende che almeno una termini, ripete.
+    // Finche' restano unita' pending/running.
+    const inFlight = new Set();
+    const drainSkips = () => {
+        // Propaga gli skip in modo transitivo: marcare uno skip puo' renderne
+        // skippabili altri (discendenti), quindi itera fino a punto fisso.
+        for (;;) {
+            const { skipped } = readyOrSkip();
+            if (!skipped.length)
+                break;
+            for (const u of skipped) {
+                status.set(u.id, "skipped");
+                const blockedBy = (u.deps ?? []).filter((d) => {
+                    const s = status.get(d);
+                    return s === "failed" || s === "skipped";
+                });
+                result.set(u.id, { id: u.id, status: "skipped", summary: "", blockedBy });
+                onNotice?.(`[${u.id}] saltata (bloccata da ${blockedBy.join(", ") || "?"})`);
+            }
+        }
+    };
+    for (;;) {
+        if (signal.aborted)
+            break;
+        drainSkips();
+        const { ready } = readyOrSkip();
+        // Riempie il pool con le unita' pronte fino al limite di concorrenza.
+        for (const u of ready) {
+            if (inFlight.size >= limit)
+                break;
+            if (status.get(u.id) !== "pending")
+                continue;
+            if (spec.compatible && units.some((active) => status.get(active.id) === "running" && !spec.compatible(u, active)))
+                continue;
+            const p = launchOne(u).finally(() => inFlight.delete(p));
+            inFlight.add(p);
+        }
+        if (!inFlight.size) {
+            // Niente in volo: o abbiamo finito, o restano solo pending bloccati che il
+            // prossimo drainSkips chiarira'; se non cambia nulla, esci.
+            const pendingLeft = units.some((u) => status.get(u.id) === "pending");
+            if (!pendingLeft)
+                break;
+            // Marca eventuali skip residui ed esci se ancora bloccato senza progresso.
+            drainSkips();
+            const stillPending = units.some((u) => status.get(u.id) === "pending");
+            const stillReady = readyOrSkip().ready.length > 0;
+            if (stillPending && !stillReady)
+                break; // stallo: nessuna unita' avviabile
+            if (!stillReady)
+                break;
+            continue;
+        }
+        await Promise.race(inFlight);
+    }
+    // Se interrotti, qualunque unita' ancora pending/running resta non-done.
+    await Promise.allSettled([...inFlight]);
+    for (const u of units) {
+        if (!result.has(u.id)) {
+            const s = status.get(u.id) ?? "pending";
+            result.set(u.id, { id: u.id, status: s === "running" ? "failed" : "skipped", summary: "", error: s === "running" ? "interrotta" : undefined });
+        }
+    }
+    const results = units.map((u) => result.get(u.id));
+    const done = results.filter((r) => r.status === "done").length;
+    const failed = results.filter((r) => r.status === "failed").length;
+    const skipped = results.filter((r) => r.status === "skipped").length;
+    return { results, ok: failed === 0 && skipped === 0, done, failed, skipped };
+}
+// Riepilogo del lancio in notazione Danilov (per la chat/log dell'Imperatore).
+export function formatGranularReport(report) {
+    const mark = {
+        done: "✓", failed: "✗", skipped: "⊘", running: "…", pending: "·",
+    };
+    const rows = report.results
+        .map((r) => `@unit[${r.id}]: ${mark[r.status]} ${r.status}${r.error ? ` · errore: ${r.error}` : ""}${r.blockedBy?.length ? ` · bloccata da ${r.blockedBy.join(", ")}` : ""}`)
+        .join("\n");
+    return `[GRANULAR_LAUNCH]
+@esito[totale]: ${report.done} done · ${report.failed} failed · ${report.skipped} skipped${report.ok ? " · OK" : ""}
+${rows}`;
+}

package/dist/vascend/kingdom-bus.d.ts

@@ -0,0 +1,25 @@
+export interface KingdomMessage {
+    readonly seq: number;
+    readonly from: string;
+    readonly to: string | null;
+    readonly text: string;
+    readonly ts: number;
+}
+export interface InboxCursor {
+    readonly last: number;
+    readonly seen?: readonly number[];
+}
+export declare function consumeInbox(board: readonly KingdomMessage[], me: string, cursor: InboxCursor, filter?: (message: KingdomMessage) => boolean): {
+    messages: KingdomMessage[];
+    cursor: InboxCursor;
+};
+export declare class KingdomBus {
+    private readonly boards;
+    private readonly cursors;
+    private seq;
+    post(kingdomId: string, from: string, to: string | null, text: string, ts: number): KingdomMessage;
+    inbox(kingdomId: string, me: string, filter?: (message: KingdomMessage) => boolean): KingdomMessage[];
+    history(kingdomId: string): readonly KingdomMessage[];
+    clear(kingdomId: string): void;
+}
+export declare const kingdomBus: KingdomBus;

package/dist/vascend/kingdom-bus.js

@@ -0,0 +1,54 @@
+// Bus di messaggi tra vassalli di un regno (Kingdoms Mode): cooperazione ATTIVA
+// stile team Claude Code. Un vassallo annuncia/chiede ("ho finito X", "mi serve
+// Y prima di Z"), gli altri leggono dalla loro inbox e si coordinano (procedono
+// con cio' che possono o aspettano un prerequisito). Store in-memory di processo,
+// keyed per kingdomId; cursore di lettura per vassallo.
+const MAX_BOARD = 500;
+// A filtered wait acknowledges only matching messages. Keep a bounded set of
+// receipts beyond the first unread message so unrelated mail is not lost.
+export function consumeInbox(board, me, cursor, filter = () => true) {
+    const seen = new Set(cursor.seen ?? []);
+    const unread = board.filter((message) => message.seq > cursor.last && !seen.has(message.seq)
+        && message.from !== me && (message.to === null || message.to === me));
+    const messages = unread.filter(filter);
+    for (const message of messages)
+        seen.add(message.seq);
+    const remaining = unread.filter((message) => !seen.has(message.seq));
+    const last = remaining.length ? remaining[0].seq - 1 : (board.at(-1)?.seq ?? cursor.last);
+    const retained = new Set(board.map((message) => message.seq));
+    return { messages, cursor: { last, seen: [...seen].filter((seq) => seq > last && retained.has(seq)) } };
+}
+export class KingdomBus {
+    boards = new Map();
+    cursors = new Map();
+    seq = 0;
+    post(kingdomId, from, to, text, ts) {
+        const m = { seq: (this.seq += 1), from, to: to && to.trim() ? to.trim() : null, text, ts };
+        const board = this.boards.get(kingdomId) ?? [];
+        board.push(m);
+        if (board.length > MAX_BOARD)
+            board.splice(0, board.length - MAX_BOARD);
+        this.boards.set(kingdomId, board);
+        return m;
+    }
+    // Messaggi NON ancora letti da `me` (destinati a me o broadcast, non miei).
+    // Avanza il cursore di lettura di `me`.
+    inbox(kingdomId, me, filter) {
+        const board = this.boards.get(kingdomId) ?? [];
+        const key = `${kingdomId}::${me}`;
+        const read = consumeInbox(board, me, this.cursors.get(key) ?? { last: 0 }, filter);
+        this.cursors.set(key, read.cursor);
+        return read.messages;
+    }
+    // Tutti i messaggi del regno (per il riepilogo/log), senza toccare i cursori.
+    history(kingdomId) {
+        return this.boards.get(kingdomId) ?? [];
+    }
+    clear(kingdomId) {
+        this.boards.delete(kingdomId);
+        for (const k of [...this.cursors.keys()])
+            if (k.startsWith(`${kingdomId}::`))
+                this.cursors.delete(k);
+    }
+}
+export const kingdomBus = new KingdomBus();

package/dist/vascend/kingdom-channel.d.ts

@@ -0,0 +1,22 @@
+import { type KingdomMessage } from "./kingdom-bus.js";
+export interface KingdomChannelOptions {
+    readonly maxBoard?: number;
+}
+export declare class PersistentKingdomChannel {
+    private readonly sessionDir;
+    private readonly maxBoard;
+    constructor(sessionDir: string, opts?: KingdomChannelOptions);
+    post(kingdomId: string, from: string, to: string | null, text: string, ts: number): KingdomMessage;
+    inbox(kingdomId: string, me: string, filter?: (message: KingdomMessage) => boolean): KingdomMessage[];
+    history(kingdomId: string): readonly KingdomMessage[];
+    clear(kingdomId: string): void;
+}
+export declare function getKingdomChannel(sessionDir: string, opts?: KingdomChannelOptions): PersistentKingdomChannel;
+export interface KingdomBusLike {
+    post(kingdomId: string, from: string, to: string | null, text: string, ts: number): KingdomMessage;
+    inbox(kingdomId: string, me: string, filter?: (message: KingdomMessage) => boolean): KingdomMessage[];
+    history(kingdomId: string): readonly KingdomMessage[];
+    clear(kingdomId: string): void;
+}
+export declare function kingdomIpcEnabled(env: NodeJS.ProcessEnv): boolean;
+export declare function resolveKingdomBus(env: NodeJS.ProcessEnv, sessionDir?: string): KingdomBusLike;