@lampdotdev/lamp 0.35.0 → 0.36.2-nightly.16

package/Resources/GameKit/web/lamp-game.js

@@ -139,7 +139,10 @@ async function loadProblem(status) {
 export function work(path, message, transfer = []) {
     read(clean(path));
     return new Promise((done, fail) => {
-        const worker = new browser.Worker(`${addressOf(clean(path))}?lamp=${++versionCount}`, { type: 'module' });
+        // At the file's own address until something changes (`fresh`): a game starts its workers again and again, and a
+        // new address each time is a new request all the way to where the page is kept, which a shared link's host
+        // can't keep up with. After a change, the address changes with it, so the new version is the one that runs.
+        const worker = new browser.Worker(fresh(addressOf(clean(path))), { type: 'module' });
         worker.onmessage = e => { worker.terminate(); done(e.data); };
         worker.onerror = e => { worker.terminate(); fail(new Error(`${path}: ${e.message || 'the worker failed'}`)); };
         worker.postMessage(message, transfer);
@@ -985,6 +988,9 @@ let hooks = {}, started = false, waiting = null, pill = null;
 // the state didn't take.
 let pending = null, reopened = false, taken = false, guarding = false;
 const host = () => window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.lampLive;
+// That the page runs on this runtime, for lamp dev (cli/page.js): a game's page without it has `__lampLive` too
+// (lamp-live.js, which hands over to this runtime as it sets its own below).
+window.__lampRuntime = true;
 // Whether the game is past its loading screen, for the picture of the app Lamp's desk shows (`LampPagePlaying` in a Mac
 // app): 'loading' from when this runtime loads, 'playing' at the first frame of play.
 const tellPlaying = state => { try { const h = window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.lampPlaying; h && h.postMessage(state); } catch (e) {} };

package/Resources/share-rules.json

@@ -0,0 +1,64 @@
+{
+  "about": "What a Lamp app file may hold, read by Lamp's app (ShareRules) and lamp's command line (cli/lampapp.mjs) alike, so the two never differ. tokenShapes are keys and tokens whoever's they are: a file holding one isn't shared. licenseFiles are the names a license or notice goes by. limits are what another Lamp opens.",
+  "tokenShapes": [
+    {
+      "pattern": "-----BEGIN [A-Z ]*PRIVATE KEY-----",
+      "what": "a private key"
+    },
+    {
+      "pattern": "\\bsk-(or-v1-|ant-|proj-)?[A-Za-z0-9_\\-]{32,}",
+      "what": "OpenRouter, Anthropic, OpenAI"
+    },
+    {
+      "pattern": "\\bgh[pousr]_[A-Za-z0-9]{36,}",
+      "what": "GitHub"
+    },
+    {
+      "pattern": "\\bgithub_pat_[A-Za-z0-9_]{60,}",
+      "what": "GitHub"
+    },
+    {
+      "pattern": "\\bAKIA[0-9A-Z]{16}\\b",
+      "what": "AWS"
+    },
+    {
+      "pattern": "\\bAIza[0-9A-Za-z_\\-]{35}\\b",
+      "what": "Google"
+    },
+    {
+      "pattern": "\\bxox[abprs]-[A-Za-z0-9\\-]{20,}",
+      "what": "Slack"
+    },
+    {
+      "pattern": "\\b(sk|rk)_live_[A-Za-z0-9]{20,}",
+      "what": "Stripe"
+    }
+  ],
+  "licenseFiles": {
+    "startsWith": [
+      "LICENSE",
+      "LICENCE",
+      "COPYING",
+      "NOTICE",
+      "UNLICENSE"
+    ],
+    "longestExtension": 10,
+    "neverExtensions": [
+      "sh",
+      "command",
+      "app",
+      "js",
+      "py",
+      "rb",
+      "pl",
+      "swift",
+      "html",
+      "htm"
+    ]
+  },
+  "limits": {
+    "files": 2000,
+    "unpackedBytes": 268435456,
+    "archiveBytes": 67108864
+  }
+}

package/Resources/skills/game/SKILL.md

@@ -25,6 +25,8 @@ The tools Lamp has for games:
   `new Worker(new URL("./<name>.worker.js", import.meta.url), { type: "module" })` (`.js`: every file is bundled flat
   into `Web/app/`; a module worker, since what it shares with the page comes as an import). Edit `src/`,
   never `Web/app/`. A game in plain JavaScript stays as it is, its modules in `Web/`.
+- **AI in a game** (`LampAI` in Web/lamp.js): checked and shown where it can't answer as the web-app skill's
+  "LampAI" says, with lamp.js's own line and its link, never words of the game's own.
 - **Phones as players**: a game on the runtime takes phones on the Wi‑Fi with `Lamp.controllers` (Web/lamp.js) and
   its page for them in Phone/ (the phone-controllers and phone-pages skills), on the Mac, in the TV preview, on a
   Samsung or LG TV and on the Xbox; elsewhere `Lamp.controllers` says it can't start, so the game stays whole with a controller,

package/Resources/skills/github-projects/SKILL.md

@@ -36,20 +36,23 @@ its credit and licenses in place, and the rest of what a Lamp app has.
    code, an engine Lamp's devices can't run.
 2. Give the app its structure with `make_app_for` (a game or an app, the devices, web or native), and read the skill
    for that kind (`game`, `web-app`, `2d-game`, `3d-game`). The structure is Lamp's: its page or its Swift package,
-   `build.sh`, `Package.swift`, Lamp's own files, `icon.json`, `APP.md`.
+   `build.sh`, `Package.swift`, Lamp's own files, `icon.json`, `APP.md`. A web page with no build step (index.html with
+   its scripts and styles, a canvas or WebGL game among them) is a web app brought in: `kind` "app", `made` "web", and
+   the web-app skill's "A web app brought in" is the rule for everything after, whatever the person's devices are.
 3. Before using any of its code or assets, call `lampify` with its address and the commit your clone is at
    (`git -C .lamp/reference/name rev-parse HEAD`). Lamp gets its own untouched copy at that commit, credits it in
    credits.json, keeps every license and notice file under `Licenses/`, and answers with the manifest and what's still
    missing. `adapted` is true for the project the app is made from (the default): its updates come to the person from
    there. Anything else you bring in from GitHub (a library, a sprite pack) is cloned and lampified the same way with
    `adapted: false`. Every later call passes the same commit: lampify never moves on to a newer one by itself.
-4. Bring its code and assets into Lamp's structure: a web game's scripts, styles and assets into the page's folder,
-   loaded from Lamp's page; native code into the package's sources. Keep what makes it work and drop only what the
-   person asked to drop. Never copy its own build scripts, package manifests, workflows or wrapper page over Lamp's
+4. Bring its code and assets into Lamp's structure: a web page's files into `Web/` as they are, laid out as the project
+   has them, in place of the scaffold's; native code into the package's sources. Keep what makes it work and drop only
+   what the person asked to drop. Never copy its own build scripts, package manifests, workflows or wrapper page over Lamp's
    files (`Package.swift`, `build.sh`, `Sources/LampSupport.swift`, the `lamp*.js` files), and never run anything it
    holds (its installers, its build, its scripts). Keep its copyright headers, and its author's credit on screen.
 5. Give it what a Lamp app has that a project on GitHub doesn't: its line in `about.json`, its icon's design in
-   `icon.json`, and `APP.md` saying what it is and what it's based on. Never write `lamp-app.json`, the project's entry
+   `icon.json`, and `APP.md` saying what it is and what it's based on (and, for a web app brought in, that it came in
+   as it is). Never write `lamp-app.json`, the project's entry
    in `credits.json` or copies of its licenses yourself: lampify does.
 6. Look at it with `look_at_app` until it works.
 7. Call `lampify` again with the same address and commit, and fix whatever it says is still missing, until it says

package/Resources/skills/web-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: web-app
-description: Apps made as a web page Lamp shows on each device - lamp.js's building blocks (AI, saved data, the app's files, the project's other apps), the remote's focus and keys, what the person's own things need from the app around the page, and what each device's browser runs. Read before writing or changing an app's page.
+description: Apps made as a web page Lamp shows on each device - lamp.js's building blocks (AI, saved data, the app's files, the project's other apps), the remote's focus and keys, what the person's own things need from the app around the page, what each device's browser runs, and a web app brought in from elsewhere, which stays as it is. Read before writing or changing an app's page.
 ---
 
 # Web apps
@@ -17,8 +17,10 @@ opening comment for the whole list. What it gives:
 
 - **LampAI**: text, pictures and quick judgments, answered by Lamp on the person's Mac with the AI they set up.
   Every call is a Promise. Text from outside the app goes in `data`, never into the prompt. Where a feature depends
-  on it, check `LampAI.isAvailable('text')` and show a short note when it can't answer: away from the Mac's Wi‑Fi, or
-  with Lamp closed, it can't.
+  on it, check `LampAI.status('text')` and, when it can't answer, show its `reason` as it's given: lamp.js words it
+  for where the page is (away from the Mac's Wi‑Fi, Lamp closed, a link on lamp.dev), so don't write your own. Where it
+  gives `help` (a page away from Lamp), add a link to it beside the reason, "How to turn on AI", so someone who has never
+  heard of Lamp finds out how.
 - **LampAI.act**: the person asks the app to do something in their own words, and the app's own reads and writes do
   it; "Doing things for the person" below, with **LampVoice** and **LampAI.hear** for saying it.
 - **LampStore**: what the app saves, as JSON on the device. Once something is saved, only ever add to it: a new field
@@ -30,24 +32,51 @@ opening comment for the whole list. What it gives:
 - **Lamp.controllers** and `Lamp.phonePage`: phones on the same Wi‑Fi as controllers or a second screen; the
   phone-controllers skill first.
 
+## A web app brought in
+
+This section is the rule for a web app someone made elsewhere and brought to Lamp: a site opened from GitHub or from
+a folder (index.html at its top, no build step), or a page with no build step made into a Lamp app from a project on
+GitHub (the github-projects skill). A project that's built before it's served (a package.json, a bundler) isn't
+covered here.
+
+It comes in as it is. Lamp's features need nothing from its code: it opens in Lamp's app around the page, is shared
+and put on GitHub with its files as they are, gets its updates from where it came from, and takes a change by opening
+again. So:
+
+- Do only what Lamp needs and what the person asks for: no refactoring, no new layout or file names, no redesign, no
+  framework, no tidying of code that works.
+- Its kind stays what it is: a web app (`make_app_for` with `kind` "app" and `made` "web"), whether it's a tool or a
+  game. Moving it onto Lamp's game runtime or into native code is a conversion, done only when the person asks for
+  that in so many words.
+- No Swift of its own: Sources/Native.swift stays as Lamp wrote it, and the app stays Lamp's ready-made one, unless
+  the person asks for something only the app around the page can reach (their own things, below) or for native code.
+- "I'm on a Mac" or "make it a Mac app" asks for nothing more: Lamp's app around the page already is one.
+- A feature its page uses that Lamp's app around it doesn't support yet (a download, a file picker) is Lamp's
+  limitation, not the app's: say so, and leave its code as it is. Never rewrite the feature, or the app, around it.
+- lamp.js only when a change the person asks for needs Lamp's building blocks, added before its own scripts, with the
+  page still working without it.
+
+APP.md says that it was brought in as it is, so every later turn keeps to this.
+
 ## On the web, without Lamp
 
-Putting it on GitHub (Also put on GitHub, on its link's card) gives a web app a page anyone opens in a browser, with no Lamp anywhere: the page as it is, with
-lamp.js. There, `LampAI.isAvailable` answers false and its calls fail with a sentence saying the page is away from
-Lamp, `LampNative.available` is false, and `Lamp.wish` can't reach the project's other apps; `LampStore` and `LampAssets`
-work as they do everywhere. So every feature that leans on Lamp keeps the app usable without it: the app's own buttons
+Sharing its link gives a web app a page on lamp.dev anyone opens in a browser, with no Lamp around it: the page as it
+is, with lamp.js. There its AI is answered only on a computer with Lamp open or running `lamp ai`, for whoever plays it there; elsewhere
+`LampAI.status` says it's unavailable, with the line to show, and its calls fail with that sentence. `LampNative.available`
+is false, and `Lamp.wish` can't reach the project's other apps; `LampStore` and `LampAssets` work as they do everywhere.
+So every feature that leans on Lamp keeps the app usable without it, going by what `status` says rather than where it is: the app's own buttons
 for everything AI would do, example content where the person's own things would be, and a short line where something
-needs Lamp, never an error or an empty screen.
+needs Lamp (for AI, `LampAI.status`'s `reason`), never an error or an empty screen.
 
 ## Doing things for the person
 
 `LampAI.act(request, { about, context, tools, history, onStep })` runs a short loop: the AI picks calls among the
 app's tools, the page runs them, the AI sees the results, until it replies (at most 4 AI calls and 6 writes a
-turn, and 25 seconds over OpenRouter or a minute through Claude Code, Codex or a model on the Mac). It works with
+turn, and no time limit unless the app sets one with `limits: { seconds }`, for a feature that should answer quickly). It works with
 whichever AI the person set up for apps' text, so don't tie it to voice: typing works wherever `act` does. Its comment in lamp.js has the shapes. This is the one recipe for it:
 
-- Show the feature where `LampAI.isAvailable('act')` is true, and keep the app's own buttons for everything: it only
-  adds a way in. Where it's false, keep it visible with a short reason and a way to set it up in Lamp, and keep what
+- Show the feature where `LampAI.status('act')` says it's available, and keep the app's own buttons for everything:
+  it only adds a way in. Where it isn't, keep it visible with its `reason`, and keep what
   was typed; don't send it by itself once setup is done. Whether AI belongs in the app at all, and the contract to
   write in APP.md, are the app-ai skill's.
 - Tools are small reads and writes over the app's own data, ids in and ids out, never "do anything". A read has
@@ -91,12 +120,17 @@ turns it into text for `act`. Their comments in lamp.js have the details. The re
 
 ## The person's own things
 
+Opening and saving files the person picks needs no Swift: on the Mac a file field (`<input type="file">`, with
+`multiple` or `webkitdirectory`) shows the open panel, and a download (a link with `download`, often to a Blob the page
+made) asks where to save it, as a browser does. Never add Native.swift for that.
+
 A page can't read the person's mail, calendar, contacts, photos or where they are. Where Lamp's app is around the page
 (a Mac, an iPhone or iPad), that app can: register a call in Sources/Native.swift and ask for it from the page with
-`LampNative.call(name, args)`. Elsewhere `LampNative.available` is false and the calls reject, so the page shows
-example content then, never an error. When a web app that's to go on a TV, Android or the Xbox lives on the person's own
-things, say what a page can't reach there; when it needs what only native code does, offer it native (the web-or-native
-skill).
+`LampNative.call(name, args)`, only when the app needs those things (in a web app brought in, only when the person
+asks for them: "A web app brought in", above). Elsewhere `LampNative.available` is false and the calls reject, so the
+page shows example content then, never an error. When a web app that's to go on a TV, Android or the Xbox lives on the
+person's own things, say what a page can't reach there; when it needs what only native code does, offer it native (the
+web-or-native skill), except for a web app brought in, which is made native only when the person asks for that.
 
 ## A remote: focus and keys
 

package/Resources/skills/web-or-native/SKILL.md

@@ -40,7 +40,9 @@ Make it **native** only when it needs something a page can't be:
 - 3D in Swift with RealityKit (the scene-3d skill), or a game inside an Apple thing (Game Center, a widget).
 
 When one of these is part of what was asked, choose native and say why in a sentence. When the person asks for one
-later in an app made web, say what it needs, and offer to make it native.
+later in an app made web, say what it needs, and offer to make it native. A web app brought in from elsewhere is the
+exception: it stays as it is, made native only when the person asks for that (the web-app skill, "A web app brought
+in").
 
 The default is where you start, not a limit:
 
@@ -50,6 +52,9 @@ The default is where you start, not a limit:
   only once the person has said that's what they want, or answered so when you asked.
 - **An app the project has is never converted to follow the default.** It's for a new app, and for a change the person
   asks for. An app made native before keeps its make.
+- **A web app brought in keeps its make and its kind.** A site or page someone made elsewhere stays a web app, with no
+  Swift of its own, unless the person asks in so many words for it to be native or a game on Lamp's runtime; being on a
+  Mac isn't such a request (the web-app skill, "A web app brought in").
 - **Separate apps that talk don't need the same make.** The project's apps reach each other through `LampWish` on
   whichever devices they're on, however each is made (the wish-links skill).
 - **Never choose a make to get around a limit of Lamp's**: two apps of one code in one project, say (the more-apps

package/cli/ai.mjs

@@ -0,0 +1,237 @@
+// The AI a page asks for with LampAI (lamp.js), answered by lamp itself for the pages it serves, with the person's own
+// Claude Code or Codex on this Mac: their subscription, through the program they signed in to, never a key in the page.
+// The same routes and answers Lamp's app gives (`/ai/status`, `/ai`, `/ai/act`, `/ai/decide`), told and checked by the
+// same code (app-ai.mjs, which Lamp's app has do it too), so a page can't tell which answered it. Pictures and
+// hearing need Lamp's app: asked here, they say so.
+
+import { spawn, execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { chatBody, decidePrompt, planPrompt, planSchema, readDecision, readMessage, readPlan, readStep } from "./app-ai.mjs";
+import { DEFAULT_MODEL, OpenRouterTrouble, chat as openRouterChat, text as openRouterText } from "./openrouter.mjs";
+
+
+/**
+ * What answers: `LAMP_AI` (claude, codex or openrouter) when it's set, else Claude Code, else Codex, else OpenRouter with
+ * the person's key in OPENROUTER_API_KEY.
+ */
+export function engine() {
+  const wanted = process.env.LAMP_AI;
+  for (const name of wanted ? [wanted] : ["claude", "codex", "openrouter"]) {
+    if (name === "openrouter") { if (process.env.OPENROUTER_API_KEY) return name; continue; }
+    if (name !== "claude" && name !== "codex") continue;
+    try { execFileSync("/usr/bin/which", [name], { stdio: ["ignore", "pipe", "ignore"] }); return name; } catch {}
+  }
+  return null;
+}
+
+const missing = "AI here needs Claude Code or Codex on this computer, signed in, or an OpenRouter key in OPENROUTER_API_KEY. Or open the app in Lamp.";
+const named = (which) => (which === "codex" ? "Codex" : which === "openrouter" ? "OpenRouter" : "Claude Code");
+
+/** Why an engine gave no answer: `kind` is "missing", "timeout", "stopped", "failed" (its own words) or "silent". */
+export class EngineTrouble extends Error {
+  constructor(kind, message) { super(message); this.kind = kind; }
+}
+
+/**
+ * One answer from Claude Code or Codex, the person's own sign-in: text, or JSON fitting `schema`. Every run is sealed:
+ * none of the person's settings, rules, hooks or MCP servers, and none of the engine's tools, so nothing of the
+ * computer is read or run whatever the prompt asks. Pictures (`images`, base64 with their `media_type`) go with the
+ * request itself: to Claude Code in its input, to Codex as attachments, never through a tool that reads files.
+ * Lamp's app runs it this way too (`engineAnswer` in calls.mjs, `AppAI.viaEngine`), naming the program (`tool`) and
+ * what it needs set (`env`); on its own lamp finds the person's own on the PATH.
+ */
+export function complete({ system, prompt, schema, seconds = 60, which = engine(), tool, env = {}, model = process.env.LAMP_AI_MODEL || "", images = [], signal } = {}) {
+  if (which === "openrouter") return viaOpenRouter({ system, prompt, schema, seconds, model, images, signal });
+  if (which !== "claude" && which !== "codex") return Promise.reject(new EngineTrouble("missing", missing));
+  const folder = mkdtempSync(join(tmpdir(), "lamp-ai-"));
+  const sayer = system || "You are a helpful assistant inside an app.";
+  const pictures = (Array.isArray(images) ? images : []).filter((image) => typeof image?.data === "string" && image.data);
+  let args, input = null;
+  if (which === "claude") {
+    // None of the person's settings or hooks (--restricted), no MCP, no tools. With pictures, the prompt and the pictures
+    // go in on its input as one message, which it takes in stream-json.
+    args = ["-p", ...(pictures.length ? [] : [prompt]), "--output-format", "stream-json", "--verbose", "--no-session-persistence", "--restricted",
+      "--strict-mcp-config", "--disable-slash-commands", "--tools", "", "--system-prompt", sayer];
+    if (model) args.push("--model", model);
+    if (schema) args.push("--json-schema", JSON.stringify(schema));
+    if (pictures.length) {
+      args.push("--input-format", "stream-json");
+      const content = [{ type: "text", text: prompt }, ...pictures.map((image) => ({ type: "image",
+        source: { type: "base64", media_type: String(image.media_type || "image/jpeg"), data: image.data } }))];
+      input = JSON.stringify({ type: "user", message: { role: "user", content } }) + "\n";
+    }
+  } else {
+    // Read-only, none of the person's config, rules or hooks, and none of its tools. Its picture tool reads any file on
+    // the computer: `features.view_image` turns it off now, `tools.view_image` did before (each version ignores the
+    // other's, with a warning); pictures given with `-i` are part of the request, not that tool. What's left, checked
+    // with Codex 0.167.1, is asking the person a question, which a run with no one to ask can't use.
+    args = ["exec", "--json", "--ignore-user-config", "--ignore-rules", "--skip-git-repo-check", "--ephemeral", "-s", "read-only",
+      "-c", "hooks={}", "-c", 'model_reasoning_effort="low"', "-c", 'approval_policy="never"',
+      "-c", "features.shell_tool=false", "-c", "features.unified_exec=false", "-c", 'web_search="disabled"',
+      "-c", "features.apps=false", "-c", "features.multi_agent=false", "-c", "features.view_image=false",
+      "-c", "tools.view_image=false", "-c", "features.goals=false",
+      "-c", `developer_instructions=${JSON.stringify(sayer + "\n\nAnswer directly. Don't run commands or change files.")}`];
+    if (model) args.push("-m", model);
+    if (schema) { writeFileSync(join(folder, "schema.json"), JSON.stringify(schema)); args.push("--output-schema", "schema.json"); }
+    pictures.forEach((image, i) => {
+      const name = `image${i}.${String(image.media_type).endsWith("png") ? "png" : "jpg"}`;
+      writeFileSync(join(folder, name), Buffer.from(image.data, "base64"));
+      args.push("-i", name);
+    });
+    args.push("--", prompt);
+  }
+  // Run on Lamp's own runtime, lamp is Bun told to be itself; the engine is never told so, or Claude Code, which is
+  // built on Bun, would be Bun too.
+  const childEnv = { ...process.env, ...env };
+  delete childEnv.BUN_BE_BUN;
+  return new Promise((resolve, reject) => {
+    const child = spawn(tool || which, args, { cwd: folder, env: childEnv, detached: true, stdio: [input ? "pipe" : "ignore", "pipe", "pipe"] });
+    let text = "", trouble = null, rest = "", said = "";
+    // The whole group, since an engine may leave a child holding its output.
+    const stop = (kind, words) => { if (!trouble) trouble = new EngineTrouble(kind, words); try { process.kill(-child.pid, "SIGKILL"); } catch { child.kill("SIGKILL"); } };
+    const timer = setTimeout(() => stop("timeout", `${named(which)} took too long to answer.`), Math.max(1, seconds) * 1000);
+    const stopped = () => stop("stopped", "Stopped.");
+    if (signal?.aborted) stopped(); else signal?.addEventListener("abort", stopped);
+    const line = (raw) => {
+      let event;
+      try { event = JSON.parse(raw); } catch { return; }
+      if (which === "codex") {
+        if (event.type === "item.completed" && event.item?.type === "agent_message" && typeof event.item.text === "string") text = event.item.text;
+        else if (event.type === "turn.failed" || event.type === "error") {
+          // Codex nests the service's error as JSON text: its message is what's said.
+          const words = String(event.message || event.error?.message || "Codex couldn't answer.");
+          let nested;
+          try { nested = JSON.parse(words)?.error?.message; } catch {}
+          trouble ??= new EngineTrouble("failed", nested || words);
+        }
+        return;
+      }
+      if (event.type !== "result") return;
+      if (event.is_error) trouble ??= new EngineTrouble("failed", String(event.result || "Claude Code couldn't answer."));
+      else if (schema && event.structured_output !== undefined) text = JSON.stringify(event.structured_output);
+      else if (typeof event.result === "string") text = event.result;
+    };
+    // Read as text across chunks, so a character split between two of them stays whole.
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      rest += chunk;
+      const lines = rest.split("\n");
+      rest = lines.pop();
+      lines.forEach(line);
+    });
+    child.stderr.on("data", (chunk) => { said = (said + chunk).slice(-400); });
+    if (input) { child.stdin.on("error", () => {}); child.stdin.end(input); }
+    const done = () => { clearTimeout(timer); signal?.removeEventListener("abort", stopped); rmSync(folder, { recursive: true, force: true }); };
+    child.on("error", () => { done(); reject(new EngineTrouble("missing", missing)); });
+    child.on("close", () => {
+      done();
+      if (rest) line(rest);
+      if (trouble) return reject(trouble);
+      if (!text) return reject(new EngineTrouble("silent", `${named(which)} didn't answer. Check it's signed in.${said.trim() ? ` ${said.trim().split("\n").pop()}` : ""}`));
+      resolve(text);
+    });
+  });
+}
+
+/** An answer from OpenRouter with the person's key (openrouter.mjs, as Lamp's app sends it), its troubles said as an engine's. */
+async function viaOpenRouter({ system, prompt, schema, seconds, model, images, signal }) {
+  try {
+    return (await openRouterText({ key: process.env.OPENROUTER_API_KEY, prompt, images, system: system || "You are a helpful assistant inside an app.",
+      model: model || DEFAULT_MODEL, json: !!schema, schema, seconds, signal })).text;
+  } catch (error) {
+    if (!(error instanceof OpenRouterTrouble)) throw error;
+    const words = error.reply?.error?.message;
+    throw new EngineTrouble(error.kind === "refused" ? "failed" : error.kind, words ? String(words) : error.message);
+  }
+}
+
+// MARK: Status and asking
+
+/** `/ai/status`: what can answer here. Text, decisions and actions with an engine; pictures only in Lamp's app. */
+export function status() {
+  const which = engine();
+  const route = which ? named(which) : null;
+  const available = (kind) => route ? { available: true, route, where: "remote" } : { available: false, reason: missing, setup: "lamp" };
+  return {
+    text: !!route, decisions: !!route, pictures: false, act: !!route,
+    details: { text: available("text"), decisions: available("decisions"), act: available("act"),
+      pictures: { available: false, reason: "Pictures need Lamp's app: open the app in Lamp.", setup: "lamp" } },
+  };
+}
+
+/** `/ai`: a text answer, or JSON when asked for it. */
+export async function ask(body) {
+  const prompt = typeof body?.prompt === "string" ? body.prompt.trim() : "";
+  if (!prompt) return [400, { error: "Missing prompt." }];
+  let system = typeof body.system === "string" ? body.system : "";
+  if (body.json) system += (system ? "\n\n" : "") + "Answer with JSON only, nothing around it.";
+  try { return [200, { text: await complete({ system, prompt, images: body.images }) }]; }
+  catch (error) { return [502, { error: error.message }]; }
+}
+
+// MARK: Decisions
+
+/** `/ai/decide`: each question answered by a text model, told and read as Lamp's app does it (app-ai.mjs). */
+export async function decide(body) {
+  const questions = body?.questions;
+  if (body?.state === undefined || !questions || typeof questions !== "object" || Array.isArray(questions) || !Object.keys(questions).length) {
+    return [400, { error: "A decision needs `state` and at least one question." }];
+  }
+  const { system, prompt, schema } = decidePrompt(body.state, questions);
+  let text;
+  try { text = await complete({ system, prompt, schema }); } catch (error) { return [502, { error: error.message }]; }
+  const read = readDecision(text, questions);
+  return read.answers ? [200, { answers: read.answers }] : [502, { error: read.problem }];
+}
+
+// MARK: Actions (`LampAI.act`)
+
+/** `/ai/act`: one step of the page's agent loop, told and checked as Lamp's app does it (app-ai.mjs). */
+export async function act(body) {
+  const which = engine();
+  if (body?.probe === true) return [200, { act: !!which, route: which || "", why: which ? "" : missing }];
+  if (!which) return [501, { error: missing }];
+  let r;
+  try { r = readStep(JSON.stringify(body ?? null)); } catch (refused) { return [refused.status ?? 400, { error: refused.message }]; }
+  // A step's guard against a call that has stopped answering, as Lamp's app gives it (`AppAct.turnSeconds`).
+  const seconds = 600;
+  const deadline = Date.now() + Math.min(r.seconds, seconds) * 1000;
+  const tag = "outside-text-" + randomBytes(4).toString("hex");
+  let retry = null;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const left = (deadline - Date.now()) / 1000;
+    if (left < 1) return [504, { error: "This step ran out of time." }];
+    let read;
+    try {
+      if (which === "openrouter") {
+        const body = chatBody(r, tag, retry, process.env.LAMP_AI_MODEL || DEFAULT_MODEL);
+        read = readMessage((await openRouterChat({ key: process.env.OPENROUTER_API_KEY, body, seconds: left })).message, r);
+      } else {
+        const { system, prompt } = planPrompt(r, tag, retry);
+        read = readPlan(await complete({ system, prompt, schema: planSchema(r), seconds: left, which }), r);
+      }
+    } catch (error) {
+      const words = error?.reply?.error?.message || error.message;
+      return Date.now() >= deadline || error?.kind === "timeout" ? [504, { error: "This step ran out of time." }] : [502, { error: String(words) }];
+    }
+    if (read.answer) return [200, { ...read.answer, route: which, seconds }];
+    if (attempt === 0) { retry = read.problem; continue; }
+    return [200, { reply: "I couldn't work out how to do that.", ask: false, route: which, seconds, trouble: read.problem }];
+  }
+  return [502, { error: "The AI didn't answer." }];
+}
+
+/** A page's AI request, by its route, as Lamp's app answers it: [status, JSON]. */
+export async function answer(path, body) {
+  if (path === "/ai/status") return [200, status()];
+  if (path === "/ai") return ask(body);
+  if (path === "/ai/act") return act(body);
+  if (path === "/ai/decide") return decide(body);
+  if (path === "/ai/hear") return body?.probe === true ? [200, { hear: false, why: "Hearing needs Lamp's app." }] : [501, { error: "Hearing needs Lamp's app: open the app in Lamp." }];
+  if (path === "/ai/image") return [501, { error: "Pictures need Lamp's app: open the app in Lamp.", needs: "pictures" }];
+  return [404, { error: "Not found." }];
+}