@vascend/talos 0.1.0

package/dist/vascend/patch-plan.js

@@ -0,0 +1,345 @@
+// Modello "Patch Plan": il PIANO STRUTTURATO che precede ogni modifica al
+// codice. Prima di editare, l'agente dichiara COSA vuole ottenere (goal), QUALI
+// file tocchera' (files), QUALI contratti/API sono coinvolti (contracts), QUALI
+// rischi/regressioni introduce (risks) e QUALI test lo verificano (tests).
+//
+// Si inserisce nel flusso: analisi-repo -> recall -> [PATCH PLAN] -> edit ->
+// verify. Lo stato del piano traccia il ciclo di vita: draft (appena scritto),
+// approved (pronto a editare), applied (edit fatto), verified (test passati),
+// abandoned (scartato). E' persistito per sessione ed emette eventi sul
+// MemoryStore (dominio "patches") cosi' da essere richiamabile via recall.
+//
+// Allineato a vision.ts: zero dipendenze a runtime, tipi readonly, parsing
+// robusto che non lancia mai, API immutabile, serializzazione deterministica.
+export const PATCH_PLAN_SCHEMA_VERSION = 1;
+const FILE_KINDS = new Set(["create", "modify", "delete", "rename"]);
+const CONTRACT_IMPACTS = new Set(["uses", "changes", "breaks"]);
+const RISK_SEVERITIES = new Set(["low", "medium", "high"]);
+const TEST_STATUSES = new Set(["pending", "passed", "failed"]);
+const PLAN_STATUSES = new Set([
+    "draft", "approved", "applied", "verified", "abandoned",
+]);
+// Tetto anti-esplosione (parita' con vision/requirements).
+const MAX_FILES = 50;
+const MAX_CONTRACTS = 30;
+const MAX_RISKS = 30;
+const MAX_TESTS = 30;
+// ---------------------------------------------------------------------------
+// 2. NORMALIZZAZIONE + VALIDAZIONE
+// ---------------------------------------------------------------------------
+function nowIso() {
+    return new Date().toISOString();
+}
+function asString(v) {
+    return typeof v === "string" ? v : v == null ? "" : String(v);
+}
+function normalizeFileKind(v) {
+    const s = asString(v).trim().toLowerCase();
+    return FILE_KINDS.has(s) ? s : "modify";
+}
+function normalizeImpact(v) {
+    const s = asString(v).trim().toLowerCase();
+    return CONTRACT_IMPACTS.has(s) ? s : "uses";
+}
+function normalizeSeverity(v) {
+    const s = asString(v).trim().toLowerCase();
+    return RISK_SEVERITIES.has(s) ? s : "medium";
+}
+function normalizeTestStatus(v) {
+    const s = asString(v).trim().toLowerCase();
+    return TEST_STATUSES.has(s) ? s : "pending";
+}
+function normalizeStatus(v) {
+    const s = asString(v).trim().toLowerCase();
+    return PLAN_STATUSES.has(s) ? s : "draft";
+}
+function normalizeFiles(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const f of raw) {
+        const obj = (f ?? {});
+        const path = asString(obj["path"]).trim();
+        if (!path)
+            continue;
+        const reason = asString(obj["reason"]).trim();
+        out.push({
+            path,
+            kind: normalizeFileKind(obj["kind"]),
+            ...(reason ? { reason } : {}),
+        });
+        if (out.length >= MAX_FILES)
+            break;
+    }
+    return out;
+}
+function normalizeContracts(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const c of raw) {
+        const obj = (c ?? {});
+        const name = asString(obj["name"]).trim();
+        if (!name)
+            continue;
+        const id = asString(obj["id"]).trim() || `C${out.length + 1}`;
+        const note = asString(obj["note"]).trim();
+        out.push({
+            id,
+            name,
+            impact: normalizeImpact(obj["impact"]),
+            ...(note ? { note } : {}),
+        });
+        if (out.length >= MAX_CONTRACTS)
+            break;
+    }
+    return out;
+}
+function normalizeRisks(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const r of raw) {
+        const obj = (r ?? {});
+        const text = asString(obj["text"]).trim();
+        if (!text)
+            continue;
+        const id = asString(obj["id"]).trim() || `R${out.length + 1}`;
+        const mitigation = asString(obj["mitigation"]).trim();
+        out.push({
+            id,
+            text,
+            severity: normalizeSeverity(obj["severity"]),
+            ...(mitigation ? { mitigation } : {}),
+        });
+        if (out.length >= MAX_RISKS)
+            break;
+    }
+    return out;
+}
+function normalizeTests(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const t of raw) {
+        const obj = (t ?? {});
+        const text = asString(obj["text"]).trim();
+        if (!text)
+            continue;
+        const id = asString(obj["id"]).trim() || `T${out.length + 1}`;
+        out.push({ id, text, status: normalizeTestStatus(obj["status"]) });
+        if (out.length >= MAX_TESTS)
+            break;
+    }
+    return out;
+}
+// Valida un Patch Plan gia' normalizzato: ritorna la lista (vuota = valido) dei
+// problemi BLOCCANTI. Un piano e' valido sse ha id, goal non vuoti e almeno un
+// file da toccare; gli id di contratti/rischi/test devono essere univoci.
+export function validatePatchPlan(p) {
+    const issues = [];
+    if (!p.id.trim())
+        issues.push({ field: "id", message: "id mancante" });
+    if (!p.goal.trim())
+        issues.push({ field: "goal", message: "goal (obiettivo della patch) mancante" });
+    if (p.files.length === 0)
+        issues.push({ field: "files", message: "nessun file da modificare" });
+    if (p.version !== PATCH_PLAN_SCHEMA_VERSION) {
+        issues.push({ field: "version", message: `versione schema attesa ${PATCH_PLAN_SCHEMA_VERSION}` });
+    }
+    dupCheck(p.contracts.map((c) => c.id), "contracts", issues);
+    dupCheck(p.risks.map((r) => r.id), "risks", issues);
+    dupCheck(p.tests.map((t) => t.id), "tests", issues);
+    return issues;
+}
+function dupCheck(ids, field, issues) {
+    const seen = new Set();
+    for (const id of ids) {
+        if (seen.has(id))
+            issues.push({ field: `${field}.${id}`, message: "id duplicato" });
+        seen.add(id);
+    }
+}
+export function isPatchPlanValid(p) {
+    return validatePatchPlan(p).length === 0;
+}
+// Costruisce un Patch Plan normalizzato e completo da un draft morbido. Applica
+// default, genera gli id mancanti e i timestamp. NON lancia: produce sempre un
+// oggetto (eventualmente non valido, da controllare con validatePatchPlan).
+export function createPatchPlan(draft, opts) {
+    const ts = opts?.now ?? nowIso();
+    return {
+        version: PATCH_PLAN_SCHEMA_VERSION,
+        id: asString(draft.id ?? opts?.id).trim() || "P1",
+        ...(asString(draft.taskRef).trim() ? { taskRef: asString(draft.taskRef).trim() } : {}),
+        goal: asString(draft.goal).trim(),
+        status: normalizeStatus(draft.status ?? "draft"),
+        files: normalizeFiles(draft.files),
+        contracts: normalizeContracts(draft.contracts),
+        risks: normalizeRisks(draft.risks),
+        tests: normalizeTests(draft.tests),
+        createdAt: ts,
+        updatedAt: ts,
+    };
+}
+// Parsing robusto da testo/JSON: estrae il primo blocco {...}, normalizza tutto.
+// Mai lancia: su input non valido ritorna null. Conserva i timestamp se presenti.
+export function parsePatchPlan(text, opts) {
+    const m = /\{[\s\S]*\}/.exec(text);
+    if (!m)
+        return null;
+    let root;
+    try {
+        root = JSON.parse(m[0]);
+    }
+    catch {
+        return null;
+    }
+    const ts = opts?.now ?? nowIso();
+    const createdAt = asString(root["createdAt"]).trim() || ts;
+    const updatedAt = asString(root["updatedAt"]).trim() || ts;
+    const taskRef = asString(root["taskRef"]).trim();
+    return {
+        version: PATCH_PLAN_SCHEMA_VERSION,
+        id: asString(root["id"]).trim() || "P1",
+        ...(taskRef ? { taskRef } : {}),
+        goal: asString(root["goal"]).trim(),
+        status: normalizeStatus(root["status"]),
+        files: normalizeFiles(root["files"]),
+        contracts: normalizeContracts(root["contracts"]),
+        risks: normalizeRisks(root["risks"]),
+        tests: normalizeTests(root["tests"]),
+        createdAt,
+        updatedAt,
+    };
+}
+// Aggiornamento immutabile: applica una patch e rinfresca updatedAt. I campi
+// passati sostituiscono quelli esistenti e vengono ri-normalizzati.
+export function updatePatchPlan(p, patch, opts) {
+    return {
+        ...p,
+        ...(patch.goal !== undefined ? { goal: asString(patch.goal).trim() } : {}),
+        ...(patch.status !== undefined ? { status: normalizeStatus(patch.status) } : {}),
+        ...(patch.taskRef !== undefined ? { taskRef: asString(patch.taskRef).trim() || undefined } : {}),
+        ...(patch.files !== undefined ? { files: normalizeFiles(patch.files) } : {}),
+        ...(patch.contracts !== undefined ? { contracts: normalizeContracts(patch.contracts) } : {}),
+        ...(patch.risks !== undefined ? { risks: normalizeRisks(patch.risks) } : {}),
+        ...(patch.tests !== undefined ? { tests: normalizeTests(patch.tests) } : {}),
+        updatedAt: opts?.now ?? nowIso(),
+    };
+}
+// ---------------------------------------------------------------------------
+// 3. SERIALIZZAZIONE
+// ---------------------------------------------------------------------------
+// Serializza in stringa JSON stabile (chiavi in ordine deterministico, indentata).
+export function patchPlanToJSON(p) {
+    return JSON.stringify(orderedPlan(p), null, 2);
+}
+// Deserializza da JSON. Alias semantico di parsePatchPlan per simmetria.
+export function patchPlanFromJSON(json, opts) {
+    return parsePatchPlan(json, opts);
+}
+function orderedPlan(p) {
+    return {
+        version: p.version,
+        id: p.id,
+        ...(p.taskRef ? { taskRef: p.taskRef } : {}),
+        goal: p.goal,
+        status: p.status,
+        files: p.files.map((f) => ({
+            path: f.path,
+            kind: f.kind,
+            ...(f.reason ? { reason: f.reason } : {}),
+        })),
+        contracts: p.contracts.map((c) => ({
+            id: c.id,
+            name: c.name,
+            impact: c.impact,
+            ...(c.note ? { note: c.note } : {}),
+        })),
+        risks: p.risks.map((r) => ({
+            id: r.id,
+            text: r.text,
+            severity: r.severity,
+            ...(r.mitigation ? { mitigation: r.mitigation } : {}),
+        })),
+        tests: p.tests.map((t) => ({ id: t.id, text: t.text, status: t.status })),
+        createdAt: p.createdAt,
+        updatedAt: p.updatedAt,
+    };
+}
+export function patchPlanSummary(p) {
+    return {
+        files: p.files.length,
+        contracts: p.contracts.length,
+        breakingContracts: p.contracts.filter((c) => c.impact === "breaks").length,
+        risks: p.risks.length,
+        highRisks: p.risks.filter((r) => r.severity === "high").length,
+        tests: p.tests.length,
+        testsPassed: p.tests.filter((t) => t.status === "passed").length,
+    };
+}
+export function patchPlanVerification(p) {
+    const total = p.tests.length;
+    const passed = p.tests.filter((t) => t.status === "passed").length;
+    const failed = p.tests.filter((t) => t.status === "failed").length;
+    return {
+        ratio: total === 0 ? 0 : passed / total,
+        verified: total > 0 && passed === total,
+        testsPassed: passed,
+        testsTotal: total,
+        testsFailed: failed,
+    };
+}
+const FILE_KIND_TAG = {
+    create: "CREATE",
+    modify: "MODIFY",
+    delete: "DELETE",
+    rename: "RENAME",
+};
+const SEVERITY_TAG = {
+    low: "LOW",
+    medium: "MED",
+    high: "HIGH",
+};
+function q(s, max = 200) {
+    return s.replace(/"/g, "'").slice(0, max);
+}
+// Formatta il Patch Plan in notazione Danilov: blocco di contesto (steer) da
+// iniettare all'agente prima dell'edit, parita' con buildVisionBlock. Ritorna
+// "" se il piano e' privo di goal.
+export function buildPatchPlanBlock(p) {
+    if (!p.goal.trim())
+        return "";
+    const fileDefs = p.files.map((f) => {
+        const why = f.reason ? ` -> ${q(f.reason, 120)}` : "";
+        return `@${FILE_KIND_TAG[f.kind]}[${q(f.path, 160)}]:${why || " -"}`;
+    });
+    const contractDefs = p.contracts.map((c) => `@${c.id}[${c.impact}]: ${q(c.name, 160)}${c.note ? ` -> ${q(c.note, 120)}` : ""}`);
+    const riskDefs = p.risks.map((r) => `@${r.id}[${SEVERITY_TAG[r.severity]}]: ${q(r.text, 160)}${r.mitigation ? ` (mitiga: ${q(r.mitigation, 120)})` : ""}`);
+    const testDefs = p.tests.map((t) => `@${t.id}[${t.status}]: ${q(t.text, 160)}`);
+    const ver = patchPlanVerification(p);
+    return `[VASCEND_PATCH_PLAN ${p.id}]
+INDICE
+1 = goal
+2 = file
+3 = contratti
+4 = rischi
+5 = test
+
+DEFINIZIONI
+@goal[patch]: "${q(p.goal)}"
+@stato[ciclo]: ${p.status}${p.taskRef ? ` (attivita ${p.taskRef})` : ""}
+${fileDefs.length ? fileDefs.join("\n") : "@file[nessuno]: -"}
+${contractDefs.length ? contractDefs.join("\n") : "@contratti[nessuno]: -"}
+${riskDefs.length ? riskDefs.join("\n") : "@rischi[nessuno]: -"}
+${testDefs.length ? testDefs.join("\n") : "@test[nessuno]: -"}
+
+RELAZIONI
+@R-edit: @goal[patch] -> @file  [ la modifica tocca questi file per l'obiettivo ]
+@R-contract: @file -> @contratti  [ i file alterano/usano queste superfici ]
+@R-risk: @contratti -> @rischi  [ i cambi di contratto generano regressioni potenziali ]
+@R-verify: @rischi -> @test  [ i test coprono i rischi prima del verify ]
+
+OUTPUT: piano di patch ${p.id}; verificato=${ver.verified} (test ${ver.testsPassed}/${ver.testsTotal}, falliti ${ver.testsFailed}). Edita solo i file elencati, poi esegui i test.`;
+}

package/dist/vascend/plan-progress.d.ts

@@ -0,0 +1,11 @@
+import { type CastlePlan, type PlanTask } from "./plan-store.js";
+export declare function taskTitles(input: unknown, available?: number): readonly string[];
+export declare function sameCastlePlan(castle: CastlePlan, title: string, tasks: readonly string[], after?: string): boolean;
+export interface PlanBlocker {
+    readonly castle: string;
+    readonly reason: "missing" | "incomplete" | "cycle";
+}
+export declare function planBlockers(castles: readonly CastlePlan[], slug: string): readonly PlanBlocker[];
+export declare function isConcreteTaskEvidence(value: string): boolean;
+export declare function hasTaskEvidence(task: PlanTask): boolean;
+export declare function nextPlanTask(castle: CastlePlan): PlanTask | undefined;

package/dist/vascend/plan-progress.js

@@ -0,0 +1,68 @@
+import { parseTaskTokens } from "./plan-store.js";
+// Public tool validation must never silently discard part of the requested work.
+export function taskTitles(input, available = 16) {
+    if (!Array.isArray(input) || input.length === 0)
+        throw new Error("tasks deve contenere almeno una attivita");
+    if (input.some((title) => typeof title !== "string" || !parseTaskTokens(title).title)) {
+        throw new Error("ogni task deve essere una stringa con un titolo non vuoto");
+    }
+    if (input.length > available) {
+        throw new Error(`troppe attivita: ${input.length} richieste, ${available} disponibili (max 16 per gruppo). Usa un altro gruppo`);
+    }
+    return input.map((title) => title.trim());
+}
+export function sameCastlePlan(castle, title, tasks, after) {
+    if (castle.title !== (title.trim() || castle.slug) || (castle.after ?? "") !== (after?.trim() ?? ""))
+        return false;
+    return castle.tasks.length === tasks.length && tasks.every((raw, index) => {
+        const meta = parseTaskTokens(raw);
+        const task = castle.tasks[index];
+        return task.title === meta.title && task.weight === meta.weight && Boolean(task.compact) === meta.compact
+            && meta.skills.every((skill) => task.skills?.includes(skill))
+            && JSON.stringify(task.files ?? []) === JSON.stringify(meta.files);
+    });
+}
+// Follow the entire prerequisite chain: forward references are allowed while
+// planning, but missing, unfinished or cyclic dependencies cannot be executed.
+export function planBlockers(castles, slug) {
+    const bySlug = new Map(castles.map((castle) => [castle.slug, castle]));
+    const seen = new Set([slug]);
+    const blockers = [];
+    let next = bySlug.get(slug)?.after;
+    while (next) {
+        if (seen.has(next)) {
+            blockers.push({ castle: next, reason: "cycle" });
+            break;
+        }
+        seen.add(next);
+        const dependency = bySlug.get(next);
+        if (!dependency) {
+            blockers.push({ castle: next, reason: "missing" });
+            break;
+        }
+        if (!dependency.tasks.length || dependency.tasks.some((task) => task.status !== "completed")) {
+            blockers.push({ castle: next, reason: "incomplete" });
+        }
+        next = dependency.after;
+    }
+    return blockers;
+}
+// This checks whether evidence is specific enough to inspect, not whether the
+// underlying claim is true. Verification remains the agent's responsibility.
+export function isConcreteTaskEvidence(value) {
+    const text = value.trim();
+    if (text.length < 12)
+        return false;
+    if (/^tool=(?:write_file|edit_file|bash|bash_output); target=.+; result=.+/.test(text))
+        return true;
+    return /(?:[A-Za-z]:[\\/]|(?:^|\s)[./]?[\w@-]+[\\/][\w./\\-]+|\.(?:ts|tsx|js|jsx|json|md|css|html|py|rs|go|java|cs|yml|yaml)\b|\b(?:test|tests|bun|npm|pnpm|pytest|cargo|build|lint|typecheck|comando|command|output|exit\s*code|pass|passed|verde|ok)\b)/i.test(text);
+}
+export function hasTaskEvidence(task) {
+    return (task.status === "running" || task.status === "completed")
+        && Boolean(task.evidence?.some(isConcreteTaskEvidence));
+}
+export function nextPlanTask(castle) {
+    return castle.tasks.find((task) => task.status === "running")
+        ?? castle.tasks.find((task) => task.status === "failed")
+        ?? castle.tasks.find((task) => task.status === "pending");
+}

package/dist/vascend/plan-store.d.ts

@@ -0,0 +1,64 @@
+export type PlanTaskStatus = "pending" | "running" | "completed" | "failed";
+export interface PlanTask {
+    readonly id: string;
+    readonly bit: number;
+    readonly mask: string;
+    readonly title: string;
+    readonly status: PlanTaskStatus;
+    readonly evidence?: readonly string[];
+    readonly tokens?: number;
+    readonly ms?: number;
+    readonly notes?: readonly string[];
+    readonly skills?: readonly string[];
+    readonly weight?: number;
+    readonly files?: readonly string[];
+    readonly compact?: boolean;
+}
+export interface TaskMeta {
+    readonly title: string;
+    readonly skills: readonly string[];
+    readonly weight?: number;
+    readonly files: readonly string[];
+    readonly compact: boolean;
+}
+export declare function parseTaskTokens(raw: string): TaskMeta;
+export interface CastlePlan {
+    readonly slug: string;
+    readonly title: string;
+    readonly maskTarget: string;
+    readonly custom: true;
+    readonly tasks: readonly PlanTask[];
+    readonly notes?: readonly string[];
+    readonly skills?: readonly string[];
+    readonly after?: string;
+}
+export interface KingdomPlan {
+    readonly castles: readonly CastlePlan[];
+}
+export declare class VascendPlanStore {
+    private readonly file;
+    private readonly memory;
+    private kingdom;
+    private constructor();
+    static open(sessionDir: string, sessionId: string, options?: {
+        strict?: boolean;
+    }): VascendPlanStore;
+    castles(): readonly CastlePlan[];
+    hasAny(): boolean;
+    runningTaskRef(): string | null;
+    setCastle(slug: string, title: string, taskTitles: readonly string[], after?: string): CastlePlan;
+    mark(slug: string, idOrBit: string, status: PlanTaskStatus, evidence?: string): PlanTask | null;
+    addEvidence(slug: string, idOrBit: string, evidence: string): PlanTask | null;
+    setRoomTokens(slug: string, idOrBit: string, tokens: number): void;
+    setRoomMetrics(slug: string, idOrBit: string, metrics: {
+        tokens?: number;
+        ms?: number;
+    }): void;
+    addTasks(slug: string, taskTitles: readonly string[]): readonly PlanTask[];
+    addNote(slug: string, idOrBit: string | null, note: string): boolean;
+    bindSkills(slug: string, idOrBit: string | null, skills: readonly string[]): boolean;
+    setAfter(slug: string, after: string): boolean;
+    castle(slug: string): CastlePlan | undefined;
+    clear(): void;
+    private persist;
+}