beplus-mcp 0.30.0 → 0.32.0

package/README.md

@@ -116,7 +116,7 @@ Reinicie o cliente. Rode a tool **`whoami`** para confirmar o vínculo.
 | `whoami` | Conta vinculada (link check do PAT). |
 
 ### Canvas online (boards colaborativos)
-Falam com `/api/v1/canvas`. **Não geram mídia nem gastam diamantes**: montam o fluxo; quem roda os nós é a pessoa, no Canvas. Funcionam com PAT e com o `beplus-mcp login`: ler boards pede `ialab:read`; criar, editar, compartilhar e subir arquivo pede `ialab:spend`.
+Falam com `/api/v1/canvas`. Montam e editam o fluxo e **não geram mídia**, com uma exceção: `canvas_run` roda nós pela aba do Canvas que a pessoa tem aberta no board e **gasta diamantes**, sempre com teto (`max_diamonds`). Funcionam com PAT e com o `beplus-mcp login`: ler boards pede `ialab:read`; criar, editar, compartilhar e subir arquivo pede `ialab:spend`.
 
 | Tool | O que faz |
 |------|-----------|
@@ -139,6 +139,13 @@ Falam com `/api/v1/canvas`. **Não geram mídia nem gastam diamantes**: montam o
 | `canvas_resolve_comment` | Fecha o comentário com uma frase obrigatória dizendo o que foi feito, postada como resposta antes de resolver. |
 | `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. 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".