virtualmatter 0.3.0 → 0.4.0

package/README.md

@@ -157,3 +157,31 @@ server with OAuth. Sign in or create a VM account, approve the connection,
 and return to Lovable. Then ask “Embed my Lava Arena world” or “Create a
 Virtual Matter lava survival arena and embed it here.” This remote endpoint
 runs on the platform; users do not install or run this CLI for that flow.
+
+## Automatic agent logs
+
+Run `virtualmatter agent-logs setup` once in a project mirror to capture future
+conversations from Codex, Claude Code, Cursor, and an installed Hermes profile.
+Keep `virtualmatter sync` (or `virtualmatter agent-logs watch`) running for
+retry and transcript catch-up. Existing hooks are retained; follow the
+harness's normal hook trust/restart flow. `agent-logs status` shows the queue;
+`agent-logs disable` stops automatic capture.
+
+Any harness can upload public event JSONL with:
+
+```sh
+virtualmatter agent-logs upload conversation.jsonl --harness my-agent --session session-123
+```
+
+Each event needs a stable `event_id`, timezone-bearing `ts`, and `type` (`user`,
+`assistant_text`, `tool_use`, `tool_result`, or `result`). Text events carry
+`text`; tools carry `name`, `input`, `tool_use_id`; results carry `tool_use_id`
+and `result`. Retries deduplicate, existing entries cannot be overwritten, and
+failed batches remain in the project's local `.virtualmatter/agent-logs/`
+outbox. `--format codex` and `--format claude-code` import explicit transcript
+files. MCP exposes the same portable contract as `upload_agent_logs`.
+
+Setup records only this project's future entries. Hidden reasoning, system
+messages, and binary media are excluded. Logs become part of the project's
+history and saved content. The server must have the agent-log API update;
+older servers return 404 and the CLI retains pending entries.

package/dist/agent-logs.js

@@ -0,0 +1,329 @@
+/** Durable project-scoped outbox. No credentials or private transcripts enter the world tree. */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { randomUUID } from "node:crypto";
+import { authorizedFetch, resolveSession, sessionBaseUrl } from "./api.js";
+import { apiBase } from "./config.js";
+import { loadState, requireState } from "./state.js";
+import { convertTranscript, eventSchema, hash, sessionKey, slug, } from "./log-events.js";
+export function projectRoot(start) {
+    let dir = path.resolve(start);
+    for (;;) {
+        if (loadState(dir))
+            return fs.realpathSync(dir);
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export const logDir = (dir) => path.join(dir, ".virtualmatter", "agent-logs");
+export function writeJson(file, obj) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temp = `${file}.${randomUUID()}.tmp`;
+    fs.writeFileSync(temp, JSON.stringify(obj, null, 2) + "\n", { mode: 0o600 });
+    fs.renameSync(temp, file);
+}
+export function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+export function logConfig(dir) {
+    return readJson(path.join(logDir(dir), "config.json"));
+}
+export function enqueue(dir, harness, session, events) {
+    slug(harness);
+    sessionKey(session);
+    const framing = requireState(dir).framing_id;
+    const indexFile = path.join(logDir(dir), "captured", hash(JSON.stringify([apiBase(), framing, harness, session])) + ".json");
+    const known = Object.assign(Object.create(null), readJson(indexFile) ?? {});
+    const fresh = [];
+    // Validate the entire capture before queueing. Checkpoints contain hashes,
+    // never transcript content. Re-reading a growing transcript while offline
+    // must queue only its new events, not every prefix of the same conversation.
+    for (const raw of events) {
+        const event = eventSchema.parse(raw);
+        const encoded = JSON.stringify(event);
+        if (Buffer.byteLength(encoded) > 256 * 1024)
+            throw new Error("Event exceeds 256 KiB");
+        const digest = hash(encoded);
+        if (Object.hasOwn(known, event.event_id)) {
+            if (known[event.event_id] !== digest)
+                throw new Error("Event ID already captured with different content");
+        }
+        else {
+            fresh.push(event);
+            known[event.event_id] = digest;
+        }
+    }
+    let queued = 0;
+    let batch = [];
+    let size = 0;
+    const commit = () => {
+        if (!batch.length)
+            return;
+        const envelope = {
+            version: 1,
+            api: apiBase(),
+            framing,
+            harness,
+            session,
+            events: batch,
+        };
+        const id = hash(JSON.stringify(envelope));
+        const root = logDir(dir);
+        if (!fs.existsSync(path.join(root, "receipts", id)) &&
+            !fs.existsSync(path.join(root, "pending", id + ".json"))) {
+            writeJson(path.join(root, "pending", id + ".json"), envelope);
+            queued += batch.length;
+        }
+        batch = [];
+        size = 0;
+    };
+    for (const event of fresh) {
+        const bytes = Buffer.byteLength(JSON.stringify(event));
+        if (bytes > 256 * 1024)
+            throw new Error("Event exceeds 256 KiB");
+        if (batch.length >= 250 || size + bytes > 800_000)
+            commit();
+        batch.push(event);
+        size += bytes + 1;
+    }
+    commit();
+    // Queue first, checkpoint second. A crash can cause a safe duplicate retry,
+    // never a checkpoint that skips events which were not durably queued.
+    if (fresh.length)
+        writeJson(indexFile, { ...(readJson(indexFile) ?? {}), ...known });
+    return queued;
+}
+export async function uploadBatch(base, framing, harness, session, events) {
+    const response = await authorizedFetch(`${base}/api/montage/${encodeURIComponent(framing)}/agent-logs/${slug(harness)}/${sessionKey(session)}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ events }),
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!response.ok)
+        throw new Error(`Agent-log upload failed: HTTP ${response.status}${response.status === 404 ? " (server may need the agent-log API update)" : ""}`);
+    const result = (await response.json());
+    if (result.accepted + result.duplicates !== events.length)
+        throw new Error("Invalid upload acknowledgement; batch retained");
+    return result;
+}
+export async function flushLogs(dir, send) {
+    const lock = path.join(logDir(dir), "flush.lock");
+    fs.mkdirSync(path.dirname(lock), { recursive: true, mode: 0o700 });
+    // Concurrent hooks share one uploader. A crashed process leaves recoverable
+    // queue files; never discard batches just because a lock was abandoned.
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = fs.openSync(lock, "wx", 0o600);
+            fs.writeFileSync(fd, String(process.pid));
+            fs.closeSync(fd);
+            try {
+                return await flushUnlocked(dir, send);
+            }
+            finally {
+                fs.rmSync(lock, { force: true });
+            }
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            let pid;
+            try {
+                pid = Number(fs.readFileSync(lock, "utf8"));
+            }
+            catch {
+                continue;
+            }
+            // A just-created, not-yet-written lock also belongs to a live writer.
+            if (!Number.isSafeInteger(pid) || pid <= 0)
+                return 0;
+            try {
+                process.kill(pid, 0);
+                return 0;
+            }
+            catch (error) {
+                if (error.code !== "ESRCH")
+                    return 0;
+                fs.rmSync(lock, { force: true });
+            }
+        }
+    }
+    return 0;
+}
+async function flushUnlocked(dir, send) {
+    const root = logDir(dir), pending = path.join(root, "pending");
+    if (!fs.existsSync(pending))
+        return 0;
+    const files = fs
+        .readdirSync(pending)
+        .filter((f) => f.endsWith(".json"))
+        .sort((a, b) => fs.statSync(path.join(pending, a)).mtimeMs -
+        fs.statSync(path.join(pending, b)).mtimeMs);
+    if (!files.length)
+        return 0;
+    let base;
+    let sent = 0;
+    for (const name of files) {
+        const file = path.join(pending, name);
+        const e = readJson(file);
+        if (!e)
+            continue; // another flushing process already acknowledged it
+        if (e.version !== 1 ||
+            e.api !== apiBase() ||
+            e.framing !== requireState(dir).framing_id)
+            throw new Error("Outbox belongs to a different project/environment; preserved");
+        try {
+            if (send)
+                await send(e);
+            else {
+                base ??= sessionBaseUrl(await resolveSession(e.framing, { timeoutMs: 30_000 }));
+                await uploadBatch(base, e.framing, e.harness, e.session, e.events);
+            }
+            const receipt = path.join(root, "receipts", name.slice(0, -5));
+            fs.mkdirSync(path.dirname(receipt), { recursive: true, mode: 0o700 });
+            fs.writeFileSync(receipt, "", { mode: 0o600 });
+            fs.rmSync(file, { force: true });
+            sent += e.events.length;
+        }
+        catch (err) {
+            writeJson(path.join(root, "last-error.json"), {
+                ts: new Date().toISOString(),
+                message: String(err),
+            });
+            throw err;
+        }
+    }
+    fs.rmSync(path.join(root, "last-error.json"), { force: true });
+    return sent;
+}
+export function registerSource(dir, source) {
+    slug(source.harness);
+    sessionKey(source.session);
+    const target = path.join(logDir(dir), "sources", hash(source.file) + ".json");
+    if (JSON.stringify(readJson(target)) !== JSON.stringify(source))
+        writeJson(target, source);
+}
+export function captureSource(dir, source, since) {
+    if (!fs.existsSync(source.file))
+        return 0;
+    if (fs.statSync(source.file).size > 128 * 1024 * 1024)
+        throw new Error("Transcript exceeds 128 MiB; split it for explicit upload");
+    const events = convertTranscript(fs.readFileSync(source.file, "utf8"), source.format, true).filter((e) => !since || Date.parse(e.ts) >= Date.parse(since));
+    return enqueue(dir, source.harness, source.session, events);
+}
+/** Discover Codex desktop/CLI sessions by their initial cwd metadata, never by text search. */
+export function discoverCodex(dir, since, home = process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex")) {
+    const root = path.join(home, "sessions"), found = [];
+    const walk = (folder, depth) => {
+        if (depth > 4 || !fs.existsSync(folder))
+            return;
+        for (const entry of fs.readdirSync(folder, { withFileTypes: true })) {
+            const file = path.join(folder, entry.name);
+            if (entry.isDirectory())
+                walk(file, depth + 1);
+            else if (entry.isFile() &&
+                entry.name.endsWith(".jsonl") &&
+                fs.statSync(file).mtimeMs >= Date.parse(since)) {
+                const fd = fs.openSync(file, "r");
+                let first;
+                try {
+                    const buffer = Buffer.alloc(16384);
+                    first = buffer
+                        .subarray(0, fs.readSync(fd, buffer, 0, buffer.length, 0))
+                        .toString()
+                        .split("\n")[0];
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+                try {
+                    const row = JSON.parse(first), p = row.payload;
+                    if (row.type === "session_meta" &&
+                        typeof p?.cwd === "string" &&
+                        projectRoot(p.cwd) === fs.realpathSync(dir)) {
+                        found.push({
+                            file,
+                            format: "codex",
+                            harness: "codex",
+                            session: sessionKey(p.id),
+                        });
+                    }
+                }
+                catch {
+                    /* unrelated/unflushed metadata */
+                }
+            }
+        }
+    };
+    walk(root, 0);
+    return found;
+}
+export async function collectLogs(dir) {
+    const config = logConfig(dir);
+    if (!config?.enabled)
+        return 0;
+    if (config.codexDiscovery)
+        for (const source of discoverCodex(dir, config.since))
+            registerSource(dir, source);
+    const sources = path.join(logDir(dir), "sources");
+    let n = 0;
+    const errors = [];
+    if (fs.existsSync(sources))
+        for (const file of fs
+            .readdirSync(sources)
+            .filter((f) => f.endsWith(".json"))) {
+            try {
+                n += captureSource(dir, readJson(path.join(sources, file)), config.since);
+            }
+            catch (err) {
+                errors.push({ source: file, message: String(err) });
+            }
+        }
+    if (errors.length)
+        writeJson(path.join(logDir(dir), "capture-errors.json"), errors);
+    else
+        fs.rmSync(path.join(logDir(dir), "capture-errors.json"), { force: true });
+    return n;
+}
+/** One non-overlapping retry loop; discovery also catches delayed final transcript writes. */
+export function startLogSync(dir, warn = (s) => console.warn(s)) {
+    let running;
+    let lastError = "";
+    const tick = () => {
+        if (running)
+            return;
+        running = (async () => {
+            try {
+                if (!logConfig(dir)?.enabled)
+                    return;
+                await collectLogs(dir);
+                await flushLogs(dir);
+                lastError = "";
+            }
+            catch (err) {
+                const message = String(err);
+                if (message !== lastError)
+                    warn(`Agent logs queued: ${message}`);
+                lastError = message;
+            }
+        })().finally(() => {
+            running = undefined;
+        });
+    };
+    tick();
+    const interval = setInterval(tick, 5000);
+    return async () => {
+        clearInterval(interval);
+        await running;
+    };
+}

package/dist/agentfiles.js

@@ -14,6 +14,7 @@ export const AGENTS_MD_STUB = `# Working with Virtual Matter
 This folder is a live mirror of a Virtual Matter world's Montage files.
 
 - \`npx virtualmatter sync\` keeps it in sync with the running session.
+- \`npx virtualmatter agent-logs setup\` enables automatic local conversation logs.
 - \`npx virtualmatter run-lua --code "..."\` executes Lua in the engine.
 - \`npx virtualmatter errors\` shows recent engine errors.
 - \`npx virtualmatter screenshot -o shot.png\` captures the current view.

package/dist/index.js

@@ -2,6 +2,7 @@
 /** virtualmatter - the CLI coding agents (and humans) install to build with Virtual Matter. */
 import fs from "node:fs";
 import path from "node:path";
+import { registerLogCommands } from "./log-commands.js";
 import { Command } from "commander";
 import { createProject, createWebsiteBuild, getWebsiteBuild, getEmbed, defaultRegion, editUrl, fetchNativeClientCatalog, listProjects, playUrl, resolveSession, sessionBaseUrl, whoami, } from "./api.js";
 import { NotLoggedInError, clearCredentials, loadCredentials, pollForToken, saveCredentials, startDeviceFlow, } from "./auth.js";
@@ -331,6 +332,7 @@ program
     .action((dir, opts) => run(async () => {
     await runMcpServer(path.resolve(dir), opts.framing);
 }));
+registerLogCommands(program);
 program.parseAsync(process.argv).catch((err) => {
     fail(err instanceof Error ? err.message : String(err));
 });

package/dist/log-commands.js

@@ -0,0 +1,201 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { captureSource, collectLogs, enqueue, flushLogs, logConfig, logDir, projectRoot, readJson, registerSource, startLogSync, writeJson, } from "./agent-logs.js";
+import { convertHook, convertTranscript, hash } from "./log-events.js";
+import { setupLogs } from "./log-setup.js";
+function root(dir = process.cwd()) {
+    const found = projectRoot(dir);
+    if (!found)
+        throw new Error("No Virtual Matter project here. Run virtualmatter pull first, or pass --dir.");
+    return found;
+}
+async function stdin() {
+    let text = "";
+    for await (const chunk of process.stdin) {
+        text += chunk;
+        if (Buffer.byteLength(text) > 8 * 1024 * 1024)
+            throw new Error("Hook input exceeds 8 MiB");
+    }
+    return text;
+}
+function kick(dir) {
+    const child = spawn(process.execPath, [
+        fileURLToPath(new URL("./index.js", import.meta.url)),
+        "agent-logs",
+        "flush",
+        "--dir",
+        dir,
+        "--quiet",
+    ], { detached: true, stdio: "ignore", windowsHide: true });
+    child.on("error", () => { });
+    child.unref();
+}
+export function registerLogCommands(program) {
+    const logs = program
+        .command("agent-logs")
+        .alias("agentlog")
+        .description("Upload and automatically sync conversations from local coding harnesses");
+    logs
+        .command("setup")
+        .option("--dir <dir>", "project folder")
+        .option("--harness <name>", "all, codex, claude-code, cursor, or hermes", "all")
+        .action((o) => {
+        for (const message of setupLogs(root(o.dir), o.harness))
+            console.log(message);
+        console.log("Capturing future entries. Keep virtualmatter sync or agent-logs watch running for offline retries and delayed transcript writes.");
+    });
+    logs
+        .command("disable")
+        .option("--dir <dir>")
+        .action((o) => {
+        const dir = root(o.dir), config = logConfig(dir);
+        if (config)
+            writeJson(path.join(logDir(dir), "config.json"), {
+                ...config,
+                enabled: false,
+            });
+        console.log("Automatic capture disabled. Existing logs and queued entries retained.");
+    });
+    logs
+        .command("status")
+        .option("--dir <dir>")
+        .action((o) => {
+        const dir = root(o.dir), pending = path.join(logDir(dir), "pending");
+        console.log(JSON.stringify({
+            project: dir,
+            config: logConfig(dir),
+            pending_batches: fs.existsSync(pending)
+                ? fs.readdirSync(pending).filter((f) => f.endsWith(".json"))
+                    .length
+                : 0,
+            last_error: readJson(path.join(logDir(dir), "last-error.json")),
+            capture_errors: readJson(path.join(logDir(dir), "capture-errors.json")),
+        }, null, 2));
+    });
+    logs
+        .command("upload")
+        .argument("<file>", "JSONL file or - for stdin")
+        .requiredOption("--harness <name>")
+        .requiredOption("--session <id>")
+        .option("--format <format>", "events, codex, or claude-code", "events")
+        .option("--dir <dir>")
+        .option("--queue-only", "persist locally without uploading")
+        .action(async (file, o) => {
+        const dir = root(o.dir);
+        const events = convertTranscript(file === "-" ? await stdin() : fs.readFileSync(file, "utf8"), o.format);
+        const n = enqueue(dir, o.harness, o.session, events);
+        console.log(`Queued ${n} events.`);
+        if (!o.queueOnly)
+            console.log(`Acknowledged ${await flushLogs(dir)} events.`);
+    });
+    logs
+        .command("follow")
+        .argument("<file>", "Keep collecting new records from this transcript")
+        .requiredOption("--harness <name>")
+        .requiredOption("--session <id>")
+        .option("--format <format>", "events, codex, or claude-code", "events")
+        .option("--dir <dir>")
+        .action((file, o) => {
+        const dir = root(o.dir);
+        if (!logConfig(dir)?.enabled)
+            throw new Error("Run agent-logs setup first.");
+        const source = {
+            file: fs.realpathSync(file),
+            format: o.format,
+            harness: o.harness,
+            session: o.session,
+        };
+        // An explicit binding supports a task that began in another folder,
+        // without guessing that every transcript on this machine belongs here.
+        captureSource(dir, source, logConfig(dir).since);
+        registerSource(dir, source);
+        console.log("Transcript registered. New entries will be collected by sync/watch and flush.");
+    });
+    logs
+        .command("hook")
+        .requiredOption("--harness <name>")
+        .option("--dir <dir>")
+        .description("Receive harness JSON on stdin; silent, local-first, and safe outside enabled projects")
+        .action(async (o) => {
+        let dir = null;
+        try {
+            const p = JSON.parse(await stdin());
+            const cwd = o.dir ?? p.cwd ?? p.workspace_roots?.[0] ?? process.cwd();
+            dir = projectRoot(cwd);
+            if (!dir || !logConfig(dir)?.enabled)
+                return;
+            const session = p.session_id ?? p.conversation_id ?? p["thread-id"];
+            if (!session)
+                throw new Error("Hook did not provide a session ID");
+            if (["codex", "claude-code"].includes(o.harness)) {
+                if (p.transcript_path) {
+                    const source = {
+                        file: path.resolve(cwd, p.transcript_path),
+                        format: o.harness,
+                        harness: o.harness,
+                        session,
+                    };
+                    registerSource(dir, source);
+                    captureSource(dir, source, logConfig(dir).since);
+                }
+                else if (o.harness === "codex")
+                    await collectLogs(dir);
+                else
+                    throw new Error("Hook did not provide transcript_path");
+            }
+            else {
+                const stateFile = path.join(logDir(dir), "hook-state", hash(`${o.harness}:${session}`) + ".json");
+                const state = readJson(stateFile) ?? {};
+                enqueue(dir, o.harness, session, convertHook(o.harness, p, new Date().toISOString(), state));
+                writeJson(stateFile, state);
+            }
+            kick(dir);
+        }
+        catch (err) {
+            if (dir)
+                writeJson(path.join(logDir(dir), "last-error.json"), {
+                    ts: new Date().toISOString(),
+                    message: String(err),
+                });
+            // Logging must not change the harness response or interrupt the turn.
+        }
+    });
+    logs
+        .command("flush")
+        .option("--dir <dir>")
+        .option("--quiet")
+        .action(async (o) => {
+        const dir = root(o.dir);
+        try {
+            if (o.quiet && !logConfig(dir)?.enabled)
+                return;
+            await collectLogs(dir);
+            const n = await flushLogs(dir);
+            if (!o.quiet)
+                console.log(`Acknowledged ${n} events.`);
+        }
+        catch (err) {
+            if (!o.quiet)
+                throw err;
+        }
+    });
+    logs
+        .command("watch")
+        .option("--dir <dir>")
+        .action(async (o) => {
+        const dir = root(o.dir);
+        if (!logConfig(dir)?.enabled)
+            throw new Error("Run agent-logs setup first.");
+        console.log(`Watching agent logs for ${dir}. Ctrl-C to stop.`);
+        const stop = startLogSync(dir);
+        await new Promise((resolve) => {
+            const done = () => {
+                void stop().then(resolve);
+            };
+            process.once("SIGINT", done);
+            process.once("SIGTERM", done);
+        });
+    });
+}

package/dist/log-events.js

@@ -0,0 +1,267 @@
+/** Harness adapters emit only public conversation/tool activity, never reasoning. */
+import { createHash, randomUUID } from "node:crypto";
+import { z } from "zod";
+export const eventSchema = z
+    .object({
+    event_id: z.string().regex(/^[A-Za-z0-9_:-]{1,128}$/),
+    ts: z.string().datetime({ offset: true }),
+    type: z.enum([
+        "user",
+        "assistant_text",
+        "tool_use",
+        "tool_result",
+        "result",
+    ]),
+    text: z.string().max(32768).optional(),
+    name: z.string().max(256).optional(),
+    input: z.union([z.record(z.unknown()), z.string()]).optional(),
+    tool_use_id: z.string().max(256).optional(),
+    result: z.string().max(32768).optional(),
+})
+    .strict();
+export const hash = (value) => createHash("sha256").update(value).digest("hex");
+export const slug = (value) => {
+    if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(value))
+        throw new Error("Invalid harness name");
+    return value;
+};
+export const sessionKey = (value) => {
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(value))
+        throw new Error("Invalid session ID");
+    return value;
+};
+export function scrub(value, depth = 0) {
+    if (depth > 15)
+        return "[nested content omitted]";
+    if (typeof value === "string") {
+        if (/^\s*[\[{]/.test(value)) {
+            try {
+                return JSON.stringify(scrub(JSON.parse(value), depth + 1)).slice(0, 32000);
+            }
+            catch {
+                /* ordinary text or truncated JSON */
+            }
+        }
+        return value
+            .replace(/data:[^\s;,]+;base64,[A-Za-z0-9+/=]+/g, "[media omitted]")
+            .replace(/Bearer\s+[A-Za-z0-9._~+/-]+=*/gi, "Bearer [redacted]")
+            .replace(/\bsk-[A-Za-z0-9_-]{16,}/g, "[redacted]")
+            .slice(0, 32000);
+    }
+    if (Array.isArray(value))
+        return value.slice(0, 200).map((v) => scrub(v, depth + 1));
+    if (value && typeof value === "object") {
+        const obj = value;
+        if (/^(image|input_image|audio|input_audio|reasoning|thinking|redacted_thinking)$/.test(obj.type ?? ""))
+            return "[non-text content omitted]";
+        return Object.fromEntries(Object.entries(obj)
+            .slice(0, 200)
+            .map(([k, v]) => [
+            k,
+            /^(authorization|password|api[_-]?key|access_token|refresh_token|encrypted_content|reasoning|analysis|thinking)$/i.test(k)
+                ? "[redacted]"
+                : scrub(v, depth + 1),
+        ]));
+    }
+    return value;
+}
+function text(value) {
+    if (typeof value === "string")
+        return scrub(value);
+    if (Array.isArray(value))
+        return value
+            .map((b) => typeof b === "string"
+            ? b
+            : b && /^(text|input_text|output_text)$/.test(b.type)
+                ? (b.text ?? "")
+                : "[non-text content omitted]")
+            .join("\n")
+            .slice(0, 32000);
+    return value == null ? "" : JSON.stringify(scrub(value)).slice(0, 32000);
+}
+function input(value) {
+    if (typeof value === "string") {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            /* command text */
+        }
+    }
+    const clean = scrub(value ?? {});
+    return JSON.stringify(clean).length > 32000 ? text(clean) : clean;
+}
+function make(type, ts, seed, fields = {}) {
+    return eventSchema.parse({ event_id: hash(seed), ts, type, ...fields });
+}
+/** Complete JSONL records only when tailing. A malformed complete record fails visibly. */
+export function parseJsonl(raw, tail = false) {
+    const lines = raw.split("\n");
+    if (tail)
+        lines.pop();
+    return lines.flatMap((line, i) => {
+        if (!line.trim())
+            return [];
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            throw new Error(`Invalid JSONL at line ${i + 1}`);
+        }
+    });
+}
+export function convertTranscript(raw, format, tail = false) {
+    const out = [];
+    const occurrences = new Map();
+    for (const row of parseJsonl(raw, tail)) {
+        const fingerprint = hash(JSON.stringify(row));
+        const n = occurrences.get(fingerprint) ?? 0;
+        occurrences.set(fingerprint, n + 1);
+        const seed = `${fingerprint}:${n}`;
+        const ts = row.timestamp ?? row.ts;
+        let count = 0;
+        const emit = (type, fields = {}) => out.push(make(type, ts, `${seed}:${count++}`, fields));
+        if (format === "events") {
+            // Accept the platform's flat logs as well as the portable event schema.
+            if (![
+                "user",
+                "assistant_text",
+                "tool_use",
+                "tool_result",
+                "result",
+            ].includes(row.type))
+                continue;
+            const fields = {};
+            for (const k of ["text", "name", "tool_use_id", "result"])
+                if (row[k] !== undefined)
+                    fields[k] = text(row[k]);
+            if (row.input !== undefined)
+                fields.input = input(row.input);
+            out.push(eventSchema.parse({
+                event_id: row.event_id ?? hash(seed),
+                ts,
+                type: row.type,
+                ...fields,
+            }));
+        }
+        else if (format === "codex") {
+            const p = row.payload ?? {};
+            if (row.type === "event_msg" && p.type === "task_complete") {
+                emit("result");
+                continue;
+            }
+            if (row.type !== "response_item")
+                continue;
+            if (p.type === "message" &&
+                ["user", "assistant"].includes(p.role) &&
+                p.channel !== "analysis" &&
+                p.phase !== "analysis") {
+                const body = text(p.content);
+                if (!body ||
+                    /^\s*<(environment_context|recommended_plugins)>/.test(body))
+                    continue;
+                emit(p.role === "user" ? "user" : "assistant_text", { text: body });
+            }
+            else if (["function_call", "custom_tool_call"].includes(p.type)) {
+                emit("tool_use", {
+                    name: p.name,
+                    input: input(p.arguments ?? p.input),
+                    tool_use_id: p.call_id,
+                });
+            }
+            else if (["function_call_output", "custom_tool_call_output"].includes(p.type)) {
+                emit("tool_result", { result: text(p.output), tool_use_id: p.call_id });
+            }
+        }
+        else if (format === "claude-code") {
+            if (row.type === "result") {
+                emit("result");
+                continue;
+            }
+            if (!["user", "assistant"].includes(row.type))
+                continue;
+            const msg = row.message ?? {};
+            if (typeof msg.content === "string")
+                emit(row.type === "user" ? "user" : "assistant_text", {
+                    text: text(msg.content),
+                });
+            else
+                for (const b of msg.content ?? []) {
+                    if (b.type === "text")
+                        emit(row.type === "user" ? "user" : "assistant_text", {
+                            text: text(b.text),
+                        });
+                    if (b.type === "tool_use")
+                        emit("tool_use", {
+                            name: b.name,
+                            input: input(b.input),
+                            tool_use_id: b.id,
+                        });
+                    if (b.type === "tool_result")
+                        emit("tool_result", {
+                            result: text(b.content),
+                            tool_use_id: b.tool_use_id,
+                        });
+                }
+        }
+        else
+            throw new Error(`Unsupported transcript format: ${format}. Use events for any other harness.`);
+    }
+    return out;
+}
+export function convertHook(harness, p, now = new Date().toISOString(), state = {}) {
+    const ts = p.timestamp ?? now;
+    const extra = p.extra ?? {};
+    const event = p.hook_event_name;
+    const seed = p.event_id ?? p.delivery_id ?? randomUUID();
+    const out = [];
+    const emit = (type, fields = {}) => out.push(make(type, ts, `${seed}:${out.length}`, fields));
+    if (harness === "cursor") {
+        if (event === "beforeSubmitPrompt")
+            emit("user", { text: text(p.prompt) });
+        if (event === "afterAgentResponse")
+            emit("assistant_text", { text: text(p.text) });
+        if (event === "postToolUse" || event === "postToolUseFailure") {
+            const id = p.tool_use_id ?? p.tool_call_id ?? seed;
+            emit("tool_use", {
+                name: p.tool_name ?? "tool",
+                input: input(p.tool_input),
+                tool_use_id: id,
+            });
+            emit("tool_result", {
+                result: text(p.tool_output ?? p.result ?? p.tool_response ?? p.error_message),
+                tool_use_id: id,
+            });
+        }
+        if (event === "stop")
+            emit("result");
+    }
+    else if (harness === "hermes") {
+        if (event === "pre_llm_call" && extra.user_message) {
+            const prompt = text(extra.user_message);
+            // The tool loop repeats pre_llm_call with the same prompt. Reset on
+            // completion so an identical prompt on the next turn is still captured.
+            if (state.prompt !== prompt)
+                emit("user", { text: prompt });
+            state.prompt = prompt;
+        }
+        if (event === "post_tool_call") {
+            const id = extra.tool_call_id ?? seed;
+            emit("tool_use", {
+                name: p.tool_name ?? "tool",
+                input: input(p.tool_input ?? extra.args),
+                tool_use_id: id,
+            });
+            emit("tool_result", { result: text(extra.result), tool_use_id: id });
+        }
+        if (event === "transform_llm_output") {
+            delete state.prompt;
+            emit("assistant_text", { text: text(extra.response_text) });
+            emit("result");
+        }
+    }
+    else if (Array.isArray(p.events)) {
+        return convertTranscript(p.events.map((e) => JSON.stringify(e)).join("\n"), "events");
+    }
+    return out;
+}

package/dist/log-setup.js

@@ -0,0 +1,123 @@
+/** Install additive, project-scoped integrations; keep other hooks and notify commands. */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "yaml";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { logConfig, logDir, readJson, writeJson } from "./agent-logs.js";
+import { requireState } from "./state.js";
+export const HARNESSES = ["codex", "claude-code", "cursor", "hermes"];
+const cli = fileURLToPath(new URL("./index.js", import.meta.url));
+// JSON double quoting is safe for Windows command paths; POSIX needs literal single quotes.
+export function quote(arg) {
+    return process.platform === "win32"
+        ? '"' + arg.replace(/"/g, '""') + '"'
+        : "'" + arg.replace(/'/g, "'\\''") + "'";
+}
+function backup(file) {
+    if (fs.existsSync(file))
+        fs.copyFileSync(file, `${file}.vm-backup-${Date.now()}`);
+}
+function command(harness) {
+    return [process.execPath, cli, "agent-logs", "hook", "--harness", harness]
+        .map(quote)
+        .join(" ");
+}
+function mergeJson(file, events, cmd, cursor = false) {
+    const config = readJson(file) ?? {};
+    if (typeof config !== "object" || Array.isArray(config))
+        throw new Error(`Invalid config: ${file}`);
+    config.hooks ??= {};
+    if (cursor)
+        config.version ??= 1;
+    for (const event of events) {
+        const groups = config.hooks[event] ?? [];
+        if (!Array.isArray(groups))
+            throw new Error(`Invalid hooks.${event} in ${file}`);
+        if (!JSON.stringify(groups).includes(cmd))
+            groups.push(cursor
+                ? { command: cmd }
+                : { hooks: [{ type: "command", command: cmd }] });
+        config.hooks[event] = groups;
+    }
+    if (JSON.stringify(readJson(file)) !== JSON.stringify(config)) {
+        backup(file);
+        writeJson(file, config);
+    }
+}
+export function setupLogs(dir, harness = "all") {
+    requireState(dir);
+    if (harness !== "all" && !HARNESSES.includes(harness))
+        throw new Error(`Choose all or ${HARNESSES.join(", ")}; custom harnesses use agent-logs hook/upload`);
+    const selected = harness === "all" ? HARNESSES : [harness];
+    const messages = [];
+    for (const h of selected) {
+        const cmd = command(h);
+        if (h === "codex") {
+            mergeJson(path.join(dir, ".codex/hooks.json"), ["SessionStart", "Stop", "Interrupt", "SessionEnd"], cmd);
+            const file = path.join(dir, ".codex/config.toml");
+            const config = fs.existsSync(file)
+                ? parseToml(fs.readFileSync(file, "utf8"))
+                : {};
+            const features = (config.features ?? {});
+            if (features.hooks !== true) {
+                features.hooks = true;
+                config.features = features;
+                backup(file);
+                fs.writeFileSync(file, stringifyToml(config), { mode: 0o600 });
+            }
+            messages.push("Codex: project hooks installed; review them with /hooks. The sync watcher also discovers this project's desktop/CLI transcripts.");
+        }
+        else if (h === "claude-code") {
+            mergeJson(path.join(dir, ".claude/settings.local.json"), ["SessionStart", "Stop", "SessionEnd"], cmd);
+            messages.push("Claude Code: project transcript hooks installed (restart the harness to load them).");
+        }
+        else if (h === "cursor") {
+            mergeJson(path.join(dir, ".cursor/hooks.json"), [
+                "beforeSubmitPrompt",
+                "afterAgentResponse",
+                "postToolUse",
+                "postToolUseFailure",
+                "stop",
+            ], cmd, true);
+            messages.push("Cursor: project event hooks installed (restart the harness to load them).");
+        }
+        else {
+            const home = process.env.HERMES_HOME ?? path.join(os.homedir(), ".hermes");
+            const file = path.join(home, "config.yaml");
+            if (harness === "all" && !fs.existsSync(file)) {
+                messages.push("Hermes is not configured here; run agent-logs setup --harness hermes after installing it.");
+                continue;
+            }
+            const doc = parseDocument(fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "{}");
+            if (doc.errors.length)
+                throw new Error(`Invalid YAML in ${file}; preserved`);
+            for (const event of [
+                "pre_llm_call",
+                "post_tool_call",
+                "transform_llm_output",
+            ]) {
+                const old = doc.getIn(["hooks", event]);
+                const list = old ? old.toJSON() : [];
+                if (!Array.isArray(list))
+                    throw new Error(`Invalid Hermes hooks.${event}; preserved`);
+                if (!list.some((v) => v.command === cmd))
+                    list.push({ command: cmd, timeout: 10 });
+                doc.setIn(["hooks", event], list);
+            }
+            backup(file);
+            fs.mkdirSync(home, { recursive: true });
+            fs.writeFileSync(file, doc.toString(), { mode: 0o600 });
+            messages.push("Hermes: cwd-gated profile hooks installed. Hermes will request its normal first-use hook approval.");
+        }
+    }
+    const old = logConfig(dir);
+    writeJson(path.join(logDir(dir), "config.json"), {
+        version: 1,
+        enabled: true,
+        since: old?.since ?? new Date().toISOString(),
+        codexDiscovery: old?.codexDiscovery || selected.includes("codex"),
+    });
+    return messages;
+}

package/dist/mcp.js

@@ -1,3 +1,5 @@
+import { uploadBatch } from "./agent-logs.js";
+import { eventSchema } from "./log-events.js";
 /**
  * `virtualmatter mcp` - a stdio MCP server that gives a coding agent direct
  * hands on Virtual Matter: the account's projects, creating one, a live
@@ -97,6 +99,15 @@ export async function writeWithRetry(client, filePath, body) {
 export async function runMcpServer(dir, framingFlag) {
     const ctx = makeContext(resolveFramingId(dir, framingFlag));
     const server = new McpServer({ name: "virtualmatter", version: packageVersion() });
+    server.registerTool("upload_agent_logs", {
+        description: "Append public conversation and tool events from any local harness to the selected project's Agent Logs. Supply stable event IDs for retry deduplication. Never include private reasoning, system prompts, credentials, or binary media. Use the CLI hook integrations for automatic full conversation capture.",
+        inputSchema: { harness: z.string().regex(/^[a-z0-9][a-z0-9_-]{0,63}$/), session_id: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/), events: z.array(eventSchema).min(1).max(500) },
+    }, async ({ harness, session_id, events }) => {
+        const framing = ctx.requireFraming();
+        // Resolve afresh so a restarted session never strands retries on an old host.
+        const session = await resolveSession(framing);
+        return textResult(JSON.stringify(await uploadBatch(sessionBaseUrl(session), framing, harness, session_id, events)));
+    });
     server.registerTool("get_embed", {
         description: "Get canonical iframe markup and hosting instructions for a shared Virtual Matter world URL. No sign-in needed. Follow the instructions and verify the published page.",
         inputSchema: { target: z.string() },

package/dist/sync.js

@@ -1,3 +1,4 @@
+import { startLogSync } from "./agent-logs.js";
 /**
  * The sync hot loop: initial pull of remote changes, watch the local tree
  * and push edits with stored etags, poll the remote listing and pull files
@@ -213,6 +214,7 @@ export async function runSyncLoop(engine, dir) {
     const { default: chokidar } = await import("chokidar");
     const { pulled, pushed } = await engine.initialSync();
     console.log(`initial sync: ${pulled} pulled, ${pushed} pushed. Watching ${dir} ...`);
+    const stopLogs = startLogSync(dir);
     const watcher = chokidar.watch(dir, {
         ignoreInitial: true,
         ignored: (p) => {
@@ -241,6 +243,7 @@ export async function runSyncLoop(engine, dir) {
         const stop = async () => {
             clearInterval(interval);
             await watcher.close();
+            await stopLogs();
             console.log("\nsync stopped.");
             resolve();
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "virtualmatter",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "CLI + MCP server for building with Virtual Matter - list and create worlds, sync their files, run Lua, capture screenshots, open the native client, and wire coding agents into a live session.",
   "license": "MIT",
   "type": "module",
@@ -25,6 +25,8 @@
     "@modelcontextprotocol/sdk": "^1.12.0",
     "chokidar": "^4.0.3",
     "commander": "^14.0.0",
+    "smol-toml": "^1.8.0",
+    "yaml": "^2.9.0",
     "zod": "^3.25.0"
   },
   "devDependencies": {