beplus-mcp 0.31.0 → 0.32.0

package/README.md

@@ -140,10 +140,13 @@ Falam com `/api/v1/canvas`. Montam e editam o fluxo e **não geram mídia**, com
 | `canvas_reopen_comment` | Reabre, com motivo opcional. |
 | `canvas_comment` | Cria comentário raiz ancorado (nó, versão, minutagem, ponto ou board), para deixar pergunta na tela da pessoa. |
 | `canvas_run` | Roda nós pela aba do Canvas aberta da própria pessoa (mesma conta; sem aba, nada roda). `max_diamonds` obrigatório: a aba estima como o botão Rodar e só roda se couber. `dry_run: true` só estima. Alvo: `node_ids` (roda de novo mesmo em cache, como o Rodar do cartão), `from_node_id` (daqui para frente) ou `all: true` (só o que mudou). `simulated: true` exige a aba no Simulado; sem ele, a aba precisa estar no Real. Prompt com PT sem aplicar no EN: recusa e diz qual. Devolve o que vai rodar, o custo e o `request_id`. |
-| `canvas_run_status` | Andamento de um `request_id`: estado de cada nó, estimado e gasto, perguntado à aba que rodou. Com a aba fechada, lê o estado de execução do board para os nós do pedido. |
+| `canvas_run_status` | Andamento de um `request_id`: estado de cada nó, estimado e gasto, perguntado à aba que rodou. Com a aba fechada, lê o estado de execução do board para os nós do pedido. Resposta grande vem cortada ("… e mais N"); o andamento sem aba de um pedido cortado avisa que é parcial. |
+| `canvas_focus` | "Olha aqui": leva a aba do Canvas que a pessoa está olhando (a visível que não é aba de agente aberta por link `?frame`; sem nenhuma, a de um agente) até `node_ids` e/ou `section_id`, sem animação, e seleciona os nós (`select: false` não mexe). **Padrão: uma vez só**, a aba não fica presa. `follow: true` segue a área e prende a aba até o "×" da pílula (modo `?frame`, com o `titulo` na pílula e no nome da aba). `zoom`: `"fit"` (padrão) ou número de 0,07 a 4. **Não gasta e não escreve no board.** Devolve qual aba enquadrou (nome, do usuário ou de agente, repassada, escondida, Montagem aberta) e os ids que não existem. Qualquer papel, leitor inclusive; pede só `ialab:read`. |
 
 Rodar pelo MCP (`canvas_run`): o servidor (academy-backend, rota `run-requests`) repassa o pedido para **uma** aba da própria pessoa (a aberta por último) e nunca roda nada. Sem resposta em 20 s, o destino fica incerto: a ferramenta manda consultar `canvas_run_status` com o mesmo `request_id`, e repetir `canvas_run` com esse `request_id` é seguro (a aba não roda duas vezes).
 
+Enquadrar pelo MCP (`canvas_focus`): o servidor (rota `focus-requests`) repassa para **uma** aba da própria pessoa, a de entrada mais recente com a versão do Canvas que enquadra (a aba antiga não conta: recarregue). Essa aba passa o pedido à aba que a pessoa está olhando no mesmo navegador. Sem resposta em 5 s, 504; chamar de novo é seguro. Por padrão a aba só vai até a área uma vez; com `follow: true` ela segue a área até a pessoa clicar no "×".
+
 Concorrência: cada edição relê o board, vai num envelope só (um `seq`) e é recusada, sem aplicar nada, se outra pessoa mexeu nos mesmos nós desde a sua leitura. Recusas do servidor (`node-missing` e afins) voltam em português com "releia". As exceções são o `canvas_patch_node` e o `canvas_update_nodes`: vários envelopes em ordem, cada um julgado sozinho, e o relatório diz qual entrou. A medida que a tela grava sozinha (`data.__measured`) não conta como "outra pessoa mexeu".
 
 Tamanho do cartão: o `size` gravado é **piso**; o cartão cresce com o conteúdo (um Prompt de 340 de largura com o `!!ESTILO` resolvido vira uma coluna de 1.800). O Canvas grava o tamanho desenhado em `data.__measured = { w, h, at }` quando o cartão passa do piso; as leituras mostram esse (`medido`) ou o piso (`gravado`). É campo interno: não aparece como dado e nenhuma ferramenta grava nele. `size: {w, h}` muda a caixa; `size: "titulo" | "subtitulo" | "corpo"` é o tamanho do texto do Texto livre (`data.size` do nó `label`).

package/dist/index.js

@@ -24087,6 +24087,7 @@ import { createHash } from "crypto";
 // src/canvas/api.ts
 var PINNED_CORE_VERSION = "ca7b3b406184c7f679f555c3a008013197182b23";
 var RUN_REQUEST_TIMEOUT_MS = 4e4;
+var FOCUS_REQUEST_TIMEOUT_MS = 12e3;
 function errorRaw(err) {
   if (!(err instanceof ApiError)) return void 0;
   const raw = err.body?.error?.raw;
@@ -24221,6 +24222,11 @@ var CanvasApi = class {
   runStatus(boardId4, requestId) {
     return this.req("GET", `/boards/${boardId4}/run-requests/${requestId}`);
   }
+  // ── enquadrar a aba do Canvas (CF1) ───────────────────────────────────────
+  /** Pede para a aba do Canvas da pessoa enquadrar nós. O servidor espera a aba até 5 s. */
+  focusRequest(boardId4, body2) {
+    return this.req("POST", `/boards/${boardId4}/focus-requests`, { body: body2, timeoutMs: FOCUS_REQUEST_TIMEOUT_MS });
+  }
   /** Só para os testes conferirem o aprendizado. */
   get currentCoreVersion() {
     return this.coreVersion;
@@ -24551,13 +24557,13 @@ function makeEdge(init) {
 }
 var setValue = (value) => ({ kind: "value", value });
 var unsetValue = () => ({ kind: "unset" });
-function removeNodeOps(doc, nodeId2) {
+function removeNodeOps(doc, nodeId3) {
   const ops = [];
-  const edgeIds = Object.keys(doc.edges).filter((id) => doc.edges[id].source === nodeId2 || doc.edges[id].target === nodeId2).sort();
+  const edgeIds = Object.keys(doc.edges).filter((id) => doc.edges[id].source === nodeId3 || doc.edges[id].target === nodeId3).sort();
   for (const edgeId of edgeIds) ops.push({ type: "edge.remove", edgeId });
-  const history = Object.hasOwn(doc.nodeHistory, nodeId2) ? doc.nodeHistory[nodeId2] : void 0;
-  if (history) for (const resultId of [...history].reverse()) ops.push({ type: "history.remove", nodeId: nodeId2, resultId });
-  ops.push({ type: "node.remove", nodeId: nodeId2 });
+  const history = Object.hasOwn(doc.nodeHistory, nodeId3) ? doc.nodeHistory[nodeId3] : void 0;
+  if (history) for (const resultId of [...history].reverse()) ops.push({ type: "history.remove", nodeId: nodeId3, resultId });
+  ops.push({ type: "node.remove", nodeId: nodeId3 });
   return ops;
 }
 function batchOf(ops) {
@@ -24958,8 +24964,8 @@ function mmss(t) {
   const pad = (n) => String(n).padStart(2, "0");
   return h ? `${h}:${pad(m)}:${pad(s)}` : `${pad(m)}:${pad(s)}`;
 }
-function nodeRef(doc, nodeId2) {
-  const node = doc.nodes[nodeId2];
+function nodeRef(doc, nodeId3) {
+  const node = doc.nodes[nodeId3];
   const kind = nodeKind(node) ?? node.type;
   return `"${oneLine(nodeName(node), 60)}" (${kind}, ${node.id})`;
 }
@@ -24983,13 +24989,13 @@ function outputKeyOf(entry) {
   if (typeof entry.url === "string" && entry.url !== "") return `url-${hashString(entry.url)}`;
   return null;
 }
-function versionOf(doc, nodeId2, outputKey) {
-  const ids = doc.nodeHistory?.[nodeId2];
+function versionOf(doc, nodeId3, outputKey) {
+  const ids = doc.nodeHistory?.[nodeId3];
   if (Array.isArray(ids)) {
     const i = ids.indexOf(outputKey);
     if (i >= 0) return i + 1;
   }
-  const history = doc.nodes[nodeId2]?.data.history;
+  const history = doc.nodes[nodeId3]?.data.history;
   if (Array.isArray(history)) {
     const i = history.findIndex(
       (h) => typeof h === "object" && h !== null && !Array.isArray(h) && outputKeyOf(h) === outputKey
@@ -25459,17 +25465,17 @@ function holdsOne(doc, node) {
   if (node.data.holds === "many") return false;
   return itemsOf(node).length === 1 && Object.values(doc.edges).some((e) => e.source === node.id);
 }
-function needMediaNode(doc, nodeId2) {
-  const node = doc.nodes[nodeId2];
-  if (!node) throw new CanvasToolError(`N\xF3 ${nodeId2} n\xE3o existe no board. Releia com canvas_read_board.`);
+function needMediaNode(doc, nodeId3) {
+  const node = doc.nodes[nodeId3];
+  if (!node) throw new CanvasToolError(`N\xF3 ${nodeId3} n\xE3o existe no board. Releia com canvas_read_board.`);
   if (nodeKind(node) !== "media") {
     throw new CanvasToolError(
-      `O n\xF3 ${nodeId2} ("${oneLine(nodeName(node), 40)}") \xE9 ${nodeKind(node) ?? node.type}, n\xE3o M\xEDdia. Passe o id de um n\xF3 media, ou omita node_id para criar um n\xF3 M\xEDdia novo.`
+      `O n\xF3 ${nodeId3} ("${oneLine(nodeName(node), 40)}") \xE9 ${nodeKind(node) ?? node.type}, n\xE3o M\xEDdia. Passe o id de um n\xF3 media, ou omita node_id para criar um n\xF3 M\xEDdia novo.`
     );
   }
   return node;
 }
-function payload(u, nodeId2) {
+function payload(u, nodeId3) {
   const out = { url: u.url, mime: u.mime, bytes: u.bytes };
   if (u.meta.duration !== void 0) out.duration = u.meta.duration;
   if (u.meta.width !== void 0) out.width = u.meta.width;
@@ -25478,14 +25484,14 @@ function payload(u, nodeId2) {
   out.media_item = mediaItem(u);
   if (u.kind !== "file") {
     out.sequence_asset = sequenceAsset(u);
-    out.libraryItemId = libraryItemId(u, nodeId2);
+    out.libraryItemId = libraryItemId(u, nodeId3);
   }
   return JSON.stringify(out);
 }
-function sequenceHint(u, nodeId2) {
+function sequenceHint(u, nodeId3) {
   if (u.kind === "file") return "Documento: entra no n\xF3 M\xEDdia, n\xE3o na timeline da Montagem.";
   const lines = [
-    "Num clipe da timeline da Montagem (data.timeline; data.sequence s\xF3 em n\xF3 que ainda n\xE3o migrou): use sequence_asset como `asset` e libraryItemId como est\xE1" + (nodeId2 ? "." : ", trocando <id do n\xF3 M\xEDdia> pelo id do n\xF3 onde o item ficou.")
+    "Num clipe da timeline da Montagem (data.timeline; data.sequence s\xF3 em n\xF3 que ainda n\xE3o migrou): use sequence_asset como `asset` e libraryItemId como est\xE1" + (nodeId3 ? "." : ", trocando <id do n\xF3 M\xEDdia> pelo id do n\xF3 onde o item ficou.")
   ];
   if (u.meta.duration !== void 0) {
     const at30 = Math.floor(u.meta.duration * 30 + 1e-9);
@@ -25543,13 +25549,13 @@ URL: ${u.url}`;
         return [head, "", payload(u), "", sequenceHint(u)].join("\n");
       }
       const boardId4 = args.board_id;
-      let nodeId2 = args.node_id;
+      let nodeId3 = args.node_id;
       let done;
       try {
         done = await edit(boardId4, async (doc) => {
           const item = mediaItem(u);
-          if (nodeId2) {
-            const node = needMediaNode(doc, nodeId2);
+          if (nodeId3) {
+            const node = needMediaNode(doc, nodeId3);
             const replacing = args.replace ?? holdsOne(doc, node);
             const items = replacing ? [item] : [...itemsOf(node), item];
             if (items.length > MAX_MEDIA_ITEMS) {
@@ -25571,7 +25577,7 @@ URL: ${u.url}`;
             zIndex: Object.values(doc.nodes).reduce((t, n) => Math.max(t, n.zIndex), 0) + 1,
             createdBy: await api.me()
           });
-          nodeId2 = created.id;
+          nodeId3 = created.id;
           return {
             ops: [{ type: "node.add", nodeId: created.id, node: created }],
             targets: [],
@@ -25587,7 +25593,7 @@ N\xE3o suba de novo: releia com canvas_read_board e grave media_item em data.ite
 ${payload(u)}`
         );
       }
-      return [head, done, "", payload(u, nodeId2), "", sequenceHint(u, nodeId2)].join("\n");
+      return [head, done, "", payload(u, nodeId3), "", sequenceHint(u, nodeId3)].join("\n");
     })
   );
 }
@@ -25615,12 +25621,16 @@ function estimateLines(estimate, titleOf) {
     const cost = n.error ? `estimativa falhou (${n.error})` : dia(n.diamonds);
     lines.push(`- ${n.title ?? titleOf(n.nodeId)} (${n.nodeId}): ${cost}`);
   }
-  const cached2 = nodes.filter((n) => !n.willRun && !n.afterApproval).length;
+  if (estimate.omitted) {
+    lines.push(`\u2026 e mais ${estimate.omitted} n\xF3(s) fora da lista (a resposta da aba foi cortada pelo tamanho; o total vale para todos).`);
+  }
+  const cached2 = estimate.cached ?? nodes.filter((n) => !n.willRun && !n.afterApproval).length;
   if (cached2) lines.push(`Em cache (n\xE3o rodam): ${cached2}.`);
-  const later = estimate.later?.nodes?.length ?? 0;
+  const later = estimate.counts?.later ?? estimate.later?.nodes?.length ?? 0;
   if (later) lines.push(`Esperando aprova\xE7\xE3o no board depois disso: ${later} n\xF3(s), \u2248 ${dia(estimate.later?.total ?? 0)} (fora desta conta).`);
-  if (estimate.unknown?.length) {
-    lines.push(`Sem estimativa: ${estimate.unknown.length} n\xF3(s) (texto cobra por token; o total \xE9 piso).`);
+  const unknown2 = estimate.counts?.unknown ?? estimate.unknown?.length ?? 0;
+  if (unknown2) {
+    lines.push(`Sem estimativa: ${unknown2} n\xF3(s) (texto cobra por token; o total \xE9 piso).`);
   }
   return lines;
 }
@@ -25648,7 +25658,7 @@ function registerCanvasRunTools(server, api, run) {
       return (id) => id;
     }
   }
-  function explain(e, requestId) {
+  function explain2(e, requestId) {
     if (!(e instanceof ApiError)) throw e;
     const reason = errorRaw(e)?.reason;
     const unknownFate = requestId && (e.httpStatus === 0 || e.httpStatus === 408 || reason === "tab-timeout" || reason === "tab-bad-answer" || e.httpStatus >= 500 && e.httpStatus !== 501);
@@ -25730,7 +25740,7 @@ function registerCanvasRunTools(server, api, run) {
           label
         });
       } catch (e) {
-        explain(e, requestId);
+        explain2(e, requestId);
       }
       const titleOf = await titles(args.board_id);
       if (answer.ok !== true) {
@@ -25743,7 +25753,8 @@ function registerCanvasRunTools(server, api, run) {
       if (answer.status === "started") {
         remember(requestId, {
           boardId: args.board_id,
-          nodeIds: nodeIds.length ? nodeIds : target.kind === "nodes" ? target.nodeIds : target.kind === "from" ? [target.nodeId] : []
+          nodeIds: nodeIds.length ? nodeIds : target.kind === "nodes" ? target.nodeIds : target.kind === "from" ? [target.nodeId] : [],
+          ...answer.estimate?.omitted ? { omitted: answer.estimate.omitted } : {}
         });
       }
       return answerText(answer, requestId, args.max_diamonds, titleOf);
@@ -25768,14 +25779,16 @@ function registerCanvasRunTools(server, api, run) {
         return statusText(await api.runStatus(board_id, requestId), await titles(board_id));
       } catch (e) {
         const reason = errorRaw(e)?.reason;
-        if (!(e instanceof ApiError) || reason !== "unknown-request" && reason !== "no-tab") explain(e);
+        if (!(e instanceof ApiError) || reason !== "unknown-request" && reason !== "no-tab") explain2(e);
         why = reason === "no-tab" ? "Nenhuma aba do Canvas sua est\xE1 aberta neste board." : "Nenhuma aba aberta conhece este pedido.";
       }
-      const ids = node_ids ?? remembered.get(requestId)?.nodeIds;
+      const known = node_ids ? void 0 : remembered.get(requestId);
+      const ids = node_ids ?? known?.nodeIds;
       if (!ids?.length) {
         return `${why} Sem a aba, o andamento sai do estado de execu\xE7\xE3o do board: chame de novo com node_ids (os n\xF3s que o pedido rodava).`;
       }
-      return `${why} Pelo estado de execu\xE7\xE3o do board:
+      const partial2 = known?.omitted ? ` (parcial: s\xF3 os ${ids.length} n\xF3s que a aba listou; outros ${known.omitted} ficaram fora da resposta. Para eles, chame com node_ids)` : "";
+      return `${why} Pelo estado de execu\xE7\xE3o do board${partial2}:
 ${fromRuns(await api.snapshot(board_id), ids)}`;
     })
   );
@@ -25815,6 +25828,7 @@ function statusText(a, titleOf) {
     const outs = typeof n.outputs === "number" && n.outputs > 0 ? ` (${n.outputs} sa\xEDda(s))` : "";
     lines.push(`- ${n.title ?? titleOf(n.nodeId)} (${n.nodeId}): ${NODE_TEXT[n.status] ?? n.status}${outs}${extra}`);
   }
+  if (a.omitted) lines.push(`\u2026 e mais ${a.omitted} n\xF3(s) fora da lista (a resposta da aba foi cortada pelo tamanho).`);
   if (a.state === "done" || a.state === "failed") lines.push("Leia o resultado com canvas_read_board (node_ids).");
   return lines.join("\n");
 }
@@ -25834,6 +25848,112 @@ function fromRuns(snap, ids) {
   }).join("\n");
 }
 
+// src/tools/canvas-focus.ts
+var MAX_IDS = 100;
+var nodeId2 = external_exports.string().min(1).max(128);
+var fmtZoom = (z) => new Intl.NumberFormat("pt-BR", { maximumFractionDigits: 2 }).format(z);
+function explain(e, usesPat) {
+  if (!(e instanceof ApiError)) throw e;
+  const reason = errorRaw(e)?.reason;
+  if (reason === "no-tab") {
+    throw new CanvasToolError(
+      "Nenhuma aba do Canvas sua est\xE1 aberta neste board (ou a aba \xE9 de uma vers\xE3o sem esta fun\xE7\xE3o). Pe\xE7a para abrir o board no Canvas com a mesma conta deste MCP (ou recarregar a aba) e tente de novo. Nada mudou."
+    );
+  }
+  if (reason === "tab-timeout") {
+    throw new CanvasToolError("A aba do Canvas n\xE3o respondeu em 5 s. Ela pode ter enquadrado; chamar de novo n\xE3o faz mal.");
+  }
+  if (reason === "tab-bad-answer") {
+    throw new CanvasToolError("A aba do Canvas respondeu fora do contrato. Pe\xE7a para recarregar a aba e tente de novo.");
+  }
+  if (e.httpStatus === 404) {
+    if (!/board/i.test(e.message)) {
+      throw new CanvasToolError("O servidor do Canvas ainda n\xE3o tem o enquadramento pelo MCP (academy-backend sem a CF1). Nada mudou.");
+    }
+    throw new CanvasToolError("Board n\xE3o encontrado, ou voc\xEA n\xE3o \xE9 membro dele. Confira o id em canvas_list_boards.");
+  }
+  if (e.httpStatus === 403 && (!usesPat || /ialab:/.test(e.message))) {
+    throw new CanvasToolError("O login pelo navegador deste MCP n\xE3o tem a permiss\xE3o que o enquadramento exige. Rode `beplus-mcp login` de novo e autorize.");
+  }
+  if (e.httpStatus === 400) throw new CanvasToolError(`O servidor recusou o pedido: ${e.message}.`);
+  if (e.httpStatus === 429) throw new CanvasToolError("Limite de pedidos de enquadramento (60 por minuto). Espere um minuto.");
+  throw e;
+}
+function focusText(a) {
+  const tab = a.tab;
+  const name = tab?.title ? `"${tab.title}"` : "aberta";
+  const found = a.found ?? 0;
+  const selected = a.selected ?? 0;
+  const zoom = typeof a.zoom === "number" ? ` Zoom ${fmtZoom(a.zoom)}.` : "";
+  const lines = [
+    `Enquadrado na aba do Canvas ${name}: ${found} n\xF3(s)${selected > 0 ? `, ${selected} selecionado(s)` : ", sem mexer na sele\xE7\xE3o"}.${zoom}`
+  ];
+  if (tab?.human !== void 0 || tab?.relayed !== void 0) {
+    const who2 = tab.human === false ? "Aba de agente (link ?frame): nenhuma aba do usu\xE1rio estava vis\xEDvel neste board." : "Aba do usu\xE1rio (a que ele est\xE1 olhando).";
+    const via = tab.relayed ? " Repassado pela aba que o servidor escolheu." : "";
+    lines.push(`${who2}${via}`);
+  }
+  if (a.mode === "follow") {
+    lines.push("Modo seguir: a aba acompanha essa \xE1rea e fica presa nela at\xE9 o usu\xE1rio clicar no \xD7 da p\xEDlula.");
+  } else if (a.mode === "light") {
+    lines.push("Uma vez s\xF3: a aba n\xE3o fica presa; o usu\xE1rio segue mexendo \xE0 vontade.");
+  }
+  const missing = a.missing ?? [];
+  if (missing.length > 0) {
+    const more = a.missingMore ? ` e mais ${a.missingMore}` : "";
+    lines.push(`N\xE3o existem no board (ou est\xE3o arquivados): ${missing.join(", ")}${more}.`);
+  }
+  if (tab?.visible === false) lines.push("A aba est\xE1 escondida (atr\xE1s de outra): pe\xE7a para o usu\xE1rio traz\xEA-la para a frente.");
+  if (tab?.montage) lines.push("O usu\xE1rio est\xE1 no editor (Montagem aberta nessa aba): o board foi enquadrado por tr\xE1s e aparece quando ele fechar a Montagem.");
+  if (tab?.wasFramed) lines.push("Essa aba estava enquadrada em outra \xE1rea (talvez a de outro agente) e agora mostra esta.");
+  return lines.join("\n");
+}
+function registerCanvasFocusTools(server, api, run) {
+  server.registerTool(
+    "canvas_focus",
+    {
+      title: "Canvas: enquadrar a aba do usu\xE1rio",
+      description: 'Mostra "olha aqui" ao usu\xE1rio: leva a aba do Canvas que ele est\xE1 olhando neste board (a vis\xEDvel, que n\xE3o \xE9 aba de agente aberta por link ?frame; sem nenhuma, a de um agente) at\xE9 n\xF3s ou uma se\xE7\xE3o, sem anima\xE7\xE3o, e seleciona os n\xF3s (select: false n\xE3o mexe na sele\xE7\xE3o). Padr\xE3o: enquadra e seleciona UMA vez; a aba n\xE3o fica presa e o usu\xE1rio segue mexendo. follow: true segue a \xE1rea e prende a aba at\xE9 o \xD7 (modo ?frame: acompanha as mudan\xE7as, titulo na p\xEDlula e no nome da aba); use s\xF3 quando ele pedir para acompanhar. N\xC3O gasta e N\xC3O escreve no board. Diga node_ids e/ou section_id (at\xE9 100 ids; com os dois, a sele\xE7\xE3o fica nos node_ids). zoom: "fit" (padr\xE3o, cabe na tela) ou n\xFAmero de 0.07 a 4. Devolve qual aba enquadrou (nome, se \xE9 a do usu\xE1rio ou de agente, se veio repassada, se est\xE1 escondida, se ele est\xE1 no editor da Montagem) e os ids que n\xE3o existem. Sem aba: pe\xE7a para abrir (ou recarregar) o board no Canvas. Chamar de novo com a mesma \xE1rea \xE9 seguro.',
+      inputSchema: {
+        board_id: external_exports.string().uuid().describe("Id (uuid) do board."),
+        node_ids: external_exports.array(nodeId2).min(1).max(MAX_IDS).optional().describe("Os n\xF3s a mostrar (e selecionar)."),
+        section_id: nodeId2.optional().describe("Uma se\xE7\xE3o: enquadra a se\xE7\xE3o e o que est\xE1 dentro dela."),
+        titulo: external_exports.string().trim().min(1).max(80).optional().describe('Com follow: texto da p\xEDlula e do nome da aba ("<titulo> \xB7 <board>"). Sem follow n\xE3o aparece.'),
+        zoom: external_exports.union([external_exports.literal("fit"), external_exports.number().finite().min(0.07).max(4)]).optional().describe('"fit" (padr\xE3o): a \xE1rea cabe na tela, zoom at\xE9 100%. N\xFAmero: zoom fixo, com a \xE1rea no meio.'),
+        select: external_exports.boolean().optional().describe("false: n\xE3o mexe na sele\xE7\xE3o. Padr\xE3o: seleciona os n\xF3s."),
+        follow: external_exports.boolean().optional().describe("true: segue a \xE1rea e prende a aba at\xE9 o \xD7 da p\xEDlula. Padr\xE3o false: enquadra e seleciona uma vez, sem prender.")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+    },
+    async (args) => run(async () => {
+      const nodeIds = args.node_ids ? [...new Set(args.node_ids)] : [];
+      if (nodeIds.length === 0 && !args.section_id) {
+        throw new CanvasToolError("Diga o que mostrar: node_ids (os n\xF3s), section_id (uma se\xE7\xE3o) ou os dois.");
+      }
+      if (nodeIds.length + (args.section_id ? 1 : 0) > MAX_IDS) {
+        throw new CanvasToolError(`At\xE9 ${MAX_IDS} ids por pedido (node_ids mais a se\xE7\xE3o).`);
+      }
+      let answer;
+      try {
+        answer = await api.focusRequest(args.board_id, {
+          ...nodeIds.length ? { nodeIds } : {},
+          ...args.section_id ? { sectionId: args.section_id } : {},
+          ...args.titulo ? { title: args.titulo } : {},
+          ...args.zoom !== void 0 ? { zoom: args.zoom } : {},
+          ...args.select !== void 0 ? { select: args.select } : {},
+          ...args.follow !== void 0 ? { follow: args.follow } : {}
+        });
+      } catch (e) {
+        explain(e, api.usesPat);
+      }
+      if (answer.ok !== true) {
+        throw new CanvasToolError(`A aba recusou, nada mudou (${answer.reason ?? "sem motivo"}): ${answer.message ?? ""}`.trim());
+      }
+      return focusText(answer);
+    })
+  );
+}
+
 // src/canvas/mentions.ts
 var VIA_MENTION = "viaMention";
 var PROMPT_REFS_INPUT = "refs";
@@ -26124,9 +26244,9 @@ ${lines.join("\n")}
     return `\u2705 ${done} em ${envs.length} envelope(s) (seq at\xE9 ${last}).
 ${lines.join("\n")}${note}`;
   }
-  function needNode(doc, nodeId2) {
-    const node = doc.nodes[nodeId2];
-    if (!node) throw new CanvasToolError(`N\xF3 ${nodeId2} n\xE3o existe no board. Releia com canvas_read_board.`);
+  function needNode(doc, nodeId3) {
+    const node = doc.nodes[nodeId3];
+    if (!node) throw new CanvasToolError(`N\xF3 ${nodeId3} n\xE3o existe no board. Releia com canvas_read_board.`);
     return node;
   }
   function portWarning(doc, source, sourcePort, target, targetPort) {
@@ -26740,13 +26860,14 @@ N\xF3s: ${Object.entries(ids).map(([k, v]) => `${k}=${v}`).join(" \xB7 ")}` : ""
   registerCanvasMediaTools(server, { api, cfg, run, edit, seen, placeFor });
   registerCanvasLayoutTools(server, { api, run, edit });
   registerCanvasRunTools(server, api, run);
+  registerCanvasFocusTools(server, api, run);
 }
 
 // src/version.ts
 import { createRequire } from "module";
 var require2 = createRequire(import.meta.url);
 function readVersion() {
-  if ("0.31.0") return "0.31.0";
+  if ("0.32.0") return "0.32.0";
   try {
     const pkg = require2("../package.json");
     return pkg.version ?? "0.0.0-unknown";
@@ -26762,6 +26883,7 @@ var SERVER_INSTRUCTIONS = [
   'M\xEDdia: generate_* gasta diamantes; confira com estimate_cost antes de lotes grandes. Sem project, a gera\xE7\xE3o cai no projeto ativo; billing:"personal" cobra do usu\xE1rio.',
   "Calls: search_calls acha, get_call traz a transcri\xE7\xE3o.",
   "Canvas online (canvas_*): leia com canvas_read_board antes de editar e siga o estado lido. Cada edi\xE7\xE3o vai num passo s\xF3; se outra pessoa mexeu nos mesmos n\xF3s, a ferramenta recusa e pede releitura. As canvas_* n\xE3o geram m\xEDdia, exceto canvas_run: roda n\xF3s pela aba do Canvas aberta do usu\xE1rio e gasta diamantes; max_diamonds \xE9 o teto que o usu\xE1rio autorizou (dry_run s\xF3 estima). D\xEA nome (label) aos n\xF3s, n\xE3o invente tipos nem portas, e confirme antes de canvas_delete.",
+  'Mostrar algo ao usu\xE1rio ("olha aqui"): canvas_focus leva a aba do Canvas que ele est\xE1 olhando at\xE9 os n\xF3s e os seleciona uma vez, sem prender a aba, sem gasto e sem escrita no board. follow: true prende a aba na \xE1rea at\xE9 o \xD7: s\xF3 se ele pedir.',
   'Arrumar o board: o size gravado \xE9 piso (o cart\xE3o cresce com o conte\xFAdo); use o tamanho "medido" do canvas_read_board. \xC1rea de revis\xE3o: canvas_arrange_rows (uma linha por vers\xE3o); posi\xE7\xE3o/tamanho em lote: canvas_update_nodes com layout_only. N\xE3o afirme que nada se sobrep\xF5e com n\xF3 sem medida.',
   '"Aplica os coment\xE1rios" do board: canvas_list_comments (abertos) \u2192 para cada um, leia o n\xF3 ancorado com canvas_read_board (node_ids), aplique a edi\xE7\xE3o pelas canvas_* e feche com canvas_resolve_comment dizendo em uma frase o que fez. Coment\xE1rio amb\xEDguo ou com alvo sumido: responda com pergunta (canvas_reply_comment) e n\xE3o resolva. D\xFAvida sua sobre um n\xF3: canvas_comment ancorado nele. As escritas j\xE1 saem espa\xE7adas (60/min); se ainda vier limite, pare e diga de onde seguir.'
 ].join("\n");