virtualmatter 0.2.0 → 0.4.0

package/dist/index.js

@@ -2,8 +2,9 @@
 /** 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, defaultRegion, editUrl, fetchNativeClientCatalog, listProjects, playUrl, resolveSession, sessionBaseUrl, whoami, } from "./api.js";
+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";
 import { openInBrowser } from "./browser.js";
 import { detectPlatform, ensureClientInstalled, launchClient, seedNativeAuth } from "./client.js";
@@ -94,7 +95,10 @@ function reportPull(result, dest) {
         console.log(`Wrote ${files.written.join(", ")} so Claude Code, Codex, and Cursor find their way around.`);
     }
     const rel = path.relative(process.cwd(), dest) || ".";
-    console.log(`Next: cd ${rel} && npx virtualmatter sync`);
+    // A relative path is friendlier only while it stays short; a folder far
+    // from the cwd reads better as the absolute path it is.
+    const shown = rel.startsWith("..") ? dest : rel;
+    console.log(`Next: cd ${JSON.stringify(shown).slice(1, -1).includes(" ") ? `"${shown}"` : shown} && npx virtualmatter sync`);
     console.log(`      (or open the folder in your agent - the MCP server is registered in .mcp.json)`);
 }
 program
@@ -117,6 +121,21 @@ program
     const me = await whoami();
     console.log(JSON.stringify(me, null, 2));
 }));
+program
+    .command("embed <target>")
+    .description("Get iframe markup and required hosting setup for a shared world; no sign-in")
+    .action((target) => run(async () => console.log(JSON.stringify(await getEmbed(target), null, 2))));
+program
+    .command("build <name>")
+    .description("Create a private world and send a build prompt to VM's agent (uses VM credits)")
+    .requiredOption("--prompt <text>", "What VM should build")
+    .requiredOption("--request-id <id>", "Stable identifier for this request; reuse on retries")
+    .option("--region <region>", "NA, EU, or AS", defaultRegion())
+    .action((name, opts) => run(async () => console.log(JSON.stringify(await createWebsiteBuild({ name, prompt: opts.prompt, request_id: opts.requestId, region: opts.region }), null, 2))));
+program
+    .command("build-status <build-id>")
+    .description("Read a previously requested VM build's progress")
+    .action((id) => run(async () => console.log(JSON.stringify(await getWebsiteBuild(id), null, 2))));
 program
     .command("list")
     .alias("ls")
@@ -234,14 +253,31 @@ program
     const { client } = await clientForDir(path.resolve(dir));
     console.log(JSON.stringify(await client.engineErrors(), null, 2));
 }));
+/** Parse an "x,y,z" flag into a numeric triple. */
+function triple(value, flag) {
+    const parts = value.split(",").map((p) => Number(p.trim()));
+    if (parts.length !== 3 || parts.some((n) => !Number.isFinite(n))) {
+        fail(`${flag} takes three numbers, e.g. ${flag} 0,20,20`);
+    }
+    return [parts[0], parts[1], parts[2]];
+}
 program
     .command("screenshot")
-    .description("Capture a PNG of the engine's current view")
+    .description("Capture a PNG of the world - a default overview, or aimed with --at/--rot or --target")
     .argument("[dir]", "a synced folder", ".")
     .option("-o, --out <file>", "output file", "screenshot.png")
+    .option("--at <x,y,z>", "camera position (default: 0,20,20)")
+    .option("--rot <yaw,pitch,roll>", "camera rotation in degrees, yaw first (default: 0,-45,0)")
+    .option("--target <id-or-name>", "frame this object instead of using a camera pose")
+    .option("--distance <meters>", "framing distance for --target (default: from the object's bounds)")
     .action((dir, opts) => run(async () => {
     const { client } = await clientForDir(path.resolve(dir));
-    const png = await client.screenshot();
+    const png = await client.screenshot({
+        at: opts.at ? triple(opts.at, "--at") : undefined,
+        rot: opts.rot ? triple(opts.rot, "--rot") : undefined,
+        target: opts.target,
+        distance: opts.distance === undefined ? undefined : Number(opts.distance),
+    });
     fs.writeFileSync(opts.out, png);
     console.log(`Wrote ${opts.out} (${png.length} bytes).`);
 }));
@@ -253,6 +289,9 @@ async function openNative(framingId, url, force = false) {
         console.log("Signed the native client in with your account.");
     launchClient(installed, url);
     console.log(`Opening ${url} in the Virtual Matter client (${installed.dir}).`);
+    if (installed.platform === "linux") {
+        console.log("Linux: the client starts through run.sh with its bundled libraries. If no window appears, read the newest file in ~/.local/share/Atomontage/Atomontage Studio/UserData/Logs/ - \"Failed to initialize graphics adapter\" means this build has no renderer for your setup yet; the world still runs in the browser at the URL above, and every CLI command works without the client.");
+    }
 }
 program
     .command("open")
@@ -293,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;
+}