@lampdotdev/lamp 0.0.0-stage → 0.36.2-nightly.16

package/cli/network.mjs

@@ -0,0 +1,209 @@
+// Everything on the person's home network, one record per address, for when they're looking for devices: SSDP and the
+// integrations find what Lamp can work with (devices.mjs); this finds the rest, so a list can say what else is there.
+// It only reads: one small datagram to each address of this computer's own subnet, so its neighbor table fills (a
+// phone that ignores everything else still answers ARP), that table, and every Bonjour service on the network
+// (mdns.mjs). And the TVs: what a Samsung or an LG TV says of itself. Nothing is kept on disk: the names a network
+// holds are often people's ("…'s iPhone").
+
+import { execFile } from "node:child_process";
+import dgram from "node:dgram";
+import { readFileSync } from "node:fs";
+import { networkInterfaces } from "node:os";
+import { isPrivate, onNetwork, ownAddresses, send, xmlAt } from "./devices.mjs";
+import { everything } from "./mdns.mjs";
+
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+
+/** What a system program says, or "" when it says nothing (it isn't there, or it failed). Never through a shell. */
+const said = (file, args) => new Promise((done) => execFile(file, args, { timeout: 5000 }, (error, out) => done(error ? "" : String(out))));
+
+// MARK: The subnet
+
+/** An IPv4 address as a number, or null. */
+export function valueOf(address) {
+  const parts = String(address).split(".");
+  if (parts.length !== 4 || !parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) < 256)) return null;
+  return parts.reduce((value, part) => (value * 256) + Number(part), 0);
+}
+const textOf = (value) => [24, 16, 8, 0].map((shift) => Math.floor(value / 2 ** shift) % 256).join(".");
+
+/**
+ * The subnet to sweep for an address and its mask: no more than the 256 addresses around this computer's on a bigger
+ * network, and none for an address that isn't on a home network.
+ */
+export function subnetOf(address, netmask) {
+  const mine = valueOf(address), mask = valueOf(netmask);
+  if (mine === null || mask === null) return null;
+  const actual = [...mask.toString(2)].filter((bit) => bit === "1").length;
+  if (actual < 8 || actual > 30 || !onNetwork(address)) return null;
+  const prefix = Math.max(actual, 24), size = 2 ** (32 - prefix);
+  return { network: textOf(mine - (mine % size)), prefix, actualPrefix: actual, mine: address };
+}
+
+const inSubnet = (subnet, address) => {
+  const value = valueOf(address), size = 2 ** (32 - subnet.prefix);
+  return value !== null && value - (value % size) === valueOf(subnet.network);
+};
+
+/** The default route: the interface it uses and the gateway it goes through. Null when there's none. */
+export async function defaultRoute() {
+  if (process.platform === "darwin") {
+    const text = await said("/sbin/route", ["-n", "get", "default"]);
+    const gateway = /^\s*gateway:\s*(\S+)/m.exec(text)?.[1], name = /^\s*interface:\s*(\S+)/m.exec(text)?.[1];
+    return name ? { interface: name, gateway: valueOf(gateway) === null ? null : gateway } : null;
+  }
+  if (process.platform === "linux") {
+    let table = "";
+    try { table = readFileSync("/proc/net/route", "utf8"); } catch { return null; }
+    for (const line of table.split("\n").slice(1)) {
+      const [name, destination, gateway, flags] = line.trim().split(/\s+/);
+      if (destination !== "00000000" || !(parseInt(flags, 16) & 2)) continue;
+      const bytes = gateway.match(/../g)?.reverse().map((byte) => parseInt(byte, 16));
+      return { interface: name, gateway: bytes?.length === 4 ? bytes.join(".") : null };
+    }
+  }
+  return null;
+}
+
+/** The subnet of the interface the default route uses, when it's a home network's. */
+export function subnetOn(name) {
+  const entry = (networkInterfaces()[name] ?? []).find((address) => address.family === "IPv4" && !address.internal);
+  return entry ? subnetOf(entry.address, entry.netmask) : null;
+}
+
+/** One datagram to each address of the subnet (one byte to the discard port, which nothing answers), a few at a time, paced, then a moment for the answers to ARP. */
+export async function sweep(subnet, { batch = 16, pause = 25, settle = 1500 } = {}) {
+  const socket = dgram.createSocket("udp4"), size = 2 ** (32 - subnet.prefix), network = valueOf(subnet.network);
+  socket.on("error", () => {});
+  await new Promise((done) => socket.bind(0, done));
+  const addresses = [];
+  for (let offset = 1; offset < size - 1; offset++) if (textOf(network + offset) !== subnet.mine) addresses.push(textOf(network + offset));
+  try {
+    for (let start = 0; start < addresses.length; start += batch) {
+      for (const address of addresses.slice(start, start + batch)) socket.send(Buffer.from([0]), 9, address, () => {});
+      await sleep(pause);
+    }
+    await sleep(settle);
+  } finally { try { socket.close(); } catch {} }
+}
+
+/** A hardware address with two digits to each part ("ae:b0:a9:01:eb:44"); null for a multicast or broadcast one, or none. */
+function hardware(text) {
+  const parts = String(text).toLowerCase().split(":");
+  if (parts.length !== 6 || !parts.every((part) => /^[0-9a-f]{1,2}$/.test(part))) return null;
+  const mac = parts.map((part) => part.padStart(2, "0"));
+  if (parseInt(mac[0], 16) & 1 || mac.every((part) => part === "ff")) return null;
+  return mac.join(":");
+}
+
+/**
+ * This computer's neighbor table: each neighbor's IPv4 address and hardware address, for those that answered. macOS
+ * shows it only to a process it lets on the local network: run on the runtime Lamp's app carries, it's empty, so
+ * Lamp's app reads its own (`Neighbours`).
+ */
+export async function neighbours() {
+  const table = {};
+  if (process.platform === "darwin") {
+    for (const [, address, mac] of (await said("/usr/sbin/arp", ["-an"])).matchAll(/\((\d+\.\d+\.\d+\.\d+)\) at ([0-9a-fA-F:]+) on /g)) {
+      const known = hardware(mac);
+      if (known) table[address] = known;
+    }
+  } else if (process.platform === "linux") {
+    let text = "";
+    try { text = readFileSync("/proc/net/arp", "utf8"); } catch {}
+    for (const line of text.split("\n").slice(1)) {
+      const [address, , flags, mac] = line.trim().split(/\s+/);
+      const known = (parseInt(flags, 16) & 2) && hardware(mac);
+      if (known && valueOf(address) !== null) table[address] = known;
+    }
+  }
+  return table;
+}
+
+/**
+ * The hosts of this computer's subnet, each with its hardware address and its Bonjour services, from a sweep, the
+ * neighbor table and every Bonjour service, browsed while the sweep runs. `swept` says which subnet was swept: on a
+ * network bigger than a /24 only the 256 addresses around this computer's are.
+ */
+export async function homeNetwork({ seconds = 3 } = {}) {
+  const services = everything({ seconds });
+  const route = await defaultRoute(), subnet = route ? subnetOn(route.interface) : null;
+  if (subnet) await sweep(subnet);
+  const table = await neighbours(), mine = ownAddresses();
+  const inside = (address) => (subnet ? inSubnet(subnet, address) : isPrivate(address)) || mine.has(address);
+  const hosts = new Map(), hostAt = (address) => hosts.get(address) ?? hosts.set(address, { address, mac: null, services: [] }).get(address);
+  for (const [address, mac] of Object.entries(table)) if (inside(address)) hostAt(address).mac = mac;
+  for (const { service, addresses } of await services) for (const address of addresses) if (inside(address)) hostAt(address).services.push(service);
+  for (const host of hosts.values()) {
+    host.isThisMac = mine.has(host.address);
+    host.isGateway = host.address === route?.gateway;
+  }
+  return { hosts: [...hosts.values()].sort((a, b) => (valueOf(a.address) ?? Infinity) - (valueOf(b.address) ?? Infinity)), swept: subnet, gateway: route?.gateway ?? null };
+}
+
+// MARK: TVs
+
+/** The service an LG TV announces for itself; the description it points at is the TV's own. */
+export const LG_TV = "urn:lge:device:tv:1";
+
+/** A page on the TV, read with every guard a request to a device has: its body, or null. */
+const fetched = (address) => (request) => send(request, address, {}, { timeout: 3000 }).then((answer) => (answer.status === 200 ? answer.body : null), () => null);
+
+/** A Samsung TV's own description of itself, from its local API; null when it isn't one. */
+export async function samsungAt(address, { get = fetched(address) } = {}) {
+  let device;
+  try { device = JSON.parse(String(await get({ port: 8001, path: "/api/v2/" }))).device; } catch { return null; }
+  if (device?.OS !== "Tizen") return null;
+  const modelID = typeof device.modelName === "string" ? device.modelName : "", frame = device.FrameTVSupport === "true";
+  // The size is in the model code (QN50…, UN65…).
+  const size = /^\d{2}$/.test(modelID.slice(2, 4)) ? modelID.slice(2, 4) : "";
+  const model = frame ? `The Frame${size ? ` ${size}` : ""}` : size ? `Smart TV ${size}` : modelID;
+  // The year is the first part of its internal model ("22_PONTUSM_FTV"), and each year has one Tizen.
+  const year = Number(String(device.model ?? "").slice(0, 2)) || 0;
+  const tizen = { 17: "3.0", 18: "4.0", 19: "5.0", 20: "5.5", 21: "6.0", 22: "6.5", 23: "7.0", 24: "8.0", 25: "9.0", 26: "10.0" }[year] ?? "";
+  const id = String(device.id ?? device.duid ?? address).replace("uuid:", "");
+  return { id: `samsung:${id}`, maker: "Samsung", name: typeof device.name === "string" ? device.name : "Samsung TV", model, modelID, address, os: "Tizen",
+    osVersion: tizen, resolution: typeof device.resolution === "string" ? device.resolution : "", frame,
+    developerIP: typeof device.developerIP === "string" ? device.developerIP : null, developerMode: device.developerMode === "1" };
+}
+
+/**
+ * An LG TV, from the UPnP descriptions its answers point at. It answers for several services, each with a
+ * description and an id of its own, and the first to answer is often one that says nothing of the TV (a streaming
+ * service's, a few bytes of "status=ok"), so each is tried until one is an LG TV's: the TV's own service first, which
+ * gives it the same id at every search. `udns` is every id it answered for, so a TV kept under another one is known.
+ */
+export async function lgAt(address, answers, { get = fetched(address) } = {}) {
+  const locations = [];
+  const own = answers.filter((answer) => String(answer.target).toLowerCase() === LG_TV).map((answer) => answer.location);
+  for (const location of [...own, ...answers.map((answer) => answer.location)]) {
+    let url;
+    try { url = new URL(location); } catch { continue; }
+    if (url.hostname === address && url.protocol === "http:" && !locations.includes(location)) locations.push(location);
+  }
+  // A USN is "uuid:<udn>" or "uuid:<udn>::<type>".
+  const udns = new Set(answers.map((answer) => String(answer.usn)).filter((usn) => usn.toLowerCase().startsWith("uuid:")).map((usn) => usn.slice(5).split("::")[0]).filter(Boolean));
+  for (const location of locations) {
+    const url = new URL(location), body = await get({ port: Number(url.port) || 80, path: (url.pathname || "/") + url.search });
+    if (!body) continue;
+    const tag = (name) => xmlAt(body, name) ?? null;
+    if (!(tag("manufacturer") ?? "").toUpperCase().startsWith("LG")) continue;
+    const udn = (tag("UDN") ?? address).replace("uuid:", "");
+    return { id: `lg:${udn}`, maker: "LG", name: tag("friendlyName") ?? "LG TV", model: tag("modelName") ?? "webOS TV", modelID: tag("modelNumber") ?? "",
+      address, os: "webOS", osVersion: "", resolution: "", udns: [...new Set([...udns, udn])].sort() };
+  }
+  return null;
+}
+
+/** The TVs among a search's answers, each asked who it is: one whose answers say Samsung, or webOS or LG. */
+export async function tvsIn(answers, { get } = {}) {
+  const byAddress = new Map();
+  for (const answer of answers) byAddress.set(answer.address, [...(byAddress.get(answer.address) ?? []), answer]);
+  const read = await Promise.all([...byAddress].map(([address, said]) => {
+    const words = said.map((answer) => `${answer.server}\n${answer.location ?? ""}\n${answer.target}`).join("\n").toLowerCase();
+    if (words.includes("samsung")) return samsungAt(address, get ? { get } : {});
+    if (words.includes("webos") || words.includes("lge")) return lgAt(address, said, get ? { get } : {});
+    return null;
+  }));
+  return read.filter(Boolean).filter((tv, index, all) => all.findIndex((other) => other.id === tv.id) === index);
+}

package/cli/openrouter.mjs

@@ -0,0 +1,133 @@
+// An app's AI asked of OpenRouter with the person's own key: the one place it's sent, for Lamp's app (`openRouterText`,
+// `openRouterChat`, `openRouterDecide` and `openRouterImage` in calls.mjs; `AppAI.viaOpenRouter`, `AppAct.openRouterStep`,
+// `AppAI.decide` and `AppAI.image`) and for lamp's own answers
+// (ai.mjs, with OPENROUTER_API_KEY). The key comes with each request and is kept nowhere here.
+
+const ENDPOINT = "https://openrouter.ai/api/v1/chat/completions";
+/** The model lamp answers with when none is named: the one Lamp's app offers first for apps' text. */
+export const DEFAULT_MODEL = "anthropic/claude-sonnet-5.5";
+const FILTERED = "The AI provider's content filter cut the reply off. Try rewording the request.";
+
+/** Why OpenRouter gave no answer: `kind` "refused" (with its `status` and `reply`), "filtered", "timeout" or "stopped". */
+export class OpenRouterTrouble extends Error {
+  constructor(kind, message, { status = 0, reply = {}, cost = 0 } = {}) {
+    super(message);
+    Object.assign(this, { kind, status, reply, cost });
+  }
+}
+
+/**
+ * A request for text: the prompt with its pictures (base64, with their `media_type`) and the system prompt. With
+ * `json` the answer must be a JSON object, with room for a long one (a cut-off reply is what breaks apps), and with a
+ * `schema` it must fit it too.
+ */
+export function textBody({ prompt, images = [], system = "", model = DEFAULT_MODEL, json = false, schema } = {}) {
+  const messages = [];
+  if (String(system).trim()) messages.push({ role: "system", content: system });
+  messages.push({ role: "user", content: [{ type: "text", text: prompt },
+    ...(Array.isArray(images) ? images : []).filter((image) => image?.data).map((image) => ({ type: "image_url", image_url: { url: `data:${image.media_type || "image/jpeg"};base64,${image.data}` } }))] });
+  const body = { model, messages, usage: { include: true } };
+  if (json) {
+    body.response_format = schema ? { type: "json_schema", json_schema: { name: "answer", strict: true, schema } } : { type: "json_object" };
+    body.max_tokens = 16000;
+  }
+  return body;
+}
+
+/**
+ * One chat completion: `{message, cost}`, the model's message as OpenRouter gives it (its text, or its tool calls) and
+ * what it cost. A provider's safety filter sometimes refuses an ordinary request at random (finish_reason
+ * "content_filter", an empty reply, HTTP 200), so it's asked again, twice at most, within the same `seconds`.
+ */
+export async function chat({ key, body, seconds = 120, signal, fetcher = fetch }) {
+  const deadline = Date.now() + seconds * 1000;
+  let cost = 0;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    // Whole milliseconds: a timer takes nothing finer, and the seconds given may have more.
+    const left = Math.floor(deadline - Date.now());
+    if (left < 1000) throw new OpenRouterTrouble("timeout", "This ran out of time.", { cost });
+    let answer;
+    try {
+      answer = await fetcher(ENDPOINT, { method: "POST", body: JSON.stringify(body),
+        headers: { Authorization: `Bearer ${key || ""}`, "Content-Type": "application/json", "X-Title": "Lamp" },
+        signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(left)]) : AbortSignal.timeout(left) });
+    } catch (error) {
+      if (signal?.aborted) throw new OpenRouterTrouble("stopped", "Stopped.", { cost });
+      if (error?.name === "TimeoutError" || Date.now() >= deadline) throw new OpenRouterTrouble("timeout", "This ran out of time.", { cost });
+      throw new OpenRouterTrouble("refused", "Couldn't reach OpenRouter.", { cost });
+    }
+    let reply = {};
+    try { reply = await answer.json(); } catch {}
+    cost += Number(reply?.usage?.cost) || 0;
+    const choice = Array.isArray(reply?.choices) ? reply.choices[0] : null;
+    if (answer.status !== 200 || !choice) throw new OpenRouterTrouble("refused", "OpenRouter didn't answer.", { status: answer.status, reply, cost });
+    if (choice.finish_reason === "content_filter") {
+      if (attempt < 2) { await new Promise((done) => setTimeout(done, Math.min(400 << attempt, Math.max(0, deadline - Date.now())))); continue; }
+      throw new OpenRouterTrouble("filtered", FILTERED, { cost });
+    }
+    return { message: choice.message ?? {}, cost };
+  }
+  throw new OpenRouterTrouble("refused", "The AI didn't answer.", { cost });
+}
+
+/** A text answer: `{text, cost}`. */
+export async function text(given) {
+  const { message, cost } = await chat({ ...given, body: textBody(given) });
+  return { text: typeof message.content === "string" ? message.content : "", cost };
+}
+
+/** One request to OpenRouter, within `seconds`: its status and its JSON, or why there was none. */
+async function post(path, { key, body, seconds, signal, fetcher = fetch }) {
+  const timeout = AbortSignal.timeout(Math.floor(seconds * 1000));
+  let answer;
+  try {
+    answer = await fetcher(`https://openrouter.ai/api/v1/${path}`, { method: "POST", body: JSON.stringify(body),
+      headers: { Authorization: `Bearer ${key || ""}`, "Content-Type": "application/json", "X-Title": "Lamp" },
+      signal: signal ? AbortSignal.any([signal, timeout]) : timeout });
+  } catch (error) {
+    if (signal?.aborted) throw new OpenRouterTrouble("stopped", "Stopped.");
+    if (error?.name === "TimeoutError") throw new OpenRouterTrouble("timeout", "This ran out of time.");
+    throw new OpenRouterTrouble("refused", "Couldn't reach OpenRouter.");
+  }
+  let reply = {};
+  try { reply = await answer.json(); } catch {}
+  return { status: answer.status, reply: reply && typeof reply === "object" ? reply : {} };
+}
+
+/**
+ * Decisions from a decision model (`LampAI.decide`, `AppAI.decide`): `{answers, cost}`. Rate limits (429) and overload
+ * (529) are expected under load, so it backs off and asks again three times at most. A request the model can't take
+ * (422) is "invalid", with what it said.
+ */
+export async function decide({ key, model, state, questions, seconds = 60, signal, fetcher }) {
+  for (let attempt = 0; attempt < 4; attempt++) {
+    const { status, reply } = await post("systemone", { key, body: { state, model, questions }, seconds, signal, fetcher });
+    if ((status === 429 || status === 529) && attempt < 3) { await new Promise((done) => setTimeout(done, 500 << attempt)); continue; }
+    if (status !== 200 || !reply.answers || typeof reply.answers !== "object") {
+      const detail = reply.error?.message ?? (reply.detail !== undefined ? String(typeof reply.detail === "string" ? reply.detail : JSON.stringify(reply.detail)) : `HTTP ${status}`);
+      throw new OpenRouterTrouble(status === 422 ? "invalid" : "refused", status === 422 ? `The decision request was invalid: ${detail}` : "The decision model didn't answer.", { status, reply });
+    }
+    // Jev charges per input token ($0.042 per million); OpenRouter may report the exact cost.
+    // A cost OpenRouter reports stands, nothing included; the estimate is only for when it reports none.
+    const reported = reply.usage?.cost;
+    const cost = typeof reported === "number" && Number.isFinite(reported) ? reported : (Number(reply.usage?.input_tokens) || 0) * 0.042 / 1_000_000;
+    return { answers: reply.answers, cost };
+  }
+  throw new OpenRouterTrouble("busy", "The decision model is busy. Try again in a moment.");
+}
+
+/**
+ * A picture from an image model (`LampAI.makeImage` and its edits, `AppAI.image`): `{image, cost}`, the PNG in base64.
+ * `references` are the pictures to edit or build on (base64, with their `media_type`).
+ */
+export async function image({ key, model, prompt, references = [], aspectRatio, seconds = 240, signal, fetcher }) {
+  const body = { model, prompt, n: 1, output_format: "png" };
+  if (aspectRatio) body.aspect_ratio = aspectRatio;
+  const given = (Array.isArray(references) ? references : []).filter((reference) => reference?.data);
+  if (given.length) body.input_references = given.map((reference) => ({ type: "image_url", image_url: { url: `data:${reference.media_type || "image/png"};base64,${reference.data}` } }));
+  const { status, reply } = await post("images", { key, body, seconds, signal, fetcher });
+  if (status !== 200) throw new OpenRouterTrouble("refused", "The image model didn't answer.", { status, reply });
+  const picture = Array.isArray(reply.data) ? reply.data[0]?.b64_json : null;
+  if (typeof picture !== "string" || !picture) throw new OpenRouterTrouble("empty", "The image model didn't return a picture.", { reply });
+  return { image: picture, cost: Number(reply.usage?.cost) || 0 };
+}

package/cli/outside.mjs

@@ -0,0 +1,203 @@
+// Lamp's app, reached the way the person's own coding agent reaches it (`OutsideServer`, Lamp's MCP endpoint): a Unix
+// socket in that Lamp's own folder, private to the person, a hello line each way, then JSON-RPC a line at a time. lamp
+// asks it to take a Mac app's folder on (`open_project`, which Lamp reviews with the person first), to put each change
+// into the app it has open (`apply_change`, which says how it went in: live, held for a Reload, reopened…), and to
+// look at it (`look_at_app`). What a change does to an open app is Lamp's app's to work out (`LiveReload`); this only
+// carries the folder's path there and the answer back.
+
+import { createConnection } from "node:net";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { Problem, stateOf } from "./state.mjs";
+
+// The handshake's version, as Lamp's helper sends it (`OutsideKit.protocolVersion`).
+const PROTOCOL = 1;
+
+/** What a Lamp is called where its folders are, by its bundle id (`OutsideKit.editionName`). */
+export function editionName(bundle) {
+  if (bundle === "dev.lamp.host.dev" || bundle.startsWith("dev.lamp.host.dev.")) {
+    const instance = bundle.startsWith("dev.lamp.host.dev.") ? bundle.slice("dev.lamp.host.dev.".length) : "";
+    return "Lamp Dev" + (instance ? ` ${instance}` : "");
+  }
+  return bundle === "dev.lamp.host.nightly" ? "Lamp Nightly" : "Lamp";
+}
+
+const socketOf = (bundle) => join(homedir(), "Library", "Application Support", editionName(bundle), "MCP", "lamp.sock");
+
+/** The Lamps lamp looks for, in order: the one LAMP_APP names (a bundle id), else the release and then Lamp Nightly. */
+const candidates = () => process.env.LAMP_APP ? [process.env.LAMP_APP] : ["dev.lamp.host", "dev.lamp.host.nightly"];
+
+/**
+ * A connection to a running Lamp, greeted: `call(tool, args)` answers what the tool said (its outcome, its words and
+ * its pictures). Null when no Lamp lamp knows of is answering.
+ */
+export async function reachLamp(bundles = candidates()) {
+  for (const bundle of bundles) {
+    if (!/^dev\.lamp\.host(\.[A-Za-z0-9-]+)*$/.test(bundle) || !existsSync(socketOf(bundle))) continue;
+    const lamp = await connected(bundle).catch(() => null);
+    if (lamp) return lamp;
+  }
+  return null;
+}
+
+function connected(bundle) {
+  return new Promise((done, failed) => {
+    const socket = createConnection(socketOf(bundle));
+    let buffer = "", greeted = false, next = 1, ended = null;
+    const waiting = new Map();
+    // Once the connection is gone, every call is refused with why, those under way and those asked later alike.
+    const fail = (problem) => {
+      ended ??= problem;
+      for (const { failed: no } of waiting.values()) no(problem);
+      waiting.clear();
+      failed(problem);
+    };
+    socket.setEncoding("utf8");
+    socket.on("error", (error) => fail(new Problem(`couldn't reach ${editionName(bundle)}: ${error.message}`)));
+    socket.on("close", () => fail(new Problem(`${editionName(bundle)} closed the connection`)));
+    socket.on("connect", () => socket.write(JSON.stringify({ lamp_hello: { protocol: PROTOCOL, client: "lamp" } }) + "\n"));
+    const send = (method, params) => new Promise((answered, no) => {
+      if (ended) return no(ended);
+      const id = next++;
+      waiting.set(id, { answered, failed: no });
+      socket.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
+    });
+    socket.on("data", async (chunk) => {
+      buffer += chunk;
+      for (let at; (at = buffer.indexOf("\n")) >= 0; ) {
+        const line = buffer.slice(0, at);
+        buffer = buffer.slice(at + 1);
+        if (!line.trim()) continue;
+        let said;
+        try { said = JSON.parse(line); } catch { continue; }
+        if (!greeted) {
+          if (said.lamp_hello?.error) { socket.destroy(); return failed(new Problem(said.lamp_hello.error)); }
+          if (!said.lamp_hello) { socket.destroy(); return failed(new Problem(`${editionName(bundle)} didn't answer as Lamp does`)); }
+          greeted = true;
+          try {
+            await send("initialize", { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "lamp", version: "1" } });
+            socket.write(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }) + "\n");
+          } catch (error) { return failed(error); }
+          done({
+            name: editionName(bundle), bundle,
+            async call(tool, args) {
+              const result = await send("tools/call", { name: tool, arguments: args });
+              return answerOf(result);
+            },
+            close() { ended ??= new Problem("the connection to Lamp was closed"); socket.removeAllListeners("close"); socket.end(); },
+          });
+          continue;
+        }
+        const one = waiting.get(said.id);
+        if (!one) continue;
+        waiting.delete(said.id);
+        if (said.error) one.failed(new Problem(said.error.message ?? "Lamp refused it"));
+        else one.answered(said.result ?? {});
+      }
+    });
+  });
+}
+
+/** A tool's answer as lamp reads it: the outcome its words lead with, the words after it, and its pictures. */
+export function answerOf(result) {
+  const content = Array.isArray(result?.content) ? result.content : [];
+  const text = content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+  const outcome = /^Outcome: ([a-z_]+)\./.exec(text)?.[1] ?? null;
+  // The facts are one line of JSON under the outcome: kept for whoever reads them, out of the words.
+  const lines = text.split("\n");
+  let facts = {};
+  if (outcome && lines[1]?.startsWith("{")) { try { facts = JSON.parse(lines[1]); } catch {} }
+  const words = (outcome ? lines.slice(lines[1]?.startsWith("{") ? 2 : 1) : lines).join("\n").trim();
+  const pictures = content.filter((part) => part.type === "image" && part.data).map((part) => Buffer.from(part.data, "base64"));
+  return { outcome, facts, words, pictures, failed: result?.isError === true };
+}
+
+/**
+ * The Lamp whose own folder an app's is in (`~/Library/Application Support/<Lamp>/Apps/…`, followed through a link to
+ * it), by its bundle id, or null for a folder of anyone else's.
+ */
+export function lampOwning(folder) {
+  let real = folder;
+  try { real = realpathSync(folder); } catch {}
+  const name = new RegExp(`${join(homedir(), "Library", "Application Support").replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/(Lamp(?: Nightly| Dev(?: [A-Za-z0-9-]+)?)?)/Apps/`).exec(real)?.[1];
+  if (!name) return null;
+  if (name === "Lamp") return "dev.lamp.host";
+  if (name === "Lamp Nightly") return "dev.lamp.host.nightly";
+  return name === "Lamp Dev" ? "dev.lamp.host.dev" : `dev.lamp.host.dev.${name.slice("Lamp Dev ".length)}`;
+}
+
+// MARK: Which folders are Lamp's app's
+
+const markOf = (folder) => join(stateOf(folder), "in-lamp.json");
+
+/** The Lamp a folder was given to (`lamp open --in-lamp`), by its bundle id, or null for one lamp runs itself. */
+export function givenTo(folder) {
+  try { return JSON.parse(readFileSync(markOf(folder), "utf8")).bundle ?? null; } catch { return null; }
+}
+
+export function giveTo(folder, bundle) {
+  mkdirSync(stateOf(folder), { recursive: true });
+  writeFileSync(markOf(folder), JSON.stringify({ bundle }));
+}
+
+export function takeBack(folder) { rmSync(markOf(folder), { force: true }); }
+
+/** The pictures an answer brought, kept where lamp keeps a look's, by their paths. */
+export function keepPictures(folder, pictures) {
+  mkdirSync(stateOf(folder), { recursive: true });
+  return pictures.map((bytes, n) => {
+    const path = join(stateOf(folder), `lamp-look${n ? `-${n + 1}` : ""}.png`);
+    writeFileSync(path, bytes);
+    return path;
+  });
+}
+
+/**
+ * The link Lamp's app keeps for an app in its own folder (its "Wish Links.json", by the app's instance id), as lamp
+ * keeps a link (`readLink`), or null. lamp shares such an app itself, to the same link, whether Lamp is open or not.
+ */
+export function lampsKeptLink(folder) {
+  const where = keptLinkOf(folder);
+  if (!where) return null;
+  let kept;
+  try { kept = JSON.parse(readFileSync(where.file, "utf8"))[where.key]; } catch { return null; }
+  if (typeof kept?.id !== "string" || typeof kept.secret !== "string" || typeof kept.url !== "string") return null;
+  const shown = kept.shown ?? {};
+  let site = "https://lamp.dev";
+  try { site = new URL(kept.url).origin; } catch {}
+  return { site, id: kept.id, url: kept.url, secret: kept.secret, name: shown.name ?? "", words: shown.words ?? "", line: shown.line ?? "",
+    by: shown.by ?? "", asks: shown.asks ?? [], ...(shown.file ? { file: true } : {}) };
+}
+
+/** Tells Lamp's app what lamp shared to an app's link (or, with none, that it was taken down), so its Share Link card
+ * shows the link as it is now. */
+export function keepInLamp(folder, link) {
+  const where = keptLinkOf(folder);
+  if (!where) return;
+  let all = {};
+  try { all = JSON.parse(readFileSync(where.file, "utf8")) || {}; } catch {}
+  const was = all[where.key] ?? {};
+  // Taken down: Lamp's card has no link for it any more.
+  if (!link) delete all[where.key];
+  else all[where.key] = { ...was, id: link.id, url: link.url, secret: link.secret,
+    // Its picture isn't the one Lamp took (Lamp knows its own by a digest), so the card offers to send Lamp's again.
+    shown: { ...(({ picture: _picture, ...rest }) => rest)(was.shown ?? {}), name: link.name, words: link.words, line: link.line, by: link.by,
+      asks: link.asks ?? [], file: link.file ? true : undefined,
+      ...(link.shape !== undefined ? { shape: link.shape === "fill" ? "fill" : Number(link.shape).toFixed(4) } : {}) } };
+  mkdirSync(dirname(where.file), { recursive: true });
+  writeFileSync(where.file, JSON.stringify(all), { mode: 0o600 });
+}
+
+/** Where Lamp's app keeps an app's link: its Lamp's "Wish Links.json", under the app's instance id (`.lamp/meta.json`). */
+function keptLinkOf(folder) {
+  let real = folder;
+  try { real = realpathSync(folder); } catch {}
+  const at = real.lastIndexOf("/Apps/");
+  if (!lampOwning(real) || at < 0) return null;
+  const app = join(real.slice(0, at), "Apps", real.slice(at + 6).split("/")[0]);
+  let meta;
+  try { meta = JSON.parse(readFileSync(join(app, ".lamp", "meta.json"), "utf8")); } catch { return null; }
+  const key = typeof meta?.instance === "string" && meta.instance ? meta.instance : meta?.id;
+  return typeof key === "string" && key ? { file: join(real.slice(0, at), "Wish Links.json"), key } : null;
+}