toolnet-memory 0.2.0

package/dist/src/work-continuity/brief-cache.js

@@ -0,0 +1,107 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { dirname, join, } from "node:path";
+import { sha256, writeJsonAtomic, } from "../session/utils.js";
+import { buildStartupBrief, } from "./brief.js";
+export function startupBriefFile(project) {
+    return join(project.rootPath, ".toolnet", "context", "startup.md");
+}
+function startupMetaFile(project) {
+    return join(project.rootPath, ".toolnet", "context", "startup.json");
+}
+function persistLocal(project, cache) {
+    const file = startupBriefFile(project);
+    mkdirSync(dirname(file), {
+        recursive: true,
+    });
+    writeFileSync(file, cache.text.endsWith("\n")
+        ? cache.text
+        : cache.text + "\n", {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    writeJsonAtomic(startupMetaFile(project), cache);
+}
+export async function refreshStartupBriefCache(project, storage, maxTokens = 900) {
+    const brief = await buildStartupBrief({
+        project,
+        storage,
+        maxTokens,
+    });
+    const cache = {
+        version: 1,
+        projectId: project.id,
+        projectName: project.name,
+        text: brief.text,
+        digest: sha256(brief.text),
+        estimatedTokens: brief.estimatedTokens,
+        generatedAt: new Date()
+            .toISOString(),
+    };
+    persistLocal(project, cache);
+    await storage.put(`projects/${project.id}/context/startup.md`, cache.text + "\n", "text/markdown");
+    await storage.put(`projects/${project.id}/context/startup.json`, JSON.stringify(cache, null, 2) + "\n", "application/json");
+    return cache;
+}
+/*
+ * Startup injection always prefers remote.
+ *
+ * Reason:
+ * OpenCode may have worked on VPS A,
+ * then Agy/Codex may start immediately on VPS B.
+ *
+ * One small remote GET at session start is much safer than
+ * trusting a potentially stale local cache.
+ */
+export async function getStartupBriefForInjection(project, storage, maxTokens = 900) {
+    try {
+        const remote = await storage.getText(`projects/${project.id}/context/startup.md`);
+        if (remote &&
+            remote.trim()) {
+            const text = remote.trim();
+            const cache = {
+                version: 1,
+                projectId: project.id,
+                projectName: project.name,
+                text,
+                digest: sha256(text),
+                estimatedTokens: Math.ceil(text.length /
+                    3.5),
+                generatedAt: new Date()
+                    .toISOString(),
+            };
+            persistLocal(project, cache);
+            return cache;
+        }
+    }
+    catch {
+        // Network unavailable -> local fallback.
+    }
+    const local = startupBriefFile(project);
+    if (existsSync(local)) {
+        try {
+            const text = readFileSync(local, "utf8").trim();
+            if (text) {
+                return {
+                    version: 1,
+                    projectId: project.id,
+                    projectName: project.name,
+                    text,
+                    digest: sha256(text),
+                    estimatedTokens: Math.ceil(text.length /
+                        3.5),
+                    generatedAt: new Date()
+                        .toISOString(),
+                };
+            }
+        }
+        catch {
+            // Fall through.
+        }
+    }
+    try {
+        return await refreshStartupBriefCache(project, storage, maxTokens);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/work-continuity/brief.js

@@ -0,0 +1,349 @@
+import { loadProjectManual, projectManualPath, } from "../project-manual/manager.js";
+import { loadLatestHandoff, } from "./handoff.js";
+import { loadWorkState, } from "./reducer.js";
+import { loadSemanticWorkState, } from "./semantic-reducer.js";
+function estimateTokens(value) {
+    if (!value) {
+        return 0;
+    }
+    const chars = Array.from(value).length;
+    const words = value
+        .trim()
+        .split(/\s+/u)
+        .filter(Boolean)
+        .length;
+    /*
+     * Lightweight conservative approximation.
+     * No tokenizer dependency required.
+     */
+    return Math.ceil(Math.max(chars / 3.5, words * 1.3));
+}
+function clip(value, maxChars) {
+    const clean = value
+        .replace(/\s+/g, " ")
+        .trim();
+    if (clean.length <=
+        maxChars) {
+        return clean;
+    }
+    return (clean.slice(0, Math.max(0, maxChars - 1))
+        .trimEnd() +
+        "…");
+}
+function manualNotes(content) {
+    const output = [];
+    let inComment = false;
+    for (const raw of content.split(/\r?\n/u)) {
+        let line = raw.trim();
+        if (line.includes("<!--")) {
+            inComment =
+                true;
+        }
+        if (inComment) {
+            if (line.includes("-->")) {
+                inComment =
+                    false;
+            }
+            continue;
+        }
+        const lower = line.toLowerCase();
+        if (!line ||
+            line.startsWith("#") ||
+            line === "```" ||
+            lower.startsWith("- [enforce]") ||
+            lower.startsWith("* [enforce]") ||
+            lower.startsWith("- [advisory]") ||
+            lower.startsWith("* [advisory]")) {
+            continue;
+        }
+        line =
+            line.replace(/^[-*]\s+/u, "");
+        if (line) {
+            output.push(clip(line, 280));
+        }
+        if (output.length >=
+            16) {
+            break;
+        }
+    }
+    return output;
+}
+function parseRemoteRules(content) {
+    const enforce = [];
+    const advisory = [];
+    for (const raw of content.split(/\\r?\\n/u)) {
+        const line = raw.trim();
+        const lower = line.toLowerCase();
+        const prefixes = [
+            "- [enforce]",
+            "* [enforce]",
+            "- [advisory]",
+            "* [advisory]",
+        ];
+        const prefix = prefixes.find(item => lower.startsWith(item));
+        if (!prefix) {
+            continue;
+        }
+        const text = line
+            .slice(prefix.length)
+            .trim();
+        if (!text) {
+            continue;
+        }
+        if (prefix.includes("enforce")) {
+            enforce.push(text);
+        }
+        else {
+            advisory.push(text);
+        }
+    }
+    return {
+        enforce,
+        advisory,
+    };
+}
+function fitLines(lines, maxTokens) {
+    const output = [];
+    for (const line of lines) {
+        const candidate = [
+            ...output,
+            line,
+        ].join("\n");
+        if (estimateTokens(candidate) <=
+            maxTokens) {
+            output.push(line);
+            continue;
+        }
+        const used = estimateTokens(output.join("\n"));
+        const remaining = Math.max(0, maxTokens -
+            used);
+        if (remaining >=
+            16) {
+            const maxChars = Math.floor(remaining *
+                3.2);
+            const partial = clip(line, maxChars);
+            if (partial) {
+                output.push(partial);
+            }
+        }
+        break;
+    }
+    return output
+        .join("\n")
+        .trim();
+}
+export async function buildStartupBrief(options) {
+    const maxTokens = Math.max(256, Math.min(2000, options.maxTokens ??
+        1000));
+    const localManual = loadProjectManual(options.project, false);
+    let manualContent = localManual?.content ??
+        "";
+    /*
+     * Cross-machine/VPS fallback.
+     * If PROJECT.md isn't local yet, read the project-scoped
+     * copy from remote storage.
+     */
+    if (!manualContent) {
+        manualContent =
+            await options.storage
+                .getText(`projects/${options.project.id}/project/manual.md`) ??
+                "";
+    }
+    const parsedRemote = parseRemoteRules(manualContent);
+    const enforce = localManual
+        ? localManual.rules
+            .filter(rule => rule.mode ===
+            "enforce")
+            .map(rule => rule.text)
+        : parsedRemote.enforce;
+    const advisory = localManual
+        ? localManual.rules
+            .filter(rule => rule.mode ===
+            "advisory")
+            .map(rule => rule.text)
+        : parsedRemote.advisory;
+    const notes = manualContent
+        ? manualNotes(manualContent)
+        : [];
+    const state = await loadWorkState(options.project, options.storage);
+    const semantic = await loadSemanticWorkState(options.project, options.storage);
+    const handoff = await loadLatestHandoff(options.project, options.storage);
+    const lines = [];
+    lines.push("[TOOLNET PROJECT CONTEXT]");
+    lines.push(`Project: ${options.project.name}`);
+    lines.push("Continue existing project state. Do not restart completed work unless evidence shows it is necessary.");
+    if (manualContent) {
+        lines.push(`Full operating manual: ${projectManualPath(options.project)}`);
+    }
+    /*
+     * Highest priority:
+     * project operating rules.
+     */
+    if (enforce.length) {
+        lines.push("", "PROJECT RULES — MUST FOLLOW");
+        for (const rule of enforce.slice(0, 24)) {
+            lines.push(`- [ENFORCE] ${clip(rule, 240)}`);
+        }
+    }
+    if (advisory.length) {
+        lines.push("", "PROJECT PREFERENCES");
+        for (const rule of advisory.slice(0, 10)) {
+            lines.push(`- ${clip(rule, 220)}`);
+        }
+    }
+    /*
+     * Semantic continuity:
+     * tell the new agent WHAT it is doing and WHY,
+     * before telling it which checkbox comes next.
+     */
+    if (semantic) {
+        if (semantic.mission) {
+            lines.push("", "MISSION", clip(semantic.mission.value, 420));
+        }
+        if (semantic.activeObjective) {
+            lines.push("", "CURRENT OBJECTIVE", clip(semantic.activeObjective.value, 420));
+        }
+        if (semantic.why) {
+            lines.push("", "WHY THIS WORK MATTERS", clip(semantic.why.value, 420));
+        }
+        if (semantic.desiredOutcome) {
+            lines.push("", "DESIRED OUTCOME", clip(semantic.desiredOutcome.value, 420));
+        }
+        if (semantic.planRationale) {
+            lines.push("", "WHY THIS APPROACH", clip(semantic.planRationale.value, 420));
+        }
+    }
+    /*
+     * Next priority:
+     * unfinished execution state.
+     */
+    if (state) {
+        lines.push("", "ACTIVE WORK");
+        if (state.goal) {
+            lines.push(`Goal: ${clip(state.goal, 320)}`);
+        }
+        if (state.plan) {
+            lines.push(`Plan: ${clip(state.plan, 320)}`);
+        }
+        lines.push(`Progress: phases ${state.progress.phasesCompleted}/${state.progress.phasesTotal}; tasks ${state.progress.tasksCompleted}/${state.progress.tasksTotal}; blocked ${state.progress.blocked}`);
+        if (state.currentPhase) {
+            lines.push(`Current phase: ${state.currentPhase.title} [${state.currentPhase.status}]`);
+        }
+        if (state.currentPhase &&
+            semantic) {
+            const semanticPhase = semantic.phases.find(item => item.order ===
+                state.currentPhase
+                    ?.order);
+            if (semanticPhase) {
+                if (semanticPhase.objective) {
+                    lines.push(`Phase objective: ${clip(semanticPhase.objective.value, 340)}`);
+                }
+                if (semanticPhase.why) {
+                    lines.push(`Why this phase: ${clip(semanticPhase.why.value, 340)}`);
+                }
+                else {
+                    lines.push("Why this phase: not explicitly recorded. Inspect existing implementation before assuming intent.");
+                }
+                if (semanticPhase.deliverable) {
+                    lines.push(`Deliverable: ${clip(semanticPhase.deliverable.value, 340)}`);
+                }
+                if (semanticPhase.dependencies.length) {
+                    lines.push(`Depends on: ${semanticPhase.dependencies
+                        .slice(0, 4)
+                        .map(item => clip(item.value, 180))
+                        .join("; ")}`);
+                }
+                if (semanticPhase.acceptanceCriteria.length) {
+                    lines.push("", "DEFINITION OF DONE");
+                    semanticPhase.acceptanceCriteria
+                        .slice(0, 6)
+                        .forEach(item => {
+                        lines.push(`- ${clip(item.value, 260)}`);
+                    });
+                }
+                if (semanticPhase.openQuestions.length) {
+                    lines.push("", "OPEN QUESTIONS FOR CURRENT PHASE");
+                    semanticPhase.openQuestions
+                        .slice(0, 4)
+                        .forEach(item => {
+                        lines.push(`- ${clip(item.value, 260)}`);
+                    });
+                }
+            }
+        }
+        if (state.currentTask) {
+            lines.push(`Current task: ${state.currentTask.title} [${state.currentTask.status}]`);
+        }
+        if (state.nextActions.length) {
+            lines.push("", "NEXT ACTIONS");
+            state.nextActions
+                .slice(0, 6)
+                .forEach((action, index) => {
+                lines.push(`${index + 1}. ${clip(action, 260)}`);
+            });
+        }
+        if (state.blockers.length) {
+            lines.push("", "BLOCKERS");
+            state.blockers
+                .slice(0, 5)
+                .forEach(blocker => {
+                lines.push(`- ${clip(blocker, 260)}`);
+            });
+        }
+        if (state.warnings.length) {
+            lines.push("", "ATTENTION");
+            state.warnings
+                .slice(-5)
+                .forEach(warning => {
+                lines.push(`- ${clip(warning, 260)}`);
+            });
+        }
+        if (state.decisions.length) {
+            lines.push("", "RECENT DECISIONS");
+            state.decisions
+                .slice(-5)
+                .forEach(decision => {
+                lines.push(`- ${clip(decision, 260)}`);
+            });
+        }
+        if (state.lastSession) {
+            lines.push("", `Last work session: ${state.lastSession.agent} / ${state.lastSession.nativeSessionId}`);
+        }
+    }
+    if (semantic &&
+        semantic.openQuestions.length) {
+        lines.push("", "UNRESOLVED QUESTIONS");
+        semantic.openQuestions
+            .slice(0, 5)
+            .forEach(item => {
+            lines.push(`- ${clip(item.value, 260)}`);
+        });
+    }
+    if (handoff) {
+        lines.push(`Latest handoff: ${handoff.reason} / ${handoff.sourceSession.agent}`);
+    }
+    /*
+     * Lower priority operational notes.
+     */
+    if (notes.length) {
+        lines.push("", "OPERATING NOTES");
+        for (const note of notes) {
+            lines.push(`- ${note}`);
+        }
+    }
+    lines.push("", "Before changing anything: verify the current repository state and continue from the active phase/task above.");
+    const text = fitLines(lines, maxTokens);
+    return {
+        version: 1,
+        projectId: options.project.id,
+        projectName: options.project.name,
+        text,
+        estimatedTokens: estimateTokens(text),
+        maxTokens,
+        hasManual: Boolean(manualContent),
+        hasWorkState: Boolean(state),
+        hasHandoff: Boolean(handoff),
+        generatedAt: new Date()
+            .toISOString(),
+    };
+}

package/dist/src/work-continuity/cli.js

@@ -0,0 +1,96 @@
+import { loadConfig, ProjectManager, } from "../core/index.js";
+import { createStorageProvider, ProjectScopedStorageProvider, withStorageRetry, } from "../storage/index.js";
+import { loadWorkState, reconcileWorkState, } from "./reducer.js";
+function after(args, flag) {
+    const index = args.indexOf(flag);
+    return index >=
+        0
+        ? args[index + 1]
+        : undefined;
+}
+function storageFor(project) {
+    const config = loadConfig();
+    const raw = withStorageRetry(createStorageProvider({
+        provider: config.storage
+            .provider,
+        huggingface: config.storage
+            .huggingface,
+        localRoot: config.storage
+            .localRoot,
+    }), {
+        attempts: 3,
+    });
+    return new ProjectScopedStorageProvider(raw, project.id, project.name, project.remote ??
+        project.name);
+}
+function printState(state) {
+    console.log();
+    console.log(`Project: ${state.projectName}`);
+    if (state.goal) {
+        console.log(`Goal: ${state.goal}`);
+    }
+    if (state.currentPhase) {
+        console.log(`Current phase: ${state.currentPhase.title} [${state.currentPhase.status}]`);
+    }
+    if (state.currentTask) {
+        console.log(`Current task: ${state.currentTask.title} [${state.currentTask.status}]`);
+    }
+    console.log(`Phases: ${state.progress.phasesCompleted}/${state.progress.phasesTotal}`);
+    console.log(`Tasks: ${state.progress.tasksCompleted}/${state.progress.tasksTotal}`);
+    if (state.nextActions.length) {
+        console.log();
+        console.log("Next actions:");
+        state.nextActions.forEach((item, index) => console.log(`${index + 1}. ${item}`));
+    }
+    if (state.blockers.length) {
+        console.log();
+        console.log("Blockers:");
+        state.blockers.forEach(item => console.log(`- ${item}`));
+    }
+    if (state.lastSession) {
+        console.log();
+        console.log(`Last session: ${state.lastSession.agent} / ${state.lastSession.nativeSessionId}`);
+    }
+}
+async function main() {
+    const [command = "help", ...args] = process.argv.slice(2);
+    const project = new ProjectManager()
+        .detect(after(args, "--project") ??
+        process.cwd());
+    const storage = storageFor(project);
+    if (command ===
+        "reconcile") {
+        const state = await reconcileWorkState(project, storage);
+        printState(state);
+        return;
+    }
+    if (command ===
+        "status") {
+        const state = await loadWorkState(project, storage);
+        if (!state) {
+            console.log("No active work state yet.");
+            return;
+        }
+        printState(state);
+        return;
+    }
+    if (command ===
+        "json") {
+        const state = await loadWorkState(project, storage);
+        console.log(JSON.stringify(state, null, 2));
+        return;
+    }
+    console.log(`Work Continuity
+
+Commands:
+  status [--project PATH]
+  json [--project PATH]
+  reconcile [--project PATH]
+`);
+}
+main().catch(error => {
+    console.error(error instanceof Error
+        ? error.message
+        : error);
+    process.exit(1);
+});

package/dist/src/work-continuity/context-cli.js

@@ -0,0 +1,106 @@
+import { loadConfig, ProjectManager, } from "../core/index.js";
+import { createStorageProvider, ProjectScopedStorageProvider, withStorageRetry, } from "../storage/index.js";
+import { createSessionIdentity, } from "../session/identity.js";
+import { buildStartupBrief, } from "./brief.js";
+import { loadLatestHandoff, SmartHandoffManager, } from "./handoff.js";
+function after(args, flag) {
+    const index = args.indexOf(flag);
+    return index >=
+        0
+        ? args[index + 1]
+        : undefined;
+}
+function storageFor(project) {
+    const config = loadConfig();
+    const raw = withStorageRetry(createStorageProvider({
+        provider: config.storage
+            .provider,
+        huggingface: config.storage
+            .huggingface,
+        localRoot: config.storage
+            .localRoot,
+    }), {
+        attempts: 3,
+    });
+    return new ProjectScopedStorageProvider(raw, project.id, project.name, project.remote ??
+        project.name);
+}
+async function main() {
+    const [command = "help", ...args] = process.argv.slice(2);
+    const project = new ProjectManager()
+        .detect(after(args, "--project") ??
+        process.cwd());
+    const storage = storageFor(project);
+    if (command ===
+        "brief") {
+        const maxTokens = Number(after(args, "--tokens") ??
+            1000);
+        const brief = await buildStartupBrief({
+            project,
+            storage,
+            maxTokens: Number.isFinite(maxTokens)
+                ? maxTokens
+                : 1000,
+        });
+        process.stdout.write(brief.text +
+            "\n");
+        return;
+    }
+    if (command ===
+        "brief-json") {
+        const brief = await buildStartupBrief({
+            project,
+            storage,
+            maxTokens: Number(after(args, "--tokens") ??
+                1000),
+        });
+        console.log(JSON.stringify(brief, null, 2));
+        return;
+    }
+    if (command ===
+        "handoff-latest") {
+        const handoff = await loadLatestHandoff(project, storage);
+        console.log(JSON.stringify(handoff, null, 2));
+        return;
+    }
+    if (command ===
+        "handoff-create") {
+        const agent = (after(args, "--agent") ??
+            "manual");
+        if (agent ===
+            "manual") {
+            /*
+             * Manual maintenance command only.
+             * Session adapters use native IDs automatically.
+             */
+            throw new Error("--agent must be opencode, agy, or codex");
+        }
+        const session = after(args, "--session");
+        if (!session) {
+            throw new Error("--session is required");
+        }
+        const identity = createSessionIdentity(project, agent, session);
+        const manager = new SmartHandoffManager({
+            project,
+            storage,
+            identity,
+        });
+        const result = await manager.capture("manual", 0);
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`Work Context
+
+Commands:
+  brief [--project PATH] [--tokens N]
+  brief-json [--project PATH] [--tokens N]
+  handoff-latest [--project PATH]
+  handoff-create --agent <opencode|agy|codex> --session <id>
+`);
+}
+main().catch(error => {
+    console.error(error instanceof Error
+        ? error.message
+        : error);
+    process.exit(1);
+});