@homie-rocks/studio 0.40.0 → 0.42.0

package/CHANGELOG.md

@@ -17,6 +17,33 @@ 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.42.0] - 2026-10-09
+
+**Plugin 0.42.0**
+
+Customers and other businesses can use a studio's tools, buy its goods and services, and trigger its own functions.
+
+### Added
+
+- Customer catalogue, cart, checkout and agent purchases through the studio MCP server, using the existing payment standards and purchase lifecycle.
+- Priced studio tools and configurable built-in audiences, with current permissions checked when listing and calling.
+- Studio functions: plain-file event handlers, local firing, durable retries and office delivery status.
+
+### Changed
+
+- MCP call rates and shop purchase/guest-buyer rates are opt-in.
+
+### Fixed
+
+- Claim refunds use the same tip, used-item and window policy as the web shop. Guest carts create usable accounts before payment.
+- Builds fully regenerate Worker configuration, remove stale generated bindings and the old default purchase limiter, and keep explicit additions in `wrangler.custom.json`.
+- New functions skip history unless explicitly replayed; indexed subscriptions and cursors avoid unused events and prune completed delivery pages.
+- Paid tools renew execution leases, return saved results on retries and automatically refund failed handlers. Unpaid quotes expire and are pruned.
+
+### Upgrade notes
+
+- Run the toolkit upgrade and build, then commit the generated Worker configuration before deploying. Move hand-added Wrangler settings to root `wrangler.custom.json`; apply migrations 0018 and 0019 with the other studio migrations. Functions add a Cloudflare cron for retries only when declared.
+
 ## [0.40.0] - 2026-10-09
 
 **Plugin 0.40.0**

package/README.md

@@ -44,6 +44,17 @@ asks (`game new <id> --from gem-rush`, or `--from ember-vale` for a hero who las
 npx -y @homie-rocks/studio mcp --studios "<the folder the studios live in>"   # the toolkit as a local MCP server (stdio)
 ```
 
+Every studio also has its own customer-facing `/mcp`. Customers can browse, quote a cart,
+and pay through the same MPP/x402 purchase engine used for paid parts, or open the studio's
+Stripe checkout for human approval. Studio tools choose `public`, `signed-in`, an app staff
+role, or `owner`; a tool can sell its service with `price`. See [Studio tools](tools/TOOLS.md).
+
+[Studio functions](functions/FUNCTIONS.md) run your code when an order is paid or refunded,
+a player joins, a room closes, an app record changes, a tool is called, or a schedule fires.
+Add one with `homie-studio function new paid-order --event order.paid`; fire an event locally
+with `homie-studio function fire order.paid --input '{"order":"example"}'`. Deliveries persist,
+retry with the same event ID, and show failures in the office. Policies and rate limits are opt-in.
+
 The toolkit as MCP tools, so the chat that shows Homie's cards also does the work: the setup status, a new studio,
 the live demo, make / port / plan a game and its Game Codex, build, run it here, the two-browser check, a
 playtest, deploy, publish, the progress feed, the studio's files, and the music, sound, art and video scripts where

package/bin/homie-studio.mjs

@@ -155,6 +155,9 @@
  *   homie-studio servers new <game> "<Name>" --policy open|humans-only|hybrid|beginner [--ai <n>] [--guides <n>]
  *                                        [--kids] [--door open|accounts|invite] [--level 1-5] [--level-max 1-5]
  *                                        [--speech game|lines|off] [--bots fill|off] [--rooms <n>] [--listed on|off]
+ *   homie-studio function new <name> [--event order.paid]
+ *   homie-studio function replay <name> --replay [--url <studio-site>]
+ *   homie-studio function fire <event> [--input <JSON>] [--id <event-id>] [--url <local-site>]
  *   homie-studio tool new <name> [--app <id>]
  *   homie-studio tool call <name> --input <JSON> [--url <site>] [--public]
  *   homie-studio servers set <game> <server> [the same flags]
@@ -489,9 +492,12 @@ function print(result) {
       lines.push(`R2 holds about ${sizeOf(result.inR2)} of this studio's media. ${result.cost}`, ...(result.warning ? [`Warning: ${result.warning}`] : []));
       break;
     }
+    case 'function new':
     case 'tool new':
       lines.push(result.file, result.next);
       break;
+    case 'function replay':
+    case 'function fire':
     case 'tool call':
     case 'tool list':
       lines.push(JSON.stringify(result.result, null, 2));
@@ -833,6 +839,7 @@ const OUTWARD_FLAGS = {
   'shop connect': ['url', 'managed', 'live', 'manual', 'renew', 'from-clipboard'], 'shop disconnect': ['url'], 'shop refund': ['url', 'reason', 'note', 'manual-transaction'], 'shop statements': ['url', 'period', 'send', 'cursor'],
   'agents pass': ['url', 'label', 'server', 'hands', 'role', 'days'], 'agents revoke': ['url'], 'agents brain': ['url', 'budget', 'remove'],
   'agents sit': ['url', 'server', 'pass', 'label', 'brain'],
+  'function replay': ['url','replay'], 'function new': ['event'], 'function fire': ['url','input','id'],
   'tool new': ['app'], 'tool call': ['url', 'input', 'public'], 'tool list': ['url', 'public'],
   // With --device it adds a phone to the person's Apple team and installs on it: a flag it does not know stops it.
   'standalone run': ['for', 'device', 'site'],
@@ -894,6 +901,7 @@ async function main() {
   // The starter library and the optimiser work anywhere; the rest of style and assets inside a studio (lib/art-cli.mjs).
   if (cmd === 'assets' && ['find', 'optimise', 'optimize'].includes(sub)) return assetsCommand(null, sub, positional, flags, { log });
   const root = requireStudio();
+  if (cmd === 'function') return (await import('../lib/functions-cli.mjs')).functionCommand(root, sub, positional, flags, { log });
   if (cmd === 'tool') return (await import('../lib/tools-cli.mjs')).toolCommand(root, sub, positional, flags, { log });
   // A trailer is the plugin's video skill; this hands the words after the id over to it (lib/trailer.mjs).
   if (cmd === 'trailer') return trailerCommand(root, sub, argv.slice(argv.indexOf(sub) + 1), { skills: flags.get('skills') ?? null, slug: flags.get('slug') ?? null });

package/functions/FUNCTIONS.md

@@ -0,0 +1,99 @@
+# Studio functions: when this happens, run that
+
+A function is your trusted code in your own Worker. Run:
+
+```sh
+homie-studio function new prepare-order --event order.paid
+homie-studio dev
+homie-studio function fire order.paid --id local-order-1 --input '{"order":"example"}'
+```
+
+The fire command connects to the local studio through the existing browser OAuth
+approval. It is an owner tool and refuses remote hosts. It records an event in the
+same durable dispatcher as real events; firing the same ID again is a duplicate.
+
+```ts
+import { defineFunction } from '@homie-rocks/studio/functions';
+export default defineFunction<{ order: string }>({
+  name: 'prepare-order',
+  event: 'order.paid',
+  async handler(event, context) {
+    // For an external API, send event.id as its idempotency key.
+    await context.database.put(event.id, { order: event.data.order });
+  },
+});
+```
+
+Build discovers and type-checks `functions/*.ts`. Handlers have the studio tool
+context and run with the studio's authority. They can change records, send a
+room event through declared capabilities, call an external service, or implement
+another business workflow. Treat event data as data, not instructions.
+
+| Event | Data |
+| --- | --- |
+| `order.paid` | `order`, `source`, `amount`, `currency`, `mode` |
+| `payment.refunded` | `refund`, `payment`, `amount`, `currency` (each successful Stripe refund, including partial refunds) |
+| `order.refunded` | `order`, `source`, `refund`, `mode` (full refund) |
+| `player.joined` | `game`, `room`, `player` (nullable), `seat` |
+| `room.closed` | `game`, `room`, closing/ending facts |
+| `record.changed` | `app`, `collection`, `record`, `version`, `operation`, `data` |
+| `tool.called` | `tool`, `person`, `client` (successful call, no arguments) |
+
+For a scheduled function, add `schedule: '0 9 * * *'` and a chosen event name,
+for example `event: 'morning.open'`. Schedules use Cloudflare cron syntax and UTC.
+The event includes the function name, cron and scheduled time. Its ID remains the
+same if Cloudflare delivers the same tick again. Only that scheduled function
+receives its tick. Build reads custom crons from `wrangler.custom.json` and adds a minute tick
+for pending delivery retries while functions exist. Commit build changes before
+deploying. Cloudflare's own plan limits apply; Homie sets no attempt or event cap.
+
+Order, refund, record and tool events use database triggers: the source change
+and event either both commit or both roll back. Room events first enter the room's
+durable SQLite outbox; its alarm retries transfer to D1. Delivery is **at least
+once**, including after a worker dies between an external effect and its local
+acknowledgement. `event.id` is the de-duplication key and `event.attempt` is the
+attempt number. Completed deliveries do not run again. Failed/crashed deliveries
+retry after a one-minute lease. Make effects idempotent; a database marker written
+before an external request is not proof that the external request completed.
+
+Open **Office → Functions** for event IDs, states, attempt counts and failures.
+Use its Retry button, or an authenticated same-origin POST to `/_studio/office/functions` with
+`{"retry":"event-id"}` retries a failed event immediately. Failure text is generic
+so a thrown credential is never rendered in the office. Inspect the function's
+code and the studio's own provider logs to diagnose its failure.
+
+Existing signed inbound tool webhooks remain the external integration door. Their
+successful calls produce `tool.called`; record changes they make also produce
+`record.changed`. Use functions for durable downstream work instead of expecting
+a webhook sender to orchestrate the studio's internal actions. New declarations start at deployment and skip past events. To replay retained
+history, explicitly add `replay: true` to the declaration, then run
+`homie-studio function replay <name> --replay --url https://your-studio.example`.
+The owner OAuth connection is required. Merely adding `replay: true` does not run
+history. Fully delivered events are pruned; replay cannot recover pruned events.
+Only declared event types are recorded. Each function has an indexed sequence
+cursor; dispatch and maintenance use pages of 100, with no event or retry cap.
+
+
+Worker configuration is generated at build and upgrade time from `studio.json`,
+shop and tool declarations, game files, and function declarations. Commit the
+build before deploy. Put custom bindings, variables, aliases, routes, crons or
+observability settings in root `wrangler.custom.json` (plain JSON); objects merge
+recursively and arrays replace generated arrays. Do not hand-edit the generated
+`wrangler.jsonc`. Move existing manual additions into that file before upgrading.
+`studio.json.cloudflare.ai` explicitly enables/disables AI; otherwise game
+chat/decision declarations determine it. Set `cloudflare.routes` for routes and
+`cloudflare.purchaseRateLimit` for an explicitly chosen Wrangler rate-limit
+binding. An old generated purchase limiter is removed unless explicitly set.
+
+Machine cart quotes bind an account before payment. Anonymous buyers receive
+`account.player` and private `account.cookies`; retain the cookie and send its
+name/value as the Cookie header to this studio to use the grants. These credentials
+are returned only to the quoting caller, never embedded in the public offer.
+Guest limits are checked at quote time using the incoming request address.
+Quotes expire after 24 hours; paid orders retain their independent snapshots.
+
+Paid handlers renew their execution lease while running. Retries share the first
+result and never rerun an abandoned handler. A failed or abandoned run requests an
+automatic Stripe refund; retries report completion or continue refund recovery.
+Paid services require the studio's refundable Stripe connection; chain settlement
+is not offered for services. Handler errors never expose their private contents.

package/functions/functions.ts

@@ -0,0 +1,13 @@
+import type { ToolContext, StudioTool } from '../tools/tools';
+export interface StudioEvent<Data = unknown> { readonly id: string; readonly type: string; readonly at: number; readonly data: Data; readonly attempt: number }
+export interface StudioFunction<Data = unknown> {
+  name: string;
+  event: string;
+  /** Cloudflare cron expression; scheduled events are named by this function. */
+  schedule?: string;
+  /** Permit an explicit owner replay command to consume retained history. */
+  replay?: boolean;
+  events?: StudioTool['events'];
+  handler(event: StudioEvent<Data>, context: ToolContext): unknown | Promise<unknown>;
+}
+export function defineFunction<Data = unknown>(definition: StudioFunction<Data>): StudioFunction<Data> { return definition; }

package/lib/build.mjs

@@ -492,6 +492,7 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
   const esbuild = await studioEsbuild(root);
   const studio = readStudio(root);
   await (await import('./tools-build.mjs')).buildTools(root, esbuild);
+  await (await import('./functions-build.mjs')).buildFunctions(root, esbuild);
   // The shop first (shop/SHOP.md): invalid shop settings stop the build before anything is built.
   const shop = shopForBuild(root, { log });
   const live = join(root, 'site', 'dist');

package/lib/cloudflare.mjs

@@ -1,3 +1,4 @@
+import { refreshWorkerConfig } from './worker-config.mjs';
 import { paidReleases, uploadPaidParts } from './parts-upload.mjs';
 /**
  * `homie-studio deploy` — the studio's site on the studio's OWN Cloudflare
@@ -41,7 +42,7 @@ import { MAX_ASSET_BYTES, R2_COST, mediaPlan, r2OverOf, recordMove, sha256File,
 import { whyFailed } from './net.mjs';
 import { repoOf } from './repo.mjs';
 import { keptRoutes, readConfig, readZoneRoutes, routesOf, shadowedDomain, wideRouteRefusal, zoneFinding } from './routes.mjs';
-import { ensureLocalIgnored, ensureMigrations, migrationWord, wranglerConfig } from './scaffold.mjs';
+import { ensureLocalIgnored, ensureMigrations, migrationWord } from './scaffold.mjs';
 import { LOCAL_STATE, configPath, domainOrigin, isRulesGame, isWorkersDev, layoutOf, listExperiences as listGames, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
 import { projectsCloudflareEnv } from './projects-env.mjs';
 
@@ -240,7 +241,6 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   const wide = wideRouteRefusal(readConfig(root), studio);
   if (wide) return { ok: false, command: 'deploy', ...wide };
   let routes = keptRoutes(root, studio);
-  const triggers = readConfig(root)?.triggers;
   const who = whoami(root);
   if (!who) {
     if (cf.auth === 'stripe-projects') {
@@ -277,6 +277,9 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   if (zone) {
     if (ownRoute && zone.state === 'foreign') {
       routes = [...(routes ?? []), zone.route];
+      const customFile=join(root,'wrangler.custom.json');
+      const custom=existsSync(customFile)?JSON.parse(readFileSync(customFile,'utf8')):{};
+      writeFileSync(customFile,JSON.stringify({...custom,routes},null,2)+'\n');
       step(`added the studio's own exact-host route to "routes" in wrangler.jsonc: ${zone.line}. It covers ${zone.host} only, and every deploy keeps it; the other site's route was not touched.`, { route: zone.route });
       const config = readConfig(root) ?? {};
       zone = await zoneCheck(root, { studio, accountId, fetchFn, config: { ...config, routes: [...routesOf(config), zone.route] } });
@@ -368,17 +371,14 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   const r2 = storage;
   if (!r2) step('no storage (R2): the studio needs none to run; `homie-studio storage add` adds it for large media');
 
-  writeFileSync(configPath(root), wranglerConfig({ partsRateLimit: readConfig(root)?.ratelimits?.find((binding) => binding.name === 'PURCHASE_RATE_LIMITER'), paidParts: paidReleases(root).length > 0 || readConfig(root)?.alias?.['@homie-rocks/studio/worker'] === '@homie-rocks/studio/worker/selling', worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root), routes, triggers }));
+  refreshWorkerConfig(root, {d1Id: db.uuid});
   if (routes) step(`kept the studio's own route${routes.length === 1 ? '' : 's'} in wrangler.jsonc: ${routes.map((r) => r.pattern).join(', ')}`);
   for (const added of ensureMigrations(root)) step(`added ${added} (${migrationWord(added)})`);
   const migrate = w(['d1', 'migrations', 'apply', cf.d1, '--remote']);
   if (migrate.code !== 0) return refuse(`D1 migrations failed: ${migrate.out.trim().split('\n').slice(-4).join(' ')}`, migrate.out);
   step('D1 migrations applied');
-  // Workers AI (0.17.0): bound only when a server's AI guides think with it.
-  if (needsWorkersAi(root, w, cf.d1)) {
-    writeFileSync(configPath(root), wranglerConfig({ partsRateLimit: readConfig(root)?.ratelimits?.find((binding) => binding.name === 'PURCHASE_RATE_LIMITER'), paidParts: paidReleases(root).length > 0 || readConfig(root)?.alias?.['@homie-rocks/studio/worker'] === '@homie-rocks/studio/worker/selling', worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root), ai: true, routes, triggers }));
-    step('Workers AI bound (AI): a server\'s AI guides think with it and typed room chat is reviewed with it, each within its day\'s budget (free allocation: 10,000 neurons a day)');
-  }
+  const subscriptions=w(['d1','execute',cf.d1,'--remote','--command',(await import('./functions-build.mjs')).functionDeploymentSQL(root)]);
+  if(subscriptions.code!==0)return refuse('Could not register studio functions',subscriptions.out);
 
   const started = Date.now();
   let dep = w(['deploy', ...repoVar(root)]);
@@ -680,7 +680,7 @@ export async function storageAdd(root, { log = () => {} } = {}) {
   writeStudio(root, next);
   if (next.cloudflare.d1Id) {
     // The studio's own routes stay through this rewrite too (lib/routes.mjs).
-    writeFileSync(configPath(root), wranglerConfig({ partsRateLimit: readConfig(root)?.ratelimits?.find((binding) => binding.name === 'PURCHASE_RATE_LIMITER'), paidParts: paidReleases(root).length > 0 || readConfig(root)?.alias?.['@homie-rocks/studio/worker'] === '@homie-rocks/studio/worker/selling', worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: next.cloudflare.d1Id, r2: bucket, layout: layoutOf(root), routes: keptRoutes(root, studio) }));
+    refreshWorkerConfig(root);
   }
   log(`created R2 ${bucket}`);
   return { ok: true, command: 'storage add', bucket, account: accountId, cost: R2_COST, next: ['npx --no-install homie-studio media move --dry-run   (which songs and videos go to R2: over 1 MiB, or left out of git)', 'npm run deploy   (binds the bucket as MEDIA, moves them, checks each by SHA-256, and serves them from R2 at the same addresses; the files stay in this folder)'] };

package/lib/dev.mjs

@@ -459,8 +459,9 @@ export async function dev(root, { lan = false, port: askedPort = 8787, remoteAi
       return;
     }
   };
+  const { functionFiles } = await import('./functions-build.mjs');
   const { toolFiles } = await import('./tools-build.mjs');
-  const toolsStamp = () => toolFiles(root).map(file => `${file}:${statSync(file).mtimeMs}:${statSync(file).size}`).join('|');
+  const toolsStamp = () => [...toolFiles(root),...functionFiles(root)].map(file => `${file}:${statSync(file).mtimeMs}:${statSync(file).size}`).join('|');
   let lastTools = toolsStamp();
   const toolsLook = async () => {
     if (rebuilding || ending) return;

package/lib/functions-build.mjs

@@ -0,0 +1,36 @@
+import {existsSync,readdirSync,mkdirSync,writeFileSync,readFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {createRequire} from 'node:module';
+const require=createRequire(import.meta.url);
+export function functionFiles(root) { const dir=join(root,'functions');return existsSync(dir)?readdirSync(dir).filter(f=>/^[a-z][a-z0-9-]*\.ts$/.test(f)).sort().map(f=>join(dir,f)):[]; }
+export async function buildFunctions(root,esbuild) {
+  const files=functionFiles(root),dir=join(root,'site/src/functions');mkdirSync(dir,{recursive:true});
+  if(files.length) {
+    const ts=require('typescript'),options={target:ts.ScriptTarget.ES2022,module:ts.ModuleKind.ESNext,moduleResolution:ts.ModuleResolutionKind.Bundler,strict:true,noEmit:true,skipLibCheck:true};
+    const errors=ts.getPreEmitDiagnostics(ts.createProgram(files,options));
+    if(errors.length)throw new Error(ts.formatDiagnosticsWithColorAndContext(errors,{getCurrentDirectory:()=>root,getCanonicalFileName:f=>f,getNewLine:()=> '\n'}));
+  }
+  const contents=files.map((f,i)=>`import f${i} from ${JSON.stringify(f)};`).join('\n')+`\nexport default [${files.map((_,i)=>'f'+i).join(',')}];`;
+  const built=await esbuild.build({stdin:{contents,resolveDir:root},bundle:true,format:'esm',platform:'neutral',write:false,logLevel:'silent'});
+  const file=join(dir,'index.mjs');writeFileSync(file,built.outputFiles[0].text);
+  const definitions=(await import(pathToFileURL(file).href+'?build='+Date.now())).default;
+  const names=new Set();
+  for(const fn of definitions) {
+    if(!/^[a-z][a-z0-9-]*$/.test(fn.name)||names.has(fn.name)||typeof fn.handler!=='function'||typeof fn.event!=='string'||!fn.event.trim())throw new Error('Function needs a unique name, event and handler');
+    if(fn.schedule && (typeof fn.schedule!=='string'||fn.schedule.trim().split(/\s+/).length!==5))throw new Error('Function schedule needs a Cloudflare cron expression');
+    names.add(fn.name);
+  }
+  const worker=join(root,'site/src/worker.mjs');
+  if(existsSync(worker)) {let text=readFileSync(worker,'utf8');if(!text.includes('useFunctions(')){text+="\nimport { useFunctions } from '@homie-rocks/studio/worker';\nuseFunctions(async () => (await import('./functions/index.mjs')).default);\n";writeFileSync(worker,text);}}
+  writeFileSync(join(dir,'declarations.json'),JSON.stringify(definitions.map(({name,event,schedule,replay})=>({name,event,schedule,replay})),null,2)+'\n');
+  (await import('./worker-config.mjs')).refreshWorkerConfig(root);
+  return definitions;
+}
+/** Install subscriptions before the new Worker can produce its first event. */
+export function functionDeploymentSQL(root) {
+  const file=join(root,'site/src/functions/declarations.json');
+  const definitions=existsSync(file)?JSON.parse(readFileSync(file,'utf8')):[];
+  const literal=value=>"'"+String(value).replaceAll("'","''")+"'";
+  return [...definitions.map(fn=>`INSERT INTO function_subscriptions(name,type,cursor,started) VALUES(${literal(fn.name)},${literal(fn.event)},(SELECT COALESCE(MAX(seq),0) FROM studio_events),unixepoch()*1000) ON CONFLICT(name) DO UPDATE SET type=excluded.type,cursor=excluded.cursor,started=excluded.started WHERE type!=excluded.type;`),`DELETE FROM function_subscriptions WHERE name NOT IN (${definitions.map(fn=>literal(fn.name)).join(',')||"''"});`,"INSERT INTO meta(key,value) VALUES('function-registry-deployed','1') ON CONFLICT(key) DO UPDATE SET value='1';"].join(' ');
+}

package/lib/functions-cli.mjs

@@ -0,0 +1,23 @@
+import {existsSync,mkdirSync,writeFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {connectToolClient} from './tools-cli.mjs';
+export async function functionCommand(root,sub,positional,flags,{log=()=>{}}={}) {
+  if(sub==='new') {
+    const name=positional[2],event=flags.get('event')??'order.paid';
+    if(!/^[a-z][a-z0-9-]*$/.test(name??''))throw new Error('Use a lowercase function name');
+    const file=join(root,'functions',name+'.ts');if(existsSync(file))throw new Error('Function already exists');
+    mkdirSync(join(root,'functions'),{recursive:true});
+    writeFileSync(file,`import { defineFunction } from '@homie-rocks/studio/functions';\nexport default defineFunction({\n  name: ${JSON.stringify(name)}, event: ${JSON.stringify(event)},\n  async handler(event, context) {\n    // Deduplicate external side effects with event.id (for example an API idempotency key).\n    await context.database.put(event.id, event.data);\n  },\n});\n`);
+    return {ok:true,command:'function new',file,next:'Edit your function, then run homie-studio dev.'};
+  }
+  if(sub==='replay') {
+    if(!flags.has('replay'))throw new Error('Pass --replay to explicitly request retained history');
+    const client=await connectToolClient(root,new URL(flags.get('url')??'http://localhost:8787'),{log});
+    try {const result=await client.callTool({name:'studio_function_replay',arguments:{name:positional[2]}});return {ok:!result.isError,command:'function replay',result};}finally{await client.close();}
+  }
+  if(sub!=='fire')throw new Error('Use function new <name> --event <event>, or function fire <event> --input <JSON>');
+  const url=new URL(flags.get('url')??'http://localhost:8787');
+  if(!['localhost','127.0.0.1','[::1]'].includes(url.hostname))throw new Error('Fire is local testing only');
+  const client=await connectToolClient(root,url,{log});
+  try {const result=await client.callTool({name:'studio_function_fire',arguments:{event:positional[2],data:JSON.parse(flags.get('input')??'{}'),...(flags.has('id')?{id:flags.get('id')}: {})}});return {ok:!result.isError,command:'function fire',result};}finally{await client.close();}
+}

package/lib/purchase-links.mjs

@@ -1,3 +1,5 @@
+import {pathToFileURL} from 'node:url';
+import {serviceTerms} from '../worker/service-terms.mjs';
 /** Uses the shop's authorized Stripe API transport; no API credential goes to the Worker. */
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
@@ -13,6 +15,12 @@ export async function syncPurchaseLinks({ root, api, slug, site, mode, list, til
     const p = readPart(packedDir(root,id,version)), config = settings[id], selected = config?.releases?.[version];
     return p.sale && config?.active !== false && selected?.active !== false && (version === versions.at(-1) || selected?.keepOnSale === true) ? [{kind:'part',resource:id,version,name:part.name,sale:{...p.sale,...config?.price}}] : [];
   }));
+  const {toolFiles,buildTools}=await import('./tools-build.mjs');
+  if(toolFiles(root).length){
+    await buildTools(root,await import('esbuild'));
+    const definitions=(await import(pathToFileURL(join(root,'site/src/tools/index.mjs')).href+'?links='+Date.now())).default;
+    offers.push(...definitions.filter(t=>t.price).map(t=>({kind:'service',resource:t.name,version:'1.0.0',name:t.description,sale:serviceTerms(t.price)})));
+  }
   const configured = offers.flatMap(o => {
     const quantities = settings[o.resource]?.quantities ?? [1];
     if (!Array.isArray(quantities) || !quantities.length || quantities.some(q=>!Number.isSafeInteger(q) || q<1 || !Number.isSafeInteger(q*o.sale.amount))) throw new Error(`Invalid Payment Link quantities for ${o.resource}`);

package/lib/scaffold.mjs

@@ -1,3 +1,4 @@
+import { FUNCTIONS_MIGRATION, FUNCTIONS_MIGRATION_FILE, FUNCTIONS_CURSOR_MIGRATION, FUNCTIONS_CURSOR_MIGRATION_FILE } from '../worker/functions-schema.mjs';
 import { MCP_MIGRATION, MCP_MIGRATION_FILE } from '../worker/mcp-store.mjs';
 import { APPS_MIGRATION, APPS_MIGRATION_FILE } from '../worker/app-records.mjs';
 import { PURCHASE_MIGRATION, PURCHASE_MIGRATION_FILE, PURCHASE_STATE, PURCHASE_STATE_FILE } from '../worker/purchase-schema.mjs';
@@ -83,7 +84,7 @@ export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layou
     // later). A game's rules run in this Worker (NETPLAY.md section 29), and nothing in them is ever made from text.
     no_bundle: true, find_additional_modules: true, rules: [{ type: 'ESModule', globs: ['**/*.js'], fallthrough: true }],
     compatibility_flags: ['nodejs_compat', 'global_fetch_strictly_public', 'disallow_eval_during_startup'],
-    ...(paidParts ? { alias: { '@homie-rocks/studio/worker': '@homie-rocks/studio/worker/selling' }, triggers: { crons: ['*/5 * * * *'] }, ratelimits: [partsRateLimit ?? { name: 'PURCHASE_RATE_LIMITER', namespace_id: '1001', simple: { limit: 60, period: 60 } }] } : {}),
+    ...(paidParts ? { alias: { '@homie-rocks/studio/worker': '@homie-rocks/studio/worker/selling' }, triggers: { crons: ['*/5 * * * *'] }, ...(partsRateLimit ? { ratelimits: [partsRateLimit] } : {}) } : {}),
     workers_dev: true,
     preview_urls: true,
     // The studio's own custom-domain and exact-host routes, as its owner wrote them: this file is written again by
@@ -154,7 +155,7 @@ An app is ONE screen that morphs with context: camera moves, panels unfold, its
 
 Declare roles, surfaces, words and lasting record collections in app.json. Netplay's host is not a staff permission. Use \`@homie-rocks/studio/apps\` for authorized lasting records and \`@homie-rocks/studio/links\` for ticket links, QR and HTTP-safe IDs. Staff use private role links plus existing account grants; keep private records out of public collections. Look for engine mechanisms and shared parts before writing a component. Credit licences; sharing is optional and separate from selling.
 
-Your studio also serves MCP at \`/mcp\`. Staff connect their own AI with their existing account and one browser approval; never ask them for a key. Add business actions with \`homie-studio tool new <name> --app <id>\`, keep their declared role narrow, and reuse the app's existing record IDs, field formats and versions. Test owner, staff and public calls locally. Read \`node_modules/@homie-rocks/studio/tools/TOOLS.md\` and the Homie plugin's \`tools\` skill.
+Your studio also serves MCP at \`/mcp\`. Staff connect their own AI with their existing account and one browser approval; never ask them for a key. Add business actions with \`homie-studio tool new <name> --app <id>\`, keep their declared role narrow, and reuse the app's existing record IDs, field formats and versions. Customers can browse and buy through this same endpoint, and tools may declare a price using the studio's existing payments. Add event handlers with \`homie-studio function new <name> --event order.paid\`; read \`node_modules/@homie-rocks/studio/functions/FUNCTIONS.md\`. Test owner, staff and public calls locally. Read \`node_modules/@homie-rocks/studio/tools/TOOLS.md\` and the Homie plugin's \`tools\` skill.
 
 Build normally, run \`homie-studio dev --lan\`, then \`homie-studio check <id> --url <origin>\`: the app check proves an actual action across a wall and two phones plus reconnect. The public screen is \`/<id>/open\`, the wall \`/<id>/tv\`. Customer apps use the same \`standalone\` build for desktop/iOS/Android; its existing sign-in and store limitations still apply. See \`node_modules/@homie-rocks/studio/apps/APPS.md\`.
 
@@ -763,6 +764,8 @@ export { default, Table, Lobby } from '@homie-rocks/studio/worker';
     [`site/migrations/${SHOP_LINES_FILE}`]: SHOP_LINES,
     [`site/migrations/${APPS_MIGRATION_FILE}`]: APPS_MIGRATION,
     [`site/migrations/${MCP_MIGRATION_FILE}`]: MCP_MIGRATION,
+    [`site/migrations/${FUNCTIONS_MIGRATION_FILE}`]: FUNCTIONS_MIGRATION,
+    [`site/migrations/${FUNCTIONS_CURSOR_MIGRATION_FILE}`]: FUNCTIONS_CURSOR_MIGRATION,
     [`site/migrations/${LOUNGE_MIGRATION_FILE}`]: LOUNGE_MIGRATION,
     'wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2, layout: 'root' }),
     '.claude/skills/.gitkeep': '',
@@ -934,13 +937,23 @@ function ensurePartsStateMigration(root) {
   return `site/migrations/${PURCHASE_STATE_FILE}`;
 }
 
+function ensureFunctionCursors(root) {
+  const file=join(root,'site','migrations',FUNCTIONS_CURSOR_MIGRATION_FILE);
+  if(existsSync(file))return null;
+  mkdirSync(dirname(file),{recursive:true});writeFileSync(file,FUNCTIONS_CURSOR_MIGRATION);return `site/migrations/${FUNCTIONS_CURSOR_MIGRATION_FILE}`;
+}
+function ensureFunctionsMigration(root) {
+  const file=join(root,'site','migrations',FUNCTIONS_MIGRATION_FILE);
+  if(existsSync(file))return null;
+  mkdirSync(dirname(file),{recursive:true});writeFileSync(file,FUNCTIONS_MIGRATION);return `site/migrations/${FUNCTIONS_MIGRATION_FILE}`;
+}
 function ensureMcpMigration(root) {
   const file=join(root,'site','migrations',MCP_MIGRATION_FILE);
   if(existsSync(file))return null;
   mkdirSync(dirname(file),{recursive:true});writeFileSync(file,MCP_MIGRATION);return `site/migrations/${MCP_MIGRATION_FILE}`;
 }
 export function ensureMigrations(root) {
-  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopStatements(root), ensureShopLines(root), ensureAppsMigration(root), ensurePartsMigration(root), ensurePartsStateMigration(root), ensureMcpMigration(root)].filter(Boolean);
+  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopStatements(root), ensureShopLines(root), ensureAppsMigration(root), ensurePartsMigration(root), ensurePartsStateMigration(root), ensureMcpMigration(root), ensureFunctionsMigration(root), ensureFunctionCursors(root)].filter(Boolean);
 }
 
 /** What a migration file the template added is for, in a few words (deploy and dev say it). */

package/lib/shop.mjs

@@ -287,7 +287,7 @@ export async function shopConnectManual(root, { fromClipboard = false, clipboard
   const shopNow = readShop(root);
   const till = managed === true ? 'stripe-managed' : managed === false ? 'stripe' : shopNow.shop?.till ?? 'stripe';
   const nonce = randomBytes(16).toString('hex');
-  const paidParts = paidReleases(root).length > 0;
+  const paidParts = paidReleases(root).length > 0 || (shopNow.shop?.items?.length??0)>0 || (await import('./tools-build.mjs')).toolFiles(root).length>0;
   const page = connectPage({ paidParts, nonce, site, studio: studio.name ?? 'Your studio', till, test: !live });
   return await new Promise((done) => {
     let finished = false;

package/lib/template-history.json

@@ -2238,6 +2238,50 @@
      }
     }
    }
+  },
+  "0.42.0": {
+   "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": "732894273a32dc3f",
+    "site/src/worker.mjs": "34444a6ca4b14437"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "c18362ed28975d81",
+     "## Apps: one screen, roles and parts": [
+      "8596f2b25edda3e2",
+      "be6f8fa45f93211a"
+     ],
+     "## Commands (all through the pinned CLI in node_modules)": "a7f290579585368c",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "2da7fa74c8884834",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": "9e020d69dd6a954e",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "2e6b29afb85dcf7e",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "7cad8fd10f62fef1"
+      }
+     }
+    }
+   }
   }
  }
 }

package/lib/tools-build.mjs

@@ -38,6 +38,7 @@ export async function buildTools(root,esbuild) {
     if(!['owner','signed-in','public'].includes(t.audience)&&!(t.audience&&typeof t.audience.app==='string'&&typeof t.audience.role==='string'))throw new Error(`tool ${t.name} needs an audience`);
     if(t.inputSchema?.type!=='object')throw new Error(`tool ${t.name} input schema must be an object`);
     validator.getValidator(t.inputSchema);
+    if(t.price && (t.kind==='prompt'||!Number.isSafeInteger(t.price.amount)||t.price.amount<=0||! /^[a-z]{3}$/.test(t.price.currency)))throw new Error(`tool ${t.name}: price needs a positive minor-unit amount and currency`);
     if(t.kind!==undefined&&!['tool','prompt'].includes(t.kind))throw new Error(`tool ${t.name}: invalid kind`);
     if(t.webhook&&(!/^[A-Z][A-Z0-9_]{0,63}$/.test(t.webhook.secret)||typeof t.webhook.person!=='string'||!t.webhook.person))throw new Error(`tool ${t.name}: webhook needs a named secret and account`);
     for(const [name,event] of Object.entries(t.events??{})){
@@ -51,5 +52,6 @@ export async function buildTools(root,esbuild) {
     let text=readFileSync(worker,'utf8');
     if(!text.includes('useTools(')){text += "\nimport { useTools } from '@homie-rocks/studio/worker';\nuseTools(async () => (await import('./tools/index.mjs')).default);\n";writeFileSync(worker,text);}
   }
+  writeFileSync(join(dir,'declarations.json'),JSON.stringify({paid:defs.some(t=>t.price)})+'\n');
   return defs.map(t=>t.name);
 }

package/lib/upgrade.mjs

@@ -1,3 +1,4 @@
+import {refreshWorkerConfig} from './worker-config.mjs';
 /**
  * `homie-studio upgrade [--apply] [--diff]` — an existing studio takes what this version's template adds, and
  * nothing it made its own is ever overwritten.
@@ -346,6 +347,7 @@ export function upgradeApply(root, plan) {
     }
     if (text !== null && (!existsSync(path) || readFileSync(path, 'utf8') !== text)) writeAtomic(path, text);
   }
+  refreshWorkerConfig(root);
   const pinned = done.some((c) => c.kind === 'pin');
   return {
     ...plan, applied: true, done, skipped,

package/lib/worker-build.mjs

@@ -1,34 +1,22 @@
-import {existsSync,mkdirSync,readFileSync,writeFileSync,rmSync} from 'node:fs';
-import {join,relative,dirname} from 'node:path';
+import {refreshWorkerConfig} from './worker-config.mjs';
+import {pathToFileURL} from 'node:url';
+import {existsSync,mkdirSync,writeFileSync,rmSync} from 'node:fs';
+import {join,relative} from 'node:path';
 import {readConfig} from './routes.mjs';
 import {paidReleases} from './parts-upload.mjs';
-import {configPath} from './studio.mjs';
 /** Preserve dynamic imports as real Worker modules: page startup never evaluates MCP libraries. */
 export async function buildWorker(root,esbuild) {
   const source=join(root,'site/src/worker.mjs');if(!existsSync(source))return;
   const out=join(root,'site/src/runtime');
+  refreshWorkerConfig(root);
   const alias={...(readConfig(root)?.alias??{})};
-  if(paidReleases(root).length)alias['@homie-rocks/studio/worker']='@homie-rocks/studio/worker/selling';
+  const toolModule=join(root,'site/src/tools/index.mjs');
+  const pricedTools=existsSync(toolModule) && (await import(pathToFileURL(toolModule).href+'?worker='+Date.now())).default.some(tool=>tool.price);
+  if(paidReleases(root).length || existsSync(join(root,'shop.json')) || pricedTools)alias['@homie-rocks/studio/worker']='@homie-rocks/studio/worker/selling';
   const result=await esbuild.build({entryPoints:[source],absWorkingDir:root,alias,outdir:out,bundle:true,splitting:true,format:'esm',platform:'browser',mainFields:['module','main'],conditions:['workerd','worker','browser'],external:['node:*','cloudflare:*'],target:'es2022',write:false,minify:true,metafile:true,logLevel:'silent'});
   rmSync(out,{recursive:true,force:true});
   mkdirSync(out,{recursive:true});
   for(const file of result.outputFiles)writeFileSync(file.path,file.contents);
-  const config=configPath(root);
-  if(existsSync(config)){
-    const original=readFileSync(config,'utf8');
-    const json=JSON.parse(original.replace(/^\s*\/\/.*$/gm,''));
-    const before=JSON.stringify(json);
-    json.main=relative(dirname(config),join(out,'worker.js')).split('\\').join('/');
-    json.no_bundle=true;json.find_additional_modules=true;
-    json.rules=[...(json.rules??[]).filter(r=>!r.homieMcp),{type:'ESModule',globs:['**/*.js'],fallthrough:true}];
-    // No duplicate rule on rebuild.
-    json.rules=json.rules.filter((r,i,all)=>all.findIndex(x=>JSON.stringify(x)===JSON.stringify(r))===i);
-    json.compatibility_flags=[...new Set([...(json.compatibility_flags??[]),'nodejs_compat'])];
-    if(JSON.stringify(json)!==before) {
-      const comments=original.match(/^(?:\s*\/\/[^\n]*\n)*/)?.[0]??'';
-      writeFileSync(config,comments+JSON.stringify(json,null,2)+'\n');
-    }
-  }
   const sizes=Object.entries(result.metafile.outputs).map(([path,value])=>({path:relative(root,path),bytes:value.bytes,imports:value.imports}));
   writeFileSync(join(out,'modules.json'),JSON.stringify(sizes,null,2)+'\n');
   return sizes;

package/lib/worker-config.mjs

@@ -0,0 +1,28 @@
+import {readFileSync,writeFileSync,existsSync} from 'node:fs';
+import {join} from 'node:path';
+import {configPath,readStudio,layoutOf,listExperiences} from './studio.mjs';
+import {wranglerConfig} from './scaffold.mjs';
+import {paidReleases} from './parts-upload.mjs';
+const parse=t=>JSON.parse(t.replace(/^\s*\/\/.*$/gm,''));
+const read=file=>existsSync(file)?parse(readFileSync(file,'utf8')):{};
+function merge(base,custom) {
+  if(Array.isArray(custom))return custom;
+  if(custom && typeof custom==='object')return Object.fromEntries([...new Set([...Object.keys(base??{}),...Object.keys(custom)])].sort().map(k=>[k,k in custom?merge(base?.[k],custom[k]):base[k]]));
+  return custom;
+}
+/** Generated output is never an input. Studio additions belong in wrangler.custom.json. */
+export function updateWorkerConfig(root,generated) {
+  const file=configPath(root),next=merge(parse(generated),read(join(root,'wrangler.custom.json')));
+  const text='// Generated by homie-studio. Edit studio.json or wrangler.custom.json, then build.\n'+JSON.stringify(next,null,2)+'\n';
+  if(!existsSync(file)||readFileSync(file,'utf8')!==text)writeFileSync(file,text);
+}
+export function refreshWorkerConfig(root,overrides={}) {
+  const studio=readStudio(root),cf=studio.cloudflare;
+  if(!cf?.worker)return;
+  const metadata=read(join(root,'site/src/functions/declarations.json'));
+  const functions=Array.isArray(metadata)?metadata:[];
+  const tools=read(join(root,'site/src/tools/declarations.json'));
+  const ai=cf.ai??listExperiences(root).some(g=>g.decide===true || g.chat!==false && (g.chat?.mode??'text')==='text' && g.chat?.ai!==false);
+  const paid=paidReleases(root).length>0||existsSync(join(root,'shop.json'))||tools.paid===true;
+  updateWorkerConfig(root,wranglerConfig({worker:cf.worker,name:studio.name,d1:cf.d1,d1Id:cf.d1Id,r2:cf.r2,layout:layoutOf(root),ai,paidParts:paid,partsRateLimit:cf.purchaseRateLimit??null,routes:cf.routes??null,triggers:functions.length?{crons:[...new Set(['* * * * *',...functions.map(f=>f.schedule).filter(Boolean)])].sort()}:null,...overrides}));
+}