@homie-rocks/studio 0.58.21 → 0.58.23

package/CHANGELOG.md

@@ -17,6 +17,36 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.58.23] - 2026-10-29
+
+**Plugin 0.58.15**
+
+A booking agent books, finds its hold, pays and cancels with one hold id and a private token, and every refusal comes with a stable error code.
+
+### Changed
+
+- `studio_book` needs no `id`. The returned `data.id` (now `hold_` and 48 hex) is the hold: pass it as `hold` to the Venue desk tools, `studio_holds` and `studio_checkout`. An `id` you still send is an optional idempotency key, scoped to your account or private token, so two guests using the same slot name never collide (that was the `Booking owner required` error). Holds made by earlier versions keep their 64-hex ids and keep working.
+- Every studio MCP tool refusal is an MCP error (`isError`) with `structuredContent` `{kind:'studio-error', error:{code, message, status}}` and a stable `code`, e.g. `hold_not_found`, `slot_full`, `hold_ended`, `invalid_input`, or a closed shop's `closed` with `details.missing`. `studio_checkout` no longer returns a closed shop as success.
+- `studio_checkout` takes top-level `app`, `hold` and `token`, the same as the Venue desk tools, and fills in the booking's line (its service item × quantity). `venue_booking_confirm` (Venue desk 1.0.1), for a venue that takes payment in advance, returns `checkout: {tool:'studio_checkout', arguments, lines}` naming exactly what to call.
+
+### Added
+
+- `studio_holds { token }` lists a guest's own active holds; `release` (a hold id, or `"all"`) releases them. Only that token's holds are ever shown or changed.
+
+### Fixed
+
+- A hold past its expiry no longer takes a place: availability stops counting it, and the next booking on that slot releases it.
+
+## [0.58.22] - 2026-10-29
+
+**Plugin 0.58.15**
+
+The parts that come with the toolkit, like the Venue desk, add to a studio with no download.
+
+### Fixed
+
+- `part_add` and `parts_find` find the parts that come with the toolkit (`parts/catalogue.json`: Venue desk, Owner action checklist, Terrain route map) in the installed toolkit, with no download: `part_add { "part": "venue-desk" }` (or `"homie.rocks/venue-desk"`) copies it in, every file checked against the catalogue's SHA-256, and `parts_find` lists them even when the shared catalogue cannot be reached.
+
 ## [0.58.21] - 2026-10-29
 
 **Plugin 0.58.15**

package/lib/parts-store.mjs

@@ -21,6 +21,7 @@ import { priceWords } from "../worker/purchase-pricing.mjs";
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import {
   LIMITS, TUNING_FILE, TUNING_UPSTREAM, assetRecords, checkPart, compareVersions, isVersion, licenceIssues, licenseOfPart, listOwnParts, packPart, packedDir,
   packedVersions, parseRef, partDir, readOrigins, readPart, requiredParts, sha256, shareProblems, syncPartCredits, vendorDir, verifyFiles, writeHashes,
@@ -32,6 +33,45 @@ export const HUB = 'https://homie.rocks';
 const isObj = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
 const line = (v, n = 200) => (typeof v === 'string' ? v.replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, n) : '');
 
+/* ------------------------------------------------------------------ the toolkit's own parts */
+
+/**
+ * The parts that come WITH the toolkit (parts/catalogue.json in this package, e.g. venue-desk): found and added from the
+ * installed toolkit, with no network. "venue-desk" alone, or "homie.rocks/venue-desk", names one; every file is checked
+ * against the catalogue's SHA-256 and size exactly as a fetched part's are.
+ */
+export const TOOLKIT_HOST = 'homie.rocks';
+const TOOLKIT_PARTS = fileURLToPath(new URL('../parts/', import.meta.url));
+export function bundledCatalogue() {
+  try {
+    const c = JSON.parse(readFileSync(join(TOOLKIT_PARTS, 'catalogue.json'), 'utf8'));
+    return Array.isArray(c?.parts) ? c.parts.filter((p) => isObj(p) && typeof p.id === 'string' && p.share === true && Array.isArray(p.files)) : [];
+  } catch { return []; }
+}
+/** A bundled part named by `refText`, read and checked; null when it is not one of the toolkit's. */
+export function bundledPart(refText) {
+  const text = String(refText ?? '').trim();
+  const bare = /^([a-z0-9][a-z0-9-]{0,47})(?:@(.{1,60}))?$/.exec(text);
+  const ref = bare ? { host: TOOLKIT_HOST, id: bare[1], version: bare[2] ?? null, ref: `${TOOLKIT_HOST}/${bare[1]}` } : parseRef(text);
+  if (!ref || ref.host !== TOOLKIT_HOST) return null;
+  const part = bundledCatalogue().find((p) => p.id === ref.id);
+  if (!part) return null;
+  if (ref.version && ref.version !== part.version) throw new Error(`The toolkit has ${ref.id} ${part.version}, not ${ref.version}. Upgrade the toolkit for a newer one.`);
+  const shape = checkPart(part);
+  if (!shape.ok) throw new Error(`${ref.ref} ${part.version} is not a part this toolkit can read: ${shape.problems.filter((p) => p.level === 'refuse').map((p) => `${p.field}: ${p.problem}`).slice(0, 3).join('; ')}`);
+  const files = new Map();
+  for (const f of part.files) {
+    const at = join(TOOLKIT_PARTS, part.id, f.path);
+    if (!at.startsWith(join(TOOLKIT_PARTS, part.id) + '/')) throw new Error(`${ref.ref}: ${f.path} is outside the part`);
+    let bytes;
+    try { bytes = readFileSync(at); } catch { throw new Error(`${ref.ref}: ${f.path} is missing from the installed toolkit. Reinstall it (npm ci).`); }
+    if (bytes.length !== f.bytes || sha256(bytes) !== f.sha256) throw new Error(`${ref.ref} ${part.version}: ${f.path} in the installed toolkit is not the file its catalogue describes. Reinstall the toolkit (npm ci).`);
+    files.set(f.path, bytes);
+  }
+  const entry = { ...part, from: { ...(isObj(part.from) ? part.from : {}), studio: 'Homie toolkit' }, studio: { name: 'Homie toolkit' } };
+  return { ref: { ...ref, version: part.version }, part, files, entry, base: baseOf(TOOLKIT_HOST), version: part.version, versions: [part.version], access: null, bundled: true };
+}
+
 /* ------------------------------------------------------------------ the one fetch */
 
 /** A studio's site from its host: https, except a site on this computer (the local preview), which has no certificate. */
@@ -196,7 +236,7 @@ export async function addPart(root, refText, { game = null, fetch, npm = runNpm,
   if (game && !existsSync(experienceFile(root, game))) return fail(`there is no game "${game}" in this studio (${listGames(root).map((g) => g.id).join(', ') || 'it has none yet'})`);
   let got;
   try {
-    got = offline ? await offlinePurchase(root, refText, game) : await fetchPart(refText, { fetch, onPaid: (ref, part, offer) => paidAccess(root, ref, part, { game, quantity, approve, fetch, offer, wallet, walletPay }) });
+    got = offline ? await offlinePurchase(root, refText, game) : bundledPart(refText) ?? await fetchPart(refText, { fetch, onPaid: (ref, part, offer) => paidAccess(root, ref, part, { game, quantity, approve, fetch, offer, wallet, walletPay }) });
     if (got.access) {
       savePurchaseBackup(root, got, got.access, game);
       const c = got.access.claims;
@@ -345,6 +385,10 @@ export async function findParts(root, query = '', { kind = null, tag = null, lic
       if (part) here.push(row({ ...part, from: e.from ?? part.from }, { where: 'here', ref, add: ref, import: part.entry ? `@parts/${ref}` : null, games: e.games ?? [], say: `Already in this studio (${e.version}): import it from '@parts/${ref}'.` }));
     }
   }
+  for (const p of bundledCatalogue()) {
+    const ref = `${TOOLKIT_HOST}/${p.id}`;
+    if (!here.some((h) => h.ref === ref)) here.push(row({ ...p, from: { ...(isObj(p.from) ? p.from : {}), studio: 'Homie toolkit' } }, { where: 'toolkit', ref, add: ref, import: null, say: `Comes with the Homie toolkit (no download): part_add { "part": "${ref}" }.` }));
+  }
   let base = hub;
   if (!base && root) { try { const d = readStudio(root).homie?.directory; base = d === false || d === null ? null : d; } catch { base = null; } }
   base = /^https?:\/\/[a-z0-9.:-]+$/i.test(String(base ?? '')) ? base : HUB;
@@ -353,7 +397,7 @@ export async function findParts(root, query = '', { kind = null, tag = null, lic
   try {
     const index = await getJson(url, { fetch, what: 'the catalogue of shared parts' });
     if (!Array.isArray(index?.parts)) throw new Error(`${url} is not a parts catalogue`);
-    const have = new Set(here.filter((h) => h.where === 'here').map((h) => h.ref));
+    const have = new Set(here.filter((h) => h.where === 'here' || h.where === 'toolkit').map((h) => h.ref));
     found = index.parts.filter((p) => isObj(p) && typeof p.id === 'string' && (typeof p.host === 'string' || typeof p.add === 'string')).map((p) => {
       const ref = parseRef(typeof p.add === 'string' ? p.add : `${p.host}/${p.id}`)?.ref;
       return ref ? row(p, { where: 'hub', ref, add: ref, studio: line(p.studio?.name, 80) || null, page: /^https:\/\//.test(String(p.page ?? '')) ? p.page : null, here: have.has(ref), say: `${p.sale ? `Paid: ${priceWords(p.sale)}. Ask for approval of the exact quote before requesting payment. ` : 'Free. '}Add it: part_add { "part": "${ref}" }.` }) : null;

package/lib/template-history.json

@@ -4866,6 +4866,90 @@
      }
     }
    }
+  },
+  "0.58.22": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "1dbdf22c03a1e505",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "af7f2f732505d379",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "2ecf713305fd26f5",
+     "## Commands (all through the pinned CLI in node_modules)": "661cbdf5d6a9dbae",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "644c1e7608bb9740",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1904f45b599a33e4",
+     "## Selling things (the shop)": "e5bd380cb77f2b11",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "b2234d80f6cbe71d",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "0a7b2c36414a29a0"
+      }
+     }
+    }
+   }
+  },
+  "0.58.23": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "1dbdf22c03a1e505",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "af7f2f732505d379",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "2ecf713305fd26f5",
+     "## Commands (all through the pinned CLI in node_modules)": "661cbdf5d6a9dbae",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "644c1e7608bb9740",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1904f45b599a33e4",
+     "## Selling things (the shop)": "e5bd380cb77f2b11",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "b2234d80f6cbe71d",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "0a7b2c36414a29a0"
+      }
+     }
+    }
+   }
   }
  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.58.21",
+  "version": "0.58.23",
   "description": "Open-source tools that let your AI build and run a multiplayer game studio on its own Cloudflare: an MCP server, multiplayer starters, Workers and Durable Objects.",
   "type": "module",
   "license": "Apache-2.0",

package/parts/catalogue.json

@@ -236,7 +236,7 @@
       "id": "venue-desk",
       "name": "Venue desk",
       "kind": "tools",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "summary": "Public venue info (hours, closures, policies, FAQ), booking contact and confirmation on top of studio holds, and a waitlist with an owner outbox. Any venue, schema.org outputs.",
       "license": "Apache-2.0",
       "attribution": "Ryan Campbell — Homie toolkit",
@@ -307,8 +307,8 @@
         },
         {
           "path": "src/index.ts",
-          "sha256": "063876b14067c97c5c5dec4dd9f04dcfa60cfee7ea72e29a347412b5eed5c3b8",
-          "bytes": 19530
+          "sha256": "16622b3ce82ffd38cf1ba9288fd6161da15aba36b63ac43ce55ef6acdd414868",
+          "bytes": 19883
         },
         {
           "path": "tools/venue-booking-cancel.ts",
@@ -367,7 +367,7 @@
         }
       ],
       "cost": {
-        "bytes": 36701
+        "bytes": 37054
       }
     }
   ]

package/parts/venue-desk/part.json

@@ -2,7 +2,7 @@
   "id": "venue-desk",
   "name": "Venue desk",
   "kind": "tools",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "summary": "Public venue info (hours, closures, policies, FAQ), booking contact and confirmation on top of studio holds, and a waitlist with an owner outbox. Any venue, schema.org outputs.",
   "license": "Apache-2.0",
   "attribution": "Ryan Campbell — Homie toolkit",
@@ -73,8 +73,8 @@
     },
     {
       "path": "src/index.ts",
-      "sha256": "063876b14067c97c5c5dec4dd9f04dcfa60cfee7ea72e29a347412b5eed5c3b8",
-      "bytes": 19530
+      "sha256": "16622b3ce82ffd38cf1ba9288fd6161da15aba36b63ac43ce55ef6acdd414868",
+      "bytes": 19883
     },
     {
       "path": "tools/venue-booking-cancel.ts",
@@ -133,6 +133,6 @@
     }
   ],
   "cost": {
-    "bytes": 36701
+    "bytes": 37054
   }
 }

package/parts/venue-desk/src/index.ts

@@ -17,7 +17,7 @@ const NS = 'venue-desk';
 const TOKEN = {type: 'string', pattern: '^[a-f0-9]{32,128}$', description: 'The private random hex token the caller chose for studio_book (or for this waitlist entry). Keep it; it is the only proof the booking is yours.'};
 const ID = {type: 'string', pattern: '^[A-Za-z0-9_-]{1,64}$'};
 const short = (n) => ({type: 'string', maxLength: n});
-const fail = (message) => Object.assign(new Error(message), {name: 'StudioOperationError'});
+const fail = (message, code = 'invalid_request', status = 400) => Object.assign(new Error(message), {name: 'StudioOperationError', code, status});
 const now = () => Date.now();
 const iso = (ms) => (Number.isFinite(ms) ? new Date(ms).toISOString() : null);
 const clean = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined && v !== null && v !== ''));
@@ -90,7 +90,7 @@ const CONTACT = {
   partySize: {type: 'integer', minimum: 1, maximum: 1000}, notes: {...short(1000), description: 'Allergies, accessibility, occasion: the guest\'s words, shown to staff.'},
 };
 async function ownHold(ctx, hold, token) {
-  try { return await ctx.bookings.get(clean({id: hold, token})); } catch { throw fail('No such booking for this token'); }
+  try { return await ctx.bookings.get(clean({id: hold, token})); } catch { throw fail('No hold with this id for this token (pass data.id from studio_book and the same token)', 'hold_not_found', 403); }
 }
 function reservation(h, c, extra = {}) {
   const status = {held: 'ReservationHold', confirmed: 'ReservationConfirmed', released: 'ReservationCancelled', pending: 'ReservationPending'}[h.state] ?? 'ReservationPending';
@@ -100,11 +100,11 @@ function reservation(h, c, extra = {}) {
 export const venueBookingDetails = {
   name: 'venue_booking_details', namespace: NS, audience: 'public',
   description: 'After studio_book: attach the guest\'s contact to the hold (name, email and/or phone, party size, notes). Staff see it; it is never shown publicly. Call again to correct it. Then venue_booking_confirm, or studio_checkout when the venue takes payment in advance.',
-  inputSchema: {type: 'object', properties: {hold: {...ID, description: 'The id given to studio_book.'}, token: TOKEN, ...CONTACT}, required: ['hold', 'name'], additionalProperties: false},
+  inputSchema: {type: 'object', properties: {hold: {...ID, description: 'The hold: data.id returned by studio_book (hold_…).'}, token: TOKEN, ...CONTACT}, required: ['hold', 'name'], additionalProperties: false},
   async handler({hold, token, ...c}, ctx) {
     if (!c.email && !c.phone) throw fail('Give an email or a phone so the venue can reach the guest');
     const h = await ownHold(ctx, hold, token);
-    if (h.state === 'released') throw fail('This hold has ended; book again');
+    if (h.state === 'released') throw fail('This hold has ended; book again', 'hold_ended', 409);
     const prev = await ctx.database.get('booking:' + hold);
     await ctx.database.put('booking:' + hold, {...(prev ?? {}), hold, slot: h.slot, quantity: h.quantity, contact: clean(c), tokenHash: token ? await hash(token) : null, state: h.state, at: prev?.at ?? now(), updatedAt: now()});
     return {ok: true, next: (await info(ctx)).booking?.paymentInAdvance ? 'studio_checkout' : 'venue_booking_confirm', reservation: reservation(h, c)};
@@ -121,8 +121,8 @@ export const venueBookingConfirm = {
     if (!rec?.contact) throw fail('Add the guest\'s contact with venue_booking_details first');
     let h = await ownHold(ctx, hold, token);
     if (h.state === 'confirmed') return {ok: true, already: true, reservation: reservation(h, rec.contact)};
-    if (h.state !== 'held') throw fail('This hold has ended; book again');
-    if (v.booking?.paymentInAdvance) return {ok: false, next: 'studio_checkout', why: 'This venue confirms bookings on payment.', checkoutBooking: {collection: v.booking.collection, slot: h.slot, hold}};
+    if (h.state !== 'held') throw fail('This hold has ended; book again', 'hold_ended', 409);
+    if (v.booking?.paymentInAdvance) return {ok: false, next: 'studio_checkout', why: 'This venue confirms bookings on payment.', checkoutBooking: {collection: v.booking.collection, slot: h.slot, hold}, checkout: clean({tool: 'studio_checkout', arguments: clean({app: h.app, hold, token}), lines: h.item ? [{item: h.item, quantity: h.quantity}] : undefined})};
     h = await ctx.bookings.confirm(clean({id: hold, token, version: h.version}));
     await ctx.database.put('booking:' + hold, {...rec, state: 'confirmed', confirmedAt: now()});
     await log(ctx, {at: now(), what: 'booking.confirmed', hold, slot: h.slot, quantity: h.quantity, name: rec.contact.name});

package/worker/booking-availability.mjs

@@ -13,7 +13,7 @@ export async function bookingAvailability(env,cat,caller,{app,collection,after='
   if(!readable)throw fail('Booking availability unavailable');
  }
  const scope=caller.testScope?`${app}:check:${caller.testScope}`:app;
- const rows=(await env.DB.prepare(`SELECT s.id,s.value,COALESCE((SELECT SUM(b.quantity) FROM shop_bookings b WHERE b.app=s.app AND b.slots=s.collection AND b.slot=s.id AND b.state IN ('held','confirmed')),0) used FROM app_records s WHERE s.app=?1 AND s.collection=?2 AND s.id>?3 ORDER BY s.id LIMIT 51`).bind(scope,spec.slots,after).all()).results;
+ const rows=(await env.DB.prepare(`SELECT s.id,s.value,COALESCE((SELECT SUM(b.quantity) FROM shop_bookings b WHERE b.app=s.app AND b.slots=s.collection AND b.slot=s.id AND (b.state='confirmed' OR b.state='held' AND NOT (b.order_id='hold:'||b.id AND b.hold_until<=?4))),0) used FROM app_records s WHERE s.app=?1 AND s.collection=?2 AND s.id>?3 ORDER BY s.id LIMIT 51`).bind(scope,spec.slots,after,Date.now()).all()).results;
  const snapshot=await resourceSnapshot(env,scope,spec);
  const items=[];
  for(const row of rows.slice(0,50)){

package/worker/booking-holds.mjs

@@ -35,25 +35,32 @@ ${['insert','update'].map(op=>{
 }).join('\n')}
 UPDATE shop_bookings SET paid_at=(SELECT paid_at FROM shop_orders WHERE id=order_id),version=version+1 WHERE EXISTS(SELECT 1 FROM shop_orders WHERE id=order_id AND paid_at IS NOT NULL);
 `;
-const refusal=(message,status=400)=>Object.assign(new Error(message),{name:'StudioOperationError',status});
+const CODES={400:'invalid_request',403:'forbidden',404:'not_found',409:'conflict'};
+const refusal=(message,status=400,code=CODES[status]??'invalid_request')=>Object.assign(new Error(message),{name:'StudioOperationError',status,code});
 const valid=v=>typeof v==='string'&&/^[A-Za-z0-9_-]{1,64}$/.test(v);
+/** A hold id: hold_ and 48 hex (from 0.58.23), or the 64-hex id earlier releases returned. Never shaped like a guest token. */
+export const HOLD_ID=/^(hold_[a-f0-9]{48}|[a-f0-9]{64})$/;
+const holdId=async parts=>'hold_'+(await hash(JSON.stringify(parts))).slice(0,48);
+const randomHex=n=>Array.from(crypto.getRandomValues(new Uint8Array(n)),b=>b.toString(16).padStart(2,'0')).join('');
 const hash=async token=>Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256',new TextEncoder().encode(token))),b=>b.toString(16).padStart(2,'0')).join('');
 export async function ownedHold(env,caller,{id,token}){
- if(!valid(id))throw refusal('Invalid booking id');
+ if(!valid(id))throw refusal('Invalid hold id: pass data.id from studio_book',400,'invalid_hold');
  const row=await env.DB.prepare('SELECT * FROM shop_bookings WHERE id=?1').bind(id).first();
- if(!row||!(caller.owner||row.actor&&row.actor===caller.id||row.token_hash&&typeof token==='string'&&await hash(token)===row.token_hash))throw refusal('Booking owner required',403);
- if(caller.testScope&&!row.app.endsWith(':check:'+caller.testScope))throw refusal('Booking owner required',403);
+ // One answer for "no such hold" and "not yours", so a hold id reveals nothing to someone without its token.
+ if(!row||!(caller.owner||row.actor&&row.actor===caller.id||row.token_hash&&typeof token==='string'&&await hash(token)===row.token_hash))throw refusal('No hold with this id for this token (pass data.id from studio_book and the same token)',403,'hold_not_found');
+ if(caller.testScope&&!row.app.endsWith(':check:'+caller.testScope))throw refusal('No hold with this id for this token (pass data.id from studio_book and the same token)',403,'hold_not_found');
  return row;
 }
 /** A hold is the very row checkout later confirms. Secrets never enter its public projection. */
 export function bookingHolds(env,caller,cat){
- const result=r=>({id:r.id,slot:r.slot,quantity:r.quantity,state:r.state,version:r.version,expiresAt:r.hold_until,paid:r.paid_at!==null,...(r.allocation&&r.allocation!=='[]'?{allocations:JSON.parse(r.allocation)}:{}),...(r.choices&&r.choices!=='{}'?{choices:JSON.parse(r.choices)}:{})});
+ const spec=r=>cat?.games?.find(g=>g.kind==='app'&&g.id===String(r.app).split(':check:')[0])?.records?.collections?.[r.collection]?.booking;
+ const result=r=>({id:r.id,hold:r.id,app:String(r.app).split(':check:')[0],collection:r.collection,...(spec(r)?.item?{item:spec(r).item}:{}),slot:r.slot,quantity:r.quantity,state:r.state,version:r.version,expiresAt:r.hold_until,paid:r.paid_at!==null,...(r.allocation&&r.allocation!=='[]'?{allocations:JSON.parse(r.allocation)}:{}),...(r.choices&&r.choices!=='{}'?{choices:JSON.parse(r.choices)}:{})});
  const change=async(args,state)=>{
   const row=await ownedHold(env,caller,args);
-  if(row.order_id!=='hold:'+row.id)throw refusal('Checkout owns this booking; reconcile payment before release');
-  if(!Number.isSafeInteger(args.version)||args.version<1)throw refusal('Booking version required');
+  if(row.order_id!=='hold:'+row.id)throw refusal('Checkout owns this booking; reconcile payment before release',409,'checkout_owns_hold');
+  if(!Number.isSafeInteger(args.version)||args.version<1)throw refusal('Booking version required',400,'version_required');
   const changed=await env.DB.prepare(`UPDATE shop_bookings SET state=?2,version=version+1,updated_at=?3 WHERE id=?1 AND version=?4 AND state IN ('held','confirmed') AND (?2='released' OR hold_until>?3) RETURNING *`).bind(row.id,state,Date.now(),args.version).first();
-  if(!changed)throw refusal('Booking changed or expired; reload',409);return result(changed);
+  if(!changed)throw refusal('Booking changed or expired; reload',409,'hold_changed_or_expired');return result(changed);
  };
  return Object.freeze({
   calendar({app,...options}){const meta=cat.games.find(g=>g.id===app&&g.kind==='app');if(!meta)throw refusal('Unknown app');return calendarSlots({timeZone:meta.timeZone,...options});},
@@ -61,27 +68,47 @@ export function bookingHolds(env,caller,cat){
    const args=normalizeBookingArgs(input);
    let {app,collection,slot,quantity=1,id,token,expiresAt}=args;
    const meta=cat.games.find(g=>g.id===app&&g.kind==='app'),spec=meta?.records?.collections?.[collection]?.booking;
-   if(!spec||!valid(id)||!valid(slot)||!Number.isSafeInteger(quantity)||quantity<1)throw refusal('Choose a declared slot, positive quantity and stable booking id');
-   if(!Number.isSafeInteger(expiresAt)||expiresAt<=Date.now())throw refusal('Hold needs a future expiry');
-   if(token!==undefined&&!(typeof token==='string'&&/^[a-f0-9]{32,128}$/.test(token)))throw refusal('Invalid private booking token');
-   if(!caller.id&&!token)throw refusal('Booking owner or private token required');
+   if(!spec)throw refusal('Unknown booking collection',400,'unknown_collection');
+   if(!valid(slot)||!Number.isSafeInteger(quantity)||quantity<1||id!==undefined&&!valid(id))throw refusal('Choose a declared slot and a positive quantity',400,'invalid_booking');
+   if(!Number.isSafeInteger(expiresAt)||expiresAt<=Date.now())throw refusal('Hold needs a future expiry',400,'invalid_expiry');
+   if(token!==undefined&&!(typeof token==='string'&&/^[a-f0-9]{32,128}$/.test(token)))throw refusal('Invalid private booking token',400,'invalid_token');
+   if(!caller.id&&!token)throw refusal('Booking owner or private token required',400,'token_required');
    if(!hasStripeKey(env)&&linkConfig(env)?.slots?.some(l=>l.app===app&&l.slots===spec.slots&&l.slot===slot))throw refusal('Keyless Stripe inventory cannot share local holds; configure session checkout first');
    const scope=caller.testScope?`${app}:check:${caller.testScope}`:app;
-   id=await hash(JSON.stringify([scope,collection,id]));
+   const secret=token?await hash(token):null;
    const choices={option:args.option??null,resource:args.resource??null,addons:args.addons??{}};
-   if(await env.DB.prepare('SELECT id FROM shop_bookings WHERE id=?1').bind(id).first()) {
-     const previous=await ownedHold(env,caller,{id,token});
-     if(previous.app!==scope||previous.collection!==collection||previous.slot!==slot||previous.quantity!==quantity||JSON.stringify({...choices,...JSON.parse(previous.choices??'{}')})!==JSON.stringify(choices))throw refusal('Booking id reused with different request',409);
-     return result(previous);
+   // `id` (optional, deprecated name for an idempotency key): a retry with the same key, token and request returns the
+   // same hold. The key is scoped to its owner (account or token), so two guests' keys never collide. The hold's own
+   // id is always the returned data.id (hold_…), never the key.
+   const same=previous=>previous.app===scope&&previous.collection===collection&&previous.slot===slot&&previous.quantity===quantity&&JSON.stringify({...choices,...JSON.parse(previous.choices??'{}')})===JSON.stringify(choices);
+   if(id!==undefined){
+     const legacy=await hash(JSON.stringify([scope,collection,id]));
+     for(const candidate of [await holdId([scope,collection,id,caller.id??secret]),legacy]){
+       const existing=await env.DB.prepare('SELECT * FROM shop_bookings WHERE id=?1').bind(candidate).first();
+       if(!existing)continue;
+       let previous;try{previous=await ownedHold(env,caller,{id:candidate,token});}catch{if(candidate===legacy)continue;throw refusal('Idempotency key reused',409,'key_conflict');}
+       if(previous.state==='released'||previous.state==='held'&&previous.hold_until<=Date.now()){if(candidate===legacy)continue;throw refusal('That key\'s hold has ended; book again without it or with a new one',409,'hold_ended');}
+       if(!same(previous))throw refusal('Idempotency key reused with a different request',409,'key_conflict');
+       return result(previous);
+     }
    }
-   let allocation;try{allocation=await loadAndAllocateResources(env,scope,spec,slot,args);}catch(error){throw refusal(error.message,409);}
-   const secret=token?await hash(token):null;
+   id=id!==undefined?await holdId([scope,collection,id,caller.id??secret]):'hold_'+randomHex(24);
+   // An abandoned hold past its expiry stops taking a place as soon as anyone books that slot.
+   await env.DB.prepare("UPDATE shop_bookings SET state='released',version=version+1,updated_at=?4 WHERE app=?1 AND slots=?2 AND slot=?3 AND state='held' AND order_id='hold:'||id AND hold_until<=?4").bind(scope,spec.slots,slot,Date.now()).run();
+   let allocation;try{allocation=await loadAndAllocateResources(env,scope,spec,slot,args);}catch(error){throw refusal(error.message,409,'resource_unavailable');}
    try {await env.DB.prepare(`INSERT INTO shop_bookings(id,app,collection,slots,slot,quantity,order_id,state,updated_at,actor,token_hash,hold_until,allocation,choices)
-    SELECT ?1,?2,?3,?4,?5,?6,'hold:'||?1,'held',?7,?8,?9,?10,?11,?12 WHERE NOT EXISTS(SELECT 1 FROM shop_bookings WHERE id=?1)`).bind(id,scope,collection,spec.slots,slot,quantity,Date.now(),caller.id??null,secret,expiresAt,JSON.stringify(allocation),JSON.stringify(choices)).run();}catch(error){if(/booking capacity unavailable|resource capacity unavailable/.test(error.message))throw refusal('That slot or resource capacity is unavailable. No place has been taken.',409);throw error;}
+    SELECT ?1,?2,?3,?4,?5,?6,'hold:'||?1,'held',?7,?8,?9,?10,?11,?12 WHERE NOT EXISTS(SELECT 1 FROM shop_bookings WHERE id=?1)`).bind(id,scope,collection,spec.slots,slot,quantity,Date.now(),caller.id??null,secret,expiresAt,JSON.stringify(allocation),JSON.stringify(choices)).run();}catch(error){if(/booking capacity unavailable|resource capacity unavailable/.test(error.message))throw refusal('That slot or resource capacity is unavailable. No place has been taken.',409,'slot_full');throw error;}
    const row=await ownedHold(env,caller,{id,token});
-   if(row.app!==scope||row.collection!==collection||row.slot!==slot||row.quantity!==quantity||JSON.stringify(JSON.parse(row.choices??'{}'))!==JSON.stringify(choices))throw refusal('Booking id reused with different request',409);
+   if(row.app!==scope||row.collection!==collection||row.slot!==slot||row.quantity!==quantity||JSON.stringify(JSON.parse(row.choices??'{}'))!==JSON.stringify(choices))throw refusal('Idempotency key reused with a different request',409,'key_conflict');
    return result(row);
   },
+  /** The caller's own holds: by its account, or by the private token (that token's holds only). Newest first. */
+  async mine({token,app,active=true}={}){
+   if(token!==undefined&&!(typeof token==='string'&&/^[a-f0-9]{32,128}$/.test(token)))throw refusal('Invalid private booking token',400,'invalid_token');
+   if(!token&&!caller.id)throw refusal('Pass the private token you gave studio_book',400,'token_required');
+   const rows=(await env.DB.prepare(`SELECT * FROM shop_bookings WHERE (${token?'token_hash=?1':'actor=?1'}) AND (?2 IS NULL OR app=?2 OR app LIKE ?2||':check:%') AND (?3=0 OR (state='confirmed' OR state='held' AND hold_until>?4)) ORDER BY updated_at DESC LIMIT 50`).bind(token?await hash(token):caller.id,app??null,active?1:0,Date.now()).all()).results??[];
+   return rows.filter(r=>!caller.testScope||r.app.endsWith(':check:'+caller.testScope)).map(result);
+  },
   async get(args){return result(await ownedHold(env,caller,args));},
   confirm:args=>change(args,'confirmed'),release:args=>change(args,'released'),
   async releaseExpired({app,collection,now=Date.now()}){

package/worker/booking-options.mjs

@@ -20,4 +20,4 @@ export function normalizeBookingArgs(input) {
 
 const text={type:'string',maxLength:64};
 const addons={oneOf:[{type:'array',maxItems:100,items:text},{type:'object',additionalProperties:{type:'integer',minimum:1,maximum:100}}]};
-export const bookingInputSchema={type:'object',properties:{app:text,collection:text,slot:text,time:text,option:text,resource:text,preferredResource:text,preferred_resource:text,addons,addOns:addons,'add-ons':addons,quantity:{type:'integer',minimum:1},id:text,token:{type:'string',pattern:'^[a-f0-9]{32,128}$'},expiresAt:{type:'integer'}},required:['app','collection','id','expiresAt'],additionalProperties:false};
+export const bookingInputSchema={type:'object',properties:{app:text,collection:text,slot:text,time:text,option:text,resource:text,preferredResource:text,preferred_resource:text,addons,addOns:addons,'add-ons':addons,quantity:{type:'integer',minimum:1},id:{type:'string',pattern:'^[A-Za-z0-9_-]{1,64}$',description:'Optional idempotency key (deprecated name): a retry with the same key and token returns the same hold. It is not the hold id; use data.id.'},token:{type:'string',pattern:'^[a-f0-9]{32,128}$'},expiresAt:{type:'integer'}},required:['app','collection','expiresAt'],additionalProperties:false};

package/worker/build-id.mjs

@@ -1,2 +1,2 @@
 // Generated by lib/build-identity.mjs; identifies the bundled runtime sources.
-export const STUDIO_BUILD = Object.freeze({"version":"0.58.21","sha256":"40282a0a4a1396e3d2856ddb8dee6dbd8998ef3bdb9884d32824479b710c975f"});
+export const STUDIO_BUILD = Object.freeze({"version":"0.58.23","sha256":"d976ca461d623e45165982deaebc53e1bda766a4ccf398701f724ca80aa46d9f"});

package/worker/customer-mcp.mjs

@@ -26,7 +26,21 @@ export function customerTools(env,cat,origin) {
   return [
     {name:'studio_catalogue',description:'Browse the public shop, paid parts and app goods. Prices use the studio’s currency minor units.',audience:'public',inputSchema:object(),handler:async(_args,ctx)=>({shop:await customerShop(env,cat,origin,ctx.caller,'/api/shop'),resources:await listOffers(env,origin)})},
     {name:'studio_cart',description:'Quote a cart for agent payment. Retain the returned private account cookies to use guest purchases. Approve this immutable offerVersion before purchase.',audience:'public',inputSchema:cartSchema,handler:(args,ctx)=>quoteCart(env,cat,origin,ctx.caller,args,ctx.request)},
-    {name:'studio_checkout',description:'Open the studio’s Stripe checkout for a person to approve. Uses the same cart, account, order and refund as the website.',audience:'public',inputSchema:{...cartSchema,properties:{...cartSchema.properties,reference:str,booking:object({collection:str,slot:str,hold:str,token:str},['collection','slot'])}},handler:(args,ctx)=>customerShop(env,cat,origin,ctx.caller,'/api/shop/buy',args)},
+    {name:'studio_checkout',description:'Open the studio’s Stripe checkout for a person to approve; returns url. For a booking pass the same top-level app, hold (data.id from studio_book) and token as the venue tools: the line (the booking\'s service item × its quantity) is filled in. For goods pass lines from studio_catalogue. Uses the same cart, account, order and refund as the website.',audience:'public',inputSchema:{type:'object',properties:{...cartSchema.properties,reference:str,app:str,hold:{type:'string',pattern:'^(hold_[a-f0-9]{48}|[a-f0-9]{64})$'},token:{type:'string',pattern:'^[a-f0-9]{32,128}$'},booking:object({collection:str,slot:str,hold:str,token:str},['collection','slot'])},additionalProperties:false},handler:async(args,ctx)=>{
+      const coded=(code,message,status=400)=>Object.assign(new Error(message),{name:'StudioOperationError',status,code});
+      const {app,hold,token,...rest}=args;let body=rest;
+      if(hold!==undefined){
+        if(rest.booking)throw coded('invalid_request','Pass either hold (with token) or booking, not both');
+        const h=await ctx.bookings.get({id:hold,...(token?{token}:{})});
+        if(app!==undefined&&app!==h.app)throw coded('hold_not_found','This hold is not in that app',403);
+        if(!h.item)throw coded('not_bookable','This booking collection names no service item to pay for');
+        body={...rest,game:rest.game??h.app,lines:rest.lines??[{item:h.item,quantity:h.quantity}],booking:{collection:h.collection,slot:h.slot,hold:h.id,...(token?{token}:{})}};
+      }else if(!rest.lines?.length)throw coded('lines_required','Pass hold (and token) for a booking, or lines for goods');
+      else if(app!==undefined&&rest.game===undefined)body={...rest,game:app};
+      const result=await customerShop(env,cat,origin,ctx.caller,'/api/shop/buy',body);
+      if(!result.ok){const {ok,error,message,...details}=result;throw Object.assign(coded(String(error??'checkout_failed').replace(/[^a-z0-9_-]/gi,'_'),message??'Checkout could not start',409),{details});}
+      return result;
+    }},
     {name:'studio_purchase',description:'Buy an approved offer with the MCP payment binding. Generate private random 32-byte hex buyer and claim values; retain the claim for retries. For x402 use the returned HTTP resource address.',audience:'public',inputSchema:{...purchaseSchema,properties:{...purchaseSchema.properties,checkout:{type:'boolean'}}},protocol:true,handler:async(args,ctx)=>{if(args.checkout&&args.kind==='cart'){const resource=await resourceKind('cart').get(env,args.resource,args.version);if(!resource)throw new Error('Cart unavailable');const result=await customerShop(env,cat,origin,{...ctx.caller,id:resource.player},'/api/shop/buy',{lines:resource.lines.map(l=>({item:l.item.id,quantity:l.quantity,amount:l.amount}))});return {content:[{type:'text',text:JSON.stringify(result)}],...(result.ok?{}:{isError:true})};}return buy(env,cat,origin,args,ctx.paymentExtra);}},
     {name:'studio_customer_refund',description:'Request a refund for your shop order under the studio refund policy.',audience:'signed-in',inputSchema:object({order:str,line:str},['order']),handler:(args,ctx)=>customerShop(env,cat,origin,ctx.caller,'/api/shop/refund',args)},
     {name:'studio_purchase_refund',description:'Request a resource or service refund with the original private purchase claim.',audience:'public',inputSchema:object({claim:{type:'string',pattern:'^[a-f0-9]{64}$'}},['claim']),handler:async({claim})=>{const url=new URL('/api/purchases/refund',origin);const response=await purchaseRoutes(new Request(url,{method:'POST',headers:{authorization:'Bearer '+claim,'content-type':'application/json'},body:'{}'}),env,url,cat);return response.json();}},

package/worker/mcp-tools.mjs

@@ -201,7 +201,7 @@ export function builtins(env,cat,origin) {
       return {app,roles,collections:Object.fromEntries(Object.entries(meta.records?.collections??{}).filter(([name])=>collections.has(name)))};
     }),
     tool('studio_availability','List available booking slots and options before studio_book. Returns schema.org Offers with exact booking arguments; availability is a snapshot, and booking rechecks capacity.','public',object({app:str,collection:str,after:str,quantity:{type:'integer',minimum:1},option:str,resource:str,addons:{type:'object',additionalProperties:{type:'integer',minimum:1,maximum:100}}},['app','collection']),async(args,ctx)=>ctx.bookings.availability(args)),
-    tool('studio_book','Reserve a declared booking slot. Accepts slot/time, resource/preferredResource, and addons/addOns as an array or quantity object. Supply a stable id, future expiresAt and a private token for an anonymous booking. Payment is separate.','public',bookingInputSchema,async(input,ctx)=>{
+    tool('studio_book','Reserve a declared booking slot. Accepts slot/time, resource/preferredResource, and addons/addOns as an array or quantity object. Give a future expiresAt and, when anonymous, a private random hex token. The returned data.id (hold_…) is the hold: pass it as hold to venue_booking_*, studio_holds and studio_checkout. Optional id is an idempotency key for retries, not the hold id. Payment is separate.','public',bookingInputSchema,async(input,ctx)=>{
       const args=normalizeBookingArgs(input),meta=cat.games.find(g=>g.id===args.app&&g.kind==='app'),spec=meta?.records?.collections?.[args.collection]?.booking;
       if(!spec)throw Object.assign(new Error('Unknown booking collection'),{name:'StudioOperationError'});
       const minutes=Number.isSafeInteger(spec.holdMinutes)&&spec.holdMinutes>0?Math.min(spec.holdMinutes,1440):15;
@@ -209,6 +209,14 @@ export function builtins(env,cat,origin) {
       await ctx.records({app:args.app,collection:spec.slots,id:args.slot});
       return ctx.bookings.hold(args);
     }),
+    tool('studio_holds','List your own booking holds (held or confirmed) with the private token you gave studio_book, or release them: release is a hold id from that list, or "all". Only that token\'s holds are ever shown or changed.','public',object({token:{type:'string',pattern:'^[a-f0-9]{32,128}$'},app:str,release:{type:'string',pattern:'^(all|hold_[a-f0-9]{48}|[a-f0-9]{64})$'},all:{type:'boolean',description:'Include ended holds.'}}),async({token,app,release,all},ctx)=>{
+      const holds=await ctx.bookings.mine({token,app,active:!all||Boolean(release)});
+      if(!release)return {holds};
+      const chosen=holds.filter(h=>release==='all'?h.state==='held':h.id===release);
+      if(release!=='all'&&!chosen.length)throw Object.assign(new Error('No active hold with this id for this token'),{name:'StudioOperationError',status:403,code:'hold_not_found'});
+      const released=[];for(const h of chosen)released.push(await ctx.bookings.release({id:h.id,token,version:h.version}));
+      return {released};
+    }),
     tool('app_records','List, read, create, update or delete app records with the app role and record version.','public',object({app:str,role:str,collection:{type:'string',pattern:'^[a-z][a-z0-9-]{0,39}$'},id:{type:'string',pattern:'^[A-Za-z0-9_-]{1,64}$',description:'1–64 letters, digits, underscore or hyphen'},operation:{enum:['read','create','update','delete']},data:{type:'object',propertyNames:{pattern:'^[a-z][a-z0-9_]*$'},description:'Field names start with a lowercase letter and use lowercase letters, digits and underscore; discover fields with app_schema.'},version:{type:'integer',minimum:1}},['app','collection']), (args,ctx)=>ctx.records(args)),
   ];
   for(const [name,path,description] of [

package/worker/mcp.mjs

@@ -159,7 +159,12 @@ export async function remoteMcp(request,env,ctx,{catalogueOf,definitions=[]}) {
             const value=await (await import('./app-tools.mjs')).invokeAppTool(tool,args,{...context,request});
             const text=JSON.stringify({kind:'untrusted-tool-data',tool:tool.name,data:value});
             outcome='ok';return {structuredContent:{kind:'untrusted-tool-data',tool:tool.name,data:value??null},content:[{type:'text',text}]};
-          }catch(error){if(error?.code===-32042)throw error;return {isError:true,content:[{type:'text',text:outcome==='denied'||outcome==='limited'||error?.name==='StudioOperationError'?error.message:(freshErrorMessage(error,env,caller))}]};}
+          }catch(error){if(error?.code===-32042)throw error;
+            const shown=outcome==='denied'||outcome==='limited'||error?.name==='StudioOperationError'||error?.message==='Input does not match the tool schema';
+            const message=shown?error.message:freshErrorMessage(error,env,caller);
+            // Stable, machine-readable refusal: {kind:'studio-error',error:{code,message,status}}. Codes only ever get added.
+            const code=typeof error?.code==='string'&&/^[a-z0-9_-]{1,64}$/.test(error.code)?error.code:outcome==='denied'?'forbidden':outcome==='limited'?'rate_limited':error?.message==='Input does not match the tool schema'?'invalid_input':error?.name==='StudioOperationError'?({400:'invalid_request',403:'forbidden',404:'not_found',409:'conflict'}[error.status]??'refused'):'internal_error';
+            return {isError:true,structuredContent:{kind:'studio-error',tool:tool?.name??null,error:{code,message,...(Number.isInteger(error?.status)?{status:error.status}:{}),...(shown&&error?.details&&typeof error.details==='object'?{details:error.details}:{})}},content:[{type:'text',text:message}]};}
           finally{
             try { await audit(env,caller,tool.name,outcome); }
             finally {

package/worker/version.mjs

@@ -1,2 +1,2 @@
 /** The @homie-rocks/studio version this Worker code is (package.json's; a test keeps them equal). Cache-busts /_homie/site.js. */
-export const STUDIO_VERSION_TAG = '0.58.21';
+export const STUDIO_VERSION_TAG = '0.58.23';