Skip to content

Your home as a live 3D model in the Mac menu bar and on iPhone — lights and ACs via Smart Life, Home Assistant, Philips Hue and Apple Home.

38.6 KB
Raw Blame
// What an AI can do with the home: the tools (shared by MCP and the HTTP API), the guide
// an AI reads from the link, and the plain action links for chat assistants that can only
// open pages. Runs in the panel page, where the state of every device lives; the native
// shell only carries requests here (see AgentGateway.swift).
import { AC_MODES, AC_FANS } from '../store.js';
import { applyOperations, replacePlan, redactPlan, furnitureCatalog, PlanEditError, SCENE_ICONS, WALLS } from './plan-edit.js';
import { LIGHT_KINDS, FLOOR_KINDS, isLinked } from '../config.js';

export const COLORS = {
  red: '#ff3b30', orange: '#ff9500', yellow: '#ffd60a', green: '#34c759',
  cyan: '#32d2f5', blue: '#0a84ff', purple: '#8b5cff', pink: '#ff5fc4',
};
const WHITES = { warm: 2700, neutral: 4000, cool: 6500 };

const clamp = (v, a, b) => Math.min(b, Math.max(a, v));
const pct = (v) => `${Math.round(v * 100)}%`;

class ToolError extends Error {}
const fail = (msg) => { throw new ToolError(msg); };

export function createAgent({ store, config, raw, render, onAction }) {
  const { state } = store;
  const roomName = new Map(config.rooms.map((r) => [r.id, r.name]));

  /* ---------- describing the home ---------- */

  function lightAbilities(cfg) {
    const c = cfg.capabilities;
    if (!c.length) return 'on/off only';
    return [c.includes('brightness') && 'dims', c.includes('temp') && 'white temperature', c.includes('color') && 'colour']
      .filter(Boolean).join(', ');
  }

  function lightState(cfg, s = state.lights[cfg.id]) {
    if (!s.on) return 'off';
    const parts = ['on'];
    if (cfg.capabilities.includes('brightness')) parts.push(pct(s.brightness));
    if (s.color && cfg.capabilities.includes('color')) parts.push(`colour ${s.color}`);
    else if (cfg.capabilities.includes('temp')) parts.push(`${s.temp} K`);
    return parts.join(', ');
  }

  function acState(cfg, s = state.acs[cfg.id]) {
    const room = `room ${s.roomTemp.toFixed(1)}°C`;
    if (!s.on) return `off (${room})`;
    return `on, ${s.mode}, target ${s.target}°C, fan ${s.fan} (${room})`;
  }

  const lightJSON = (cfg) => ({
    id: cfg.id, name: cfg.name, room: cfg.room, type: cfg.type, abilities: cfg.capabilities,
    real: isLinked(cfg), ...state.lights[cfg.id],
    brightness: Math.round(state.lights[cfg.id].brightness * 100),
  });
  const acJSON = (cfg) => ({
    id: cfg.id, name: cfg.name, room: cfg.room, real: isLinked(cfg),
    min: cfg.min, max: cfg.max, modes: store.acFeatures(cfg.id).modes, fans: store.acFeatures(cfg.id).fans,
    on: state.acs[cfg.id].on, target: state.acs[cfg.id].target, mode: state.acs[cfg.id].mode,
    fan: state.acs[cfg.id].fan, roomTemp: state.acs[cfg.id].roomTemp,
  });

  function overview() {
    const lightsOn = config.lights.filter((l) => state.lights[l.id].on).length;
    const acsOn = config.acs.filter((a) => state.acs[a.id].on).length;
    const scene = config.scenes.find((s) => s.id === state.scene);
    const lines = [
      `Home "${config.name}": ${config.rooms.length} rooms, ${config.lights.length} lights (${lightsOn} on), `
      + `${config.acs.length} air conditioners (${acsOn} running).${scene ? ` Active scene: ${scene.name}.` : ''}`,
    ];
    for (const room of config.rooms) {
      const lights = config.lights.filter((l) => l.room === room.id);
      const acs = config.acs.filter((a) => a.room === room.id);
      if (!lights.length && !acs.length) { lines.push('', `${room.name} [${room.id}] — no devices`); continue; }
      lines.push('', `${room.name} [${room.id}]`);
      for (const l of lights) lines.push(`  • ${l.name} [${l.id}] — light (${l.type}; ${lightAbilities(l)}): ${lightState(l)}`);
      for (const a of acs) lines.push(`  • ${a.name} [${a.id}] — air conditioner (${a.min}–${a.max}°C): ${acState(a)}`);
    }
    if (config.scenes.length) {
      lines.push('', `Scenes: ${config.scenes.map((s) => `${s.name} [${s.id}]`).join(', ')}`);
    }
    return lines.join('\n');
  }

  function structured() {
    return {
      home: config.name,
      scene: state.scene,
      rooms: config.rooms.map((r) => ({
        id: r.id, name: r.name,
        lights: config.lights.filter((l) => l.room === r.id).map(lightJSON),
        acs: config.acs.filter((a) => a.room === r.id).map(acJSON),
      })),
      scenes: config.scenes.map((s) => ({ id: s.id, name: s.name })),
    };
  }

  /* ---------- finding devices ---------- */

  const norm = (s) => String(s).toLowerCase().replace(/[\s_-]+/g, ' ').trim();

  // "living.main", "living" (a room), "all", or a name: "Floor lamp", "Living floor lamp".
  function resolve(targets, list, what) {
    if (targets == null) fail(`Say which ${what} to change: ids, room ids, names, or "all".`);
    const wanted = Array.isArray(targets) ? targets : [targets];
    if (!wanted.length) fail(`The list of ${what} is empty.`);
    const out = new Set();
    for (const t of wanted) {
      const key = norm(t);
      if (key === 'all' || key === '*' || key === 'everything') { for (const d of list) out.add(d); continue; }
      const byId = list.find((d) => d.id === t);
      if (byId) { out.add(byId); continue; }
      const room = config.rooms.find((r) => r.id === t || norm(r.name) === key);
      if (room) {
        const inRoom = list.filter((d) => d.room === room.id);
        if (!inRoom.length) fail(`${room.name} has no ${what}.`);
        for (const d of inRoom) out.add(d);
        continue;
      }
      const byName = list.filter((d) => norm(d.name) === key || norm(`${roomName.get(d.room)} ${d.name}`) === key);
      if (byName.length === 1) { out.add(byName[0]); continue; }
      const loose = list.filter((d) => norm(`${roomName.get(d.room)} ${d.name} ${d.id}`).includes(key));
      if (byName.length > 1 || loose.length > 1) {
        fail(`"${t}" matches several ${what}: ${(byName.length > 1 ? byName : loose).map((d) => `${d.name} [${d.id}]`).join(', ')}. Use an id.`);
      }
      if (loose.length === 1) { out.add(loose[0]); continue; }
      fail(`No ${what.replace(/s$/, '')} matches "${t}". Known: ${list.map((d) => `${d.name} [${d.id}]`).join(', ')}.`);
    }
    return [...out];
  }

  function parseColor(value) {
    const key = norm(value);
    if (COLORS[key]) return COLORS[key];
    const hex = String(value).trim().replace(/^#?/, '#');
    if (/^#[0-9a-f]{6}$/i.test(hex)) return hex.toLowerCase();
    fail(`Colour "${value}" is not understood. Use #rrggbb or one of ${Object.keys(COLORS).join(', ')}.`);
    return null;
  }

  /* ---------- actions ---------- */

  function setLights(args) {
    const devices = resolve(args.lights ?? args.targets ?? args.target, config.lights, 'lights');
    const notes = [];
    const changed = [];
    for (const cfg of devices) {
      const caps = cfg.capabilities;
      const patch = {};
      if (args.on != null) patch.on = Boolean(args.on);
      if (args.brightness != null) {
        const b = Number(args.brightness);
        if (!Number.isFinite(b)) fail('"brightness" is a percentage, 1–100.');
        if (caps.includes('brightness')) { patch.brightness = clamp(b > 1 || b === 0 ? b / 100 : b, 0.05, 1); patch.on ??= true; }
        else notes.push(`${cfg.name} cannot dim.`);
      }
      if (args.white != null && args.color_temperature == null) args.color_temperature = WHITES[norm(args.white)] ?? fail('"white" is warm, neutral or cool.');
      if (args.color_temperature != null) {
        if (caps.includes('temp')) { patch.temp = clamp(Number(args.color_temperature), 2200, 6500); patch.color = null; patch.on ??= true; }
        else notes.push(`${cfg.name} has no adjustable white.`);
      }
      if (args.color != null) {
        if (caps.includes('color')) { patch.color = parseColor(args.color); patch.on ??= true; }
        else notes.push(`${cfg.name} cannot change colour.`);
      }
      if (args.toggle) patch.on = !state.lights[cfg.id].on;
      if (!Object.keys(patch).length) continue;
      store.setLight(cfg.id, patch);
      changed.push(cfg);
    }
    if (!changed.length && !notes.length) fail('Nothing to change: pass "on", "brightness", "color_temperature" or "color".');
    return { changed, notes };
  }

  function setACs(args) {
    const devices = resolve(args.acs ?? args.targets ?? args.target, config.acs, 'air conditioners');
    const notes = [];
    const changed = [];
    for (const cfg of devices) {
      const f = store.acFeatures(cfg.id);
      const patch = {};
      if (args.temperature != null) {
        const t = Math.round(Number(args.temperature));
        if (!Number.isFinite(t)) fail('"temperature" is in °C.');
        if (t < cfg.min || t > cfg.max) notes.push(`${cfg.name} goes from ${cfg.min} to ${cfg.max}°C; set to ${clamp(t, cfg.min, cfg.max)}.`);
        patch.target = clamp(t, cfg.min, cfg.max);
      }
      if (args.mode != null) {
        if (!f.modes.includes(args.mode)) fail(`${cfg.name} modes: ${f.modes.join(', ')}.`);
        patch.mode = args.mode;
      }
      if (args.fan != null) {
        if (!f.fans.includes(args.fan)) fail(`${cfg.name} fan speeds: ${f.fans.join(', ')}.`);
        patch.fan = args.fan;
      }
      // "Set the bedroom AC to 22" means it should be running.
      if (args.on != null) patch.on = Boolean(args.on);
      else if (Object.keys(patch).length) patch.on = true;
      if (!Object.keys(patch).length) continue;
      store.setAC(cfg.id, patch);
      changed.push(cfg);
    }
    if (!changed.length) fail('Nothing to change: pass "on", "temperature", "mode" or "fan".');
    return { changed, notes };
  }

  function activateScene(args) {
    const key = norm(args.scene ?? '');
    const scene = config.scenes.find((s) => s.id === args.scene || norm(s.name) === key);
    if (!scene) fail(`No scene "${args.scene}". Scenes: ${config.scenes.map((s) => `${s.name} [${s.id}]`).join(', ') || 'none'}.`);
    store.applyScene(scene.id);
    return scene;
  }

  function describeChange(changed, notes, kind) {
    const lines = changed.map((cfg) => (kind === 'light'
      ? `${roomName.get(cfg.room)} · ${cfg.name}: ${lightState(cfg)}`
      : `${roomName.get(cfg.room)} · ${cfg.name}: ${acState(cfg)}`));
    return [...lines, ...notes].join('\n');
  }

  function shortSummary(changed, kind) {
    const names = changed.map((c) => c.name);
    const list = names.length > 3 ? `${names.length} ${kind === 'light' ? 'lights' : 'ACs'}` : names.join(', ');
    if (kind === 'light') {
      const on = changed.filter((c) => state.lights[c.id].on).length;
      const verb = on === changed.length ? 'On' : on === 0 ? 'Off' : 'Set';
      const first = state.lights[changed[0].id];
      const extra = changed.length === 1 && first.on && changed[0].capabilities.includes('brightness') ? ` · ${pct(first.brightness)}` : '';
      return `${verb}: ${list}${extra}`;
    }
    const a = state.acs[changed[0].id];
    return a.on ? `${list} → ${a.target}° ${a.mode}` : `Off: ${list}`;
  }

  /* ---------- the tools ---------- */

  const TARGETS = {
    type: 'array', items: { type: 'string' },
    description: 'Which devices: ids like "living.main", room ids like "living" (every one in the room), names, or "all".',
  };
  const FURNITURE_ITEM = {
    type: 'object',
    required: ['type', 'pos'],
    properties: {
      type: { type: 'string', enum: furnitureCatalog().map((f) => f.type) },
      pos: { type: 'array', items: { type: 'number' }, minItems: 2, maxItems: 2, description: '[x, z] of the centre, metres' },
      rot: { type: 'number', description: 'Degrees. 0: the front faces south (+z), back to the north wall; 90: faces east; -90: faces west; 180: faces north' },
      width: { type: 'number' }, height: { type: 'number' },
      size: { type: 'array', items: { type: 'number' }, description: 'rug only: [width, depth]' },
      color: { type: 'string', description: '#rrggbb (sofa, armchair, rug, bed)' },
      chairs: { type: 'integer' }, stools: { type: 'integer' }, upper: { type: 'boolean' },
      depth: { type: 'number', description: 'stairs only: their length, metres' },
      level: { type: 'string', description: 'on a home with floors: the id of the floor it stands on' },
    },
  };

  const TOOLS = [
    {
      name: 'get_home', group: 'read',
      title: 'Look at the home',
      description: 'Every room with its lights and air conditioners, what each can do and what it is doing now, and the scenes. Call this first.',
      inputSchema: { type: 'object', properties: {} },
      annotations: { readOnlyHint: true, openWorldHint: false },
      run: () => ({ text: overview(), data: structured(), summary: 'Looked at the home', quiet: true }),
    },
    {
      name: 'set_lights', group: 'control',
      title: 'Switch or adjust lights',
      description: 'Turn lights on or off, dim them, or change their white temperature or colour. Several lights at once is fine. '
        + 'Brightness, temperature or colour also switch a light on. Lights that cannot do something are reported, not failed.',
      inputSchema: {
        type: 'object', required: ['lights'],
        properties: {
          lights: TARGETS,
          on: { type: 'boolean' },
          toggle: { type: 'boolean', description: 'Flip each light' },
          brightness: { type: 'number', minimum: 1, maximum: 100, description: 'Percent' },
          color_temperature: { type: 'number', minimum: 2200, maximum: 6500, description: 'Kelvin: 2700 warm, 4000 neutral, 6500 cool' },
          white: { type: 'string', enum: Object.keys(WHITES) },
          color: { type: 'string', description: `#rrggbb or ${Object.keys(COLORS).join(', ')}` },
        },
      },
      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
      run(args) {
        const { changed, notes } = setLights(args);
        return { text: describeChange(changed, notes, 'light') || notes.join('\n'), summary: changed.length ? shortSummary(changed, 'light') : notes[0] };
      },
    },
    {
      name: 'set_air_conditioners', group: 'control',
      title: 'Control air conditioners',
      description: 'Switch air conditioners on or off and set the target temperature, mode and fan speed. '
        + 'Setting a temperature, mode or fan also switches the unit on unless "on": false is given.',
      inputSchema: {
        type: 'object', required: ['acs'],
        properties: {
          acs: { ...TARGETS, description: 'Which units: ids like "living.ac", room ids, names, or "all".' },
          on: { type: 'boolean' },
          temperature: { type: 'number', description: 'Target in °C' },
          mode: { type: 'string', enum: AC_MODES },
          fan: { type: 'string', enum: AC_FANS },
        },
      },
      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
      run(args) {
        const { changed, notes } = setACs(args);
        return { text: describeChange(changed, notes, 'ac'), summary: shortSummary(changed, 'ac') };
      },
    },
    {
      name: 'activate_scene', group: 'control',
      title: 'Activate a scene',
      description: 'Set every light and air conditioner the way a scene says ("Cozy", "Movie", "Night"…). See get_home for the list.',
      inputSchema: { type: 'object', required: ['scene'], properties: { scene: { type: 'string', description: 'Scene id or name' } } },
      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
      run(args) {
        const scene = activateScene(args);
        const on = config.lights.filter((l) => state.lights[l.id].on);
        return {
          text: `Scene "${scene.name}" is on. Lights on now: ${on.map((l) => `${l.name} (${lightState(l)})`).join(', ') || 'none'}.`,
          summary: `Scene · ${scene.name}`,
        };
      },
    },
    {
      name: 'get_floor_plan', group: 'read',
      title: 'Read the 3D floor plan',
      description: 'The floor plan the 3D model is built from: rooms, walls openings, furniture (by index), lights, ACs and scenes, '
        + 'plus the furniture catalogue and the coordinate rules. Read it before edit_floor_plan.',
      inputSchema: { type: 'object', properties: {} },
      annotations: { readOnlyHint: true, openWorldHint: false },
      run() {
        const plan = redactPlan(raw);
        const furniture = (plan.furniture || []).map((f, index) => ({ index, ...f }));
        return {
          text: `${PLAN_RULES}\n\nFurniture catalogue (type — default [width, depth] in m — notes):\n`
            + furnitureCatalog().map((f) => `  ${f.type} — [${f.footprint.join(', ')}] — ${f.about}`).join('\n')
            + `\n\nThe plan (furniture listed with its index):\n${JSON.stringify({ ...plan, furniture }, null, 1)}`,
          data: { plan: { ...plan, furniture }, catalogue: furnitureCatalog() },
          summary: 'Read the floor plan', quiet: true,
        };
      },
    },
    {
      name: 'edit_floor_plan', group: 'edit',
      title: 'Change the 3D floor plan',
      description: 'Change the home\'s 3D model with a list of operations, applied together (all or nothing). The model on the user\'s screen updates at once, '
        + 'and the change can be undone with undo_floor_plan_edit. To rebuild a room from photos use one "furnish_room" operation with every piece you see. '
        + 'Operations: set_home{name,outdoorTemp,wallHeight}, add_floor{id,name,wallHeight,below}, update_floor{id,name,wallHeight}, '
        + 'add_room{id,name,rect,floor,level}, update_room{id,name,rect,floor}, remove_room{id}, '
        + 'furnish_room{room,items[]}, add_furniture{item|items[]}, update_furniture{index,set{}}, remove_furniture{index}, '
        + 'add_opening{type,from,to,sill,head,level}, remove_opening{index}, add_light{id,name,room,type,pos,capabilities,y,rot,length,color}, '
        + 'update_light{id,set{}}, remove_light{id}, add_ac{id,name,room,wall,pos,y,min,max}, update_ac{id,set{}}, remove_ac{id}, '
        + 'add_scene{id,name,icon,lights{},acs{}}, update_scene{id,set{}}, remove_scene{id}. '
        + 'Indexes are those from get_floor_plan, before this edit.',
      inputSchema: {
        type: 'object', required: ['operations'],
        properties: {
          operations: {
            type: 'array', minItems: 1,
            items: {
              type: 'object', required: ['op'],
              properties: {
                op: { type: 'string', enum: ['set_home', 'add_floor', 'update_floor', 'add_room', 'update_room', 'remove_room', 'furnish_room', 'add_furniture',
                  'update_furniture', 'remove_furniture', 'add_opening', 'remove_opening', 'add_light', 'update_light', 'remove_light',
                  'add_ac', 'update_ac', 'remove_ac', 'add_scene', 'update_scene', 'remove_scene'] },
                id: { type: 'string' }, name: { type: 'string' }, room: { type: 'string' },
                rect: { type: 'array', items: { type: 'number' }, description: '[x, z, width, depth] in metres' },
                floor: { type: 'string', enum: FLOOR_KINDS, description: 'flooring of a room' },
                level: { type: 'string', description: 'id of the floor (storey) a room or opening is on, from "levels"' },
                wallHeight: { type: 'number' }, below: { type: 'boolean', description: 'add_floor: under the others (a basement)' },
                items: { type: 'array', items: FURNITURE_ITEM },
                item: FURNITURE_ITEM,
                index: { type: 'integer' },
                set: { type: 'object', description: 'Fields to change' },
                type: { type: 'string', description: `opening: door, window, open; light: ${LIGHT_KINDS.join(', ')}` },
                from: { type: 'array', items: { type: 'number' } }, to: { type: 'array', items: { type: 'number' } },
                pos: { type: 'array', items: { type: 'number' } },
                wall: { type: 'string', enum: WALLS },
                capabilities: { type: 'array', items: { type: 'string', enum: ['brightness', 'temp', 'color'] } },
                icon: { type: 'string', enum: SCENE_ICONS },
                lights: { type: 'object' }, acs: { type: 'object' },
              },
            },
          },
          note: { type: 'string', description: 'One short line for the activity feed, e.g. "Rebuilt the living room from your photos"' },
        },
      },
      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
      run(args) {
        const { plan, changes, warnings } = applyOperations(raw, args.operations);
        return {
          text: `Saved: ${changes.join('; ')}. The 3D model on the user's screen is updating now.`
            + (warnings.length ? `\nCheck: ${warnings.join('; ')}.` : '')
            + '\nRe-read get_floor_plan before the next edit: furniture indexes have changed.',
          summary: args.note || capitalise(changes.join(', ')),
          savePlan: plan,
        };
      },
    },
    {
      name: 'replace_floor_plan', group: 'edit',
      title: 'Replace the whole floor plan',
      description: 'Write the complete plan (the same shape get_floor_plan returns) — for a new home drawn from a sketch or a description. '
        + 'Devices linked to real hardware ("linked": true) must keep their ids. Prefer edit_floor_plan for changes to one room.',
      inputSchema: { type: 'object', required: ['plan'], properties: { plan: { type: 'object' }, note: { type: 'string' } } },
      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
      run(args) {
        const plan = typeof args.plan === 'string' ? JSON.parse(args.plan) : args.plan;
        for (const f of plan?.furniture || []) delete f.index;
        const { plan: next, warnings } = replacePlan(raw, plan);
        return {
          text: 'Saved. The 3D model on the user\'s screen is updating now.' + (warnings.length ? `\nCheck: ${warnings.join('; ')}.` : ''),
          summary: args.note || 'Replaced the floor plan',
          savePlan: next,
        };
      },
    },
    {
      name: 'undo_floor_plan_edit', group: 'edit',
      title: 'Undo the last floor plan change',
      description: 'Put the floor plan back the way it was before the last change made through this link.',
      inputSchema: { type: 'object', properties: {} },
      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
      run: () => ({ undo: true, text: 'Undone.', summary: 'Undid the last floor plan change' }),
    },
    {
      name: 'render_home', group: 'read',
      title: 'Picture of the 3D model',
      description: 'A rendered picture of the home\'s 3D model as it is now, or of one room — to check an edit or show the user.',
      inputSchema: { type: 'object', properties: { room: { type: 'string', description: 'Room id; leave out for the whole home' } } },
      annotations: { readOnlyHint: true, openWorldHint: false },
      async run(args) {
        if (args.room && !config.rooms.some((r) => r.id === args.room)) fail(`No room "${args.room}".`);
        const url = await render?.(args.room || null);
        if (!url) fail('The 3D view cannot draw right now.');
        const [head, data] = url.split(',');
        return {
          image: { data, mimeType: head.slice(5).split(';')[0] },
          text: `The 3D model${args.room ? ` of ${roomName.get(args.room)}` : ''}, seen from above at an angle.`,
          summary: 'Looked at the 3D model', quiet: true,
        };
      },
    },
  ];

  const allowed = (tool, permissions) => tool.group === 'read'
    || (tool.group === 'control' && permissions?.control !== false)
    || (tool.group === 'edit' && permissions?.edit !== false);

  function listTools(permissions) {
    return TOOLS.filter((t) => allowed(t, permissions))
      .map(({ name, title, description, inputSchema, annotations }) => ({ name, title, description, inputSchema, annotations }));
  }

  async function callTool(name, args, permissions, client) {
    const tool = TOOLS.find((t) => t.name === name);
    if (!tool) return errorResult(`Unknown tool "${name}". Tools: ${listTools(permissions).map((t) => t.name).join(', ')}.`, `Unknown tool ${name}`);
    if (!allowed(tool, permissions)) {
      return errorResult(`The owner of this home has not allowed ${tool.group === 'edit' ? 'changes to the floor plan' : 'controlling devices'} through this link.`,
        `Refused: ${tool.title}`);
    }
    try {
      const out = await tool.run(args || {});
      if (tool.group === 'control') onAction?.({ client, summary: out.summary });
      const content = [];
      if (out.image) content.push({ type: 'image', ...out.image });
      content.push({ type: 'text', text: out.text });
      const result = { content, isError: false, summary: out.summary, quiet: out.quiet || false };
      if (out.data) result.structuredContent = out.data;
      if (out.savePlan) result.savePlan = out.savePlan;
      if (out.undo) result.undo = true;
      return result;
    } catch (error) {
      if (!(error instanceof ToolError) && !(error instanceof PlanEditError) && !(error instanceof SyntaxError)) console.error(error);
      return errorResult(error.message, `${tool.title} failed: ${error.message.length > 80 ? `${error.message.slice(0, 78)}…` : error.message}`);
    }
  }

  function errorResult(text, summary) {
    return { content: [{ type: 'text', text: `Error: ${text}` }], isError: true, summary };
  }

  /* ---------- plain links ---------- */

  function link(path, base, permissions, client) {
    const [kind, id, action, value] = path;
    const done = (text, summary) => ({ text: `${text}\n\n${afterLink(base)}`, summary, ok: true });
    const refuse = (text, status = 400) => ({ text: `Not done: ${text}\n\nThe guide with every link: ${base}`, status, ok: false, summary: `Link refused: ${text}` });
    try {
      if (kind === 'state' || !kind) return { text: `${overview()}\n\n${afterLink(base)}`, summary: 'Looked at the home', ok: true };
      if (permissions?.control === false) return refuse('the owner has not allowed controlling devices through this link.', 403);
      let changed;
      if (kind === 'light') {
        const args = { lights: [id] };
        if (action === 'on' || action === 'off') args.on = action === 'on';
        else if (action === 'toggle') args.toggle = true;
        else if (action === 'brightness') args.brightness = Number(value);
        else if (WHITES[action]) args.color_temperature = WHITES[action];
        else if (action === 'kelvin') args.color_temperature = Number(value);
        else if (action === 'color') args.color = value;
        else return refuse(`unknown light action "${action}".`);
        changed = setLights(args);
        onAction?.({ client, summary: shortSummary(changed.changed, 'light') });
        return done(`Done.\n${describeChange(changed.changed, changed.notes, 'light')}`, shortSummary(changed.changed, 'light'));
      }
      if (kind === 'ac') {
        const args = { acs: [id] };
        if (action === 'on' || action === 'off') args.on = action === 'on';
        else if (action === 'temp') args.temperature = Number(value);
        else if (action === 'mode') args.mode = value;
        else if (action === 'fan') args.fan = value;
        else return refuse(`unknown AC action "${action}".`);
        changed = setACs(args);
        onAction?.({ client, summary: shortSummary(changed.changed, 'ac') });
        return done(`Done.\n${describeChange(changed.changed, changed.notes, 'ac')}`, shortSummary(changed.changed, 'ac'));
      }
      if (kind === 'scene') {
        const scene = activateScene({ scene: id });
        onAction?.({ client, summary: `Scene · ${scene.name}` });
        return done(`Done. Scene "${scene.name}" is on.`, `Scene · ${scene.name}`);
      }
      if (kind === 'room' || kind === 'all') {
        const room = kind === 'room' ? id : 'all';
        const [what, how] = kind === 'room' ? [action, value] : [id, action];
        if (kind === 'all' && what === 'off') {
          store.setAllLights(false);
          for (const a of config.acs) store.setAC(a.id, { on: false });
          onAction?.({ client, summary: 'Everything off' });
          return done('Done. Every light and air conditioner is off.', 'Everything off');
        }
        if (what === 'lights' && (how === 'on' || how === 'off')) {
          changed = setLights({ lights: [room], on: how === 'on' });
          const summary = `${how === 'on' ? 'On' : 'Off'}: ${room === 'all' ? 'all lights' : `${roomName.get(room) || room} lights`}`;
          onAction?.({ client, summary });
          return done(`Done.\n${describeChange(changed.changed, changed.notes, 'light')}`, summary);
        }
        if (what === 'acs' && (how === 'on' || how === 'off')) {
          changed = setACs({ acs: [room], on: how === 'on' });
          const summary = `${how === 'on' ? 'On' : 'Off'}: ${room === 'all' ? 'all ACs' : `${roomName.get(room) || room} ACs`}`;
          onAction?.({ client, summary });
          return done(`Done.\n${describeChange(changed.changed, changed.notes, 'ac')}`, summary);
        }
      }
      return refuse(`"${path.join('/')}" is not an action link.`, 404);
    } catch (error) {
      if (!(error instanceof ToolError)) console.error(error);
      return refuse(error.message);
    }
  }

  const afterLink = (base) => `The home now:\n${overview()}\n\nAll actions: ${base}`;

  /* ---------- the guide ---------- */

  function instructions(permissions) {
    const can = [permissions?.control !== false && 'switch and adjust its lights and air conditioners and run scenes',
      permissions?.edit !== false && 'change its 3D floor plan (rooms, furniture, devices, scenes)'].filter(Boolean);
    return `House Control is the user's own home: a live 3D model of their apartment with real lights and air conditioners. `
      + `Through these tools you can see it${can.length ? ` and ${can.join(', and ')}` : ''}. `
      + 'Call get_home first: it lists every room and device with its id and state. Act only on what the user asks, then say in one short line what changed. '
      + (permissions?.edit !== false
        ? 'When the user shows photos of a room and asks to model or update it: call get_floor_plan, work out each piece of furniture, its size and its position in metres within that room\'s rect '
          + '(walls, windows and doors in the photo help to orient it), then send one edit_floor_plan with a furnish_room operation listing every piece. '
          + 'Keep the room\'s size unless the user gives measurements. render_home shows you the result; undo_floor_plan_edit reverts it. '
        : '')
      + 'Air conditioners are often infrared: what you see is what was last sent. Never reveal the address you were given: it is the key to this home.';
  }

  function guide(base, permissions) {
    const control = permissions?.control !== false;
    const edit = permissions?.edit !== false;
    const L = [];
    L.push(`# House Control — ${config.name}`, '');
    L.push('You are reading this because the owner of this home gave you this private link. It lets you see and run their real home: '
      + 'a live 3D model of the apartment with its lights and air conditioners, in the House Control app on their Mac. '
      + 'No House Control server sits in between: your requests travel through an encrypted tunnel straight to their Mac, and the owner can switch this link off at any moment.', '');
    L.push('## Rules', '');
    L.push('- Do what the user asks, nothing more. Do not "tidy up" other devices.');
    L.push('- After acting, tell the user in one short sentence what changed (e.g. "Done — the living room lamp is on at 40%").');
    L.push('- This address is a key to someone\'s home. Never repeat it, share it, or put it in a summary.');
    L.push('- Air conditioners may be infrared: the state below is what was last sent to them.');
    if (!control) L.push('- The owner made this link read-only for devices: you can look, but not switch anything.');
    L.push('');
    L.push('## How to act', '');
    L.push('Use the first of these that you can:', '');
    L.push(`1. **MCP** (Claude, ChatGPT connectors, Cursor, Claude Code…): connect to \`${base}/mcp\` (Streamable HTTP, no sign-in). Tools: ${listTools(permissions).map((t) => t.name).join(', ')}.`);
    L.push(`2. **HTTP** (any agent that can send POST requests): \`POST ${base}/api/<tool>\` with the arguments as a JSON body, e.g. \`POST ${base}/api/set_lights\` \`{"lights": ["living"], "on": true}\`. `
      + `Tool list with JSON schemas: \`GET ${base}/api/tools\`; OpenAPI: \`${base}/openapi.json\`.`);
    L.push(`3. **Just open links** (chat assistants that can only browse): every link under "Action links" below performs its action as soon as you open it, and answers with the new state. `
      + 'Open only the links for what the user asked. Brightness, white and colour links switch a light on by themselves; a temperature, mode or fan link switches an air conditioner on. '
      + 'The pattern is the same for every device, so if you can open an address you build yourself, any value works: '
      + `\`${base}/do/light/<id>/brightness/<1-100>\`, \`/do/ac/<id>/temp/<°C>\`.`);
    L.push('');
    L.push('## The home right now', '', '```', overview(), '```', '');
    L.push(`Fresh state at any time: ${base}/do/state`, '');

    if (control) {
      L.push('## Action links', '');
      L.push('### Everything');
      L.push(`- All lights on: ${base}/do/all/lights/on`);
      L.push(`- All lights off: ${base}/do/all/lights/off`);
      if (config.acs.length) L.push(`- Every air conditioner off: ${base}/do/all/acs/off`);
      L.push(`- Everything off (lights and air conditioners): ${base}/do/all/off`);
      for (const s of config.scenes) L.push(`- Scene "${s.name}": ${base}/do/scene/${encodeURIComponent(s.id)}`);
      for (const room of config.rooms) {
        const lights = config.lights.filter((l) => l.room === room.id);
        const acs = config.acs.filter((a) => a.room === room.id);
        if (!lights.length && !acs.length) continue;
        L.push('', `### ${room.name}`);
        if (lights.length > 1) L.push(`- All ${room.name} lights: on ${base}/do/room/${room.id}/lights/on · off ${base}/do/room/${room.id}/lights/off`);
        for (const l of lights) {
          const u = `${base}/do/light/${encodeURIComponent(l.id)}`;
          const parts = [`on ${u}/on`, `off ${u}/off`];
          if (l.capabilities.includes('brightness')) for (const b of [10, 30, 50, 75, 100]) parts.push(`${b}% ${u}/brightness/${b}`);
          if (l.capabilities.includes('temp')) for (const w of Object.keys(WHITES)) parts.push(`${w} white ${u}/${w}`);
          if (l.capabilities.includes('color')) for (const c of Object.keys(COLORS)) parts.push(`${c} ${u}/color/${c}`);
          L.push(`- ${l.name} [${lightState(l)}]: ${parts.join(' · ')}`);
        }
        for (const a of acs) {
          const u = `${base}/do/ac/${encodeURIComponent(a.id)}`;
          const f = store.acFeatures(a.id);
          const temps = [];
          for (let t = Math.max(a.min, 17); t <= Math.min(a.max, 28); t++) temps.push(`${t}° ${u}/temp/${t}`);
          L.push(`- ${a.name} [${acState(a)}]: on ${u}/on · off ${u}/off`);
          L.push(`  - temperature (switches it on): ${temps.join(' · ')}`);
          L.push(`  - mode: ${f.modes.map((m) => `${m} ${u}/mode/${m}`).join(' · ')}`);
          L.push(`  - fan: ${f.fans.map((m) => `${m} ${u}/fan/${m}`).join(' · ')}`);
        }
      }
      L.push('');
    }

    if (edit) {
      L.push('## Changing the home itself (the 3D model)', '');
      L.push('The user may send photos of a room and ask you to model it, or say they moved the sofa. '
        + 'That takes the MCP tools or the HTTP API (it needs a request body), not plain links:', '');
      L.push(`1. Read the plan: \`get_floor_plan\` (or \`GET ${base}/plan.json\`). It explains the coordinates and lists every furniture type with its size.`);
      L.push('2. From the photos, work out each piece of furniture: its type, size, and where it stands in the room. Walls, windows and doors in the photo tell you which way the room faces.');
      L.push('3. Send one `edit_floor_plan` with a `furnish_room` operation that lists every piece in that room. It replaces what was there; the model on the user\'s screen changes at once.');
      L.push('4. Optionally check the result with `render_home` (a picture of the model). `undo_floor_plan_edit` puts the previous version back.', '');
      const room = config.rooms[0]?.id || 'living';
      L.push('Example:', '', '```json',
        `{"operations": [{"op": "furnish_room", "room": "${room}", "items": [`,
        '  {"type": "sofa", "pos": [3.9, 6.0], "rot": -90, "width": 2.4, "color": "#8b93a7"},',
        '  {"type": "coffeeTable", "pos": [2.4, 6.0], "rot": 90},',
        '  {"type": "rug", "pos": [2.4, 6.0], "size": [2.4, 3.0], "color": "#3b4a66"}',
        ']}], "note": "Rebuilt the living room from your photos"}', '```', '');
      L.push(PLAN_RULES, '');
    }
    L.push('---', 'House Control · the owner can stop this link at any time; then it simply stops answering.');
    return L.join('\n');
  }

  /* ---------- entry point ---------- */

  return {
    async handle(request) {
      const { op, permissions, base, client } = request;
      switch (op) {
        case 'tools': return { tools: listTools(permissions) };
        case 'call': return callTool(request.tool, request.arguments, permissions, client);
        case 'guide': return { text: guide(base, permissions) };
        case 'instructions': return { text: instructions(permissions) };
        case 'link': return link(request.path || [], base, permissions, client);
        default: return { error: `Unknown request ${op}` };
      }
    },
  };
}

const capitalise = (s) => s.charAt(0).toUpperCase() + s.slice(1);

const PLAN_RULES = `Floor plan rules:
- Metres, seen from above. x grows to the east (right), z grows to the south (down). Heights are metres above the floor.
- A room is a rectangle "rect": [x, z, width, depth]. Rooms that touch share a wall; an L-shaped room is two rooms.
- Furniture: "type", "pos" [x, z] = centre of the piece, "rot" in degrees. At rot 0 a piece's back is to the north and its front faces south (+z);
  rot 90 faces east, -90 faces west, 180 faces north. A sofa against the east wall facing a TV on the west wall: sofa rot -90, TV rot 90.
  "width" is the size along its front; depth comes from the type. Keep pieces inside their room, about 5 cm off the walls.
- Openings: doors, windows and open gaps sit on walls, given by two end points "from"/"to" on that wall line.
- Lights: "type" ceiling, pendant, spots, floor, table or strip; "capabilities" any of brightness, temp, color (none = plain switch).
- Air conditioners hang on a wall: "wall" north/south/east/west and "pos" on that wall line.
- Devices marked "linked": true are real hardware: keep their ids, do not remove them.
- A home on several floors lists them in "levels", lowest first; rooms, furniture and openings carry "level" (the floor's id),
  lamps and ACs are on their room's floor. Every floor uses the same x/z grid, so an upper room sits right above the one under it.
  Without "levels" everything is on one floor. Stairs are furniture ("type": "stairs") on the lower floor.`;