@lampdotdev/lamp 0.35.0 → 0.36.2-nightly.16

package/cli/lamps/lamp-for-games.js

@@ -113,10 +113,11 @@
     image: function (name) { return loadImage(LampAssets.url(name)); }
   };
 
-  function Failure(message, needsSetup) {
+  function Failure(message, needsSetup, help) {
     this.name = 'LampAI.Failure';
     this.message = message;
     this.needsSetup = needsSetup || null;
+    this.help = help || null;
     this.stack = (new Error(message)).stack;
   }
   Failure.prototype = Object.create(Error.prototype);
@@ -190,6 +191,8 @@
   }
 
   // Why a copy Lamp didn't put on a device has no AI: a page on the web (its published page) is away from Lamp.
+  // Where someone with no Lamp finds how to turn AI on, for a page away from Lamp.
+  var AI_HELP = 'https://lamp.dev';
   function unplaced() {
     return here.protocol === 'https:'
       ? 'This page is on the web, away from Lamp, so it has no AI here. Open it in Lamp for that.'
@@ -206,7 +209,7 @@
       var ipv4 = /^http:\/\/\d+\.\d+\.\d+\.\d+:/;
       list = list.filter(function (r) { return ipv4.test(r); }).concat(list.filter(function (r) { return !ipv4.test(r); }));
     }
-    if (!list.length) return Promise.reject(new Failure(unplaced()));
+    if (!list.length) return Promise.reject(new Failure(unplaced(), null, AI_HELP));
     // With a deadline (LampAI.act's turn), each try gets only the time left, and none starts after it.
     function left() { return deadline ? deadline - Date.now() : timeout; }
     function attempt(i, round) {
@@ -229,7 +232,7 @@
   function token() {
     var kept = read('install.token', null);
     if (kept && installed && kept.app === installed.app) return Promise.resolve(kept.token);
-    if (!installed) return Promise.reject(new Failure(unplaced()));
+    if (!installed) return Promise.reject(new Failure(unplaced(), null, AI_HELP));
     return send('/app/claim', { app: installed.app }, null, 10000).then(function (answer) {
       if (answer.status !== 200 || !answer.reply.token) {
         throw new Failure('This app needs Lamp to put it on this device once more before it can use AI: press Play in Lamp on your Mac.');
@@ -240,10 +243,50 @@
     });
   }
 
+  // A page shared on lamp.dev plays from a host of its own under play.lamp.dev, away from Lamp. The person's own
+  // Lamp or lamp on this computer can answer it (Lamp's `SharedPagesAI`, or `lamp ai`, at a port of the computer's
+  // own), once they've allowed this
+  // page there; the token it's given is kept with the page's saved things. Whether there's an AI is asked first,
+  // without one, so the person is asked only when the page uses it.
+  var NEARBY = 'http://127.0.0.1:47423';
+  function shared() { return !installed && here.protocol === 'https:' && /\.play\.lamp\.dev$/.test(here.hostname || ''); }
+  function safari() {
+    var ua = (window.navigator && navigator.userAgent) || '';
+    return /Safari\//.test(ua) && !/Chrome|Chromium|CriOS|Edg|OPR|Firefox|FxiOS/.test(ua);
+  }
+  function nearby(path, body, timeout, deadline) {
+    var text = JSON.stringify(body);
+    function go(t) { return exchange(NEARBY, path, t, text, deadline ? Math.max(1000, deadline - Date.now()) : timeout); }
+    function allow() {
+      return exchange(NEARBY, '/pair', null, JSON.stringify({ name: document.title || '' }), 130000).then(function (answer) {
+        if (answer.status !== 200 || !answer.reply.token) throw new Failure('This computer didn\'t allow this page to use its AI.');
+        write('nearby.token', answer.reply.token);
+        return answer.reply.token;
+      });
+    }
+    var kept = read('nearby.token', null);
+    var done = path === '/ai/status' || (body && body.probe === true) ? go(kept) : (kept ? Promise.resolve(kept) : allow()).then(function (t) {
+      return go(t).then(function (answer) {
+        if (answer.status !== 401) return answer;
+        // Taken back on the computer: ask once more.
+        forget('nearby.token');
+        return allow().then(go);
+      });
+    });
+    return done.then(null, function (e) {
+      if (e instanceof Failure) throw e;
+      // Safari never lets a page on the web reach this computer this way, so Lamp or lamp ai open here wouldn't help.
+      if (safari()) throw new Failure('AI here works in Chrome or in Lamp, or with Lamp\'s command line: lamp play and this page\'s link.', null, AI_HELP);
+      throw new Failure('AI isn\'t available here. Open Lamp on this computer, or with Lamp\'s command line, run lamp ai.', null, AI_HELP);
+    });
+  }
+
   function post(path, body, timeout, deadline) {
     timeout = timeout || 240000;
     var done;
-    if (bridge) {
+    if (!bridge && shared()) {
+      done = nearby(path, body, timeout, deadline);
+    } else if (bridge) {
       // The TV preview on the Mac answers for Lamp itself.
       done = bridge.postMessage({ path: path, body: JSON.stringify(body), timeout: timeout }).then(function (r) {
         var reply = {};
@@ -454,8 +497,11 @@
 
   // Doing things for the person: LampAI.act
 
-  // 60 seconds is the longest any route allows; each answer says its route's own (`seconds`), and the turn keeps to it.
-  var ACT_LIMITS = { steps: 4, writes: 6, seconds: 60 };
+  // A turn has no time limit of its own: a real answer is never cut off, however long the model takes. Each step is
+  // given ACT_STEP_SECONDS, which only a call that has stopped answering reaches. An app that wants a quicker turn
+  // asks for one (`limits: { seconds }`); steps and writes it may only lower.
+  var ACT_LIMITS = { steps: 4, writes: 6 };
+  var ACT_STEP_SECONDS = 600;
   var actRan = {};      // turn id -> call key -> the result a write gave, while this copy of the page is open
   function actId() { return 't' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8); }
   function isList(v) { return Object.prototype.toString.call(v) === '[object Array]'; }
@@ -481,10 +527,11 @@
   function act(request, options) {
     var o = options || {}, tools = o.tools || {};
     var limits = {};
-    ['steps', 'writes', 'seconds'].forEach(function (k) {
+    ['steps', 'writes'].forEach(function (k) {
       var asked = o.limits && typeof o.limits[k] === 'number' ? o.limits[k] : ACT_LIMITS[k];
       limits[k] = Math.max(1, Math.min(asked, ACT_LIMITS[k]));
     });
+    var asked = o.limits && typeof o.limits.seconds === 'number' && o.limits.seconds > 0 ? o.limits.seconds : null;
     var id = o.turn || actId();
     if (!actRan[id]) {
       var kept = Object.keys(actRan);
@@ -492,7 +539,7 @@
       actRan[id] = {};
     }
     var ran = actRan[id];
-    var started = Date.now(), deadline = started + limits.seconds * 1000;
+    var started = Date.now(), deadline = asked ? started + Math.max(1, asked) * 1000 : Infinity;
     var out = { turn: id, reply: '', ask: false, choices: [], done: [], failed: [], skipped: [], reads: [], stopped: null, error: '' };
     var steps = [], route = null, writes = 0, over = false, settle;
     var declared = Object.keys(tools).map(function (name) {
@@ -514,7 +561,7 @@
       return over;
     }
     var result = new Promise(function (resolve) { settle = resolve; });
-    var timer = setTimeout(function () { stop('time'); }, limits.seconds * 1000);
+    var timer = asked ? setTimeout(function () { stop('time'); }, Math.max(1, asked) * 1000) : null;
     result.then(function () { clearTimeout(timer); });
 
     // Reads run together; then the writes, one after another, each checked right before it runs. A write that
@@ -590,23 +637,15 @@
       if (over) return;
       var left = deadline - Date.now();
       if (left <= 500) return stop('time');
+      // The step's own time: what's left of an app's turn, or the step's guard against a call that has stopped.
+      var stepTime = Math.min(left, ACT_STEP_SECONDS * 1000);
       var body = { request: String(request), about: o.about || '', now: present(), tools: declared, steps: steps,
-                   history: (o.history || []).slice(-3), seconds: Math.floor(left / 1000) };
+                   history: (o.history || []).slice(-3), seconds: Math.floor(stepTime / 1000) };
       if (o.context !== undefined) body.context = jsonState(o.context);
       if (route) body.route = route;
       if (steps.length >= limits.steps - 1) body.final = true;
       if (o.model) body.model = o.model;
-      post('/ai/act', body, left, deadline).then(function (answer) {
-        // The route's own time for a turn (25 seconds over OpenRouter, a minute through Claude Code, Codex or a model
-        // on the Mac) shortens the turn's deadline, counted from its start; it never lengthens it.
-        if (!over && typeof answer.seconds === 'number' && answer.seconds > 0) {
-          var end = started + Math.min(answer.seconds, limits.seconds) * 1000;
-          if (end < deadline) {
-            deadline = end;
-            clearTimeout(timer);
-            timer = setTimeout(function () { stop('time'); }, Math.max(0, deadline - Date.now()));
-          }
-        }
+      post('/ai/act', body, stepTime, Date.now() + stepTime).then(function (answer) {
         // Cancelled, out of time or already over: an answer that comes late runs nothing.
         if (late()) return;
         route = answer.route || route;
@@ -693,24 +732,42 @@
    * Text calls take a few seconds; decisions well under a second; image calls 10-60 seconds. Show `error.message` on
    * failure. Aspect ratios look like "1:1", "16:9", "3:4".
    *
-   * Not every Mac has every kind of AI set up, and a device away from the Mac's Wi-Fi, or with Lamp closed, has none.
-   * `LampAI.isAvailable('pictures')` (or 'text', 'decisions') says whether it can answer now: check it where a
-   * feature depends on it, and show the feature with a short note ("Pictures need AI set up in Lamp") rather than
-   * hiding it or failing at it. A call that fails for that reason has `needsSetup` set on its error.
+   * Not every Mac has every kind of AI set up, a device away from the Mac's Wi-Fi or with Lamp closed has none, and a
+   * page shared on lamp.dev has it only on a computer that answers it. `LampAI.status('pictures')` (or 'text',
+   * 'decisions', 'act', 'hear') says whether it can answer now and, when it can't, the line to show: check it where
+   * a feature depends on it, and show the feature with its `reason` as it's given rather than words of the app's
+   * own, or hiding it or failing at it, and where it gives `help` (a page away from Lamp), a link to it beside the
+   * reason: "How to turn on AI". A call that fails for that reason has `needsSetup`, or `help`, set on its error.
    */
   var LampAI = {
     Failure: Failure,
 
-    /** Whether this kind of AI ('text', 'decisions', 'pictures' or 'act') can answer now. False when Lamp can't be reached. */
-    isAvailable: function (capability) {
-      // 'act' is asked of /ai/act itself: true only when this lamp.js has it, the app around the page lets the
-      // route through (an older one answers Not found) and the AI that answers the app can take it.
-      if (capability === 'act') return post('/ai/act', { probe: true }, 10000).then(function (reply) { return reply.act === true; }, function () { return false; });
-      // 'hear' the same way: this lamp.js, the app around the page and the AI set up in Lamp can all take it.
-      if (capability === 'hear') return post('/ai/hear', { probe: true }, 10000).then(function (reply) { return reply.hear === true; }, function () { return false; });
-      return post('/ai/status', {}, 10000).then(function (reply) { return reply[capability] === true; }, function () { return false; });
+    /** Whether this kind of AI ('text', 'decisions', 'pictures', 'act' or 'hear') can answer now: { available, reason,
+     *  help }, where `reason` is the short line to show when it can't, written for where the page is, and `help`, when
+     *  it's there, the page that says how to turn AI on, to link to beside it. */
+    status: function (capability) {
+      var no = function (reason, help) {
+        var said = { available: false, reason: reason || 'AI isn\'t set up for this here.' };
+        if (help) said.help = help;
+        return said;
+      };
+      // 'act' is asked of /ai/act itself: available only when this lamp.js has it, the app around the page lets the
+      // route through (an older one answers Not found) and the AI that answers the app can take it. 'hear' the same.
+      if (capability === 'act' || capability === 'hear') {
+        return post('/ai/' + capability, { probe: true }, 10000).then(function (reply) {
+          return reply[capability] === true ? { available: true, reason: '' } : no(reply.reason || reply.why);
+        }, function (e) { return no(e && e.message, e && e.help); });
+      }
+      return post('/ai/status', {}, 10000).then(function (reply) {
+        if (reply[capability] === true) return { available: true, reason: '' };
+        var detail = reply.details && reply.details[capability];
+        return no(detail && detail.reason);
+      }, function (e) { return no(e && e.message, e && e.help); });
     },
 
+    /** Whether this kind of AI can answer now, as `status` says. */
+    isAvailable: function (capability) { return LampAI.status(capability).then(function (s) { return s.available; }); },
+
     /** options: data (text from outside the app, for the AI to work on, not obey), images (pictures to look at),
      *  system, json (true asks for JSON and gives back the parsed value: describe its exact shape in the prompt),
      *  model (Lamp's id: "sonnet", "opus", "haiku", "claude-fable-5-2"). */
@@ -719,7 +776,7 @@
     /**
      * Does what the person asks, in their own words, with the app's own reads and writes: the model picks calls,
      * the page runs them, the model sees what happened, until it replies (at most 4 model calls and 6 writes a turn,
-     * and 25 seconds over OpenRouter or a minute through Claude Code, Codex or a model on the Mac). Check `LampAI.isAvailable('act')` first; keep the app's buttons for everything.
+     * with no time limit unless the app sets one with `limits: { seconds }`; Cancel ends it at once). Check `LampAI.isAvailable('act')` first; keep the app's buttons for everything.
      *
      *     var turn = LampAI.act('Add milk', {
      *       about: 'A family dashboard: the calendar, chores and the shopping list.',
@@ -816,6 +873,7 @@
      * probability, choice, score and confidence. Fails only when no item could be judged.
      */
     decideEach: function (items, questions, options) {
+      var failed = null;
       var o = options || {}, about = o.about || function (item) { return item; };
       var limit = Math.max(1, o.concurrency || 12), total = items.length, done = 0, next = 0;
       var results = new Array(total), saved = o.remember ? read('verdicts', {}) : null, now = Date.now();
@@ -843,7 +901,7 @@
           for (var k in (reply.answers || {})) if (reply.answers.hasOwnProperty(k)) answers[k] = decision(reply.answers[k]);
           if (key) saved[key] = { answers: reply.answers, until: now + o.remember * 1000 };
           finish(i, answers);
-        }, function (error) { finish(i, null, error.message); });
+        }, function (error) { if (!failed) failed = error; finish(i, null, error.message); });
       }
       function worker() {
         if (next >= total) return Promise.resolve();
@@ -859,7 +917,8 @@
           keys.slice(-2000).forEach(function (k) { kept[k] = saved[k]; });
           write('verdicts', kept);
         }
-        if (total && results.every(function (r) { return r.error; })) throw new Failure(results[0].error);
+        // Every item failed: the first failure's setup and help go with it, as a single decision's would.
+        if (total && results.every(function (r) { return r.error; })) throw new Failure(results[0].error, failed && failed.needsSetup, failed && failed.help);
         return results;
       });
     },

package/cli/lamps/lamp.js

@@ -113,10 +113,11 @@
     image: function (name) { return loadImage(LampAssets.url(name)); }
   };
 
-  function Failure(message, needsSetup) {
+  function Failure(message, needsSetup, help) {
     this.name = 'LampAI.Failure';
     this.message = message;
     this.needsSetup = needsSetup || null;
+    this.help = help || null;
     this.stack = (new Error(message)).stack;
   }
   Failure.prototype = Object.create(Error.prototype);
@@ -190,6 +191,8 @@
   }
 
   // Why a copy Lamp didn't put on a device has no AI: a page on the web (its published page) is away from Lamp.
+  // Where someone with no Lamp finds how to turn AI on, for a page away from Lamp.
+  var AI_HELP = 'https://lamp.dev';
   function unplaced() {
     return here.protocol === 'https:'
       ? 'This page is on the web, away from Lamp, so it has no AI here. Open it in Lamp for that.'
@@ -206,7 +209,7 @@
       var ipv4 = /^http:\/\/\d+\.\d+\.\d+\.\d+:/;
       list = list.filter(function (r) { return ipv4.test(r); }).concat(list.filter(function (r) { return !ipv4.test(r); }));
     }
-    if (!list.length) return Promise.reject(new Failure(unplaced()));
+    if (!list.length) return Promise.reject(new Failure(unplaced(), null, AI_HELP));
     // With a deadline (LampAI.act's turn), each try gets only the time left, and none starts after it.
     function left() { return deadline ? deadline - Date.now() : timeout; }
     function attempt(i, round) {
@@ -229,7 +232,7 @@
   function token() {
     var kept = read('install.token', null);
     if (kept && installed && kept.app === installed.app) return Promise.resolve(kept.token);
-    if (!installed) return Promise.reject(new Failure(unplaced()));
+    if (!installed) return Promise.reject(new Failure(unplaced(), null, AI_HELP));
     return send('/app/claim', { app: installed.app }, null, 10000).then(function (answer) {
       if (answer.status !== 200 || !answer.reply.token) {
         throw new Failure('This app needs Lamp to put it on this device once more before it can use AI: press Play in Lamp on your Mac.');
@@ -240,10 +243,50 @@
     });
   }
 
+  // A page shared on lamp.dev plays from a host of its own under play.lamp.dev, away from Lamp. The person's own
+  // Lamp or lamp on this computer can answer it (Lamp's `SharedPagesAI`, or `lamp ai`, at a port of the computer's
+  // own), once they've allowed this
+  // page there; the token it's given is kept with the page's saved things. Whether there's an AI is asked first,
+  // without one, so the person is asked only when the page uses it.
+  var NEARBY = 'http://127.0.0.1:47423';
+  function shared() { return !installed && here.protocol === 'https:' && /\.play\.lamp\.dev$/.test(here.hostname || ''); }
+  function safari() {
+    var ua = (window.navigator && navigator.userAgent) || '';
+    return /Safari\//.test(ua) && !/Chrome|Chromium|CriOS|Edg|OPR|Firefox|FxiOS/.test(ua);
+  }
+  function nearby(path, body, timeout, deadline) {
+    var text = JSON.stringify(body);
+    function go(t) { return exchange(NEARBY, path, t, text, deadline ? Math.max(1000, deadline - Date.now()) : timeout); }
+    function allow() {
+      return exchange(NEARBY, '/pair', null, JSON.stringify({ name: document.title || '' }), 130000).then(function (answer) {
+        if (answer.status !== 200 || !answer.reply.token) throw new Failure('This computer didn\'t allow this page to use its AI.');
+        write('nearby.token', answer.reply.token);
+        return answer.reply.token;
+      });
+    }
+    var kept = read('nearby.token', null);
+    var done = path === '/ai/status' || (body && body.probe === true) ? go(kept) : (kept ? Promise.resolve(kept) : allow()).then(function (t) {
+      return go(t).then(function (answer) {
+        if (answer.status !== 401) return answer;
+        // Taken back on the computer: ask once more.
+        forget('nearby.token');
+        return allow().then(go);
+      });
+    });
+    return done.then(null, function (e) {
+      if (e instanceof Failure) throw e;
+      // Safari never lets a page on the web reach this computer this way, so Lamp or lamp ai open here wouldn't help.
+      if (safari()) throw new Failure('AI here works in Chrome or in Lamp, or with Lamp\'s command line: lamp play and this page\'s link.', null, AI_HELP);
+      throw new Failure('AI isn\'t available here. Open Lamp on this computer, or with Lamp\'s command line, run lamp ai.', null, AI_HELP);
+    });
+  }
+
   function post(path, body, timeout, deadline) {
     timeout = timeout || 240000;
     var done;
-    if (bridge) {
+    if (!bridge && shared()) {
+      done = nearby(path, body, timeout, deadline);
+    } else if (bridge) {
       // The TV preview on the Mac answers for Lamp itself.
       done = bridge.postMessage({ path: path, body: JSON.stringify(body), timeout: timeout }).then(function (r) {
         var reply = {};
@@ -454,8 +497,11 @@
 
   // Doing things for the person: LampAI.act
 
-  // 60 seconds is the longest any route allows; each answer says its route's own (`seconds`), and the turn keeps to it.
-  var ACT_LIMITS = { steps: 4, writes: 6, seconds: 60 };
+  // A turn has no time limit of its own: a real answer is never cut off, however long the model takes. Each step is
+  // given ACT_STEP_SECONDS, which only a call that has stopped answering reaches. An app that wants a quicker turn
+  // asks for one (`limits: { seconds }`); steps and writes it may only lower.
+  var ACT_LIMITS = { steps: 4, writes: 6 };
+  var ACT_STEP_SECONDS = 600;
   var actRan = {};      // turn id -> call key -> the result a write gave, while this copy of the page is open
   function actId() { return 't' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8); }
   function isList(v) { return Object.prototype.toString.call(v) === '[object Array]'; }
@@ -481,10 +527,11 @@
   function act(request, options) {
     var o = options || {}, tools = o.tools || {};
     var limits = {};
-    ['steps', 'writes', 'seconds'].forEach(function (k) {
+    ['steps', 'writes'].forEach(function (k) {
       var asked = o.limits && typeof o.limits[k] === 'number' ? o.limits[k] : ACT_LIMITS[k];
       limits[k] = Math.max(1, Math.min(asked, ACT_LIMITS[k]));
     });
+    var asked = o.limits && typeof o.limits.seconds === 'number' && o.limits.seconds > 0 ? o.limits.seconds : null;
     var id = o.turn || actId();
     if (!actRan[id]) {
       var kept = Object.keys(actRan);
@@ -492,7 +539,7 @@
       actRan[id] = {};
     }
     var ran = actRan[id];
-    var started = Date.now(), deadline = started + limits.seconds * 1000;
+    var started = Date.now(), deadline = asked ? started + Math.max(1, asked) * 1000 : Infinity;
     var out = { turn: id, reply: '', ask: false, choices: [], done: [], failed: [], skipped: [], reads: [], stopped: null, error: '' };
     var steps = [], route = null, writes = 0, over = false, settle;
     var declared = Object.keys(tools).map(function (name) {
@@ -514,7 +561,7 @@
       return over;
     }
     var result = new Promise(function (resolve) { settle = resolve; });
-    var timer = setTimeout(function () { stop('time'); }, limits.seconds * 1000);
+    var timer = asked ? setTimeout(function () { stop('time'); }, Math.max(1, asked) * 1000) : null;
     result.then(function () { clearTimeout(timer); });
 
     // Reads run together; then the writes, one after another, each checked right before it runs. A write that
@@ -590,23 +637,15 @@
       if (over) return;
       var left = deadline - Date.now();
       if (left <= 500) return stop('time');
+      // The step's own time: what's left of an app's turn, or the step's guard against a call that has stopped.
+      var stepTime = Math.min(left, ACT_STEP_SECONDS * 1000);
       var body = { request: String(request), about: o.about || '', now: present(), tools: declared, steps: steps,
-                   history: (o.history || []).slice(-3), seconds: Math.floor(left / 1000) };
+                   history: (o.history || []).slice(-3), seconds: Math.floor(stepTime / 1000) };
       if (o.context !== undefined) body.context = jsonState(o.context);
       if (route) body.route = route;
       if (steps.length >= limits.steps - 1) body.final = true;
       if (o.model) body.model = o.model;
-      post('/ai/act', body, left, deadline).then(function (answer) {
-        // The route's own time for a turn (25 seconds over OpenRouter, a minute through Claude Code, Codex or a model
-        // on the Mac) shortens the turn's deadline, counted from its start; it never lengthens it.
-        if (!over && typeof answer.seconds === 'number' && answer.seconds > 0) {
-          var end = started + Math.min(answer.seconds, limits.seconds) * 1000;
-          if (end < deadline) {
-            deadline = end;
-            clearTimeout(timer);
-            timer = setTimeout(function () { stop('time'); }, Math.max(0, deadline - Date.now()));
-          }
-        }
+      post('/ai/act', body, stepTime, Date.now() + stepTime).then(function (answer) {
         // Cancelled, out of time or already over: an answer that comes late runs nothing.
         if (late()) return;
         route = answer.route || route;
@@ -693,24 +732,42 @@
    * Text calls take a few seconds; decisions well under a second; image calls 10-60 seconds. Show `error.message` on
    * failure. Aspect ratios look like "1:1", "16:9", "3:4".
    *
-   * Not every Mac has every kind of AI set up, and a device away from the Mac's Wi-Fi, or with Lamp closed, has none.
-   * `LampAI.isAvailable('pictures')` (or 'text', 'decisions') says whether it can answer now: check it where a
-   * feature depends on it, and show the feature with a short note ("Pictures need AI set up in Lamp") rather than
-   * hiding it or failing at it. A call that fails for that reason has `needsSetup` set on its error.
+   * Not every Mac has every kind of AI set up, a device away from the Mac's Wi-Fi or with Lamp closed has none, and a
+   * page shared on lamp.dev has it only on a computer that answers it. `LampAI.status('pictures')` (or 'text',
+   * 'decisions', 'act', 'hear') says whether it can answer now and, when it can't, the line to show: check it where
+   * a feature depends on it, and show the feature with its `reason` as it's given rather than words of the app's
+   * own, or hiding it or failing at it, and where it gives `help` (a page away from Lamp), a link to it beside the
+   * reason: "How to turn on AI". A call that fails for that reason has `needsSetup`, or `help`, set on its error.
    */
   var LampAI = {
     Failure: Failure,
 
-    /** Whether this kind of AI ('text', 'decisions', 'pictures' or 'act') can answer now. False when Lamp can't be reached. */
-    isAvailable: function (capability) {
-      // 'act' is asked of /ai/act itself: true only when this lamp.js has it, the app around the page lets the
-      // route through (an older one answers Not found) and the AI that answers the app can take it.
-      if (capability === 'act') return post('/ai/act', { probe: true }, 10000).then(function (reply) { return reply.act === true; }, function () { return false; });
-      // 'hear' the same way: this lamp.js, the app around the page and the AI set up in Lamp can all take it.
-      if (capability === 'hear') return post('/ai/hear', { probe: true }, 10000).then(function (reply) { return reply.hear === true; }, function () { return false; });
-      return post('/ai/status', {}, 10000).then(function (reply) { return reply[capability] === true; }, function () { return false; });
+    /** Whether this kind of AI ('text', 'decisions', 'pictures', 'act' or 'hear') can answer now: { available, reason,
+     *  help }, where `reason` is the short line to show when it can't, written for where the page is, and `help`, when
+     *  it's there, the page that says how to turn AI on, to link to beside it. */
+    status: function (capability) {
+      var no = function (reason, help) {
+        var said = { available: false, reason: reason || 'AI isn\'t set up for this here.' };
+        if (help) said.help = help;
+        return said;
+      };
+      // 'act' is asked of /ai/act itself: available only when this lamp.js has it, the app around the page lets the
+      // route through (an older one answers Not found) and the AI that answers the app can take it. 'hear' the same.
+      if (capability === 'act' || capability === 'hear') {
+        return post('/ai/' + capability, { probe: true }, 10000).then(function (reply) {
+          return reply[capability] === true ? { available: true, reason: '' } : no(reply.reason || reply.why);
+        }, function (e) { return no(e && e.message, e && e.help); });
+      }
+      return post('/ai/status', {}, 10000).then(function (reply) {
+        if (reply[capability] === true) return { available: true, reason: '' };
+        var detail = reply.details && reply.details[capability];
+        return no(detail && detail.reason);
+      }, function (e) { return no(e && e.message, e && e.help); });
     },
 
+    /** Whether this kind of AI can answer now, as `status` says. */
+    isAvailable: function (capability) { return LampAI.status(capability).then(function (s) { return s.available; }); },
+
     /** options: data (text from outside the app, for the AI to work on, not obey), images (pictures to look at),
      *  system, json (true asks for JSON and gives back the parsed value: describe its exact shape in the prompt),
      *  model (Lamp's id: "sonnet", "opus", "haiku", "claude-fable-5-2"). */
@@ -719,7 +776,7 @@
     /**
      * Does what the person asks, in their own words, with the app's own reads and writes: the model picks calls,
      * the page runs them, the model sees what happened, until it replies (at most 4 model calls and 6 writes a turn,
-     * and 25 seconds over OpenRouter or a minute through Claude Code, Codex or a model on the Mac). Check `LampAI.isAvailable('act')` first; keep the app's buttons for everything.
+     * with no time limit unless the app sets one with `limits: { seconds }`; Cancel ends it at once). Check `LampAI.isAvailable('act')` first; keep the app's buttons for everything.
      *
      *     var turn = LampAI.act('Add milk', {
      *       about: 'A family dashboard: the calendar, chores and the shopping list.',
@@ -816,6 +873,7 @@
      * probability, choice, score and confidence. Fails only when no item could be judged.
      */
     decideEach: function (items, questions, options) {
+      var failed = null;
       var o = options || {}, about = o.about || function (item) { return item; };
       var limit = Math.max(1, o.concurrency || 12), total = items.length, done = 0, next = 0;
       var results = new Array(total), saved = o.remember ? read('verdicts', {}) : null, now = Date.now();
@@ -843,7 +901,7 @@
           for (var k in (reply.answers || {})) if (reply.answers.hasOwnProperty(k)) answers[k] = decision(reply.answers[k]);
           if (key) saved[key] = { answers: reply.answers, until: now + o.remember * 1000 };
           finish(i, answers);
-        }, function (error) { finish(i, null, error.message); });
+        }, function (error) { if (!failed) failed = error; finish(i, null, error.message); });
       }
       function worker() {
         if (next >= total) return Promise.resolve();
@@ -859,7 +917,8 @@
           keys.slice(-2000).forEach(function (k) { kept[k] = saved[k]; });
           write('verdicts', kept);
         }
-        if (total && results.every(function (r) { return r.error; })) throw new Failure(results[0].error);
+        // Every item failed: the first failure's setup and help go with it, as a single decision's would.
+        if (total && results.every(function (r) { return r.error; })) throw new Failure(results[0].error, failed && failed.needsSetup, failed && failed.help);
         return results;
       });
     },

package/cli/lamps/mac-starter/.lamp/meta.json

@@ -1 +1 @@
-{"exe":"ZqxAppName","name":"Zqx App Name","platform":"mac","instance":"3986240D-BDA8-4CAF-B8C3-9F96F9A932FB"}
+{"instance":"0B0B3EAA-A528-48AA-99D7-F9045656CF78","name":"Zqx App Name","exe":"ZqxAppName","platform":"mac"}