toolnet-memory 0.2.0

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

@@ -0,0 +1,88 @@
+import { existsSync, } from "node:fs";
+import { dirname, join, resolve, } from "node:path";
+import { loadConfig, ProjectManager, } from "../core/index.js";
+import { createStorageProvider, ProjectScopedStorageProvider, withStorageRetry, } from "../storage/index.js";
+import { getStartupBriefForInjection, refreshStartupBriefCache, } from "./brief-cache.js";
+function after(args, flag) {
+    const index = args.indexOf(flag);
+    return index >=
+        0
+        ? args[index + 1]
+        : undefined;
+}
+function existingProjectRoot(start) {
+    let current = resolve(start);
+    while (true) {
+        if (existsSync(join(current, ".toolnet", "project.json"))) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent ===
+            current) {
+            return null;
+        }
+        current =
+            parent;
+    }
+}
+function storageFor(project) {
+    const config = loadConfig();
+    const raw = withStorageRetry(createStorageProvider({
+        provider: config.storage
+            .provider,
+        huggingface: config.storage
+            .huggingface,
+        localRoot: config.storage
+            .localRoot,
+    }), {
+        attempts: 2,
+    });
+    return new ProjectScopedStorageProvider(raw, project.id, project.name, project.remote ??
+        project.name);
+}
+async function main() {
+    const [command = "print", ...args] = process.argv.slice(2);
+    const requested = after(args, "--project") ??
+        process.cwd();
+    const root = existingProjectRoot(requested);
+    /*
+     * Global agent integrations must silently ignore
+     * projects which are not managed by ToolNet.
+     */
+    if (!root) {
+        return;
+    }
+    const project = new ProjectManager()
+        .detect(root);
+    const storage = storageFor(project);
+    const tokens = Number(after(args, "--tokens") ??
+        900);
+    if (command ===
+        "refresh") {
+        const cache = await refreshStartupBriefCache(project, storage, Number.isFinite(tokens)
+            ? tokens
+            : 900);
+        console.log(cache.text);
+        return;
+    }
+    const cache = await getStartupBriefForInjection(project, storage, Number.isFinite(tokens)
+        ? tokens
+        : 900);
+    if (!cache) {
+        return;
+    }
+    if (command ===
+        "sync") {
+        console.log(cache.digest);
+        return;
+    }
+    process.stdout.write(cache.text +
+        "\n");
+}
+main().catch(() => {
+    /*
+     * Context integration must never break an agent.
+     */
+    process.exitCode =
+        0;
+});

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

@@ -0,0 +1,339 @@
+import { sha256, } from "../session/utils.js";
+const TEXT_KEYS = new Set([
+    "content",
+    "text",
+    "message",
+    "prompt",
+    "summary",
+    "description",
+    "title",
+    "reason",
+    "last_assistant_message",
+    "lastAssistantMessage",
+]);
+function normalize(value) {
+    return value
+        .normalize("NFKC")
+        .replace(/\s+/g, " ")
+        .replace(/^[\s>*#•-]+/u, "")
+        .trim();
+}
+function keyOf(value) {
+    return normalize(value)
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function collectStrings(value, output, depth = 0) {
+    if (depth > 6) {
+        return;
+    }
+    if (typeof value === "string") {
+        output.push(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value.slice(0, 50)) {
+            collectStrings(item, output, depth + 1);
+        }
+        return;
+    }
+    if (!value ||
+        typeof value !== "object") {
+        return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        if (TEXT_KEYS.has(key) ||
+            [
+                "data",
+                "payload",
+                "parts",
+                "messages",
+            ].includes(key)) {
+            collectStrings(child, output, depth + 1);
+        }
+    }
+}
+function statusFrom(text) {
+    if (/\b(cancelled|canceled)\b|đã hủy|bỏ qua/iu
+        .test(text)) {
+        return "cancelled";
+    }
+    if (/\b(blocked|blocker)\b|đang vướng|bị vướng|đang kẹt|chưa thể/iu
+        .test(text)) {
+        return "blocked";
+    }
+    if (/\b(completed|complete|done|finished|passed)\b|hoàn thành|hoàn tất|đã xong|đã làm xong|\bxong\b/iu
+        .test(text)) {
+        return "completed";
+    }
+    if (/\bin[\s_-]*progress\b|working on|đang làm|đang thực hiện|đang xử lý|đang triển khai/iu
+        .test(text)) {
+        return "in_progress";
+    }
+    return "pending";
+}
+function isStatusOnly(value) {
+    const text = normalize(value);
+    return /^(?:đang\s+làm|đang\s+thực\s+hiện|đang\s+xử\s+lý|đang\s+triển\s+khai|hoàn\s+thành|hoàn\s+tất|đã\s+xong|đã\s+làm\s+xong|xong|pending|in[\s_-]*progress|completed|complete|done|finished|blocked|cancelled|canceled)[.!]*$/iu
+        .test(text);
+}
+function makeObservation(identity, event, kind, text, options = {}) {
+    const clean = normalize(text);
+    const key = options.key ??
+        keyOf(clean);
+    /*
+     * One agent message can contain both:
+     *
+     *   Phase 1 - Setup
+     *   Phase 1 hoàn thành
+     *
+     * They share event.id + phase key but represent DIFFERENT
+     * observations/state transitions.
+     *
+     * Include normalized content + status/order so only truly
+     * identical observations inside the same event are deduped.
+     */
+    const id = sha256([
+        identity.projectId,
+        kind,
+        key,
+        event.id,
+        clean,
+        options.status ?? "",
+        options.order ?? "",
+    ].join("|")).slice(0, 32);
+    return {
+        version: 1,
+        id,
+        projectId: identity.projectId,
+        kind,
+        key,
+        text: clean,
+        status: options.status,
+        order: options.order,
+        confidence: options.confidence ??
+            0.85,
+        occurredAt: event.timestamp,
+        sequence: event.sequence,
+        agent: identity.agent,
+        nativeSessionId: identity.nativeSessionId,
+        sessionKey: identity.sessionKey,
+        eventId: event.id,
+        sourceEventId: event.sourceEventId,
+    };
+}
+function extractFromLine(identity, event, rawLine) {
+    const line = normalize(rawLine);
+    if (line.length < 5 ||
+        line.length > 1200) {
+        return [];
+    }
+    const result = [];
+    /*
+     * A next-action sentence may REFER to phases without
+     * changing their current state.
+     *
+     * Example:
+     *   "Bước tiếp theo: hoàn tất Phase 3 rồi chuyển Phase 4"
+     *
+     * This means:
+     *   Phase 3 is still current/in-progress
+     *   Phase 4 is upcoming
+     *
+     * It must NOT be interpreted as "Phase 3 completed".
+     */
+    const isNextActionLine = /^(?:next|next action|next step|tiếp theo|bước tiếp theo|cần làm tiếp)\b/iu
+        .test(line);
+    const goal = line.match(/^(?:mục tiêu|goal|objective)\s*(?::|-)\s*(.+)$/iu);
+    if (goal?.[1]) {
+        result.push(makeObservation(identity, event, "goal", goal[1], {
+            confidence: 0.97,
+        }));
+    }
+    const plan = line.match(/^(?:kế hoạch|plan)\s*(?::|-)\s*(.+)$/iu);
+    if (plan?.[1]) {
+        result.push(makeObservation(identity, event, "plan", plan[1], {
+            confidence: 0.95,
+        }));
+    }
+    /*
+     * Stable Phase identity.
+     *
+     * Phase 2 - Work Continuity
+     * Phase 2 đang làm
+     * Phase 2 hoàn thành
+     *
+     * => all become phase:2
+     */
+    const phasePattern = /\b(?:phase|giai đoạn|giai doan|stage)\s*(\d+)\s*(?:[:\-–—]\s*)?([^.;\n]{0,220})/giu;
+    let phaseMatch;
+    /*
+     * Only explicit phase declarations/status lines mutate
+     * WorkState. References inside "next action" are advisory.
+     */
+    while (!isNextActionLine &&
+        (phaseMatch =
+            phasePattern.exec(line))) {
+        const number = Number(phaseMatch[1]);
+        const suffix = normalize(phaseMatch[2] ??
+            "");
+        const title = suffix &&
+            !isStatusOnly(suffix)
+            ? `Phase ${number} - ${suffix}`
+            : `Phase ${number}`;
+        result.push(makeObservation(identity, event, "phase", title, {
+            key: `phase:${number}`,
+            order: number,
+            status: statusFrom(line),
+            confidence: 0.93,
+        }));
+    }
+    const checkbox = rawLine.match(/^\s*[-*]\s*\[([ xX])\]\s*(.+)$/u);
+    if (checkbox?.[2]) {
+        result.push(makeObservation(identity, event, "task", checkbox[2], {
+            status: checkbox[1].trim()
+                ? "completed"
+                : statusFrom(checkbox[2]),
+            confidence: 0.96,
+        }));
+    }
+    /*
+     * Stable numbered TODO identity.
+     *
+     * TODO 2: Viết adapter
+     * TODO 2 đang làm
+     * TODO 2 hoàn thành
+     *
+     * => all become task:2
+     */
+    const todo = line.match(/^(?:todo|task|việc)\s*(\d+)?(?:\s*[:.\-–—]\s*|\s+)(.+)$/iu);
+    if (todo?.[2]) {
+        const order = todo[1]
+            ? Number(todo[1])
+            : undefined;
+        const todoText = normalize(todo[2]);
+        const statusOnly = isStatusOnly(todoText);
+        result.push(makeObservation(identity, event, "task", statusOnly &&
+            order !== undefined
+            ? `TODO ${order}`
+            : todoText, {
+            key: order !== undefined
+                ? `task:${order}`
+                : keyOf(todoText),
+            order,
+            status: statusFrom(line),
+            confidence: 0.93,
+        }));
+    }
+    if (/^(?:next|next action|next step|tiếp theo|bước tiếp theo|cần làm tiếp)\b/iu
+        .test(line)) {
+        const cleaned = line.replace(/^(?:next|next action|next step|tiếp theo|bước tiếp theo|cần làm tiếp)\s*(?::|-)?\s*/iu, "");
+        if (cleaned) {
+            result.push(makeObservation(identity, event, "next_action", cleaned, {
+                confidence: 0.9,
+            }));
+        }
+    }
+    if (/\b(blocker|blocked)\b|đang vướng|bị vướng|đang kẹt/iu
+        .test(line)) {
+        result.push(makeObservation(identity, event, "blocker", line, {
+            confidence: 0.9,
+        }));
+    }
+    if (/\b(chú ý|lưu ý|warning|attention|cẩn thận)\b/iu
+        .test(line)) {
+        result.push(makeObservation(identity, event, "warning", line, {
+            confidence: 0.88,
+        }));
+    }
+    if (/\b(chốt|quyết định|decided|decision)\b/iu
+        .test(line)) {
+        result.push(makeObservation(identity, event, "decision", line, {
+            confidence: 0.9,
+        }));
+    }
+    return result;
+}
+export function extractWorkObservations(identity, events) {
+    if (events.length === 0) {
+        return [];
+    }
+    const observations = [];
+    const seen = new Set();
+    function push(observation) {
+        if (seen.has(observation.id)) {
+            return;
+        }
+        seen.add(observation.id);
+        observations.push(observation);
+    }
+    for (const event of events) {
+        if (event.type ===
+            "decision") {
+            const raw = [];
+            collectStrings(event.data, raw);
+            for (const value of raw) {
+                push(makeObservation(identity, event, "decision", value, {
+                    confidence: 1,
+                }));
+            }
+        }
+        if (event.type ===
+            "todo") {
+            const raw = [];
+            collectStrings(event.data, raw);
+            for (const value of raw) {
+                push(makeObservation(identity, event, "task", value, {
+                    status: statusFrom(value),
+                    confidence: 1,
+                }));
+            }
+        }
+        if ([
+            "file_write",
+            "file_edit",
+        ].includes(event.type)) {
+            for (const key of [
+                "filePath",
+                "path",
+                "file",
+            ]) {
+                const value = event.data[key];
+                if (typeof value ===
+                    "string" &&
+                    value) {
+                    push(makeObservation(identity, event, "file", value, {
+                        confidence: 1,
+                    }));
+                }
+            }
+        }
+        if (event.type ===
+            "test") {
+            const raw = [];
+            collectStrings(event.data, raw);
+            for (const value of raw) {
+                push(makeObservation(identity, event, "test", value, {
+                    confidence: 1,
+                }));
+            }
+        }
+        const blocks = [];
+        collectStrings(event.data, blocks);
+        for (const block of blocks) {
+            for (const rawLine of block.split(/\n+/u)) {
+                for (const observation of extractFromLine(identity, event, rawLine)) {
+                    push(observation);
+                }
+            }
+        }
+    }
+    const last = events[events.length - 1];
+    push(makeObservation(identity, last, "session", `${identity.agent}:${identity.nativeSessionId}`, {
+        key: identity.sessionKey,
+        confidence: 1,
+    }));
+    return observations;
+}

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

@@ -0,0 +1,185 @@
+import { mkdirSync, } from "node:fs";
+import { join, } from "node:path";
+import { sha256, writeJsonAtomic, } from "../session/utils.js";
+import { loadProjectManual, } from "../project-manual/manager.js";
+import { loadWorkState, reconcileWorkState, } from "./reducer.js";
+function substantiveState(state) {
+    return {
+        goal: state.goal,
+        plan: state.plan,
+        phases: state.phases.map(item => ({
+            id: item.id,
+            title: item.title,
+            status: item.status,
+            order: item.order,
+        })),
+        tasks: state.tasks.map(item => ({
+            id: item.id,
+            title: item.title,
+            status: item.status,
+            order: item.order,
+        })),
+        decisions: state.decisions,
+        blockers: state.blockers,
+        warnings: state.warnings,
+        nextActions: state.nextActions,
+        filesTouched: state.filesTouched,
+        tests: state.tests,
+    };
+}
+function hasUnfinishedWork(state) {
+    return (state.phases.some(item => item.status ===
+        "pending" ||
+        item.status ===
+            "in_progress" ||
+        item.status ===
+            "blocked") ||
+        state.tasks.some(item => item.status ===
+            "pending" ||
+            item.status ===
+                "in_progress" ||
+            item.status ===
+                "blocked") ||
+        state.nextActions.length >
+            0 ||
+        state.blockers.length >
+            0);
+}
+export class SmartHandoffManager {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async capture(reason, sequence) {
+        let state = await loadWorkState(this.options
+            .project, this.options
+            .storage);
+        if (!state) {
+            state =
+                await reconcileWorkState(this.options
+                    .project, this.options
+                    .storage);
+        }
+        if (!hasUnfinishedWork(state)) {
+            return null;
+        }
+        const manual = loadProjectManual(this.options
+            .project, false);
+        const enforceRules = manual
+            ? manual.rules
+                .filter(rule => rule.mode ===
+                "enforce")
+                .map(rule => rule.text)
+            : [];
+        const stateDigest = sha256(JSON.stringify(substantiveState(state)));
+        /*
+         * Stable handoff ID.
+         *
+         * Multiple idle/checkpoint events with no substantive
+         * work-state change reuse the same handoff object.
+         */
+        const id = sha256([
+            this.options
+                .project.id,
+            this.options
+                .identity
+                .sessionKey,
+            stateDigest,
+        ].join("|")).slice(0, 24);
+        const createdAt = new Date()
+            .toISOString();
+        const handoff = {
+            version: 1,
+            id,
+            projectId: this.options
+                .project.id,
+            projectName: this.options
+                .project.name,
+            createdAt,
+            reason,
+            sourceSession: {
+                agent: this.options
+                    .identity.agent,
+                nativeSessionId: this.options
+                    .identity
+                    .nativeSessionId,
+                sessionKey: this.options
+                    .identity
+                    .sessionKey,
+                sequence,
+            },
+            goal: state.goal,
+            plan: state.plan,
+            progress: state.progress,
+            currentPhase: state.currentPhase,
+            currentTask: state.currentTask,
+            incompletePhases: state.phases.filter(item => item.status !==
+                "completed" &&
+                item.status !==
+                    "cancelled"),
+            incompleteTasks: state.tasks.filter(item => item.status !==
+                "completed" &&
+                item.status !==
+                    "cancelled"),
+            nextActions: state.nextActions
+                .slice(0, 10),
+            blockers: state.blockers
+                .slice(0, 10),
+            decisions: state.decisions
+                .slice(-10),
+            warnings: state.warnings
+                .slice(-10),
+            attention: [
+                ...enforceRules,
+                ...state.warnings,
+            ].slice(0, 20),
+            filesTouched: state.filesTouched
+                .slice(-20),
+            tests: state.tests
+                .slice(-15),
+            stateDigest,
+        };
+        const remoteKey = `projects/${this.options.project.id}/work/handoffs/${id}.json`;
+        /*
+         * Historical handoff is immutable.
+         */
+        if (!await this.options
+            .storage
+            .exists(remoteKey)) {
+            await this.options
+                .storage
+                .put(remoteKey, JSON.stringify(handoff, null, 2) +
+                "\n", "application/json");
+        }
+        /*
+         * Latest pointer is intentionally mutable.
+         */
+        await this.options
+            .storage
+            .put(`projects/${this.options.project.id}/work/handoff-latest.json`, JSON.stringify(handoff, null, 2) +
+            "\n", "application/json");
+        const localDirectory = join(this.options
+            .project
+            .rootPath, ".toolnet", "work", "handoffs");
+        mkdirSync(localDirectory, {
+            recursive: true,
+        });
+        writeJsonAtomic(join(localDirectory, `${id}.json`), handoff);
+        writeJsonAtomic(join(this.options
+            .project
+            .rootPath, ".toolnet", "work", "handoff-latest.json"), handoff);
+        return handoff;
+    }
+}
+export async function loadLatestHandoff(project, storage) {
+    const text = await storage.getText(`projects/${project.id}/work/handoff-latest.json`);
+    if (!text) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,14 @@
+export * from "./types.js";
+export * from "./extractor.js";
+export * from "./journal.js";
+export * from "./reducer.js";
+export * from "./learner.js";
+export * from "./handoff.js";
+export * from "./brief.js";
+export * from "./semantic-types.js";
+export * from "./semantic-extractor.js";
+export * from "./semantic-journal.js";
+export * from "./semantic-reducer.js";
+export * from "./semantic-learner.js";
+export * from "./brief-cache.js";
+export * from "./injection.js";

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

@@ -0,0 +1,84 @@
+import { existsSync, mkdirSync, readFileSync, } from "node:fs";
+import { homedir, } from "node:os";
+import { dirname, join, } from "node:path";
+import { writeJsonAtomic, } from "../session/utils.js";
+import { getStartupBriefForInjection, } from "./brief-cache.js";
+function markerFile(project, conversationId, overrideDirectory) {
+    const base = overrideDirectory ??
+        join(homedir(), ".config", "toolnet-memory", "injections", "agy");
+    return join(base, `${project.id}-${conversationId}.json`);
+}
+function loadMarker(file) {
+    if (!existsSync(file)) {
+        return null;
+    }
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export async function buildAgyPreInvocationOutput(options) {
+    const now = options.now ??
+        Date.now();
+    const resumeAfterMs = options.resumeAfterMs ??
+        6 * 60 * 60 * 1000;
+    const markerPath = markerFile(options.project, options.conversationId, options.markerDirectory);
+    const marker = loadMarker(markerPath);
+    const markerTime = marker
+        ? Date.parse(marker.injectedAt)
+        : 0;
+    const age = markerTime
+        ? now -
+            markerTime
+        : Number.POSITIVE_INFINITY;
+    /*
+     * Avoid duplicate injection on immediate retry.
+     */
+    if (marker &&
+        age <
+            60_000) {
+        return {};
+    }
+    const firstInvocation = options.invocationNum ===
+        0;
+    const resumedAfterPause = age >=
+        resumeAfterMs;
+    if (marker &&
+        !firstInvocation &&
+        !resumedAfterPause) {
+        return {};
+    }
+    const cache = await getStartupBriefForInjection(options.project, options.storage, 900);
+    if (!cache?.text) {
+        return {};
+    }
+    mkdirSync(dirname(markerPath), {
+        recursive: true,
+    });
+    writeJsonAtomic(markerPath, {
+        digest: cache.digest,
+        injectedAt: new Date(now)
+            .toISOString(),
+    });
+    return {
+        injectSteps: [
+            {
+                ephemeralMessage: cache.text,
+            },
+        ],
+    };
+}
+export async function buildCodexSessionStartOutput(options) {
+    const cache = await getStartupBriefForInjection(options.project, options.storage, 900);
+    if (!cache?.text) {
+        return {};
+    }
+    return {
+        hookSpecificOutput: {
+            hookEventName: "SessionStart",
+            additionalContext: cache.text,
+        },
+    };
+}