@volter/world 2.0.0 → 2.0.2

package/dist/src/mcp.js

@@ -0,0 +1,203 @@
+// `volter mcp` (docs/contributing/architecture.md, "The way in is the app's folder"): an MCP server over stdio whose tools
+// are the `volter` command's own verbs. A tool that reads (status, log, diff, branches) asks the SDK; a tool that acts runs
+// the command itself, as a child, so there is one implementation of each verb and an agent gets what a person would.
+// Locally a World is reached with its own token (the command finds it); the platform with the person's token from
+// `volter login`, which only the person can approve, in their browser.
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { World } from "./world.js";
+import { agentPrompt } from "./agent-prompt.js";
+/** This command's own entry, beside this module (src/cli.ts in a checkout, dist/src/cli.js when published). */
+const CLI = fileURLToPath(new URL(`./cli${import.meta.url.endsWith('.ts') ? '.ts' : '.js'}`, import.meta.url));
+const MAX_OUTPUT = 20_000;
+/** Run `volter <args>` in `dir` to its end (or its timeout), its stdout and stderr together, the tail kept. */
+function volter(args, dir, timeoutSeconds = 600) {
+    return new Promise((done) => {
+        const child = spawn(process.execPath, [CLI, ...args], { cwd: dir, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+        let output = '';
+        const take = (d) => { output += d.toString(); if (output.length > MAX_OUTPUT * 2)
+            output = output.slice(-MAX_OUTPUT); };
+        child.stdout.on('data', take);
+        child.stderr.on('data', take);
+        const timer = setTimeout(() => { output += `\n(stopped after ${timeoutSeconds}s)`; child.kill(); }, timeoutSeconds * 1000);
+        child.on('error', (e) => { clearTimeout(timer); done({ code: 1, output: `${output}${e.message}` }); });
+        child.on('close', (code) => { clearTimeout(timer); done({ code: code ?? 1, output: output.length > MAX_OUTPUT ? `…${output.slice(-MAX_OUTPUT)}` : output }); });
+    });
+}
+/** A command that keeps running (the World's view, a sign-in waiting for approval): started once, answered as soon as
+ *  its first lines say what the agent needs, left running for as long as this server runs. */
+const background = new Map();
+function startBackground(key, args, dir, ready, seconds = 60) {
+    background.get(key)?.kill();
+    background.delete(key);
+    return new Promise((done) => {
+        const child = spawn(process.execPath, [CLI, ...args], { cwd: dir, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+        background.set(key, child);
+        let output = '';
+        let answered = false;
+        const answer = (code) => { if (!answered) {
+            answered = true;
+            clearTimeout(timer);
+            done({ code, output });
+        } };
+        const take = (d) => { output += d.toString(); if (ready.test(output))
+            answer(0); };
+        child.stdout.on('data', take);
+        child.stderr.on('data', take);
+        child.on('error', (e) => { output += e.message; answer(1); });
+        child.on('close', (code) => { background.delete(key); answer(code ?? 1); });
+        const timer = setTimeout(() => answer(0), seconds * 1000);
+    });
+}
+/** Everything this server left running, ended: a World under a dashboard is brought down through its own command first
+ *  (its state kept, its teardown recorded), then the command itself. */
+function stopAll() {
+    for (const [key, child] of background) {
+        if (key.startsWith('view:'))
+            spawnSync(process.execPath, [CLI, 'world', 'down'], { cwd: key.slice('view:'.length), windowsHide: true, stdio: 'ignore', timeout: 60_000 });
+        child.kill();
+    }
+    background.clear();
+}
+for (const signal of ['SIGINT', 'SIGTERM'])
+    process.on(signal, () => { stopAll(); process.exit(0); });
+process.on('exit', stopAll);
+const text = (s, isError = false) => ({ content: [{ type: 'text', text: s.trim() || '(no output)' }], ...(isError ? { isError: true } : {}) });
+const ran = (r) => text(r.output, r.code !== 0);
+const asJson = (v) => text(JSON.stringify(v, null, 2));
+const fail = (e) => text(e instanceof Error ? e.message : String(e), true);
+const INSTRUCTIONS = `Volter World runs an app against twins of the SaaS APIs it calls (Stripe, Slack, GitHub, OpenAI and about a hundred more): the app keeps its real SDKs and code, and every write lands in a World that can be branched, reset and looked at on each vendor's own screens.
+
+Work in the app's folder (each tool takes "dir", defaulting to where this server was started).
+- Set up: world_init detects the vendors from the app's manifests and env names; show the person the list before keeping it. Then world_up.
+- Run the app or its tests inside the World with world_run (never bare against the real vendors).
+- Look: world_log and world_diff say what the app changed at each vendor; world_view starts the dashboard and returns its link for the person.
+- Branch and reset like a database: world_branch, world_checkout, world_reset.
+- Share with a team: platform_login returns a link and a code the PERSON must approve in their browser (you cannot approve it); after they do, remote_link links this World to <org>/<world> on the platform (create: true makes it there from this World's vendors); world_changeset cuts the changes with a message, and world_push sends them.
+The guide: https://github.com/volter-ai/twin/blob/main/docs/guides/use-with-a-coding-agent.md`;
+export async function serveMcp(version) {
+    const server = new McpServer({ name: 'volter', title: 'Volter World', version }, { instructions: INSTRUCTIONS });
+    const here = (dir) => resolve(dir ?? process.cwd());
+    const dirArg = { dir: z.string().optional().describe("The app's folder (the World's root). Defaults to where this server was started.") };
+    server.registerTool('world_status', {
+        title: 'World status', description: 'The World of the app folder: its branch, whether it is running, each twin\'s URL, its origin (the remote it pushes to) and unpushed changes.',
+        inputSchema: dirArg, annotations: { readOnlyHint: true },
+    }, async ({ dir }) => { try {
+        return asJson(World.open({ root: here(dir) }).status());
+    }
+    catch (e) {
+        return fail(e);
+    } });
+    server.registerTool('world_init', {
+        title: 'Set up a World for the app', description: "Detect the vendors the app calls (from its package manifests and env var names), install their twins when none are installed yet, and write .volter/world.json beside the code. Show the person the detected vendors; pass allowUnknown to keep going when some have no twin yet.",
+        inputSchema: { ...dirArg, name: z.string().optional().describe('The World\'s name (defaults to the folder\'s).'), allowUnknown: z.boolean().optional(), force: z.boolean().optional().describe('Overwrite an existing .volter/world.json.') },
+    }, async ({ dir, name, allowUnknown, force }) => ran(await volter(['world', 'init', '--install', ...(name ? ['--name', name] : []), ...(allowUnknown ? ['--allow-unknown'] : []), ...(force ? ['--force'] : [])], here(dir))));
+    server.registerTool('world_up', {
+        title: 'Start the World', description: 'Start the twins on the current branch. A fresh branch loads its default data (the story); a stopped one resumes where it was.',
+        inputSchema: { ...dirArg, seed: z.boolean().optional().describe('Load the default data on a fresh branch (default true).') },
+    }, async ({ dir, seed }) => ran(await volter(['world', 'up', ...(seed === false ? ['--no-seed'] : [])], here(dir))));
+    server.registerTool('world_run', {
+        title: 'Run a command in the World', description: "Run the app or its tests inside the World: the vendors' hosts go to their twins, so the real SDKs work unchanged. Returns the command's exit code and the tail of its output.",
+        inputSchema: { ...dirArg, command: z.array(z.string()).min(1).describe('The command and its arguments, e.g. ["npm", "test"].'), timeoutSeconds: z.number().int().positive().max(3600).optional() },
+    }, async ({ dir, command, timeoutSeconds }) => { const r = await volter(['world', 'run', '--', ...command], here(dir), timeoutSeconds ?? 600); return text(`exit ${r.code}\n${r.output}`, r.code !== 0); });
+    server.registerTool('world_down', {
+        title: 'Stop the World', description: 'Stop the twins. Their state is kept for the next world_up unless purge is true.',
+        inputSchema: { ...dirArg, purge: z.boolean().optional() }, annotations: { destructiveHint: true },
+    }, async ({ dir, purge }) => ran(await volter(['world', 'down', ...(purge ? ['--purge'] : [])], here(dir))));
+    server.registerTool('world_view', {
+        title: 'Open the dashboard', description: "Run the World with its dashboard on this machine (each vendor's own screens, the calls, the changes, the branches) and return its link for the person. The dashboard runs the World itself: a World already started with world_up is stopped first (its state is kept) and comes back under the dashboard. It keeps running while this server does; world_run works against it meanwhile.",
+        inputSchema: dirArg,
+    }, async ({ dir }) => {
+        const root = here(dir);
+        let before = '';
+        try {
+            const s = World.open({ root }).status();
+            if (s.running && !s.served) {
+                const down = await volter(['world', 'down'], root);
+                if (down.code !== 0)
+                    return ran(down);
+                before = `${down.output.trim()} (state kept; the dashboard runs it now)\n`;
+            }
+        }
+        catch (e) {
+            return fail(e);
+        }
+        const r = await startBackground(`view:${root}`, ['world', 'view', '--no-open'], root, /console\s+\S+/);
+        return text(`${before}${r.output}`, r.code !== 0);
+    });
+    server.registerTool('world_log', {
+        title: 'What the app changed', description: 'Every write the app made in this World, newest last: vendor, operation and subject.',
+        inputSchema: { ...dirArg, limit: z.number().int().positive().max(1000).optional().describe('The newest this many (default 50).') }, annotations: { readOnlyHint: true },
+    }, async ({ dir, limit }) => { try {
+        const rows = World.open({ root: here(dir) }).log();
+        return asJson(rows.slice(-(limit ?? 50)).map((r) => ({ vendor: r.service, operation: r.operation ?? r.op, subject: r.subject, ...(r.receipt ? { receipt: r.receipt } : {}) })));
+    }
+    catch (e) {
+        return fail(e);
+    } });
+    server.registerTool('world_diff', {
+        title: 'Changes since the default data', description: 'How many changes each vendor has since the default data (or the last mark).',
+        inputSchema: dirArg, annotations: { readOnlyHint: true },
+    }, async ({ dir }) => { try {
+        const d = World.open({ root: here(dir) }).diff();
+        return asJson({ base: d.base, vendors: d.vendors });
+    }
+    catch (e) {
+        return fail(e);
+    } });
+    server.registerTool('world_branch', {
+        title: 'List or make branches', description: 'Without a name, the branches (the checked-out one first). With a name, make a branch from here and check it out, like a database branch: try something, then check out the old one or reset.',
+        inputSchema: { ...dirArg, name: z.string().optional() },
+    }, async ({ dir, name }) => {
+        if (name)
+            return ran(await volter(['world', 'branch', name], here(dir)));
+        try {
+            const w = World.open({ root: here(dir) });
+            return asJson({ current: w.name, branches: w.branches() });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool('world_checkout', {
+        title: 'Switch branch', description: 'Check out another branch of the World.',
+        inputSchema: { ...dirArg, name: z.string() },
+    }, async ({ dir, name }) => ran(await volter(['world', 'checkout', name], here(dir))));
+    server.registerTool('world_reset', {
+        title: 'Back to the default data', description: "Discard the current branch's changes and load its default data again.",
+        inputSchema: dirArg, annotations: { destructiveHint: true },
+    }, async ({ dir }) => ran(await volter(['world', 'reset'], here(dir))));
+    server.registerTool('platform_login', {
+        title: 'Sign in to a platform', description: 'Start signing this machine\'s `volter` command in to a Volter World platform. Returns a link and a code: give both to the PERSON, who approves it in their browser (you cannot). The sign-in completes by itself once they do; check with platform_whoami.',
+        inputSchema: { url: z.string().url().describe("The platform's address (https://…), as the person gave it") },
+    }, async ({ url }) => ran(await startBackground('login', ['login', url, '--no-open'], process.cwd(), /code\s+[A-Z]{4}-[A-Z]{4}/, 30)));
+    server.registerTool('platform_whoami', {
+        title: 'Who the command is signed in as', description: 'The platform this machine\'s `volter` command is signed in to, as whom, and their orgs.',
+        inputSchema: {}, annotations: { readOnlyHint: true },
+    }, async () => ran(await volter(['whoami'], process.cwd())));
+    server.registerTool('remote_link', {
+        title: 'Link the World to the platform', description: "Link this World to <org>/<world> on the platform the command is signed in to, as the remote it pushes to. create: true makes that World on the platform from this World's vendors when it does not exist.",
+        inputSchema: { ...dirArg, target: z.string().regex(/^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/).describe('<org>/<world>'), name: z.string().optional().describe('The remote\'s name (default origin).'), create: z.boolean().optional() },
+    }, async ({ dir, target, name, create }) => ran(await volter(['remote', 'add', name ?? 'origin', target, ...(create ? ['--create'] : [])], here(dir))));
+    server.registerTool('world_changeset', {
+        title: 'Cut a changeset', description: "Cut the World's unpushed changes into a reviewable changeset, with a message saying what and why; world_push sends it.",
+        inputSchema: { ...dirArg, message: z.string().min(1).describe('What the changes are and why.'), name: z.string().optional() },
+    }, async ({ dir, message, name }) => ran(await volter(['world', 'changeset', ...(name ? [name] : []), '-m', message], here(dir))));
+    server.registerTool('world_push', {
+        title: 'Push to the remote', description: "Send this World's unpushed changes to its remote (the platform's World after remote_link); the remote answers with a receipt for each change.",
+        inputSchema: { ...dirArg, changeset: z.string().optional().describe('Push one changeset by name; default all unpushed.') },
+    }, async ({ dir, changeset }) => ran(await volter(['world', 'push', ...(changeset ? [changeset] : [])], here(dir))));
+    server.registerPrompt('get-started', {
+        title: 'Set up Volter World for this app', description: 'Walks through setting up a World for the app in this folder, running its tests in it, and optionally sharing it on a platform.',
+        argsSchema: { platform: z.string().optional().describe("A platform to share the World on: its address"), world: z.string().optional().describe('<org>/<world> on that platform') },
+    }, ({ platform, world }) => ({ messages: [{ role: 'user', content: { type: 'text', text: agentPrompt({ ...(platform ? { platform } : {}), ...(world ? { world } : {}), tools: true }) } }] }));
+    // the client closing the connection (its stdin ends) ends this server, and the commands it left running with it
+    const stop = () => { stopAll(); process.exit(0); };
+    server.server.onclose = stop;
+    process.stdin.on('end', stop);
+    await server.connect(new StdioServerTransport());
+}

package/dist/src/update-notice.d.ts

@@ -0,0 +1,7 @@
+/** This package's version, read from its own package.json. */
+export declare function currentVersion(): string;
+/** Whether `a` is a newer release than `b` (major.minor.patch; a prerelease is not offered). */
+export declare function newer(a: string, b: string): boolean;
+/** Start the day's check if one is due, while the command runs; the returned function, called when the command is
+ *  done, waits a moment at most for it and prints the notice when there is one. Off, it does nothing and asks nothing. */
+export declare function startUpdateCheck(args: string[], env?: NodeJS.ProcessEnv): () => Promise<void>;

package/dist/src/update-notice.js

@@ -0,0 +1,60 @@
+// The update notice (docs/contributing/architecture.md, "The way in is the app's folder"): at most once a day the command
+// asks the npm registry for @volter/world's latest version, while it does its own work, and says in one line on stderr
+// when a newer one exists. Never in CI, never for --json, never when the person opted out (VOLTER_NO_UPDATE_NOTIFIER=1):
+// then nothing is asked at all. The answer is kept beside the credentials, so a day's commands ask once.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { credentialsPath } from "./credentials.js";
+const DAY = 86_400_000;
+const REGISTRY = 'https://registry.npmjs.org/@volter/world/latest';
+/** This package's version, read from its own package.json. */
+export function currentVersion() {
+    try {
+        return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/** Whether `a` is a newer release than `b` (major.minor.patch; a prerelease is not offered). */
+export function newer(a, b) {
+    const parse = (v) => (/^\d+\.\d+\.\d+$/.test(v) ? v.split('.').map(Number) : null);
+    const x = parse(a);
+    const y = parse(b);
+    if (!x || !y)
+        return false;
+    for (let i = 0; i < 3; i++)
+        if (x[i] !== y[i])
+            return x[i] > y[i];
+    return false;
+}
+/** Start the day's check if one is due, while the command runs; the returned function, called when the command is
+ *  done, waits a moment at most for it and prints the notice when there is one. Off, it does nothing and asks nothing. */
+export function startUpdateCheck(args, env = process.env) {
+    if (env.VOLTER_NO_UPDATE_NOTIFIER || env.CI || args.includes('--json') || !process.stderr.isTTY)
+        return async () => undefined;
+    const path = join(dirname(credentialsPath()), 'update-check.json');
+    let kept = null;
+    try {
+        if (existsSync(path))
+            kept = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        kept = null;
+    }
+    const due = !kept || Date.now() - Date.parse(kept.checkedAt) > DAY;
+    const check = due
+        ? fetch(REGISTRY, { signal: AbortSignal.timeout(1500) }).then(async (r) => (r.ok ? (await r.json()).version ?? null : null)).catch(() => null)
+            .then((latest) => { try {
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, `${JSON.stringify({ checkedAt: new Date().toISOString(), latest })}\n`);
+        }
+        catch { /* a read-only home only loses the cache */ } return latest; })
+        : Promise.resolve(kept?.latest ?? null);
+    return async () => {
+        const latest = await Promise.race([check, new Promise((r) => setTimeout(() => r(null), 800))]);
+        const here = currentVersion();
+        if (latest && newer(latest, here))
+            process.stderr.write(`\nvolter ${latest} is out (you have ${here}): npm install -g @volter/world\n`);
+    };
+}

package/dist/src/world.d.ts

@@ -1,13 +1,11 @@
 import { rebaseChangeset, worldBootMarker, type Changeset, type LedgerDelta, type TwinAction, type WorldMarker, type ApplyReceipt, applyTwinWrite, type TwinResource } from '@volter/world-core';
-import { approveWorldChangeset, createWorldChangeset, downWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, seedWorld, statusWorldChangeset, verifyWorldChangeset, type ServedWorld, type DeployTwinOutcome, type ChangesetLocation, type InitOptions, type InitResult, type WorldInstance } from '@volter/world-runtime';
+import { approveWorldChangeset, createWorldChangeset, downWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, seedWorld, statusWorldChangeset, verifyWorldChangeset, type ServedWorld, type ViewConsole, type WorldView, type DeployTwinOutcome, type ChangesetLocation, type InitOptions, type InitResult, type WorldInstance } from '@volter/world-runtime';
 import { rebaseBranch, type Receipt, type RootConfig } from '@volter/world-core';
 export type WorldRef = {
     name?: string;
     root?: string;
 };
 export type WorldMode = 'local' | 'share' | 'sealed';
-/** One change as `log` shows it: the write, and the receipt the vendor answered with once pushed. */
-/** A twin's branch log as the world reads it: the twin's name, the state service it records under, its control root. */
 export declare class TwinLog {
     readonly service: string;
     readonly stateService: string;
@@ -164,15 +162,23 @@ export declare class World {
     isMain(): boolean;
     /** What this branch's changes are measured from, as `diff` says it: the branch point, origin, or the story. */
     diffBase(): string;
-    /** The world's clock: the frozen instant every twin stamps from, or the wall clock when unset. */
+    /** The world's clock (world-clock.cjs): its time now, and whether it is frozen at an instant, running (moved with
+     *  `shiftClock`), or the wall clock (unset). */
     clock(): {
         at: string;
         frozen: boolean;
+        running: boolean;
     };
-    /** Set the world's clock to an instant; every twin stamps from it until it moves. */
+    /** Set the world's clock to an instant; every twin, and the World's application, stamps from it until it moves. */
     setClock(iso: string): string;
-    /** Move a set clock forward: `30d`, `12h`, `5m`, `90s`. */
+    /** Move a set clock forward, frozen or running: `30d`, `12h`, `5m`, `90s`. */
     advanceClock(by: string): string;
+    /** Move the World forward while its time keeps running (a World serving an application): from the wall clock, or a
+     *  running clock further. */
+    shiftClock(by: string): string;
+    /** Return the World to the machine's time. */
+    clearClock(): string;
+    private writeClock;
     /** Rebase this branch onto its base's current position, every twin; conflicts named per subject and field. */
     rebaseBranch(): Array<{
         service: string;
@@ -192,6 +198,16 @@ export declare class World {
             console: string | null;
         }) => void;
     }): Promise<ServedWorld>;
+    /** `volter world view`: this World, its mirrors, its branches and the console on one origin (docs/contributing/architecture.md, "Viewing a World"). */
+    view(opts?: {
+        port?: number;
+        host?: string;
+        console?: ViewConsole;
+        announce?: (line: string) => void;
+        origins?: boolean;
+    }): Promise<WorldView>;
+    /** The vendors this world has a twin of, as world.json names them (a twin service's package, else its id). */
+    vendors(): string[];
     /** The remotes named in world.json (`volter remote add`), name → url or path. */
     remotes(): Record<string, string>;
     /** Name a remote; `origin` is the one fetch and push use by default. A token given is remembered for it. */

package/dist/src/world.js

@@ -4,14 +4,22 @@
 // user reads. The `volter` command is one client of this class and adds nothing.
 import { rebaseChangeset, worldBootMarker, listActions, isTwinBookkeeping, pushablePendingActions, pendingActions, applyTwinWrite, twinResources } from '@volter/world-core';
 import { spawnSync } from 'node:child_process';
-import { activateScript, approveWorldChangeset, branchWorld, clockFile, checkoutWorld, createWorldChangeset, diffWorld, downWorld, fetchFromOrigin, findWorldChangeset, initWorld, listWorldChangesets, listWorldMarks, listWorlds, markWorld, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, runWithWorldEnv, seedWorld, shellWorld, statusWorld, statusWorldChangeset, upWorld, verifyWorldChangeset, worldLedgers, worldOrigin, deployWorld, loadWorldConfig, writeWorldConfig, readServeRecord, refreshTwin, serveWorld, findInstalledPackage, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, credentialPayloadFrom, materializeRoots } from '@volter/world-runtime';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import clockForm from '@volter/world-core/world-clock';
+import { activateScript, approveWorldChangeset, branchWorld, clockFile, checkoutWorld, createWorldChangeset, diffWorld, downWorld, fetchFromOrigin, findWorldChangeset, initWorld, listWorldChangesets, listWorldMarks, listWorlds, markWorld, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, runWithWorldEnv, seedWorld, shellWorld, statusWorld, statusWorldChangeset, upWorld, verifyWorldChangeset, worldLedgers, worldOrigin, deployWorld, loadWorldConfig, writeWorldConfig, readServeRecord, refreshTwin, serveWorld, serveWorldView, findInstalledPackage, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, credentialPayloadFrom, materializeRoots } from '@volter/world-runtime';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { requireToken, storeToken } from "./credentials.js";
 import { currentBranch, findWorldRoot, mainBranch, requireWorldRoot, setCurrentBranch, worldConfigRelative, worldEnvPath, worldSeedPath } from "./locate.js";
 import { parentEntries, rebaseBranch } from '@volter/world-core';
 /** One change as `log` shows it: the write, and the receipt the vendor answered with once pushed. */
 /** A twin's branch log as the world reads it: the twin's name, the state service it records under, its control root. */
+/** `30d`, `12h`, `5m`, `90s` in ms. */
+function durationMs(by) {
+    const m = /^(\d+(?:\.\d+)?)(s|m|h|d)$/.exec(by.trim());
+    if (!m)
+        throw new Error(`${JSON.stringify(by)} is not <N>(s|m|h|d)`);
+    return Number(m[1]) * { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+}
 export class TwinLog {
     service;
     stateService;
@@ -86,7 +94,7 @@ export class World {
         if (opts.install !== false && !twins.every((t) => findInstalledPackage(dir, `@volter/twin-${t}`))) {
             // the runtime's own installer: bun under Bun, npm under Node — never assumed
             const cmd = typeof Bun !== 'undefined' ? ['bun', 'add', '-d'] : ['npm', 'install', '--save-dev'];
-            const r = spawnSync(cmd[0], [...cmd.slice(1), ...twins.map((t) => `@volter/twin-${t}`)], { cwd: dir, stdio: 'inherit' });
+            const r = spawnSync(cmd[0], [...cmd.slice(1), ...twins.map((t) => `@volter/twin-${t}`)], { windowsHide: true, cwd: dir, stdio: 'inherit' });
             if (r.status !== 0)
                 throw new Error(`installing the twins failed (${cmd.join(' ')} exited ${r.status})`);
         }
@@ -248,9 +256,19 @@ export class World {
     async branch(name, opts = {}) {
         if (listWorlds(this.root).some((w) => w.name === name))
             throw new Error(`A branch "${name}" already exists — \`volter world checkout ${name}\` switches to it`);
-        await branchWorld(this.name, name, { root: this.root, envFile: worldEnvPath(this.root), ...(opts.at ? { at: opts.at } : {}) });
-        if (this.instance()?.running)
+        // this branch stops first (a managed database is copied from a stopped World, and the two would share its port),
+        // and comes back if the new one fails
+        const wasRunning = !!this.instance()?.running;
+        if (wasRunning)
             await downWorld(this.name, this.root);
+        try {
+            await branchWorld(this.name, name, { root: this.root, envFile: worldEnvPath(this.root), ...(opts.at ? { at: opts.at } : {}) });
+        }
+        catch (error) {
+            if (wasRunning)
+                await checkoutWorld(this.name, { root: this.root });
+            throw error;
+        }
         setCurrentBranch(this.root, name);
         return new World(name, this.root);
     }
@@ -283,31 +301,54 @@ export class World {
         return existsSync(worldSeedPath(this.root)) ? 'the story' : 'the default data';
     }
     // ── the clock ───────────────────────────────────────────────────────────────────────────
-    /** The world's clock: the frozen instant every twin stamps from, or the wall clock when unset. */
+    /** The world's clock (world-clock.cjs): its time now, and whether it is frozen at an instant, running (moved with
+     *  `shiftClock`), or the wall clock (unset). */
     clock() {
         const file = clockFile(this.root, this.name);
-        return existsSync(file) ? { at: readFileSync(file, 'utf8').trim(), frozen: true } : { at: new Date().toISOString(), frozen: false };
+        if (!existsSync(file))
+            return { at: new Date().toISOString(), frozen: false, running: false };
+        const c = clockForm.parseClock(readFileSync(file, 'utf8'));
+        return { at: new Date(clockForm.clockNowMs(c, Date.now())).toISOString(), frozen: c.kind === 'frozen', running: c.kind === 'running' };
     }
-    /** Set the world's clock to an instant; every twin stamps from it until it moves. */
+    /** Set the world's clock to an instant; every twin, and the World's application, stamps from it until it moves. */
     setClock(iso) {
         const parsed = Date.parse(iso);
         if (Number.isNaN(parsed))
             throw new Error(`${JSON.stringify(iso)} is not an ISO-8601 instant`);
-        const file = clockFile(this.root, this.name);
-        mkdirSync(dirname(file), { recursive: true });
-        writeFileSync(file, `${new Date(parsed).toISOString()}\n`);
+        this.writeClock({ kind: 'frozen', at: parsed });
         return new Date(parsed).toISOString();
     }
-    /** Move a set clock forward: `30d`, `12h`, `5m`, `90s`. */
+    /** Move a set clock forward, frozen or running: `30d`, `12h`, `5m`, `90s`. */
     advanceClock(by) {
-        const m = /^(\d+(?:\.\d+)?)(s|m|h|d)$/.exec(by.trim());
-        if (!m)
-            throw new Error(`${JSON.stringify(by)} is not <N>(s|m|h|d)`);
-        const current = this.clock();
-        if (!current.frozen)
-            throw new Error('the clock is not set — `volter world clock set <iso>` first; advancing the wall clock would freeze time as a side effect');
-        const ms = Number(m[1]) * { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
-        return this.setClock(new Date(Date.parse(current.at) + ms).toISOString());
+        const file = clockFile(this.root, this.name);
+        if (!existsSync(file))
+            throw new Error('the clock is not set — `volter world clock set <iso>` first; advancing the wall clock would freeze time as a side effect (`volter world clock shift` moves a running World)');
+        const c = clockForm.parseClock(readFileSync(file, 'utf8'));
+        this.writeClock({ ...c, at: c.at + durationMs(by) });
+        return this.clock().at;
+    }
+    /** Move the World forward while its time keeps running (a World serving an application): from the wall clock, or a
+     *  running clock further. */
+    shiftClock(by) {
+        const file = clockFile(this.root, this.name);
+        const c = existsSync(file) ? clockForm.parseClock(readFileSync(file, 'utf8')) : null;
+        if (c?.kind === 'frozen')
+            throw new Error('the clock is frozen — `volter world clock advance` moves it');
+        const wall = Date.now();
+        this.writeClock(c ? { ...c, at: c.at + durationMs(by) } : { kind: 'running', at: wall + durationMs(by), since: wall });
+        return this.clock().at;
+    }
+    /** Return the World to the machine's time. */
+    clearClock() {
+        const file = clockFile(this.root, this.name);
+        if (existsSync(file))
+            rmSync(file);
+        return new Date().toISOString();
+    }
+    writeClock(c) {
+        const file = clockFile(this.root, this.name);
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, `${clockForm.formatClock(c)}\n`);
     }
     /** Rebase this branch onto its base's current position, every twin; conflicts named per subject and field. */
     rebaseBranch() { return this.repos().map((r) => ({ service: r.service, ...rebaseBranch(r.stateService, r.root) })); }
@@ -316,7 +357,14 @@ export class World {
     // ── serving ─────────────────────────────────────────────────────────────────────────────
     /** Serve this world on a port under `/<org>/<world>/`; returns when listening. */
     serve(opts = {}) { return serveWorld(this.name, { root: this.root, ...opts }); }
+    /** `volter world view`: this World, its mirrors, its branches and the console on one origin (docs/contributing/architecture.md, "Viewing a World"). */
+    view(opts = {}) { return serveWorldView(this.name, { root: this.root, ...opts }); }
     // ── remotes ─────────────────────────────────────────────────────────────────────────────
+    /** The vendors this world has a twin of, as world.json names them (a twin service's package, else its id). */
+    vendors() {
+        const { config } = loadWorldConfig(this.configRef(), this.root);
+        return [...new Set(config.services.filter((s) => (s.type ?? 'twin') === 'twin').map((s) => /^@volter\/twin-(.+)$/.exec(s.package ?? '')?.[1] ?? s.id))].sort();
+    }
     /** The remotes named in world.json (`volter remote add`), name → url or path. */
     remotes() { return { ...(loadWorldConfig(this.configRef(), this.root).config.remotes ?? {}) }; }
     /** Name a remote; `origin` is the one fetch and push use by default. A token given is remembered for it. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Run your app against a world of twins. `World` and `Repo` — one method per verb: init, up, run, log, diff, reset, branch, checkout, clone, fetch, changeset, push — and the `volter` command, one client of them.",
   "keywords": [
     "volter",
@@ -13,6 +13,11 @@
   ],
   "author": "Volter (https://github.com/volter-ai)",
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/cli"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -20,18 +25,32 @@
   "main": "dist/src/index.js",
   "files": [
     "src",
-    "dist"
+    "dist",
+    "skills"
   ],
   "dependencies": {
-    "@volter/world-core": "2.0.0",
-    "@volter/world-runtime": "2.0.0"
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "@volter/world-core": "2.0.2",
+    "@volter/world-runtime": "2.0.2",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "@volter/world-console": "2.0.2"
+  },
+  "peerDependenciesMeta": {
+    "@volter/world-console": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@volter/world-console": "2.0.2"
   },
   "bin": {
     "volter": "dist/src/cli.js"
   },
   "scripts": {
     "build": "node ../../scripts/publish/build.mjs",
-    "prepack": "node ../../scripts/publish/prepare-publish.mjs prepack",
-    "postpack": "node ../../scripts/publish/prepare-publish.mjs postpack"
+    "prepack": "node ./scripts/ship-skill.mjs in && node ../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../scripts/publish/prepare-publish.mjs postpack && node ./scripts/ship-skill.mjs out"
   }
 }