@vascend/talos 0.1.0

package/dist/core/doctor.js

@@ -0,0 +1,125 @@
+// `talos doctor`: diagnostica dell'ambiente PRIMA di lavorare. Verifica cio'
+// che rompe silenziosamente una sessione: credenziali/provider risolvibili,
+// modello configurato instradabile, directory sessioni scrivibile, config
+// caricabile, risorse locali del progetto. Nessuna chiamata di rete: la
+// diagnosi e' locale e deterministica.
+//
+// Separazione host/logica: runDoctor produce dati (DoctorReport), il render e
+// l'exit code stanno in renderDoctorReport/doctorExitCode. Cosi' la CLI stampa,
+// i test verificano il report, un host futuro (Horizon) puo' consumare il JSON.
+import { accessSync, constants, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildConfig } from "./config.js";
+import { applyStoredCredentials, credentialsPath } from "./credentials.js";
+import { defaultRegistry, resolveStartupModel } from "../providers/registry.js";
+function worst(a, b) {
+    const rank = { ok: 0, warn: 1, fail: 2 };
+    return rank[b] > rank[a] ? b : a;
+}
+export function runDoctor(input, deps = {}) {
+    const makeRegistry = deps.registry ?? defaultRegistry;
+    const checks = [];
+    const push = (id, label, status, detail) => {
+        checks.push({ id, label, status, detail });
+    };
+    // 1) Runtime: versioni di Bun/Node (informativo, fail solo se irriconoscibile).
+    const bunVersion = globalThis.Bun?.version ?? "";
+    const nodeVersion = process.versions?.node ?? "";
+    push("runtime", "runtime", bunVersion || nodeVersion ? "ok" : "fail", bunVersion ? `bun ${bunVersion} (node ${nodeVersion})` : nodeVersion ? `node ${nodeVersion}` : "runtime non riconosciuto");
+    // 2) Config: buildConfig non deve lanciare; elenca i file caricati.
+    let cwd = input.cwd ?? process.cwd();
+    let sessionDir = "";
+    let configuredModel = input.model ?? "";
+    try {
+        const config = buildConfig({ ...(input.cwd !== undefined ? { cwd: input.cwd } : {}), ...(input.model !== undefined ? { model: input.model } : {}), env: input.env });
+        cwd = config.cwd;
+        sessionDir = config.sessionDir;
+        configuredModel = config.model;
+        push("config", "configurazione", "ok", config.loadedConfigFiles.length
+            ? `caricata da: ${config.loadedConfigFiles.join(", ")}`
+            : "default (nessun file di config)");
+    }
+    catch (err) {
+        push("config", "configurazione", "fail", `buildConfig fallita: ${err.message}`);
+    }
+    // 3) Credenziali persistite + provider risolvibili con l'env effettivo.
+    const env = applyStoredCredentials(input.env);
+    const storedPath = credentialsPath(input.env);
+    const stored = storedPath && existsSync(storedPath);
+    let providerIds = [];
+    try {
+        providerIds = makeRegistry(env).list().map((p) => p.id);
+        push("providers", "provider", providerIds.length ? "ok" : "fail", providerIds.length
+            ? `${providerIds.length} configurati: ${providerIds.join(", ")}${stored ? ` (credenziali: ${storedPath})` : ""}`
+            : "nessun provider con credenziali: esporta una API key (es. ANTHROPIC_API_KEY) o usa un login OAuth");
+    }
+    catch (err) {
+        push("providers", "provider", "fail", err.message);
+    }
+    // 4) Modello configurato: instradabile? Segnala il fallback silenzioso.
+    if (providerIds.length) {
+        try {
+            const startup = resolveStartupModel(makeRegistry(env), configuredModel);
+            const fellBack = configuredModel && startup.model !== configuredModel;
+            push("model", "modello", fellBack ? "warn" : "ok", fellBack
+                ? `"${configuredModel}" non instradabile: fallback a ${startup.model}`
+                : startup.model);
+        }
+        catch (err) {
+            push("model", "modello", "fail", err.message);
+        }
+    }
+    else {
+        push("model", "modello", "warn", `configurato ${configuredModel || "(default)"}; nessun provider per instradarlo`);
+    }
+    // 5) Directory sessioni scrivibile (crea, tocca, pulisce).
+    if (sessionDir) {
+        try {
+            mkdirSync(sessionDir, { recursive: true });
+            const probe = join(sessionDir, `.doctor-${process.pid}.tmp`);
+            writeFileSync(probe, "ok");
+            rmSync(probe, { force: true });
+            push("sessions", "sessioni", "ok", sessionDir);
+        }
+        catch (err) {
+            push("sessions", "sessioni", "fail", `directory non scrivibile: ${sessionDir} (${err.message})`);
+        }
+    }
+    // 6) Risorse locali del progetto (estensioni/skill/config): presenza e trust.
+    const localDirs = [".talos/extensions", ".talos/config.json", "talos.config.json", "AGENTS.md"]
+        .filter((rel) => existsSync(join(cwd, rel)));
+    if (localDirs.length) {
+        let readable = true;
+        for (const rel of localDirs) {
+            try {
+                accessSync(join(cwd, rel), constants.R_OK);
+            }
+            catch {
+                readable = false;
+            }
+        }
+        push("local", "risorse locali", readable ? "ok" : "warn", `${localDirs.join(", ")}${readable ? "" : " (non tutte leggibili)"}`);
+    }
+    else {
+        push("local", "risorse locali", "ok", "nessuna (il progetto non definisce estensioni/skill)");
+    }
+    const status = checks.reduce((acc, check) => worst(acc, check.status), "ok");
+    return { cwd, checks, status };
+}
+const STATUS_MARK = { ok: "ok  ", warn: "WARN", fail: "FAIL" };
+export function renderDoctorReport(report) {
+    const lines = [];
+    lines.push(`talos doctor — ${report.cwd}`);
+    for (const check of report.checks) {
+        lines.push(`  [${STATUS_MARK[check.status]}] ${check.label.padEnd(14)} ${check.detail}`);
+    }
+    lines.push(report.status === "ok"
+        ? "tutto in ordine."
+        : report.status === "warn"
+            ? "avvisi presenti: la sessione parte ma con fallback."
+            : "problemi bloccanti: risolvi i FAIL prima di avviare una sessione.");
+    return lines.join("\n");
+}
+export function doctorExitCode(report) {
+    return report.status === "fail" ? 1 : 0;
+}

package/dist/core/effort.d.ts

@@ -0,0 +1,5 @@
+export type Effort = "" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export declare function effectiveToolName(name: string, input?: Record<string, unknown>): string;
+export declare function effortRoutingEnabled(env: NodeJS.ProcessEnv): boolean;
+export declare function isRoutineBatch(toolNames: readonly string[], hadError: boolean): boolean;
+export declare function routeEffort(base: Effort, turn: number, routine: boolean, enabled: boolean): Effort;

package/dist/core/effort.js

@@ -0,0 +1,42 @@
+// Effort routing dinamico: abbassa il livello di reasoning sui turni di ROUTINE
+// (digestione di letture/ricerche, niente scrittura ne' errori) e tiene l'effort
+// pieno sui turni che decidono/scrivono. Riduce latenza e costo senza perdere
+// qualita' dove serve. Modulo PURO (testabile); il gate via env.
+// Tool di sola lettura/ricerca: un turno che ha eseguito SOLO questi e' "routine"
+// (il modello deve solo assorbire l'output e proseguire).
+const READONLY_TOOLS = new Set([
+    "read_file", "list_dir", "glob", "grep", "recall", "web_fetch",
+    "tool_search", "resolve", "skill_search", "output_page", "bash_output",
+]);
+// Nome del tool che ha DAVVERO lavorato. Una chiamata via tool_invoke porta il
+// bersaglio in `input.name`: senza questa risoluzione un turno di sole letture
+// mediate dal meta-tool non risulterebbe mai di routine, e il routing
+// dell'effort resterebbe inattivo per l'intero profilo Horizon.
+export function effectiveToolName(name, input) {
+    if (name === "execute") {
+        const target = input?.["mode"] === "call" ? input["tool"] : undefined;
+        return typeof target === "string" && target.trim() ? target.trim() : name;
+    }
+    if (name !== "tool_invoke")
+        return name;
+    const target = input?.["name"];
+    return typeof target === "string" && target.trim() ? target.trim() : name;
+}
+export function effortRoutingEnabled(env) {
+    const v = (env["TALOS_EFFORT_ROUTING"] ?? "").trim().toLowerCase();
+    return !(v === "0" || v === "off" || v === "false" || v === "no");
+}
+// Il batch di tool appena eseguito e' di routine? (solo read-only, nessun errore).
+export function isRoutineBatch(toolNames, hadError) {
+    return !hadError && toolNames.length > 0 && toolNames.every((n) => READONLY_TOOLS.has(n));
+}
+// Effort effettivo del prossimo turno. Turno 0 (decisione iniziale) e turni non
+// di routine usano l'effort configurato; i turni di routine lo abbassano. Non
+// alza mai sopra il configurato.
+export function routeEffort(base, turn, routine, enabled) {
+    if (!enabled || turn === 0 || !routine)
+        return base;
+    if (base === "max" || base === "xhigh" || base === "high" || base === "medium")
+        return "low";
+    return base; // low / "" restano invariati
+}

package/dist/core/env-paths.d.ts

@@ -0,0 +1,3 @@
+export declare function homeDirFromEnv(env: NodeJS.ProcessEnv): string;
+export declare function talosConfigDir(env: NodeJS.ProcessEnv): string;
+export declare function defaultSessionDir(cwd: string, env: NodeJS.ProcessEnv): string;

package/dist/core/env-paths.js

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+function nonEmpty(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+// Risolve la home dall'OGGETTO env ricevuto, senza consultare implicitamente
+// process.env. Questo rende bootstrap e test isolabili: su Windows USERPROFILE
+// ha precedenza, su POSIX HOME; l'altra variabile resta un fallback portabile.
+export function homeDirFromEnv(env) {
+    const home = nonEmpty(env["HOME"]);
+    const profile = nonEmpty(env["USERPROFILE"]);
+    const configured = process.platform === "win32"
+        ? profile ?? home
+        : home ?? profile;
+    return configured ?? homedir();
+}
+// Directory globale di Talos. TALOS_CONFIG_DIR e' l'override esplicito comune
+// a config, settings e credenziali; altrimenti vive sotto la home risolta sopra.
+export function talosConfigDir(env) {
+    return nonEmpty(env["TALOS_CONFIG_DIR"]) ?? join(homeDirFromEnv(env), ".talos");
+}
+// Lo stato runtime appartiene all'utente, non al repository. Il path completo
+// distingue checkout omonimi; realpath e case folding unificano gli alias.
+export function defaultSessionDir(cwd, env) {
+    let canonical = resolve(cwd);
+    try {
+        canonical = realpathSync.native(canonical);
+    }
+    catch { /* cwd non ancora creato */ }
+    if (process.platform === "win32")
+        canonical = canonical.toLowerCase();
+    const name = (basename(canonical).replace(/[^a-zA-Z0-9._-]/g, "_") || "workspace").slice(0, 60);
+    const digest = createHash("sha256").update(canonical).digest("hex").slice(0, 24);
+    return resolve(cwd, talosConfigDir(env), "projects", `${name}-${digest}`, "sessions");
+}

package/dist/core/execution-guidance.d.ts

@@ -0,0 +1,9 @@
+import type { ToolCallPart, ToolResultPart } from "./types.js";
+export declare const EXECUTION_GUIDANCE = "Efficient execution\n- Determine whether the user wants advice, an explanation, instructions for manual work, or\n  actual execution. Advice and manual instructions are fulfilled by the response; do not run\n  their example scripts or perform the user's setup. A todo list does not grant authorization.\n  Before continuing after an error, check whether further agent action is needed and authorized.\n  Stop when the request is answered; wait when the next step belongs to the user or needs input.\n  Preserve incomplete tasks honestly instead of forcing completion or retrying indefinitely.\n- For a small cosmetic change (one button color, label, spacing or font), locate the affected\n  component, edit it, then verify the local result. Do not create a plan, delegate, research the\n  web, inspect the whole repository or run a global test/build cycle unless evidence requires it.\n  Escalate scope only when the actual dependency or failure demands it.\n- Decide what evidence is needed for the next decision. Issue independent reads together and\n  reuse results that are still valid. Do not spend a model round on each already-decided action.\n- Use run_program for known sequences: await dependent edits and plan transitions in order,\n  stop on errors, and return a concise summary. Complete a task only after its checks succeed.\n- Prepare related replacements in one round. Never edit the same file concurrently. Independent\n  edits on distinct files may run together in bounded groups of at most four; await every outcome\n  before inspecting the result or starting dependent work. Keep permission gates in place.\n- For short checks use foreground bash, or background with its brief initial wait. Use\n  background=true with yield_time_ms=0 for persistent servers or work that must detach immediately.\n  Collect ready background results together; a running command is not a passed check.\n- Run the relevant integrated checks after the edits. Repeat checks only after changes, failures\n  or a concrete unresolved concern; do not duplicate typecheck and build without a reason.\n- When parallel work is authorized and worthwhile, start with at most two collaborators on\n  concrete disjoint areas, agree on interfaces and acceptance checks, and declare after dependencies.\n  The coordinator reviews the combined result. Prefer one agent for small or tightly coupled work.\n- Format user-facing responses in readable Markdown: short paragraphs, **bold** key findings,\n  lists for steps, tables for comparisons, fenced code with a language, and descriptive links.\n  Keep internal planning notation out of ordinary explanations unless the user asks for it.";
+export declare class ExecutionGuidance {
+    private previous;
+    private readonly reminded;
+    observe(calls: readonly ToolCallPart[], results: readonly ToolResultPart[]): string;
+}
+export declare function isSmallPresentationChange(text: string): boolean;
+export declare function smallChangeGuidance(text: string): string;

package/dist/core/execution-guidance.js

@@ -0,0 +1,73 @@
+import { effectiveToolName } from "./effort.js";
+export const EXECUTION_GUIDANCE = `Efficient execution
+- Determine whether the user wants advice, an explanation, instructions for manual work, or
+  actual execution. Advice and manual instructions are fulfilled by the response; do not run
+  their example scripts or perform the user's setup. A todo list does not grant authorization.
+  Before continuing after an error, check whether further agent action is needed and authorized.
+  Stop when the request is answered; wait when the next step belongs to the user or needs input.
+  Preserve incomplete tasks honestly instead of forcing completion or retrying indefinitely.
+- For a small cosmetic change (one button color, label, spacing or font), locate the affected
+  component, edit it, then verify the local result. Do not create a plan, delegate, research the
+  web, inspect the whole repository or run a global test/build cycle unless evidence requires it.
+  Escalate scope only when the actual dependency or failure demands it.
+- Decide what evidence is needed for the next decision. Issue independent reads together and
+  reuse results that are still valid. Do not spend a model round on each already-decided action.
+- Use run_program for known sequences: await dependent edits and plan transitions in order,
+  stop on errors, and return a concise summary. Complete a task only after its checks succeed.
+- Prepare related replacements in one round. Never edit the same file concurrently. Independent
+  edits on distinct files may run together in bounded groups of at most four; await every outcome
+  before inspecting the result or starting dependent work. Keep permission gates in place.
+- For short checks use foreground bash, or background with its brief initial wait. Use
+  background=true with yield_time_ms=0 for persistent servers or work that must detach immediately.
+  Collect ready background results together; a running command is not a passed check.
+- Run the relevant integrated checks after the edits. Repeat checks only after changes, failures
+  or a concrete unresolved concern; do not duplicate typecheck and build without a reason.
+- When parallel work is authorized and worthwhile, start with at most two collaborators on
+  concrete disjoint areas, agree on interfaces and acceptance checks, and declare after dependencies.
+  The coordinator reviews the combined result. Prefer one agent for small or tightly coupled work.
+- Format user-facing responses in readable Markdown: short paragraphs, **bold** key findings,
+  lists for steps, tables for comparisons, fenced code with a language, and descriptive links.
+  Keep internal planning notation out of ordinary explanations unless the user asks for it.`;
+// One reminder per pattern per run, transient and outside conversation history.
+export class ExecutionGuidance {
+    previous = "";
+    reminded = new Set();
+    observe(calls, results) {
+        if (calls.length !== 1 || results.length !== 1 || results[0]?.isError) {
+            this.previous = "";
+            return "";
+        }
+        const call = calls[0];
+        const name = effectiveToolName(call.name, call.input);
+        const input = call.name === "tool_invoke" || call.name === "execute" ? call.input["args"] : call.input;
+        const path = input && typeof input === "object" ? input["path"] : undefined;
+        const pattern = name === "vascend_mark" ? "plan"
+            : name === "bash_output" && input && typeof input === "object" && input["kill"] !== true ? "poll"
+                : name === "edit_file" && typeof path === "string" ? `edit:${path}` : "";
+        const repeated = pattern && pattern === this.previous;
+        this.previous = pattern;
+        const category = pattern.startsWith("edit:") ? "edit" : pattern;
+        if (!repeated || this.reminded.has(category))
+            return "";
+        this.reminded.add(category);
+        const advice = category === "plan"
+            ? "Group already-decided plan transitions with the next work in run_program, using sequential await and checking each outcome. Do not mark unverified work completed."
+            : category === "edit"
+                ? "Prepare the remaining known edits together. Apply edits to the same file sequentially in run_program; independent files may be edited concurrently. Await all outcomes."
+                : "Avoid a separate model round for each ready background result. Collect them together with independent work, and use foreground mode for short checks. Confirm the final exit status.";
+        return `[Execution efficiency]\n${advice} Keep dependencies, permissions and verification intact.`;
+    }
+}
+// Conservative hint, not a capability restriction or a deadline. Broad work,
+// explicit continuation and assigned collaborator tasks keep their full plan.
+export function isSmallPresentationChange(text) {
+    if (text.length > 240 || /\b(tutt[oaie]|inter[oaie]|ovunque|all|entire|every|refactor|redesign|migra\w*|sicurezza|security|accessibil\w*|architett\w*|continua\w*|riprend\w*|resume|continue|team|parallel\w*|collabor\w*|poi|anche|inoltre|then|also|performance|logic[ae]?|auth\w*|database|comportamento|behavior|api|funzion\w*)\b/i.test(text))
+        return false;
+    return /\b(cambia|modifica|imposta|rinomina|sostituisci|change|set|rename|adjust|update)\b/i.test(text)
+        && /\b(colore|color|colour|padding|margine|margin|spaziatura|spacing|font|etichetta|label)\b/i.test(text);
+}
+export function smallChangeGuidance(text) {
+    return isSmallPresentationChange(text)
+        ? "[Small presentation change]\nStay on this local edit: locate the component, change it, verify the affected result, and finish concisely. Do not resume an unrelated old plan or start planning, delegation, broad research or global checks without a concrete need. Preserve required project checks."
+        : "";
+}

package/dist/core/execution-target.d.ts

@@ -0,0 +1,41 @@
+export type ExecutionTargetKind = "local" | "wsl" | "ssh" | "container";
+export type ExecutionPlatform = "windows" | "macos" | "linux";
+export interface LocalExecutionTarget {
+    readonly kind: "local";
+    readonly platform: ExecutionPlatform;
+}
+export interface WslExecutionTarget {
+    readonly kind: "wsl";
+    readonly distro: string;
+    readonly platform: "linux";
+}
+export interface SshExecutionTarget {
+    readonly kind: "ssh";
+    readonly host: string;
+    readonly platform: ExecutionPlatform;
+}
+export interface ContainerExecutionTarget {
+    readonly kind: "container";
+    readonly containerId: string;
+    readonly platform: "linux";
+    readonly parent: LocalExecutionTarget | WslExecutionTarget | SshExecutionTarget;
+}
+export type ExecutionTarget = LocalExecutionTarget | WslExecutionTarget | SshExecutionTarget | ContainerExecutionTarget;
+export interface ExecutionCapabilities {
+    readonly platform: ExecutionPlatform;
+    readonly arch: string;
+    readonly caseSensitive: boolean;
+    readonly home: string;
+    readonly shell: string;
+    readonly pathSeparator: "/" | "\\";
+    readonly node?: string;
+    readonly bun?: string;
+    readonly git?: string;
+    readonly terminal?: boolean;
+    readonly agentHostRuntimeReady?: boolean;
+}
+export declare function localExecutionTarget(platform?: NodeJS.Platform): LocalExecutionTarget;
+export declare function normalizeExecutionTarget(value: unknown, platform?: NodeJS.Platform): ExecutionTarget;
+export declare function executionTargetKey(target: ExecutionTarget): string;
+export declare function executionPathKey(target: ExecutionTarget, path: string): string;
+export declare function workspaceUri(target: ExecutionTarget, path: string): string;

package/dist/core/execution-target.js

@@ -0,0 +1,69 @@
+function currentPlatform(platform = process.platform) {
+    if (platform === "win32")
+        return "windows";
+    if (platform === "darwin")
+        return "macos";
+    return "linux";
+}
+function safeId(value, label) {
+    const id = String(value ?? "").trim();
+    if (!id || id.length > 160 || !/^[A-Za-z0-9._@+-]+$/.test(id)) {
+        throw new Error(`${label} non valido`);
+    }
+    return id;
+}
+export function localExecutionTarget(platform = process.platform) {
+    return Object.freeze({ kind: "local", platform: currentPlatform(platform) });
+}
+export function normalizeExecutionTarget(value, platform = process.platform) {
+    if (!value || typeof value !== "object")
+        return localExecutionTarget(platform);
+    const row = value;
+    const kind = String(row["kind"] ?? "local").toLowerCase();
+    if (kind === "wsl") {
+        return Object.freeze({ kind: "wsl", distro: safeId(row["distro"], "distribuzione WSL"), platform: "linux" });
+    }
+    if (kind === "ssh") {
+        const remotePlatform = String(row["platform"] ?? "linux").toLowerCase();
+        const resolvedPlatform = remotePlatform === "windows" || remotePlatform === "macos"
+            ? remotePlatform
+            : "linux";
+        return Object.freeze({ kind: "ssh", host: safeId(row["host"], "host SSH"), platform: resolvedPlatform });
+    }
+    if (kind === "container") {
+        const parent = normalizeExecutionTarget(row["parent"], platform);
+        if (parent.kind === "container")
+            throw new Error("un container non puo' contenere un altro target container");
+        return Object.freeze({
+            kind: "container",
+            containerId: safeId(row["containerId"], "container"),
+            platform: "linux",
+            parent,
+        });
+    }
+    return localExecutionTarget(platform);
+}
+export function executionTargetKey(target) {
+    if (target.kind === "local")
+        return `local:${target.platform}`;
+    if (target.kind === "wsl")
+        return `wsl:${target.distro.toLowerCase()}`;
+    if (target.kind === "ssh")
+        return `ssh:${target.host.toLowerCase()}`;
+    return `container:${executionTargetKey(target.parent)}:${target.containerId}`;
+}
+export function executionPathKey(target, path) {
+    const clean = String(path ?? "").replace(/[\\/]+$/, "");
+    const caseSensitive = target.kind === "wsl" || target.kind === "container" || target.platform !== "windows";
+    return caseSensitive ? clean : clean.toLowerCase();
+}
+export function workspaceUri(target, path) {
+    const encodedPath = String(path ?? "").replace(/\\/g, "/").split("/").map(encodeURIComponent).join("/");
+    if (target.kind === "local")
+        return `file://${encodedPath.startsWith("/") ? "" : "/"}${encodedPath}`;
+    if (target.kind === "wsl")
+        return `horizon-wsl://${encodeURIComponent(target.distro)}/${encodedPath.replace(/^\/+/, "")}`;
+    if (target.kind === "ssh")
+        return `horizon-ssh://${encodeURIComponent(target.host)}/${encodedPath.replace(/^\/+/, "")}`;
+    return `horizon-container://${encodeURIComponent(target.containerId)}/${encodedPath.replace(/^\/+/, "")}`;
+}

package/dist/core/file-coordination.d.ts

@@ -0,0 +1,66 @@
+import { type ExecutionTarget } from "./execution-target.js";
+export type FileActivityMode = "viewing" | "editing" | "writing";
+export type FileActorKind = "human" | "main" | "subagent" | "agent" | "external";
+export interface FileActor {
+    readonly id: string;
+    readonly label: string;
+    readonly kind: FileActorKind;
+}
+export interface FilePresence {
+    readonly path: string;
+    readonly mode: FileActivityMode;
+    readonly actor: FileActor;
+    readonly updatedAt: number;
+}
+export interface FileCoordinationEvent {
+    readonly phase: "observed" | "blocked" | "acquired" | "released" | "presence";
+    readonly path: string;
+    readonly actor: FileActor;
+    readonly mode: FileActivityMode;
+    readonly others: readonly FilePresence[];
+    readonly at: number;
+}
+export interface FileLease {
+    readonly id: string;
+    readonly path: string;
+    readonly actor: FileActor;
+}
+export type FileLeaseResult = {
+    readonly ok: true;
+    readonly lease: FileLease;
+} | {
+    readonly ok: false;
+    readonly conflicts: readonly FilePresence[];
+};
+export interface FileCoordinationContext {
+    readonly hub: FileCoordinationHub;
+    readonly actor: FileActor;
+    readonly emit?: (event: FileCoordinationEvent) => void;
+}
+/** Registro condiviso fra engine, main agent, sub-agent e host desktop. */
+export declare class FileCoordinationHub {
+    readonly cwd: string;
+    readonly executionTarget: ExecutionTarget;
+    private readonly persistent;
+    private readonly byPath;
+    private readonly leases;
+    constructor(cwd: string, executionTarget?: ExecutionTarget, leaseDirectory?: string);
+    path(value: string): string;
+    list(path?: string, exceptActorId?: string): readonly FilePresence[];
+    replaceActorPresence(actor: FileActor, entries: readonly {
+        readonly path: string;
+        readonly mode: FileActivityMode;
+    }[]): readonly FileCoordinationEvent[];
+    observe(pathValue: string, actor: FileActor): readonly FilePresence[];
+    acquire(pathValue: string, actor: FileActor): FileLeaseResult;
+    validate(lease: FileLease): readonly FilePresence[];
+    release(lease: FileLease): void;
+    clearActor(actorId: string, includeLeases?: boolean): void;
+    private activeConflicts;
+    private storageFailure;
+    private put;
+    private prune;
+}
+export declare function fileActor(id: string, label: string, kind: FileActorKind): FileActor;
+export declare function withFileActor(context: FileCoordinationContext, actor: FileActor): FileCoordinationContext;
+export declare function formatFileConflicts(conflicts: readonly FilePresence[]): string;

package/dist/core/file-coordination.js

@@ -0,0 +1,176 @@
+import { isAbsolute, normalize, resolve, dirname, basename, join } from "node:path";
+import { realpathSync } from "node:fs";
+import { executionPathKey, localExecutionTarget } from "./execution-target.js";
+import { randomUUID } from "node:crypto";
+import { FileLeaseStore, workspaceLeaseDirectory } from "./file-lease-store.js";
+const ACTIVE_MODES = new Set(["editing", "writing"]);
+const EXTERNAL_PRESENCE_TTL_MS = 15_000;
+/** Registro condiviso fra engine, main agent, sub-agent e host desktop. */
+export class FileCoordinationHub {
+    cwd;
+    executionTarget;
+    persistent;
+    byPath = new Map();
+    leases = new Map();
+    constructor(cwd, executionTarget = localExecutionTarget(), leaseDirectory = workspaceLeaseDirectory(cwd, executionTarget)) {
+        this.cwd = cwd;
+        this.executionTarget = executionTarget;
+        this.persistent = new FileLeaseStore(leaseDirectory);
+    }
+    path(value) {
+        const absolute = isAbsolute(value) ? value : resolve(this.cwd, value);
+        const clean = this.executionTarget.kind === "local" ? canonicalLocalPath(normalize(absolute)) : normalize(absolute);
+        return executionPathKey(this.executionTarget, clean);
+    }
+    list(path, exceptActorId) {
+        this.prune();
+        const rows = path
+            ? [...(this.byPath.get(this.path(path))?.values() ?? [])]
+            : [...this.byPath.values()].flatMap((entries) => [...entries.values()]);
+        let shared = [];
+        try {
+            shared = this.persistent.list(path ? this.path(path) : undefined);
+        }
+        catch { /* reads remain available */ }
+        return [...new Map([...rows, ...shared].map((entry) => [entry.path + "\0" + entry.actor.id, entry])).values()]
+            .filter((entry) => !exceptActorId || entry.actor.id !== exceptActorId)
+            .map((entry) => ({ path: entry.path, mode: entry.mode, actor: entry.actor, updatedAt: entry.updatedAt }))
+            .sort((a, b) => b.updatedAt - a.updatedAt || a.actor.label.localeCompare(b.actor.label));
+    }
+    replaceActorPresence(actor, entries) {
+        this.clearActor(actor.id, false);
+        const events = [];
+        for (const entry of entries) {
+            const path = this.path(entry.path);
+            const others = this.activeConflicts(path, actor.id);
+            const at = Date.now();
+            this.put({ path, mode: entry.mode, actor, updatedAt: at });
+            events.push({ phase: "presence", path, actor, mode: entry.mode, others, at });
+        }
+        return events;
+    }
+    observe(pathValue, actor) {
+        const path = this.path(pathValue);
+        const others = this.activeConflicts(path, actor.id);
+        this.put({ path, mode: "viewing", actor, updatedAt: Date.now() });
+        return others;
+    }
+    acquire(pathValue, actor) {
+        const path = this.path(pathValue);
+        const conflicts = this.activeConflicts(path, actor.id);
+        if (conflicts.length)
+            return { ok: false, conflicts };
+        const lease = {
+            id: `fl-${randomUUID()}`,
+            path,
+            actor,
+        };
+        try {
+            const shared = this.persistent.acquire(lease);
+            if (shared.length)
+                return { ok: false, conflicts: shared };
+        }
+        catch (error) {
+            return { ok: false, conflicts: [this.storageFailure(path, error)] };
+        }
+        this.leases.set(lease.id, lease);
+        this.put({ path, mode: "writing", actor, updatedAt: Date.now(), leaseId: lease.id });
+        return { ok: true, lease };
+    }
+    validate(lease) {
+        try {
+            return [...this.activeConflicts(lease.path, lease.actor.id), ...this.persistent.validate(lease)];
+        }
+        catch (error) {
+            return [this.storageFailure(lease.path, error)];
+        }
+    }
+    release(lease) {
+        try {
+            this.persistent.release(lease);
+        }
+        catch { /* fail closed: a later writer sees the retained lease */ }
+        this.leases.delete(lease.id);
+        const entries = this.byPath.get(lease.path);
+        const current = entries?.get(lease.actor.id);
+        if (current?.leaseId === lease.id)
+            entries?.delete(lease.actor.id);
+        if (entries && entries.size === 0)
+            this.byPath.delete(lease.path);
+    }
+    clearActor(actorId, includeLeases = true) {
+        for (const [path, entries] of this.byPath) {
+            const current = entries.get(actorId);
+            if (current && (includeLeases || !current.leaseId))
+                entries.delete(actorId);
+            if (!entries.size)
+                this.byPath.delete(path);
+        }
+        if (includeLeases) {
+            for (const [id, lease] of this.leases) {
+                if (lease.actor.id === actorId)
+                    this.release(lease);
+            }
+        }
+    }
+    activeConflicts(path, actorId) {
+        this.prune(path);
+        return [...(this.byPath.get(path)?.values() ?? [])]
+            .filter((entry) => entry.actor.id !== actorId && ACTIVE_MODES.has(entry.mode))
+            .map(({ leaseId: _leaseId, ...entry }) => entry);
+    }
+    storageFailure(path, error) {
+        return { path, mode: "writing", updatedAt: Date.now(), actor: { id: "lease-store", kind: "external",
+                label: "coordinamento file non disponibile: " + (error instanceof Error ? error.message : String(error)) } };
+    }
+    put(entry) {
+        let entries = this.byPath.get(entry.path);
+        if (!entries) {
+            entries = new Map();
+            this.byPath.set(entry.path, entries);
+        }
+        entries.set(entry.actor.id, entry);
+    }
+    prune(onlyPath) {
+        const cutoff = Date.now() - EXTERNAL_PRESENCE_TTL_MS;
+        const paths = onlyPath ? [onlyPath] : [...this.byPath.keys()];
+        for (const path of paths) {
+            const entries = this.byPath.get(path);
+            if (!entries)
+                continue;
+            for (const [actorId, entry] of entries) {
+                const external = entry.actor.kind === "human" || entry.actor.kind === "external";
+                if (external && !entry.leaseId && entry.updatedAt < cutoff)
+                    entries.delete(actorId);
+            }
+            if (!entries.size)
+                this.byPath.delete(path);
+        }
+    }
+}
+function canonicalLocalPath(path) {
+    let parent = path;
+    const tail = [];
+    for (;;) {
+        try {
+            return join(realpathSync(parent), ...tail);
+        }
+        catch { /* resolve the closest existing ancestor */ }
+        const next = dirname(parent);
+        if (next === parent)
+            return path;
+        tail.unshift(basename(parent));
+        parent = next;
+    }
+}
+export function fileActor(id, label, kind) {
+    return Object.freeze({ id: id.trim(), label: label.trim() || id.trim(), kind });
+}
+export function withFileActor(context, actor) {
+    return { ...context, actor };
+}
+export function formatFileConflicts(conflicts) {
+    return conflicts
+        .map((entry) => `${entry.actor.label} (${entry.mode === "writing" ? "sta scrivendo" : "sta modificando"})`)
+        .join(", ");
+}