@vascend/talos 0.1.0

package/dist/tools/registry.d.ts

@@ -0,0 +1,51 @@
+import type { RegisteredTool, Tool, ToolDef } from "../core/types.js";
+export interface ToolRegistryOptions {
+    /**
+     * Quando presente, solo questi tool entrano in defs(). Tutti gli altri
+     * restano nel medesimo registro ma diventano deferred, quindi sono
+     * raggiungibili tramite i meta-tool di discovery.
+     */
+    readonly directTools?: ReadonlySet<string>;
+    readonly compact?: boolean;
+}
+export interface ToolScope {
+    readonly allow?: readonly string[];
+    readonly deny?: readonly string[];
+}
+export declare class ToolRegistry {
+    private readonly options;
+    private readonly tools;
+    private readonly deferred;
+    private readonly baselineDeferred;
+    private phase;
+    private definitions;
+    private deferredDefinitions;
+    private readonly identity;
+    private generation;
+    get revision(): string;
+    get compact(): boolean;
+    private invalidate;
+    constructor(options?: ToolRegistryOptions);
+    register(tool: Tool, deferred?: boolean): void;
+    remove(name: string): boolean;
+    /**
+     * Promuove un tool del catalogo fra quelli diretti per il resto del giro.
+     *
+     * Serve a tool_search: prima la ricerca incollava lo schema completo nella
+     * CONVERSAZIONE (fuori dalla cache del prompt, e per sempre), quindi cercare
+     * tre volte significava pagare tre volte gli stessi schemi. Promuovendo, lo
+     * schema entra UNA volta nella lista strumenti — che sta nel prefisso
+     * cacheabile — e il messaggio di risposta resta una riga per tool.
+     */
+    promote(name: string): boolean;
+    get(name: string): RegisteredTool | undefined;
+    isDeferred(name: string): boolean;
+    defs(): readonly ToolDef[];
+    catalog(): readonly ToolDef[];
+    names(): readonly string[];
+    setActive(names: readonly string[]): void;
+    /** Discovery promotions remain stable until the task epoch changes. */
+    enterPhase(phase: string): void;
+    activeNames(): readonly string[];
+    scoped(scope?: ToolScope): ToolRegistry;
+}

package/dist/tools/registry.js

@@ -0,0 +1,185 @@
+import { isToolVisibleToModel, toolInputSchema } from "../mcp/protocol.js";
+import { randomBytes } from "node:crypto";
+import { NATIVE_CALL_TOOLS, PROTOCOL_TOOLS } from "./capabilities.js";
+// Registro degli strumenti. L'agente espone al modello solo i ToolDef dei tool
+// CORE; l'esecuzione passa sempre da qui (single choke point per i permessi).
+// I tool DEFERRED (catalogo) non entrano in defs() — quindi non occupano il
+// system prompt — ma sono scopribili/eseguibili via i meta-tool (tool_search/
+// tool_invoke). Cosi' il contesto resta leggero anche con molti tool.
+export class ToolRegistry {
+    options;
+    tools = new Map();
+    deferred = new Set();
+    baselineDeferred = new Set();
+    phase;
+    definitions = null;
+    deferredDefinitions = null;
+    identity = randomBytes(8).toString("hex");
+    generation = 0;
+    get revision() { return `${this.identity}.${this.generation}`; }
+    get compact() { return this.options.compact === true; }
+    invalidate() {
+        this.definitions = null;
+        this.deferredDefinitions = null;
+    }
+    constructor(options = {}) {
+        this.options = options;
+    }
+    register(tool, deferred = false) {
+        const inputSchema = toolInputSchema(tool);
+        const normalized = { ...tool, inputSchema, schema: inputSchema };
+        this.tools.set(tool.name, normalized);
+        this.generation++;
+        this.invalidate();
+        if (this.compact) {
+            const direct = PROTOCOL_TOOLS.has(tool.name) || NATIVE_CALL_TOOLS.has(tool.name) || tool.requiresNativeCall;
+            if (direct) {
+                this.deferred.delete(tool.name);
+                this.baselineDeferred.delete(tool.name);
+            }
+            else {
+                this.deferred.add(tool.name);
+                this.baselineDeferred.add(tool.name);
+            }
+            return;
+        }
+        // Con una policy dell'host (directTools) decide SOLO l'appartenenza
+        // all'insieme diretto: sostituisce la selezione storica del chiamante nei
+        // due versi, altrimenti un tool dell'hot set che l'host vuole diretto
+        // resterebbe deferred perche' la CLI lo classifica come on demand.
+        if (this.options.directTools !== undefined) {
+            if (this.options.directTools.has(tool.name))
+                this.deferred.delete(tool.name);
+            else
+                this.deferred.add(tool.name);
+            if (this.deferred.has(tool.name))
+                this.baselineDeferred.add(tool.name);
+            else
+                this.baselineDeferred.delete(tool.name);
+            return;
+        }
+        if (deferred)
+            this.deferred.add(tool.name);
+        else
+            this.deferred.delete(tool.name);
+        if (deferred)
+            this.baselineDeferred.add(tool.name);
+        else
+            this.baselineDeferred.delete(tool.name);
+    }
+    // Rimuove uno strumento (es. --exclude-tools). No-op se assente.
+    remove(name) {
+        this.deferred.delete(name);
+        this.baselineDeferred.delete(name);
+        const removed = this.tools.delete(name);
+        if (removed) {
+            this.generation++;
+            this.invalidate();
+        }
+        return removed;
+    }
+    /**
+     * Promuove un tool del catalogo fra quelli diretti per il resto del giro.
+     *
+     * Serve a tool_search: prima la ricerca incollava lo schema completo nella
+     * CONVERSAZIONE (fuori dalla cache del prompt, e per sempre), quindi cercare
+     * tre volte significava pagare tre volte gli stessi schemi. Promuovendo, lo
+     * schema entra UNA volta nella lista strumenti — che sta nel prefisso
+     * cacheabile — e il messaggio di risposta resta una riga per tool.
+     */
+    promote(name) {
+        if (this.compact)
+            return false;
+        if (!this.tools.has(name) || !this.deferred.has(name))
+            return false;
+        this.deferred.delete(name);
+        this.invalidate();
+        return true;
+    }
+    get(name) {
+        return this.tools.get(name === "vascend_addrooms" ? "vascend_addtasks" : name);
+    }
+    isDeferred(name) {
+        return this.deferred.has(name);
+    }
+    // Tool esposti al modello: solo i CORE (non deferred).
+    defs() {
+        return this.definitions ??= Object.freeze([...this.tools.values()]
+            .filter((t) => !this.deferred.has(t.name) && isToolVisibleToModel(t._meta))
+            .map((tool) => Object.freeze(toolDefinition(tool))));
+    }
+    // Catalogo dei tool DEFERRED (scopribili via tool_search): name+description+schema.
+    catalog() {
+        return this.deferredDefinitions ??= Object.freeze([...this.tools.values()]
+            .filter((t) => this.deferred.has(t.name) && isToolVisibleToModel(t._meta))
+            .map((tool) => Object.freeze(toolDefinition(tool))));
+    }
+    names() {
+        return [...this.tools.keys()];
+    }
+    // Le estensioni Pi possono cambiare l'hot set dei tool durante la sessione.
+    // Gli strumenti non selezionati restano installati e scopribili, ma non
+    // occupano il prompt del modello.
+    setActive(names) {
+        if (this.compact)
+            return; // The compact surface is stable; scopes use scoped().
+        const active = new Set(names);
+        let changed = false;
+        for (const name of this.tools.keys()) {
+            if (active.has(name) === this.deferred.has(name))
+                changed = true;
+            if (active.has(name))
+                this.deferred.delete(name);
+            else
+                this.deferred.add(name);
+        }
+        this.baselineDeferred.clear();
+        for (const name of this.deferred)
+            this.baselineDeferred.add(name);
+        if (changed)
+            this.invalidate();
+    }
+    /** Discovery promotions remain stable until the task epoch changes. */
+    enterPhase(phase) {
+        if (this.phase === phase)
+            return;
+        if (this.phase !== undefined) {
+            this.deferred.clear();
+            for (const name of this.baselineDeferred)
+                this.deferred.add(name);
+            this.invalidate();
+        }
+        this.phase = phase;
+    }
+    activeNames() {
+        return [...this.tools.keys()].filter((name) => !this.deferred.has(name));
+    }
+    // Vista immutabile del registro per un singolo collaboratore. Non rimuove
+    // nulla dal registro dell'orchestratore e conserva la classificazione
+    // direct/deferred dei tool inclusi.
+    scoped(scope = {}) {
+        const allow = scope.allow && scope.allow.length ? new Set(scope.allow) : null;
+        const deny = new Set(scope.deny ?? []);
+        const compact = this.compact && [...PROTOCOL_TOOLS].every(name => this.get(name) && !deny.has(name));
+        const next = new ToolRegistry({ compact });
+        for (const [name, tool] of this.tools) {
+            if ((allow && !allow.has(name) && !(compact && PROTOCOL_TOOLS.has(name))) || deny.has(name))
+                continue;
+            next.register(tool, this.compact && !compact ? false : this.deferred.has(name));
+        }
+        return next;
+    }
+}
+function toolDefinition(tool) {
+    return {
+        name: tool.name,
+        ...(tool.title ? { title: tool.title } : {}),
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        // Alias temporaneo per host/estensioni Talos precedenti a MCP 2026-07-28.
+        schema: tool.inputSchema,
+        ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
+        ...(tool.annotations ? { annotations: tool.annotations } : {}),
+        ...(tool._meta ? { _meta: tool._meta } : {}),
+    };
+}

package/dist/tools/resolve.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from "../core/types.js";
+export declare const resolveTool: Tool;

package/dist/tools/resolve.js

@@ -0,0 +1,107 @@
+import { estimateTokens } from "../core/compaction.js";
+import { nativeCall, protocolCatalog, protocolError, protocolResult } from "./protocol-catalog.js";
+import { PROTOCOL_TOOLS } from "./capabilities.js";
+import { DISCOVERY_TOOL_NAMES } from "./discovery.js";
+function strings(input) {
+    if (input === undefined)
+        return [];
+    if (!Array.isArray(input) || input.length > 24 || input.some(item => typeof item !== "string" || !item.trim()))
+        return;
+    return [...new Set(input.map(value => value.trim()))];
+}
+function integer(input, fallback, min, max) {
+    if (input === undefined)
+        return fallback;
+    return typeof input === "number" && Number.isSafeInteger(input) && input >= min && input <= max ? input : undefined;
+}
+function bounded(data, budget, error = false) {
+    const estimatedTokens = estimateTokens(JSON.stringify(data));
+    if (estimatedTokens > budget)
+        return protocolError("budget_exceeded", "Request fewer capabilities/names, a smaller inventory page, or increase schema_budget.", { required_tokens: estimatedTokens, schema_budget: budget });
+    return protocolResult(data, error);
+}
+export const resolveTool = {
+    name: "resolve",
+    execution: "parallel",
+    description: "Resolve exact capability IDs or tool names into reusable input contracts and a catalog revision. "
+        + "Interpret the user's language yourself; capabilities are stable IDs, not natural-language queries. "
+        + "Batch everything needed. No arguments lists families; namespace lists operations (tools lists all tools). "
+        + "Follow next_offset for pages. Does not execute or activate tools. Reuse contracts with execute.",
+    schema: { type: "object", properties: {
+            capabilities: { type: "array", items: { type: "string" }, maxItems: 24 },
+            names: { type: "array", items: { type: "string" }, maxItems: 24 },
+            namespace: { type: "string" }, offset: { type: "integer", minimum: 0 },
+            limit: { type: "integer", minimum: 1, maximum: 50 },
+            schema_budget: { type: "integer", minimum: 100, maximum: 32000, description: "Estimated tokens, default 4000" },
+        } },
+    handler: async (input, ctx) => resolve(input, ctx),
+};
+function resolve(input, ctx) {
+    if (ctx.signal.aborted)
+        return protocolError("cancelled", "Resolution cancelled.");
+    if (!ctx.tools)
+        return protocolError("unavailable", "Tool registry unavailable.");
+    const capabilities = strings(input["capabilities"]);
+    const requested = strings(input["names"]);
+    const offset = integer(input["offset"], 0, 0, Number.MAX_SAFE_INTEGER);
+    const limit = integer(input["limit"], 30, 1, 50);
+    const budget = integer(input["schema_budget"], 4000, 100, 32000);
+    if (!capabilities || !requested || offset === undefined || limit === undefined || budget === undefined
+        || input["namespace"] !== undefined && typeof input["namespace"] !== "string") {
+        return protocolError("invalid_input", "Use arrays of up to 24 exact IDs/names and integer limits within the schema.");
+    }
+    const namespace = String(input["namespace"] ?? "").trim();
+    const catalog = protocolCatalog(ctx.tools);
+    if (!capabilities.length && !requested.length) {
+        const rows = namespace === "tools"
+            ? [...catalog.tools.values()].filter(tool => !PROTOCOL_TOOLS.has(tool.name)).map(tool => ({
+                name: tool.name, description: tool.description.replace(/\s+/g, " ").slice(0, 180),
+                capabilities: ctx.tools.get(tool.name)?.capabilities ?? [],
+            }))
+            : namespace
+                ? [...catalog.capabilities.keys()].filter(cap => cap.startsWith(`${namespace}.`)).sort()
+                : [...new Set([...catalog.capabilities.keys()].map(cap => cap.split(".")[0])), "tools"].sort();
+        const end = Math.min(offset + limit, rows.length);
+        return bounded({ status: "inventory", revision: catalog.revision, namespace: namespace || "families",
+            entries: rows.slice(offset, end), total: rows.length, next_offset: end < rows.length ? end : null }, budget);
+    }
+    if (namespace || offset)
+        return protocolError("invalid_input", "Namespace and offset apply only to inventory listing.");
+    const unknown = capabilities.filter(cap => !catalog.capabilities.has(cap));
+    const names = new Set([...requested, ...capabilities.flatMap(cap => catalog.capabilities.get(cap) ?? [])]);
+    const unavailable = [...names].filter(name => !catalog.tools.has(name) || PROTOCOL_TOOLS.has(name));
+    // Continuation graph: walk once, include whole contracts, never run the continuation.
+    const pending = [...names].filter(name => !unavailable.includes(name));
+    const included = new Set();
+    const missingContinuations = new Set();
+    for (let cursor = 0; cursor < pending.length; cursor++) {
+        const name = pending[cursor];
+        if (included.has(name))
+            continue;
+        included.add(name);
+        for (const next of ctx.tools.get(name)?.continuations ?? []) {
+            if (!catalog.tools.has(next) || PROTOCOL_TOOLS.has(next))
+                missingContinuations.add(next);
+            else if (!included.has(next))
+                pending.push(next);
+        }
+    }
+    const contracts = [...included].map(name => {
+        const def = catalog.tools.get(name);
+        const tool = ctx.tools.get(name);
+        return { name, description: def.description, inputSchema: def.inputSchema,
+            ...(def.outputSchema ? { outputSchema: def.outputSchema } : {}),
+            ...(def.annotations ? { annotations: def.annotations } : {}),
+            ...(def._meta ? { _meta: def._meta } : {}),
+            mode: nativeCall(tool) ? "native" : name === "run_program" ? "program"
+                : name === "tool_invoke" ? "legacy" : DISCOVERY_TOOL_NAMES.has(name) ? "call" : "call_or_program",
+            continuations: tool.continuations ?? [] };
+    });
+    const incomplete = unknown.length > 0 || unavailable.length > 0 || missingContinuations.size > 0;
+    return bounded({ status: incomplete ? contracts.length ? "partial" : "unavailable" : "ready",
+        revision: catalog.revision, contracts,
+        ...(unknown.length ? { unknown_capabilities: unknown, hint: "List a namespace or use exact names; availability is catalog-scoped." } : {}),
+        ...(unavailable.length ? { unavailable_tools: unavailable } : {}),
+        ...(missingContinuations.size ? { unavailable_continuations: [...missingContinuations] } : {}),
+    }, budget, incomplete);
+}

package/dist/tools/shell-env.d.ts

@@ -0,0 +1,2 @@
+/** Python's legacy Windows encoding can truncate a file before failing to write Unicode. */
+export declare function shellEnvironment(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): NodeJS.ProcessEnv;

package/dist/tools/shell-env.js

@@ -0,0 +1,7 @@
+/** Python's legacy Windows encoding can truncate a file before failing to write Unicode. */
+export function shellEnvironment(env = process.env, platform = process.platform) {
+    if (platform !== "win32" || env["PYTHONUTF8"] !== undefined)
+        return env;
+    // Inherited by Python launched from bash, cmd or PowerShell; preserve explicit overrides.
+    return { ...env, PYTHONUTF8: "1" };
+}

package/dist/tools/team-input.d.ts

@@ -0,0 +1,3 @@
+import type { SpawnAgentSpec, ToolContext } from "../core/types.js";
+export declare function memberSlug(value: string): string;
+export declare function parseTeamMembers(raw: unknown, ctx: ToolContext): readonly SpawnAgentSpec[];

package/dist/tools/team-input.js

@@ -0,0 +1,129 @@
+import { posix } from "node:path";
+import { VascendPlanStore } from "../vascend/plan-store.js";
+import { validateTeamGraph } from "../vascend/team-scheduler.js";
+import { planBlockers } from "../vascend/plan-progress.js";
+export function memberSlug(value) {
+    return value.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+export function parseTeamMembers(raw, ctx) {
+    if (!Array.isArray(raw) || !raw.length || raw.length > 32)
+        throw new Error("members richiede da 1 a 32 collaboratori");
+    const members = raw.map((value) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error("ogni collaboratore deve essere un oggetto");
+        const m = value;
+        const slug = memberSlug(string(m, "slug"));
+        const goal = string(m, "mandate");
+        const castle = string(m, "group") || string(m, "castle");
+        if (!slug || (!goal && !castle))
+            throw new Error("ogni collaboratore richiede slug e mandate oppure group");
+        const effort = string(m, "effort").toLowerCase();
+        if (effort && !["low", "medium", "high", "max"].includes(effort))
+            throw new Error(`effort non valido: ${effort}`);
+        const after = list(m, "after").map(memberSlug);
+        if (after.some((slug) => !slug))
+            throw new Error("dipendenza senza slug valido");
+        const area = list(m, "area").map((path) => posix.normalize(path.replaceAll("\\", "/")));
+        if (area.some((path) => /[*?\[\]{}]/.test(path)))
+            throw new Error("area richiede percorsi, non glob");
+        const tasks = list(m, "tasks");
+        if (tasks.length && !castle)
+            throw new Error("tasks richiede group");
+        const tools = m["tools"];
+        if (tools !== undefined && (!tools || typeof tools !== "object" || Array.isArray(tools)))
+            throw new Error("tools deve essere un oggetto allow/deny");
+        return {
+            slug, goal,
+            ...(castle ? { castle } : {}), ...(tasks.length ? { tasks } : {}),
+            ...(area.length ? { area } : {}), ...(after.length ? { after: [...new Set(after)] } : {}),
+            ...(string(m, "parent") ? { parent: string(m, "parent") } : {}),
+            ...(string(m, "role") ? { role: string(m, "role") } : {}),
+            ...(string(m, "model") ? { model: string(m, "model") } : {}),
+            ...(effort ? { effort } : {}), ...(string(m, "instructions") ? { instructions: string(m, "instructions") } : {}),
+            ...(tools ? { tools: {
+                    ...("allow" in tools ? { allow: list(tools, "allow") } : {}),
+                    ...("deny" in tools ? { deny: list(tools, "deny") } : {}),
+                } } : {}),
+        };
+    });
+    validateTeamGraph(members);
+    if (!members.some((member) => member.castle))
+        return members;
+    const scope = ctx.planStoreId ?? ctx.roomStoreId ?? ctx.sessionId;
+    if (!ctx.sessionDir || !scope)
+        throw new Error("lista non disponibile per assegnare gruppi e attivita");
+    const store = VascendPlanStore.open(ctx.sessionDir, scope, { strict: true });
+    const owners = new Map();
+    const resolved = members.map((member) => {
+        if (!member.castle)
+            return member;
+        const castle = store.castle(member.castle);
+        if (!castle)
+            throw new Error(`gruppo non trovato: ${member.castle}`);
+        if (ctx.planCastle && ctx.planCastle !== castle.slug)
+            throw new Error(`delega fuori dal gruppo assegnato: ${castle.slug}`);
+        const tasks = member.tasks?.length ? member.tasks.map((ref) => {
+            const task = castle.tasks.find((task) => task.id.toLowerCase() === ref.toLowerCase() || String(task.bit) === ref);
+            if (!task)
+                throw new Error(`attivita non trovata: ${castle.slug}/${ref}`);
+            return task;
+        }) : castle.tasks.filter((task) => task.status !== "completed");
+        if (!tasks.length || tasks.every((task) => task.status === "completed"))
+            throw new Error(`nessun task aperto: ${castle.slug}`);
+        for (const task of tasks) {
+            if (ctx.planTasks && !ctx.planTasks.includes(task.id))
+                throw new Error(`delega fuori dai task assegnati: ${castle.slug}/${task.id}`);
+            const ref = `${castle.slug}/${task.id}`;
+            const previous = owners.get(ref);
+            if (previous)
+                throw new Error(`task ${ref} assegnato sia a ${previous} sia a ${member.slug}`);
+            owners.set(ref, member.slug);
+        }
+        const after = new Set(member.after ?? []);
+        if (castle.after && store.castle(castle.after)?.tasks.some((task) => task.status !== "completed")) {
+            const prerequisites = members.filter((candidate) => candidate.castle === castle.after);
+            if (!prerequisites.length)
+                throw new Error(`prerequisito ${castle.after} ancora aperto e non assegnato`);
+            for (const prerequisite of prerequisites)
+                after.add(prerequisite.slug);
+        }
+        if (castle.after && !store.castle(castle.after))
+            throw new Error(`prerequisito mancante: ${castle.after}`);
+        return { ...member, tasks: tasks.map((task) => task.id), ...(after.size ? { after: [...after] } : {}),
+            goal: member.goal || `${castle.title}: ${tasks.map((task) => `${task.id} ${task.title}`).join("; ")}` };
+    });
+    const completeDependencies = resolved.map((member) => {
+        if (!member.castle)
+            return member;
+        const after = new Set(member.after ?? []);
+        for (const blocker of planBlockers(store.castles(), member.castle)) {
+            if (blocker.reason !== "incomplete")
+                throw new Error(`prerequisito ${blocker.castle}: ${blocker.reason}`);
+            for (const task of store.castle(blocker.castle).tasks.filter((task) => task.status !== "completed")) {
+                const owner = owners.get(`${blocker.castle}/${task.id}`);
+                if (!owner)
+                    throw new Error(`prerequisito non assegnato: ${blocker.castle}/${task.id}`);
+                after.add(owner);
+            }
+        }
+        return { ...member, ...(after.size ? { after: [...after] } : {}) };
+    });
+    validateTeamGraph(completeDependencies);
+    return completeDependencies;
+}
+function string(input, key) {
+    const value = input[key];
+    if (value === undefined)
+        return "";
+    if (typeof value !== "string")
+        throw new Error(`${key} deve essere una stringa`);
+    return value.trim();
+}
+function list(input, key) {
+    const value = input[key];
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item.trim()))
+        throw new Error(`${key} deve contenere stringhe non vuote`);
+    return value.map((item) => item.trim());
+}

package/dist/tools/team-tools.d.ts

@@ -0,0 +1,7 @@
+import type { Tool } from "../core/types.js";
+export declare const teamEngageTool: Tool;
+export declare const teamSayTool: Tool;
+export declare const teamInboxTool: Tool;
+export declare const teamWaitTool: Tool;
+export declare const teamReportTool: Tool;
+export declare const teamTools: readonly Tool[];