toolnet-memory 0.2.0

package/dist/src/session/opencode/cli.js

@@ -0,0 +1,121 @@
+import { loadConfig, ProjectManager, } from "../../core/index.js";
+import { createStorageProvider, ProjectScopedStorageProvider, withStorageRetry, } from "../../storage/index.js";
+import { recoverOpenCodeProject, syncOpenCodeSession, } from "./adapter.js";
+import { installOpenCodePlugin, } from "./plugin-installer.js";
+import { refreshStartupBriefCache, } from "../../work-continuity/brief-cache.js";
+function valueAfter(args, flag) {
+    const index = args.indexOf(flag);
+    if (index < 0) {
+        return undefined;
+    }
+    return args[index + 1];
+}
+function has(args, flag) {
+    return args.includes(flag);
+}
+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);
+    if (command ===
+        "install-plugin") {
+        const target = installOpenCodePlugin({
+            binary: valueAfter(args, "--bin"),
+        });
+        console.log(`✅ OpenCode plugin installed: ${target}`);
+        console.log("OpenCode will load it automatically on next start.");
+        return;
+    }
+    const projectPath = valueAfter(args, "--project") ??
+        process.cwd();
+    const project = new ProjectManager()
+        .detect(projectPath);
+    const storage = storageFor(project);
+    const dbPath = valueAfter(args, "--db");
+    if (command ===
+        "sync") {
+        const nativeSessionId = args.find(value => !value.startsWith("--") &&
+            value !==
+                projectPath &&
+            value !==
+                dbPath);
+        if (!nativeSessionId) {
+            throw new Error("Usage: session:opencode-sync <session-id>");
+        }
+        const idle = has(args, "--idle");
+        const error = has(args, "--error");
+        const compacted = has(args, "--compacted");
+        const result = await syncOpenCodeSession({
+            project,
+            storage,
+            nativeSessionId,
+            dbPath,
+            idle,
+            error,
+            compacted,
+        });
+        if (idle ||
+            compacted ||
+            error) {
+            try {
+                await refreshStartupBriefCache(project, storage, 900);
+            }
+            catch {
+                // Derived cache must never break session capture.
+            }
+        }
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (command ===
+        "recover") {
+        const limitValue = valueAfter(args, "--limit");
+        const limit = limitValue
+            ? Number(limitValue)
+            : 100;
+        const results = await recoverOpenCodeProject({
+            project,
+            storage,
+            dbPath,
+            limit: Number.isFinite(limit)
+                ? limit
+                : 100,
+        });
+        console.log(JSON.stringify({
+            project: project.name,
+            sessions: results.length,
+            importedMessages: results.reduce((total, item) => total +
+                item
+                    .importedMessages, 0),
+            importedParts: results.reduce((total, item) => total +
+                item
+                    .importedParts, 0),
+        }, null, 2));
+        return;
+    }
+    console.log(`OpenCode Session Adapter
+
+Commands:
+  sync <session-id> [--project PATH] [--idle]
+  recover [--project PATH] [--limit N]
+  install-plugin [--bin PATH]
+`);
+}
+main().catch(error => {
+    console.error(error instanceof Error
+        ? error.message
+        : error);
+    process.exit(1);
+});

package/dist/src/session/opencode/index.js

@@ -0,0 +1,2 @@
+export * from "./adapter.js";
+export * from "./plugin-installer.js";

package/dist/src/session/opencode/plugin-installer.js

@@ -0,0 +1,230 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { homedir, } from "node:os";
+import { join, } from "node:path";
+const START = "<!-- TOOLNET_MEMORY_BOOTSTRAP_START -->";
+const END = "<!-- TOOLNET_MEMORY_BOOTSTRAP_END -->";
+function installBootstrapInstructions() {
+    const file = join(homedir(), ".config", "opencode", "AGENTS.md");
+    mkdirSync(join(homedir(), ".config", "opencode"), {
+        recursive: true,
+    });
+    const block = `${START}
+## ToolNet Memory — Project Continuity
+
+When the current workspace belongs to a ToolNet project, identified by a nearest ancestor containing \`.toolnet/project.json\`:
+
+1. Before planning, editing, or running implementation commands, read that project root's \`.toolnet/context/startup.md\`.
+2. Treat its PROJECT RULES, MISSION, CURRENT OBJECTIVE, rationale, current phase/task, Definition of Done, blockers and next actions as project continuity context.
+3. Do not restart work already marked completed unless repository evidence proves it must be revisited.
+4. Verify current repository state before continuing old work.
+5. If \`.toolnet/context/startup.md\` is missing, run \`toolnet-memory context:sync --project <project-root>\`, then read it.
+6. Never invent missing rationale. If ToolNet says a reason was not explicitly recorded, inspect the implementation or ask rather than guessing.
+
+This applies automatically to every ToolNet-managed project.
+${END}`;
+    let content = existsSync(file)
+        ? readFileSync(file, "utf8")
+        : "";
+    const start = content.indexOf(START);
+    const end = content.indexOf(END);
+    if (start >= 0 &&
+        end >= start) {
+        content =
+            content.slice(0, start) +
+                block +
+                content.slice(end +
+                    END.length);
+    }
+    else {
+        content =
+            content.trimEnd();
+        if (content) {
+            content +=
+                "\n\n";
+        }
+        content +=
+            block;
+    }
+    writeFileSync(file, content.trimEnd() +
+        "\n", {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    return file;
+}
+export function installOpenCodePlugin(options = {}) {
+    const directory = options.directory ??
+        join(homedir(), ".config", "opencode", "plugins");
+    mkdirSync(directory, {
+        recursive: true,
+    });
+    installBootstrapInstructions();
+    const target = join(directory, "toolnet-memory.js");
+    const binary = options.binary ??
+        process.env
+            .TOOLNET_MEMORY_BIN ??
+        "toolnet-memory";
+    const content = `// Generated by ToolNet Memory.
+// OpenCode session capture + continuity bootstrap.
+
+function getSessionId(event) {
+  const p = event?.properties ?? {}
+
+  const candidates = [
+    p.sessionID,
+    p.sessionId,
+    p.info?.id,
+    p.session?.id,
+  ]
+
+  return candidates.find(
+    value => typeof value === "string" && value.length > 0
+  ) ?? null
+}
+
+export const ToolNetMemoryPlugin = async ({ directory }) => {
+  const binary = ${JSON.stringify(binary)}
+
+  async function refreshContext() {
+    try {
+      const child = Bun.spawn(
+        [
+          binary,
+          "context:sync",
+          "--project",
+          directory,
+        ],
+        {
+          stdin: "ignore",
+          stdout: "ignore",
+          stderr: "ignore",
+        }
+      )
+
+      await child.exited
+    } catch {
+      // Context sync must never break OpenCode startup.
+    }
+  }
+
+  async function readContext() {
+    try {
+      const child = Bun.spawn(
+        [
+          binary,
+          "context:print",
+          "--project",
+          directory,
+          "--tokens",
+          "900",
+        ],
+        {
+          stdin: "ignore",
+          stdout: "pipe",
+          stderr: "ignore",
+        }
+      )
+
+      const text =
+        await new Response(
+          child.stdout
+        ).text()
+
+      await child.exited
+
+      return text.trim()
+    } catch {
+      return ""
+    }
+  }
+
+  function sync(sessionId, flag) {
+    if (!sessionId) return
+
+    try {
+      const args = [
+        binary,
+        "session:opencode-sync",
+        sessionId,
+        "--project",
+        directory,
+      ]
+
+      if (flag) {
+        args.push(flag)
+      }
+
+      const child = Bun.spawn(args, {
+        stdin: "ignore",
+        stdout: "ignore",
+        stderr: "ignore",
+      })
+
+      if (
+        typeof child.unref === "function"
+      ) {
+        child.unref()
+      }
+    } catch {
+      // Memory capture must never break OpenCode.
+    }
+  }
+
+  /*
+   * Pull the latest project brief from ToolNet remote storage
+   * before the new OpenCode session starts doing work.
+   */
+  await refreshContext()
+
+  return {
+    event: async ({ event }) => {
+      const sessionId =
+        getSessionId(event)
+
+      if (!sessionId) {
+        return
+      }
+
+      if (event.type === "session.idle") {
+        sync(sessionId, "--idle")
+        return
+      }
+
+      if (event.type === "session.compacted") {
+        sync(sessionId, "--compacted")
+        return
+      }
+
+      if (event.type === "session.error") {
+        sync(sessionId, "--error")
+      }
+    },
+
+    /*
+     * Official OpenCode compaction hook.
+     * Preserve ToolNet's semantic state after context compaction.
+     */
+    "experimental.session.compacting": async (_input, output) => {
+      const context =
+        await readContext()
+
+      if (
+        context &&
+        Array.isArray(
+          output.context
+        )
+      ) {
+        output.context.push(
+          context
+        )
+      }
+    },
+  }
+}
+`;
+    writeFileSync(target, content, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    return target;
+}

package/dist/src/session/store.js

@@ -0,0 +1,242 @@
+import { sha256, } from "./utils.js";
+function padSequence(value) {
+    return String(value).padStart(12, "0");
+}
+export class RemoteSessionStore {
+    storage;
+    maxEventsPerChunk;
+    maxChunkBytes;
+    constructor(storage, maxEventsPerChunk = 100, maxChunkBytes = 512 * 1024) {
+        this.storage = storage;
+        this.maxEventsPerChunk = maxEventsPerChunk;
+        this.maxChunkBytes = maxChunkBytes;
+        if (maxEventsPerChunk <
+            1) {
+            throw new Error("maxEventsPerChunk must be positive");
+        }
+        if (maxChunkBytes <
+            1_024) {
+            throw new Error("maxChunkBytes is too small");
+        }
+    }
+    async getJson(key) {
+        const text = await this.storage
+            .getText(key);
+        if (!text) {
+            return null;
+        }
+        return JSON.parse(text);
+    }
+    async putJson(key, value) {
+        await this.storage.put(key, JSON.stringify(value, null, 2) + "\n", "application/json");
+    }
+    async scan(identity) {
+        const prefix = `${identity.remotePrefix}/events/`;
+        const objects = await this.storage.list(prefix);
+        const chunks = [];
+        let maxSequence = 0;
+        for (const object of objects) {
+            const match = object.key.match(/\/events\/(\d+)-(\d+)-[a-f0-9]+\.jsonl$/);
+            if (!match) {
+                continue;
+            }
+            const start = Number(match[1]);
+            const end = Number(match[2]);
+            if (!Number.isFinite(start) ||
+                !Number.isFinite(end)) {
+                continue;
+            }
+            chunks.push({
+                key: object.key,
+                start,
+                end,
+            });
+            maxSequence =
+                Math.max(maxSequence, end);
+        }
+        chunks.sort((left, right) => left.start -
+            right.start);
+        return {
+            chunks,
+            maxSequence,
+        };
+    }
+    split(events) {
+        const result = [];
+        let current = [];
+        let bytes = 0;
+        for (const event of events) {
+            const lineBytes = Buffer.byteLength(JSON.stringify(event) + "\n", "utf8");
+            if (current.length >
+                0 &&
+                (current.length >=
+                    this
+                        .maxEventsPerChunk ||
+                    bytes +
+                        lineBytes >
+                        this
+                            .maxChunkBytes)) {
+                result.push(current);
+                current =
+                    [];
+                bytes =
+                    0;
+            }
+            current.push(event);
+            bytes +=
+                lineBytes;
+        }
+        if (current.length >
+            0) {
+            result.push(current);
+        }
+        return result;
+    }
+    async loadManifest(identity) {
+        return this.getJson(`${identity.remotePrefix}/session.json`);
+    }
+    async loadCursor(identity) {
+        return this.getJson(`${identity.remotePrefix}/cursor.json`);
+    }
+    async recover(identity) {
+        const scan = await this.scan(identity);
+        return {
+            maxSequence: scan.maxSequence,
+            chunkCount: scan.chunks.length,
+        };
+    }
+    async append(identity, events, sourceCursors, options = {}) {
+        const previousManifest = await this.loadManifest(identity);
+        const before = await this.scan(identity);
+        /*
+         * Crash recovery:
+         * chunks may already exist even when cursor/session.json
+         * was not successfully updated.
+         */
+        const pending = events.filter(event => event.sequence >
+            before.maxSequence);
+        let uploadedEvents = 0;
+        for (const chunk of this.split(pending)) {
+            const first = chunk[0];
+            const last = chunk[chunk.length -
+                1];
+            const content = chunk
+                .map(event => JSON.stringify(event))
+                .join("\n") +
+                "\n";
+            const digest = sha256(content).slice(0, 16);
+            const key = [
+                identity
+                    .remotePrefix,
+                "events",
+                `${padSequence(first.sequence)}-${padSequence(last.sequence)}-${digest}.jsonl`,
+            ].join("/");
+            if (!await this.storage
+                .exists(key)) {
+                await this.storage.put(key, content, "application/x-ndjson");
+            }
+            uploadedEvents +=
+                chunk.length;
+        }
+        const after = await this.scan(identity);
+        const lastInput = events[events.length -
+            1];
+        let status = previousManifest
+            ?.status ??
+            "active";
+        if ((lastInput
+            ?.type ===
+            "session_end" ||
+            lastInput
+                ?.type ===
+                "session_idle")) {
+            status =
+                "idle";
+        }
+        else if (lastInput
+            ?.type ===
+            "error") {
+            status =
+                "error";
+        }
+        else if (events.length >
+            0) {
+            status =
+                "active";
+        }
+        const now = new Date()
+            .toISOString();
+        const firstInput = events[0];
+        const manifest = {
+            version: 1,
+            projectId: identity.projectId,
+            projectName: identity
+                .projectName,
+            agent: identity.agent,
+            nativeSessionId: identity
+                .nativeSessionId,
+            sessionKey: identity.sessionKey,
+            status,
+            createdAt: previousManifest
+                ?.createdAt ??
+                firstInput
+                    ?.timestamp ??
+                now,
+            updatedAt: lastInput
+                ?.timestamp ??
+                now,
+            firstEventAt: previousManifest
+                ?.firstEventAt ??
+                firstInput
+                    ?.timestamp,
+            lastEventAt: lastInput
+                ?.timestamp ??
+                previousManifest
+                    ?.lastEventAt,
+            eventCount: after.maxSequence,
+            chunkCount: after.chunks.length,
+            metadata: {
+                ...previousManifest
+                    ?.metadata,
+                ...options.metadata,
+            },
+        };
+        if (options.title ??
+            previousManifest
+                ?.title) {
+            manifest.title =
+                options.title ??
+                    previousManifest
+                        ?.title;
+        }
+        const cursor = {
+            version: 1,
+            projectId: identity.projectId,
+            agent: identity.agent,
+            nativeSessionId: identity
+                .nativeSessionId,
+            lastLocalSequence: events.length >
+                0
+                ? events[events.length -
+                    1].sequence
+                : after
+                    .maxSequence,
+            lastRemoteSequence: after.maxSequence,
+            sourceCursors,
+            updatedAt: now,
+        };
+        /*
+         * Chunk first, then cursor, then manifest.
+         * Immutable chunks are the source of truth.
+         */
+        await this.putJson(`${identity.remotePrefix}/cursor.json`, cursor);
+        await this.putJson(`${identity.remotePrefix}/session.json`, manifest);
+        return {
+            uploadedEvents,
+            lastRemoteSequence: after.maxSequence,
+            eventCount: manifest.eventCount,
+            chunkCount: manifest.chunkCount,
+            status,
+        };
+    }
+}

package/dist/src/session/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/session/utils.js

@@ -0,0 +1,47 @@
+import { createHash, } from "node:crypto";
+import { dirname, } from "node:path";
+import { mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+export function sha256(value) {
+    return createHash("sha256")
+        .update(value)
+        .digest("hex");
+}
+function normalize(value) {
+    if (Array.isArray(value)) {
+        return value.map(normalize);
+    }
+    if (value &&
+        typeof value ===
+            "object") {
+        const source = value;
+        const result = {};
+        for (const key of Object.keys(source).sort()) {
+            result[key] =
+                normalize(source[key]);
+        }
+        return result;
+    }
+    return value;
+}
+export function stableStringify(value) {
+    return JSON.stringify(normalize(value));
+}
+export function readJsonFile(filePath) {
+    try {
+        return JSON.parse(readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeJsonAtomic(filePath, value) {
+    mkdirSync(dirname(filePath), {
+        recursive: true,
+    });
+    const temporary = `${filePath}.${process.pid}.tmp`;
+    writeFileSync(temporary, JSON.stringify(value, null, 2) + "\n", {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    renameSync(temporary, filePath);
+}