virtualmatter 0.2.0 → 0.4.0

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
@@ -12,7 +14,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { createProject, defaultRegion, editUrl, listProjects, playUrl, resolveSession, sessionBaseUrl, } from "./api.js";
+import { createProject, createWebsiteBuild, getWebsiteBuild, getEmbed, defaultRegion, editUrl, listProjects, playUrl, resolveSession, sessionBaseUrl, } from "./api.js";
 import { ensureClientInstalled, launchClient, seedNativeAuth } from "./client.js";
 import { packageVersion } from "./config.js";
 import { ConflictError, FilesClient } from "./files.js";
@@ -97,6 +99,23 @@ 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() },
+    }, async ({ target }) => textResult(JSON.stringify(await getEmbed(target))));
+    server.registerTool("get_build_status", {
+        description: "Check a VM build by build_id. Do not create another project to check progress. Review the world and enable sharing before embedding.",
+        inputSchema: { build_id: z.string() },
+    }, async ({ build_id }) => textResult(JSON.stringify(await getWebsiteBuild(build_id))));
     server.registerTool("list_projects", {
         description: "List the signed-in maker's Virtual Matter projects (worlds): name, id, region, the editing framing id, and edit/play URLs. Call this to find a world to work in, then select_project.",
         inputSchema: {},
@@ -105,6 +124,8 @@ export async function runMcpServer(dir, framingFlag) {
         description: "Create a new Virtual Matter world (project) for the signed-in maker and select it for this session. The world spins up live on Virtual Matter servers; its content is SDK Lua plus assets that hot-reload as you write them. Region defaults to the one nearest this machine.",
         inputSchema: {
             name: z.string().min(1).max(100).describe("Project name, e.g. \"Lava Arena\""),
+            prompt: z.string().min(1).max(16000).optional().describe("Optional build prompt to send to VM's agent, using VM credits. Requires request_id. Starts privately."),
+            request_id: z.string().min(8).max(100).optional().describe("Stable id for a prompted build; reuse unchanged on retries."),
             description: z.string().max(1000).optional().describe("One-line description (optional)"),
             region: z.enum(["NA", "EU", "AS"]).optional().describe("Hosting region (default: nearest)"),
             pull_to: z
@@ -112,7 +133,17 @@ export async function runMcpServer(dir, framingFlag) {
                 .optional()
                 .describe("Local folder to mirror the new world's files into (optional; sync works from there)"),
         },
-    }, async ({ name, description, region, pull_to }) => {
+    }, async ({ name, description, region, pull_to, prompt, request_id }) => {
+        if (prompt) {
+            if (!request_id)
+                throw new Error("A stable request_id is required when sending a build prompt.");
+            if (pull_to || description)
+                throw new Error("Prompted builds run in VM. Omit pull_to/description and use select_project afterwards if local files are needed.");
+            const build = await createWebsiteBuild({ name, prompt, request_id, region: region ?? defaultRegion() });
+            if (build.framing_id)
+                ctx.select(build.framing_id);
+            return textResult(JSON.stringify(build));
+        }
         const project = await createProject({ name, description, region: region ?? defaultRegion() });
         const framingId = makeFramingOf(project);
         ctx.select(framingId, project);
@@ -192,11 +223,30 @@ export async function runMcpServer(dir, framingFlag) {
         return textResult(JSON.stringify(await client.engineErrors(), null, 2));
     });
     server.registerTool("capture_screenshot", {
-        description: "Capture a PNG screenshot of the engine's current view and return it as an image. Use it to visually verify what a change actually looks like in the world.",
-        inputSchema: {},
-    }, async () => {
+        description: "Capture a PNG screenshot of the world and return it as an image - how you SEE what you built. With no arguments it shoots a default overview of the world origin. Pass target to frame one object by name or id (easiest and usually what you want), or a full at + rot camera pose. Use it to visually verify a change instead of assuming it worked.",
+        inputSchema: {
+            target: z
+                .string()
+                .optional()
+                .describe("Object name or id to frame; the engine picks the distance"),
+            at: z
+                .array(z.number())
+                .length(3)
+                .optional()
+                .describe("Camera position [x, y, z]; Y is up and -Z is forward"),
+            rot: z
+                .array(z.number())
+                .length(3)
+                .optional()
+                .describe("Camera rotation in degrees as [yaw, pitch, roll] - that order. Yaw 0 faces -Z; pitch -90 looks straight down, 0 is the horizon. Default [0, -45, 0] looks down at the origin."),
+        },
+    }, async ({ target, at, rot }) => {
         const client = await ctx.getClient();
-        const png = await client.screenshot();
+        const png = await client.screenshot({
+            target,
+            at: at,
+            rot: rot,
+        });
         return {
             content: [
                 { type: "image", data: png.toString("base64"), mimeType: "image/png" },

package/dist/pull.js

@@ -2,7 +2,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { resolveSession, sessionBaseUrl } from "./api.js";
-import { fetchAgentsMd, writeAgentFiles } from "./agentfiles.js";
+import { composeAgentsMd, fetchAgentsMd, writeAgentFiles } from "./agentfiles.js";
 import { FilesClient } from "./files.js";
 import { isIgnoredPath } from "./ignore.js";
 import { saveState } from "./state.js";
@@ -33,6 +33,19 @@ function makeProgress(total) {
         },
     };
 }
+/** The engine SDK's AGENTS.md from the Montage tree, or null when the world has none. */
+export async function fetchEngineAgentsMd(client) {
+    try {
+        const listing = await client.list();
+        if (!listing.some((f) => f.path === "AGENTS.md"))
+            return null;
+        const { bytes } = await client.get("AGENTS.md");
+        return bytes.toString("utf8");
+    }
+    catch {
+        return null;
+    }
+}
 export async function pullTree(client, dir, framingId) {
     fs.mkdirSync(dir, { recursive: true });
     const remote = (await client.list()).filter((f) => !isIgnoredPath(f.path));
@@ -64,6 +77,7 @@ export async function pullCommand(framingId, dir) {
     const client = new FilesClient(sessionBaseUrl(session), framingId);
     console.log(`Session ready at ${sessionBaseUrl(session)}. Downloading files ...`);
     const result = await pullTree(client, dir, framingId);
-    result.agentFiles = writeAgentFiles(dir, await fetchAgentsMd());
+    const [platformDoc, engineDoc] = await Promise.all([fetchAgentsMd(), fetchEngineAgentsMd(client)]);
+    result.agentFiles = writeAgentFiles(dir, composeAgentsMd(platformDoc, engineDoc));
     return result;
 }

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.2.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": {