@gtanczyk/diorama 0.0.0-stage → 0.2.0

package/app/src/studio/events.ts

@@ -0,0 +1,48 @@
+// The live feed: everything the studio, its jobs and the agent do becomes an event with a sequence number.
+// The browser and `diorama mcp` read the same feed, so a change made by either shows up in the other at once.
+
+export type StudioEvent = { seq: number; at: string; type: string; world?: string; [k: string]: unknown };
+type Listener = (e: StudioEvent) => void;
+
+/** Events a page opened mid-build needs to draw the build's progress and its model call counts: a long build's
+ * logs and files push them out of the recent window long before it ends, so they are kept apart (else a refreshed
+ * Studio showed done steps as empty and counted calls from zero). */
+const LASTING = new Set(['job.queued', 'job.start', 'job.end', 'build.start', 'step.start', 'step.end', 'step.fail', 'call']);
+
+export class Events {
+  private seq = 0;
+  private readonly recent: StudioEvent[] = [];
+  private readonly lasting: StudioEvent[] = [];
+  private readonly listeners = new Set<Listener>();
+
+  constructor(private readonly keep = 2000) {}
+
+  publish(type: string, data: Record<string, unknown> = {}): StudioEvent {
+    const event: StudioEvent = { ...data, seq: ++this.seq, at: new Date().toISOString(), type };
+    this.recent.push(event);
+    if (this.recent.length > this.keep) this.recent.splice(0, this.recent.length - this.keep);
+    if (LASTING.has(type)) {
+      this.lasting.push(event);
+      if (this.lasting.length > this.keep * 5) this.lasting.splice(0, this.lasting.length - this.keep * 5);
+    }
+    for (const listener of this.listeners) listener(event);
+    return event;
+  }
+
+  /** Events after `seq` (for a reconnecting client), optionally for one world plus the studio-wide ones. */
+  since(seq: number, world?: string): StudioEvent[] {
+    const oldest = this.recent[0]?.seq ?? Infinity;
+    const kept = this.lasting.filter((e) => e.seq < oldest);
+    return [...kept, ...this.recent].filter((e) => e.seq > seq && (!world || !e.world || e.world === world));
+  }
+
+  /** The sequence number of the latest event. */
+  get last(): number {
+    return this.seq;
+  }
+
+  subscribe(listener: Listener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+}

package/app/src/studio/history.ts

@@ -0,0 +1,124 @@
+// Undo for everything the Studio runs: before a job or an edit touches a world, its files are snapshotted
+// under worlds/<slug>/studio/history/. Files are stored once by content hash, so a snapshot after the
+// first costs only what changed. The memo (model answers) is not part of it: it never changes meaning.
+import { createHash, randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import type { Events } from './events.ts';
+import type { Job } from './jobs.ts';
+
+export type Snapshot = { id: string; at: string; label: string; by: string; files: Record<string, string> };
+type Index = Record<string, { size: number; mtimeMs: number; hash: string }>;
+
+const SKIP = new Set(['memo', 'studio']);
+
+function walk(dir: string, rel = ''): string[] {
+  if (!fs.existsSync(path.join(dir, rel))) return [];
+  return fs.readdirSync(path.join(dir, rel), { withFileTypes: true }).flatMap((d) => {
+    const r = rel ? `${rel}/${d.name}` : d.name;
+    if (!rel && SKIP.has(d.name)) return [];
+    if (d.isDirectory()) return walk(dir, r);
+    return d.isFile() && !d.name.endsWith('.tmp') ? [r] : [];
+  });
+}
+
+export class History {
+  readonly home: string;
+
+  constructor(readonly dir: string) {
+    this.home = path.join(dir, 'studio', 'history');
+  }
+
+  private blob(hash: string) {
+    return path.join(this.home, 'blobs', hash.slice(0, 2), hash);
+  }
+
+  /** The world's files right now, by content hash (rehashing only files whose size or mtime moved). */
+  current(): Record<string, string> {
+    const indexFile = path.join(this.home, 'index.json');
+    let index: Index = {};
+    try {
+      index = JSON.parse(fs.readFileSync(indexFile, 'utf8')) as Index;
+    } catch {}
+    const files: Record<string, string> = {};
+    const next: Index = {};
+    for (const rel of walk(this.dir)) {
+      const at = path.join(this.dir, rel);
+      const stat = fs.statSync(at);
+      const known = index[rel];
+      const hash = known && known.size === stat.size && known.mtimeMs === stat.mtimeMs
+        ? known.hash
+        : createHash('sha256').update(fs.readFileSync(at)).digest('hex');
+      if (!fs.existsSync(this.blob(hash))) {
+        fs.mkdirSync(path.dirname(this.blob(hash)), { recursive: true });
+        fs.copyFileSync(at, this.blob(hash), fs.constants.COPYFILE_FICLONE);
+      }
+      files[rel] = hash;
+      next[rel] = { size: stat.size, mtimeMs: stat.mtimeMs, hash };
+    }
+    fs.mkdirSync(this.home, { recursive: true });
+    fs.writeFileSync(indexFile, JSON.stringify(next));
+    return files;
+  }
+
+  list(): Snapshot[] {
+    if (!fs.existsSync(this.home)) return [];
+    return fs.readdirSync(this.home)
+      .filter((f) => /^\d{8}T\d{6}-[0-9a-f]{4}\.json$/.test(f))
+      .map((f) => JSON.parse(fs.readFileSync(path.join(this.home, f), 'utf8')) as Snapshot)
+      // Newest first by time to the millisecond: ids only say the second.
+      .sort((a, b) => b.at.localeCompare(a.at) || b.id.localeCompare(a.id));
+  }
+
+  /** Records the world as it is before `label`. Nothing new when nothing changed since the last snapshot. */
+  snapshot(label: string, by: string): Snapshot {
+    const files = this.current();
+    const last = this.list()[0];
+    const same = last && Object.keys(last.files).length === Object.keys(files).length && Object.entries(files).every(([f, h]) => last.files[f] === h);
+    // Strictly after the last one, so two snapshots in the same millisecond keep their order.
+    const at = new Date(Math.max(Date.now(), last ? Date.parse(last.at) + 1 : 0));
+    const snap: Snapshot = { id: `${at.toISOString().replace(/[-:]/g, '').slice(0, 15)}-${randomBytes(2).toString('hex')}`, at: at.toISOString(), label, by, files };
+    if (same) return last;
+    fs.writeFileSync(path.join(this.home, `${snap.id}.json`), JSON.stringify(snap));
+    return snap;
+  }
+
+  /** Puts the world back as it was in snapshot `id`; what is there now is snapshotted first, so undo can be undone. */
+  restore(id: string, by: string, kind: 'undo' | 'redo' = 'undo'): { restored: string[]; removed: string[]; before: string } {
+    const target = this.list().find((s) => s.id === id);
+    if (!target) throw new Error(`no snapshot ${id}`);
+    const before = this.snapshot(`before ${kind} to ${id}`, by);
+    const restored: string[] = [];
+    const removed: string[] = [];
+    for (const [rel, hash] of Object.entries(target.files)) {
+      if (before.files[rel] === hash) continue;
+      const at = path.join(this.dir, rel);
+      fs.mkdirSync(path.dirname(at), { recursive: true });
+      fs.copyFileSync(this.blob(hash), at);
+      restored.push(rel);
+    }
+    for (const rel of Object.keys(before.files)) {
+      if (target.files[rel]) continue;
+      fs.rmSync(path.join(this.dir, rel), { force: true });
+      removed.push(rel);
+    }
+    return { restored, removed, before: before.id };
+  }
+
+  /** What changed from one snapshot to the next (or to now). */
+  static diff(a: Record<string, string>, b: Record<string, string>): { added: string[]; changed: string[]; removed: string[] } {
+    return {
+      added: Object.keys(b).filter((f) => !(f in a)),
+      changed: Object.keys(b).filter((f) => f in a && a[f] !== b[f]),
+      removed: Object.keys(a).filter((f) => !(f in b)),
+    };
+  }
+}
+
+/** All action entry points snapshot at the same job boundary, including CLI and standalone MCP. */
+export function snapshotBeforeJob(root: string, events: Events): (job: Job) => void {
+  return (job) => {
+    const dir = path.join(root, job.world);
+    if (fs.existsSync(dir)) events.publish('history.snapshot', { world: job.world, id: new History(dir).snapshot(job.label, job.by).id });
+  };
+}

package/app/src/studio/jobs.ts

@@ -0,0 +1,291 @@
+// A job is a diorama command run as a child process, exactly as you would type it. One job per world runs
+// at a time, the rest wait their turn. Output lines and `@@diorama` events go to the live feed, keys redacted.
+import { spawn, type ChildProcess } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { redact } from '../secrets.ts';
+import type { Events } from './events.ts';
+import type { ExtensionProgress } from '../world/extension-progress.ts';
+
+const BIN = fileURLToPath(new URL('../../bin/diorama.mjs', import.meta.url));
+
+export type Job = {
+  id: string;
+  world: string;
+  label: string;
+  args: string[];
+  by: string;
+  state: 'queued' | 'running' | 'done' | 'failed' | 'cancelled';
+  queuedAt: string;
+  startedAt?: string;
+  endedAt?: string;
+  /** The steps running now, joined ("model + verify"): a build runs independent steps side by side. */
+  step?: string;
+  /** Each step running now, in the order it started. */
+  steps?: string[];
+  /** Last confirmed extension milestone, available when a client opens mid-job. */
+  extension?: ExtensionProgress;
+  error?: string;
+  /** Optional stages completed with missing assets; distinct from a failed job. */
+  warnings?: Record<string, string[]>;
+  /** A queued addition reserves its key before its source correction is applied. */
+  addedThing?: { place: string; key: string };
+  /** Places verify found not playable, with why: the reason a build that finished still fails. */
+  unplayable?: Array<{ place: string; errors: string[] }>;
+  /** The last lines it printed. */
+  tail: string[];
+};
+
+type Activity = { at: string; type: string; message?: string; stream?: string; kind?: string; label?: string; outcome?: string; ms?: number; error?: string };
+type Operation = { id: string; kind: string; label: string; startedAt: string };
+type Progress = { completed: number; total: number; failed: number; kept?: number };
+type Diagnostics = { lastActivityAt: string; recent: Activity[]; failures: Activity[]; active: Map<string, Operation>; progress: Record<string, Progress>; operations: Record<string, { started: number; completed: number; failed: number }> };
+
+export class Jobs {
+  private readonly all: Job[] = [];
+  private readonly children = new Map<string, ChildProcess>();
+  private readonly waiters = new Map<string, Array<(job: Job) => void>>();
+  private readonly prepare = new Map<string, () => void>();
+  private readonly diagnostics = new Map<string, Diagnostics>();
+
+  /** echo: also print the job's output (the CLI runs jobs in the foreground). */
+  /** beforeStart runs as a job leaves the queue (the Studio snapshots the world there, for undo). */
+  constructor(private readonly events: Events, private readonly opts: { cwd?: string; echo?: boolean; bin?: string; beforeStart?: (job: Job) => void } = {}) {}
+
+  /** Whether a job for this world is running or waiting. */
+  busy(world: string): Job | undefined {
+    return this.all.find((j) => j.world === world && (j.state === 'running' || j.state === 'queued'));
+  }
+
+  /**
+   * Polish that must never hold up the game: speaking faces. They run only when nothing else for the world is
+   * waiting, and any other job stops a running one (face work is saved as it goes; it resumes on the next run).
+   */
+  static polish(args: readonly string[]): boolean {
+    const at = (flag: string) => (args.includes(flag) ? args[args.indexOf(flag) + 1] : undefined);
+    return args[0] === 'faces' || (args[0] === 'build' && at('--from') === 'faces' && at('--to') === 'faces');
+  }
+
+  start(world: string, args: string[], label: string, by: string, prepare?: () => void, addedThing?: Job['addedThing']): Job {
+    // The same job already waiting or running (a button pressed again, the agent asking twice) is that job:
+    // a second run would only pay for the same model calls again. A pending edit is its own job.
+    const same = prepare ? undefined : this.all.find((j) => j.world === world && (j.state === 'queued' || j.state === 'running') && !this.prepare.has(j.id) && j.args.join('\0') === args.join('\0'));
+    if (same) return same;
+    const job: Job = { id: randomBytes(4).toString('hex'), world, label, args, by, state: 'queued', queuedAt: new Date().toISOString(), tail: [], ...(addedThing && { addedThing }) };
+    this.all.push(job);
+    this.diagnostics.set(job.id, { lastActivityAt: job.queuedAt, recent: [], failures: [], active: new Map(), progress: {}, operations: {} });
+    if (prepare) this.prepare.set(job.id, prepare);
+    this.events.publish('job.queued', { world, job: { ...job } });
+    if (!Jobs.polish(args)) for (const running of this.all.filter((j) => j.world === world && j.state === 'running' && Jobs.polish(j.args))) {
+      running.error = `stopped so "${label}" can run first (speaking faces resume later)`;
+      this.cancel(running.id);
+      this.start(world, running.args, running.label, running.by);
+    }
+    this.next(world);
+    return job;
+  }
+
+  list(world?: string): Job[] {
+    return this.all.filter((j) => !world || j.world === world).map((j) => ({ ...j }));
+  }
+
+  get(id: string): Job | undefined {
+    return this.all.find((j) => j.id === id);
+  }
+
+  /** A bounded, timestamped view of this job, including work in flight in its own process. */
+  inspect(id: string, limit = 40) {
+    const job = this.get(id);
+    const data = this.diagnostics.get(id);
+    if (!job || !data) throw new Error(`no job ${id}`);
+    const now = Date.now();
+    const end = job.endedAt ? Date.parse(job.endedAt) : now;
+    return {
+      id: job.id, world: job.world, label: job.label, state: job.state,
+      startedAt: job.startedAt ?? null, endedAt: job.endedAt ?? null,
+      elapsedSeconds: job.startedAt ? Math.max(0, Math.round((end - Date.parse(job.startedAt)) / 1000)) : 0,
+      lastActivityAt: data.lastActivityAt,
+      quietSeconds: Math.max(0, Math.round((end - Date.parse(data.lastActivityAt)) / 1000)),
+      steps: [...(job.steps ?? [])], extension: job.extension ?? null, error: job.error ?? null,
+      activeOperations: [...data.active.values()].map(op => ({ ...op, elapsedSeconds: Math.max(0, Math.round((end - Date.parse(op.startedAt)) / 1000)) })),
+      operations: { ...data.operations }, progress: { ...data.progress }, recentFailures: data.failures.slice(-20), recent: data.recent.slice(-limit),
+      note: 'Active operations are observed in this process, not proof of the remote service state. Operations may be nested; their counts are not billing. Silence alone does not prove a hang.',
+    };
+  }
+
+  private activity(job: Job, event: Omit<Activity, 'at'>, at = new Date().toISOString()) {
+    const data = this.diagnostics.get(job.id);
+    if (!data) return;
+    data.lastActivityAt = at;
+    const record = { at, ...event };
+    data.recent.push(record);
+    if (event.outcome === 'failed' || event.type === 'step.fail' || event.type === 'place.fail' || event.stream === 'err' || (event.type === 'log' && /^\s*(?:FAIL\b|warning:|.*\bFAILED\b)/i.test(event.message ?? ''))) {
+      data.failures.push(record);
+      if (data.failures.length > 20) data.failures.shift();
+    }
+    if (data.recent.length > 200) data.recent.splice(0, data.recent.length - 200);
+  }
+
+  /** A cancelled queued edit has not changed its source yet; retry keeps that pending edit. */
+  retry(id: string, args: string[], by: string): Job {
+    const job = this.get(id);
+    if (!job) throw new Error(`no job ${id}`);
+    const prepare = this.prepare.get(id);
+    this.prepare.delete(id);
+    return this.start(job.world, args, job.label, by, prepare, job.addedThing);
+  }
+
+  cancel(id: string): Job {
+    const job = this.get(id);
+    if (!job) throw new Error(`no job ${id}`);
+    if (job.state === 'queued') this.finish(job, 'cancelled');
+    else if (job.state === 'running') {
+      job.state = 'cancelled';
+      this.children.get(id)?.kill('SIGTERM');
+    }
+    return { ...job };
+  }
+
+  /** Resolves when the job has ended, however it ended. */
+  wait(id: string, timeoutMs?: number, signal?: AbortSignal): Promise<Job> {
+    const job = this.get(id);
+    if (!job) return Promise.reject(new Error(`no job ${id}`));
+    if (!['queued', 'running'].includes(job.state) || signal?.aborted) return Promise.resolve({ ...job });
+    return new Promise((resolve) => {
+      const done = (j: Job) => {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', early);
+        resolve(j);
+      };
+      // Past the timeout, or when the signal ends the wait, it answers with the job as it stands, still running.
+      const early = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', early);
+        this.waiters.set(id, (this.waiters.get(id) ?? []).filter((w) => w !== done));
+        resolve({ ...job });
+      };
+      const timer = timeoutMs === undefined ? undefined : setTimeout(early, timeoutMs);
+      signal?.addEventListener('abort', early);
+      this.waiters.set(id, [...(this.waiters.get(id) ?? []), done]);
+    });
+  }
+
+  stopAll() {
+    for (const job of this.all) if (job.state === 'queued' || job.state === 'running') this.cancel(job.id);
+  }
+
+  private next(world: string) {
+    if (this.all.some((j) => j.world === world && j.state === 'running')) return;
+    const queued = this.all.filter((j) => j.world === world && j.state === 'queued');
+    const job = queued.find((j) => !Jobs.polish(j.args)) ?? queued[0];
+    if (!job) return;
+    try {
+      this.opts.beforeStart?.(job);
+    } catch (error) {
+      this.finish(job, 'failed', `snapshot failed: ${error instanceof Error ? error.message : error}`);
+      return;
+    }
+    try {
+      this.prepare.get(job.id)?.();
+      this.prepare.delete(job.id);
+    } catch (error) {
+      this.finish(job, 'failed', error instanceof Error ? error.message : String(error));
+      return;
+    }
+    job.state = 'running';
+    job.startedAt = new Date().toISOString();
+    this.activity(job, { type: 'job.start' }, job.startedAt);
+    this.events.publish('job.start', { world, job: { ...job } });
+    const child = spawn(process.execPath, [this.opts.bin ?? BIN, ...job.args], {
+      cwd: this.opts.cwd,
+      env: { ...process.env, DIORAMA_EVENTS: '1', FORCE_COLOR: '0' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    this.children.set(job.id, child);
+    const lines = (stream: 'out' | 'err') => {
+      let rest = '';
+      return (chunk: Buffer) => {
+        const parts = (rest + chunk.toString('utf8')).split('\n');
+        rest = parts.pop() ?? '';
+        for (const line of parts) this.line(job, stream, line);
+      };
+    };
+    child.stdout!.on('data', lines('out'));
+    child.stderr!.on('data', lines('err'));
+    child.on('error', (error) => (job.error = error.message));
+    child.on('close', (code) => {
+      this.children.delete(job.id);
+      if (job.state === 'cancelled') this.finish(job, 'cancelled');
+      else this.finish(job, code === 0 ? 'done' : 'failed', code === 0 ? undefined : job.error ?? (job.unplayable?.length ? `not playable: ${job.unplayable.map((u) => `${u.place} (${u.errors.join('; ') || 'see verify.json'})`).join(', ')}` : `exited with ${code}`));
+    });
+  }
+
+  private line(job: Job, stream: 'out' | 'err', raw: string) {
+    const line = redact(raw);
+    if (line.startsWith('@@diorama ')) {
+      try {
+        const { type, ...data } = JSON.parse(line.slice('@@diorama '.length)) as { type: string } & Record<string, unknown>;
+        const step = (data as { step?: string }).step;
+        const diagnostics = this.diagnostics.get(job.id);
+        const at = new Date().toISOString();
+        if (diagnostics && type === 'operation.start' && typeof data.id === 'string' && typeof data.kind === 'string' && typeof data.label === 'string') {
+          const operation = { id: data.id, kind: data.kind.slice(0, 80), label: data.label.slice(0, 160), startedAt: at };
+          diagnostics.active.set(data.id, operation);
+          (diagnostics.operations[operation.kind] ??= { started: 0, completed: 0, failed: 0 }).started++;
+          this.activity(job, { type, kind: operation.kind, label: operation.label }, at);
+        } else if (diagnostics && type === 'operation.end' && typeof data.id === 'string') {
+          const op = diagnostics.active.get(data.id);
+          diagnostics.active.delete(data.id);
+          if (op) {
+            const count = diagnostics.operations[op.kind];
+            if (data.outcome === 'failed') count.failed++;
+            else count.completed++;
+          }
+          this.activity(job, { type, ...(op && { kind: op.kind, label: op.label }), ...(typeof data.outcome === 'string' && { outcome: data.outcome }), ...(typeof data.ms === 'number' && { ms: data.ms }), ...(typeof data.error === 'string' && { error: data.error.slice(0, 500) }) }, at);
+        } else if (diagnostics && type === 'work.progress' && typeof data.kind === 'string' && typeof data.completed === 'number' && typeof data.total === 'number' && typeof data.failed === 'number') {
+          diagnostics.progress[data.kind] = { completed: data.completed, total: data.total, failed: data.failed, ...(typeof data.kept === 'number' && { kept: data.kept }) };
+          this.activity(job, { type, kind: data.kind, message: `${data.completed}/${data.total}, ${data.failed} failed` }, at);
+        } else if (['step.start', 'step.end', 'step.fail', 'extension.progress', 'place.fail', 'place.verdict', 'repair.start', 'repair.end'].includes(type)) {
+          const failure = (type === 'place.verdict' || type === 'repair.end') && data.ok === false;
+          const reason = typeof data.error === 'string' ? data.error : failure && Array.isArray(data.errors) ? data.errors.join('; ') : undefined;
+          this.activity(job, { type, message: String(step ?? data.phase ?? data.place ?? '').slice(0, 160), ...(failure && { outcome: 'failed' }), ...(reason && { error: reason.slice(0, 500) }) }, at);
+        }
+        if (type === 'extension.progress') {
+          const next = data as ExtensionProgress;
+          job.extension = { ...next, newPlaces: next.newPlaces ?? job.extension?.newPlaces };
+        }
+        if (step && type === 'step.end' && data.status === 'incomplete' && Array.isArray(data.warnings)) (job.warnings ??= {})[step] = data.warnings.filter((v): v is string => typeof v === 'string');
+        if (step && type === 'step.start') job.steps = [...(job.steps ?? []).filter((s) => s !== step), step];
+        if (step && (type === 'step.end' || type === 'step.fail')) job.steps = (job.steps ?? []).filter((s) => s !== step);
+        // A failed step stays shown, so the job says where it broke; a finished one leaves the steps still running.
+        if (step && type === 'step.fail') job.step = step;
+        else if (type === 'step.start' || type === 'step.end') job.step = job.steps?.length ? job.steps.join(' + ') : job.error ? job.step : undefined;
+        if (type === 'step.fail') job.error = String((data as { error?: unknown }).error ?? '');
+        if (type === 'place.verdict') {
+          const v = data as { place: string; ok: boolean; errors?: string[] };
+          if (!v.ok) (job.unplayable ??= []).push({ place: v.place, errors: v.errors ?? [] });
+        }
+        this.events.publish(type, { ...data, world: job.world, job: job.id });
+        return;
+      } catch {}
+    }
+    if (stream === 'err' && line.startsWith('diorama ')) job.error = line;
+    if (line.trim()) this.activity(job, { type: 'log', stream, message: line.slice(0, 1200) });
+    job.tail.push(line);
+    if (job.tail.length > 40) job.tail.shift();
+    if (this.opts.echo) (stream === 'out' ? process.stdout : process.stderr).write(`${line}\n`);
+    this.events.publish('log', { world: job.world, job: job.id, stream, line });
+  }
+
+  private finish(job: Job, state: Job['state'], error?: string) {
+    job.state = state;
+    job.endedAt = new Date().toISOString();
+    if (error) job.error = error;
+    this.diagnostics.get(job.id)?.active.clear();
+    this.activity(job, { type: 'job.end', outcome: state, ...(error && { error }) }, job.endedAt);
+    this.events.publish('job.end', { world: job.world, job: { ...job } });
+    for (const resolve of this.waiters.get(job.id) ?? []) resolve({ ...job });
+    this.waiters.delete(job.id);
+    this.next(job.world);
+  }
+}

package/app/src/studio/locks.ts

@@ -0,0 +1,33 @@
+// Locks keep the agent's hands off what the person is working on: a locked world or place refuses the
+// agent's jobs and undo. The person's own actions go through; a lock only the person can lift.
+import fs from 'node:fs';
+import path from 'node:path';
+
+export type Lock = { by: string; at: string };
+export type Locks = { world?: Lock; places: Record<string, Lock> };
+
+const file = (dir: string) => path.join(dir, 'studio', 'locks.json');
+
+export function readLocks(dir: string): Locks {
+  try {
+    return { places: {}, ...(JSON.parse(fs.readFileSync(file(dir), 'utf8')) as Partial<Locks>) };
+  } catch {
+    return { places: {} };
+  }
+}
+
+export function writeLocks(dir: string, locks: Locks) {
+  fs.mkdirSync(path.dirname(file(dir)), { recursive: true });
+  fs.writeFileSync(file(dir), `${JSON.stringify(locks, null, 2)}\n`);
+}
+
+/** Why the agent may not change this world (or, given one, this place) now, or null. */
+export function agentBlocked(dir: string, by: string, place?: string): string | null {
+  if (by !== 'agent') return null;
+  const locks = readLocks(dir);
+  if (locks.world) return `the person locked this world (${locks.world.at}); ask them to unlock it`;
+  if (place) return locks.places[place] ? `the person locked ${place}; ask them to unlock it` : null;
+  const places = Object.keys(locks.places);
+  if (places.length) return `the person locked ${places.join(', ')}; a build would touch every place, so ask them first`;
+  return null;
+}

package/app/src/studio/mcp.ts

@@ -0,0 +1,86 @@
+// The Studio's actions as MCP tools: one tool per action, same name, same input schema. The studio serves
+// this over streamable HTTP at /mcp (Muse Code connects there) and `diorama mcp` over stdio.
+import { actions, describeActions, runAction, type ActionContext } from '../actions/registry.ts';
+import { redact } from '../secrets.ts';
+
+type Message = { jsonrpc: '2.0'; id?: string | number | null; method?: string; params?: Record<string, unknown> };
+export type Reply = { jsonrpc: '2.0'; id: string | number | null; result?: unknown; error?: { code: number; message: string } };
+
+const PROTOCOL = '2025-06-18';
+
+export const INSTRUCTIONS = 'Diorama builds painted point-and-click worlds. Every tool here is a Diorama Studio action; the person sees each call '
+  + 'in the Studio at once. Long work (world_build, run_step) starts a job: follow it with job_wait. Use ui_focus to show the person the '
+  + 'world or place you are talking about. Keys are never available to you: if setup_status says one is missing, ask the person to run diorama setup.';
+
+export function mcpTools() {
+  return describeActions().map((a) => ({
+    name: a.name,
+    description: a.description,
+    inputSchema: a.input,
+    annotations: { readOnlyHint: a.reads, openWorldHint: false },
+  }));
+}
+
+/** Answers one JSON-RPC message; null for a notification. */
+/** `world`: the world the calling agent session is about; a tool call that leaves out `slug` gets it. */
+/** `seen`: told of each tool call (name, arguments) and, through the function it returns, of how it ended. */
+export async function handleMcp(message: Message, ctx: ActionContext, world?: string, seen?: (name: string, args: Record<string, unknown>) => (ok: boolean, result: unknown) => void): Promise<Reply | null> {
+  if (message.id === undefined || message.id === null) return null;
+  const id = message.id;
+  const ok = (result: unknown): Reply => ({ jsonrpc: '2.0', id, result });
+  switch (message.method) {
+    case 'initialize':
+      return ok({
+        protocolVersion: typeof message.params?.protocolVersion === 'string' ? message.params.protocolVersion : PROTOCOL,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: 'diorama', version: '0.1.0' },
+        instructions: INSTRUCTIONS,
+      });
+    case 'ping':
+      return ok({});
+    case 'tools/list':
+      return ok({ tools: mcpTools() });
+    case 'tools/call': {
+      const name = String(message.params?.name ?? '');
+      if (!actions.has(name)) return { jsonrpc: '2.0', id, error: { code: -32602, message: `no tool ${name}` } };
+      try {
+        const args = { ...((message.params?.arguments ?? {}) as Record<string, unknown>) };
+        if (world && args.slug === undefined && takesSlug(name)) args.slug = world;
+        const settle = seen?.(name, args);
+        let ran: unknown;
+        try {
+          ran = await runAction(name, args, ctx);
+        } catch (error) {
+          settle?.(false, error);
+          throw error;
+        }
+        settle?.(true, ran);
+        const { result, images } = withoutImages(ran);
+        const content = [{ type: 'text', text: redact(JSON.stringify(result, null, 1)) }, ...images.map((i) => ({ type: 'image', data: i.data, mimeType: i.mimeType }))];
+        return ok({ content, structuredContent: wrap(result), isError: false });
+      } catch (error) {
+        return ok({ content: [{ type: 'text', text: redact(error instanceof Error ? error.message : String(error)) }], isError: true });
+      }
+    }
+    default:
+      return { jsonrpc: '2.0', id, error: { code: -32601, message: `method not found: ${message.method}` } };
+  }
+}
+
+/** structuredContent must be an object. */
+const wrap = (result: unknown) => (result && typeof result === 'object' && !Array.isArray(result) ? result : { result });
+
+type Image = { mimeType: string; data: string };
+
+/** An action that shows a picture returns it as `images`: the agent gets it as image content, not as text. */
+function withoutImages(result: unknown): { result: unknown; images: Image[] } {
+  if (!result || typeof result !== 'object' || !Array.isArray((result as { images?: unknown }).images)) return { result, images: [] };
+  const { images, ...rest } = result as { images: Image[] };
+  return { result: rest, images };
+}
+
+/** Whether a tool's input has a top-level `slug`. */
+function takesSlug(name: string): boolean {
+  const input = actions.get(name)?.input;
+  return !!input && 'shape' in input && typeof input.shape === 'object' && input.shape !== null && 'slug' in input.shape;
+}

package/app/src/studio/operation.ts

@@ -0,0 +1,18 @@
+// A local operation's lifetime, not a claim about what a remote service is doing.
+import { randomUUID } from 'node:crypto';
+import { emit } from '../registry.ts';
+
+export async function trackOperation<T>(kind: string, label: string, run: () => Promise<T>): Promise<T> {
+  if (process.env.DIORAMA_EVENTS !== '1') return run();
+  const id = randomUUID();
+  const started = Date.now();
+  emit('operation.start', { id, kind, label });
+  try {
+    const result = await run();
+    emit('operation.end', { id, kind, label, outcome: 'ok', ms: Date.now() - started });
+    return result;
+  } catch (error) {
+    emit('operation.end', { id, kind, label, outcome: 'failed', ms: Date.now() - started, error: (error instanceof Error ? error.message : String(error)).slice(0, 500) });
+    throw error;
+  }
+}

package/app/src/studio/repair.ts

@@ -0,0 +1,31 @@
+// The second tier of repair: when a build fails, the Studio hands it to the agent at once, without anyone
+// asking. Places that are not playable (and that the build could not fix for free) get the playbook; any other
+// failure (a step that broke, a service that did not answer) gets the error and the job's last lines. The agent's
+// brief says how; what it cannot fix it tells the person, which is the third tier.
+import type { Job } from './jobs.ts';
+
+/** Whether a job that just ended should wake the agent. */
+export function wantsRepair(job: Job, opts: { enabled: boolean }): boolean {
+  if (!opts.enabled) return false;
+  // The agent's own fix jobs come back to it through job_wait; only builds someone else started wake it.
+  if (job.by === 'agent' || job.args[0] !== 'build') return false;
+  return job.state === 'failed' || job.state === 'done' && !!job.warnings?.faces?.length;
+}
+
+/** What the agent is told: which places or which step, why, and what is expected back. */
+export function repairPrompt(job: Job): string {
+  const animation = job.warnings?.faces?.length ? `\nSpeaking animation also needs attention: ${job.warnings.faces.join('; ')}. Use faces_status and inspect the saved work. For a bad articulation use faces_inspect then face_frame_repair; for uncertain head lip bounds use faces_inspect then face_lips_set; for source/final-patch bounds use face_calibration_inspect then face_calibration_set. Preserve accepted artwork, inspect actual pixels before coordinates, and do not repeat an unchanged failed repair.` : '';
+  if (job.state === 'done' && animation) return `[Studio] The build "${job.label}" finished with incomplete speaking animation. This does not block other build steps and does not certify gameplay or audio quality.${animation}\nRepair the affected stage, wait for the job, check coverage and reload after success. If the image is too ambiguous to calibrate, explain what is still missing.`;
+  if (job.unplayable?.length) {
+    const places = job.unplayable.map((u) => `- ${u.place}: ${u.errors.join('; ') || 'see place_status'}`).join('\n');
+    return `[Studio] The build "${job.label}" ended with places that are not playable, and its free fixes did not help:\n${places}\n`
+      + 'Repair them as your brief says: place_status and place_view first, then the playbook\'s fix tools in order, at most three fixes a place, '
+      + 'and ask me before the last resort. Then tell me in two sentences what you fixed and what is left for me.' + animation;
+  }
+  const tail = job.tail.slice(-15).map((l) => `  ${l}`).join('\n');
+  return `[Studio] The build "${job.label}" (job ${job.id}) failed${job.step ? ` at ${job.step}` : ''}: ${job.error ?? 'no error said'}\n`
+    + (tail ? `Its last lines:\n${tail}\n` : '')
+    + 'Find the cause and fix it as your brief says for a failed build: job_inspect first; a service that did not answer (HTTP 5xx, a timeout) gets one job_retry; '
+    + 'a step that broke on the world gets that step\'s own tool (cast_status, place_status, …). Do not retry the same error twice. '
+    + 'Then tell me in two sentences what you fixed and what is left for me.' + animation;
+}