suite-timesheet-mcp 1.0.0 → 1.1.0

package/CONTRACT.md

@@ -10,12 +10,12 @@ Um serviço que implemente estas três rotas passa a poder pedir leituras e prop
 
 | método | rota | corpo / resposta |
 |---|---|---|
-| `POST` | `/bridge/contexto` | a extensão envia `{ano, mes, diasNoMes, projetos: [{option_id, nome, trancado}], lidoEm}` sempre que a Folha de Horas carrega ou muda de mês |
+| `POST` | `/bridge/contexto` | a extensão envia `{ano, mes, diasNoMes, projetos: [{option_id, nome, trancado}], lidoEm, versaoExtensao}` (`versaoExtensao` a partir da extensão 1.1.0) sempre que a Folha de Horas carrega ou muda de mês |
 | `GET` | `/bridge/next?wait=25` | responde `204` sem corpo se não houver comando ao fim de `wait` segundos, ou `200` com um comando |
 | `POST` | `/bridge/result/{id}` | a extensão publica o resultado do comando `id` |
 
 Comando: `{"id": "texto", "tipo": "estado" | "projetos" | "ler" | "propor" | "aplicar", "ano": 2026, "mes": 9}`.
-`propor` leva ainda `"linhas": [{option_id | project, date, hours}]`, `"espelho": false` e
+`propor` leva ainda `"linhas": [{option_id | project, date, hours, comment?}]` (`comment` vai para as Observações do projeto), `"modo": "normal" | "somar" | "sobregravar"` (defeito `normal`; ver a tabela de modos no `CONTRACT.md` da extensão; `"espelho": true`, da 1.0, vale como `sobregravar` e é sempre enviado junto para uma extensão 1.0 perceber o sobregravar) e
 `"nome": "texto"`. O mês tem de ser o que a página mostra; caso contrário a resposta é
 `ERR_MES_DIFERENTE` e nada é lido nem escrito.
 
@@ -49,7 +49,7 @@ com o plano calculado (o painel abre nesse momento), e depois, quando o utilizad
 
 A extensão continua a ser a única coisa que escreve no Suite, sempre depois de o utilizador
 clicar Aplicar no painel ou de aprovar a tool `aplicar` no cliente MCP (ver secção "aplicar"
-abaixo). Nunca submete o mês, nunca muda o mês.
+abaixo), e só no mês aberto na página. Nunca submete as horas, nunca troca o mês selecionado.
 
 ### Prazo de `/bridge/next`
 
@@ -68,7 +68,7 @@ Resultado com `"ok": true`, no campo `dados`:
 |---|---|
 | `estado` | `{ano, mes, projetos: N, loteEmCurso: boolean}` — `projetos` é a contagem, não a lista |
 | `projetos` | `[{option_id, nome, trancado}]` |
-| `ler` | `{ano, mes, linhas: [{option_id, nome, status, dias: {D: horas}, total}], totaisPorDia: {D: horas}}` |
+| `ler` | `{ano, mes, linhas: [{option_id, nome, status, dias: {D: horas}, total, comentario}], totaisPorDia: {D: horas}}` — `comentario` a partir da extensão 1.1.0 |
 | `propor`, fase `previa` | `{fase: 'previa', previa: {matriz, criar, atualizar, apagar, ignoradas, avisos, erros, bloqueio}}` — `criar`/`atualizar`/`apagar` são listas de `{option_id, projeto, dias}`; `bloqueio` é a mensagem em português ou `null` |
 | `propor`, fase `final` | `{fase: 'final', estado: 'aplicado' \| 'cancelado' \| 'erro', report?, motivo?, erro?}` — `report` só em `aplicado` (`{results, stopped, reconciliacao, skipped}`), `motivo` só em `cancelado`, `erro` (`{code, message}`) só em `erro` |
 | `aplicar` (uma só fase) | `{estado: 'aplicado' \| 'erro', report?, stopped?, erro?}` — sem `fase: 'previa'`; ver secção "aplicar" acima |
@@ -79,6 +79,7 @@ Resultado com `"ok": true`, no campo `dados`:
 
 | código | motivo |
 |---|---|
+| `ERR_EXTENSAO_ANTIGA` | (só na tool `propor`) a extensão é anterior à 1.1.0 e o modo pedido não é `sobregravar`: a 1.0 faria outra coisa |
 | `ERR_COMANDO` | corpo do comando malformado (id/tipo/ano/mes/linhas inválidos) |
 | `ERR_MES_DIFERENTE` | o comando pede um mês diferente do que a página do Suite tem aberto |
 | `ERR_SEM_CONTEXTO` | a Folha de Horas do Suite ainda não foi aberta nesta sessão |

package/README.md

@@ -1,7 +1,44 @@
-# suite-timesheet-mcp
+<p align="center">
+  <img src="docs/media/icone.png" alt="Ícone do Suite Timesheet Importer" width="96">
+</p>
 
-Servidor MCP que deixa um assistente (Claude, GitHub Copilot, ou outro cliente MCP) **ler e
-propor horas** na Folha de Horas do Suite, através da extensão **Suite Timesheet Importer**.
+<h1 align="center">suite-timesheet-mcp</h1>
+
+<p align="center">
+  <strong>O agente propõe. Tu aprovas.</strong><br>
+  Servidor MCP que deixa um agente de IA <strong>ler e propor horas</strong> na Folha de Horas do
+  Suite, através da extensão <strong>Suite Timesheet Importer</strong>.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/suite-timesheet-mcp"><img alt="versão no npm" src="https://img.shields.io/npm/v/suite-timesheet-mcp?color=1f6699&label=npm"></a>
+  <img alt="Model Context Protocol" src="https://img.shields.io/badge/MCP-stdio-2a7fba">
+  <img alt="Node 20 ou superior" src="https://img.shields.io/badge/node-%E2%89%A5%2020-1e7a34">
+  <img alt="só loopback" src="https://img.shields.io/badge/rede-s%C3%B3%20127.0.0.1-1e7a34">
+  <img alt="sem telemetria" src="https://img.shields.io/badge/telemetria-nenhuma-1e7a34">
+</p>
+
+<p align="center">
+  <a href="docs/media/lancamento-1.1.0.mp4">
+    <img src="docs/media/agente.gif" alt="Um agente recebe um pedido, propõe o lançamento e pede aprovação" width="820">
+  </a>
+  <br>
+  <sub>Excerto do vídeo de lançamento da 1.1.0, com o Copilot como exemplo de agente. Clica para ver o vídeo completo. Dados fictícios.</sub>
+</p>
+
+## Porquê
+
+O Suite não tem API para agentes. Este pacote dá-lhe uma, sem tocar no Suite:
+
+- **Pedes em linguagem natural.** "Lança 4 h de hoje no Alfa: migração de dados."
+- **O agente lê e propõe.** Vê o mês aberto, os projetos do teu dropdown e o que já está
+  lançado, e monta a proposta.
+- **Tu decides.** A proposta abre no painel da extensão com a pré-visualização. Só é escrita
+  depois de aprovares.
+
+Funciona com qualquer agente que fale MCP. O servidor não sabe nem precisa de saber qual é.
+
+## Garantias
 
 - **Nunca fala com o Suite.** Quem lê e escreve é a extensão, no teu browser, com a tua sessão.
 - **Nunca escreve sem ti.** Cada lançamento é uma proposta; só é escrito quando clicas Aplicar
@@ -26,18 +63,12 @@ Nas **Opções** da extensão, liga **Ligação ao servidor local (ponte MCP)**,
 
 Este passo é manual e feito uma vez: sem ele a extensão nunca toca na rede local.
 
-### 2. Registar o servidor no teu cliente MCP
+### 2. Registar o servidor no teu agente
 
 Não é preciso clonar nada: o `npx` descarrega o pacote do npm e corre-o. `@1` fixa a versão
 principal: recebes as correções 1.x, nunca uma versão incompatível. A primeira execução demora
 alguns segundos; as seguintes usam a cache.
 
-**Claude Code**
-
-```bash
-claude mcp add --scope user suite-timesheet -- npx -y suite-timesheet-mcp@1
-```
-
 **GitHub Copilot (VS Code)**
 
 ```bash
@@ -46,6 +77,12 @@ code --add-mcp '{"name":"suite-timesheet","command":"npx","args":["-y","suite-ti
 
 Depois recarrega a janela; as tools aparecem no modo **Agent** do Copilot.
 
+**Claude Code**
+
+```bash
+claude mcp add --scope user suite-timesheet -- npx -y suite-timesheet-mcp@1
+```
+
 **Claude Desktop (inclui Cowork)**
 
 Em Definições → Programador → Editar configuração
@@ -65,7 +102,7 @@ Em Definições → Programador → Editar configuração
 
 Reinicia o Claude Desktop.
 
-**Outros clientes**
+**Outros agentes**
 
 O mesmo comando: `npx -y suite-timesheet-mcp@1`, por stdio. Atenção à
 chave do ficheiro de configuração: o VS Code usa `servers`, a maioria dos outros usa
@@ -77,9 +114,9 @@ chave do ficheiro de configuração: o VS Code usa `servers`, a maioria dos outr
 
 ### 3. Verificar
 
-Pede ao assistente: *"consulta o estado da ponte do Suite Timesheet"*. A tool `estado` deve
+Pede ao agente: *"consulta o estado da ponte do Suite Timesheet"*. A tool `estado` deve
 responder com a ponte ligada e o mês visível na página. As Opções da extensão passam a mostrar
-"Claude ligado há N s" (o texto é o mesmo para qualquer cliente).
+"Agente ligado há N s" (o texto é o mesmo para qualquer agente).
 
 ## Instalação feita por um agente
 
@@ -102,18 +139,22 @@ Exemplos de pedidos:
 - *"Quantas horas tenho lançadas este mês no Suite?"* → `ler_mes`
 - *"Que projetos tenho disponíveis?"* → `projetos`
 - *"Lança 8 h no projeto X de segunda a sexta desta semana."* → `propor`, depois `aplicar`
+- *"Soma 2 h ao dia de hoje no projeto X, com a nota 'reunião de arranque'."* → `propor` em
+  modo `somar`, com `comment`
 
 Lançar horas tem sempre duas fases:
 
 1. **`propor`** calcula o plano, abre o painel da extensão com a pré-visualização e devolve-a ao
-   assistente. Nada é escrito.
+   agente. Nada é escrito.
 2. **Confirmação**, de uma de duas formas:
    - clicas **Aplicar** no painel, ou
    - dizes OK no chat e aprovas a chamada da tool **`aplicar`** no cliente MCP.
 
-Por isso: **mantém a aprovação manual da tool `aplicar`**. Com ela em aprovação automática,
-qualquer proposta é escrita sem mais nenhuma confirmação. Linhas trancadas e propostas
-bloqueadas são sempre recusadas pela extensão.
+> [!IMPORTANT]
+> Mantém a aprovação manual da tool `aplicar`. Com ela em aprovação automática, qualquer
+> proposta é escrita sem mais nenhuma confirmação.
+
+Linhas trancadas e propostas bloqueadas são sempre recusadas pela extensão.
 
 ## Tools
 
@@ -121,11 +162,56 @@ bloqueadas são sempre recusadas pela extensão.
 |---|---|
 | `estado` | ponte ligada?, mês visível, nº de projetos, lote a correr |
 | `projetos` | projetos do dropdown da página: `option_id`, nome, trancado |
-| `ler_mes` | horas já lançadas no mês visível |
+| `ler_mes` | horas e Observações já lançadas no mês visível |
 | `propor` | calcula o plano, abre o painel, devolve a pré-visualização e um `id` |
-| `aplicar` | escreve a proposta `id` no Suite através da extensão |
+| `aplicar` | escreve a proposta `id` no Suite através da extensão, sem esperar pelo clique no painel |
 | `resultado` | espera pela decisão (painel ou `aplicar`): aplicado, cancelado, erro ou pendente |
 
+### `propor`
+
+```json
+{
+  "modo": "somar",
+  "linhas": [
+    {
+      "project": "Alfa - Projeto SAP",
+      "date": "2026-10-14",
+      "hours": 4,
+      "comment": "Migração de dados"
+    }
+  ]
+}
+```
+
+| campo | notas |
+|---|---|
+| `linhas[].option_id` ou `project` | um dos dois: id do dropdown ou nome tal como lá aparece |
+| `linhas[].date` | `YYYY-MM-DD`, dentro do mês visível |
+| `linhas[].hours` | 0,5 a 23,5 em passos de 0,5; em `somar` pode ser negativo |
+| `linhas[].comment` | opcional; vai para as Observações do projeto no mês |
+| `modo` | `normal` (defeito), `somar` ou `sobregravar` |
+| `nome` | opcional; rótulo que aparece no painel |
+
+| modo | o que vem nas linhas | o que não vem |
+|---|---|---|
+| `normal` | fica com o valor pedido | fica como está |
+| `somar` | Suite + pedido (negativos subtraem) | fica como está |
+| `sobregravar` | fica com o valor pedido | é apagado |
+
+Propor duas vezes em `somar` duplica. Mais de 8 h num dia é só aviso.
+
+## Novidades da 1.1.0
+
+- **`propor` aceita `modo`**: `normal`, `somar` ou `sobregravar`, no lugar do antigo `espelho`
+  (que continua aceite).
+- **`propor` aceita `comment` por linha**, que vai para as Observações do projeto.
+- **`ler_mes` devolve as Observações.**
+- **Comentários que o Suite ignoraria em silêncio são recusados** antes de propor.
+- **`ERR_EXTENSAO_ANTIGA`**: com uma extensão anterior à 1.1.0, os modos `normal` e `somar` são
+  recusados, porque a extensão antiga faria outra coisa.
+
+Os modos `normal` e `somar` e os comentários precisam da extensão ≥ 1.1.0.
+
 ## Erros
 
 | erro | o que fazer |
@@ -133,16 +219,25 @@ bloqueadas são sempre recusadas pela extensão.
 | `ERR_SERVE_EM_BAIXO` | o serviço local não responde; reinicia o cliente MCP (ele arranca-o sozinho) |
 | `ERR_SEM_CHROME` | abre a Folha de Horas e confirma que a ponte está ligada nas Opções |
 | `ERR_SEM_CONTEXTO` | recarrega a Folha de Horas (o serviço reiniciou depois de a página carregar) |
+| `ERR_SEM_ABA` | não há nenhuma aba do Suite aberta; abre-a ou recarrega-a |
 | `ERR_MES_DIFERENTE` | muda o mês na página; o MCP nunca o muda por ti |
 | `ERR_OCUPADO` | há uma proposta à espera no painel; aplica-a ou cancela-a primeiro |
+| `ERR_LOTE_A_CORRER` | já está um lote a escrever no Suite; espera que termine |
+| `ERR_SESSION` | a sessão do Suite expirou; entra outra vez |
 | `ERR_PROPOSTA_DESCONHECIDA` | o `id` passado a `aplicar` não corresponde a nenhuma proposta pendente |
+| `ERR_EXTENSAO_ANTIGA` | atualiza a extensão para a 1.1.0, ou usa `modo: "sobregravar"` |
+
+Lista completa em [CONTRACT.md](CONTRACT.md).
 
 ## Como funciona
 
-```
-cliente MCP ──stdio──▶ mcp.js ──HTTP──▶ serve.js ◀──long-poll── extensão ──▶ Suite
-                                        127.0.0.1                    │
-                                                              painel: Aplicar
+```mermaid
+flowchart LR
+    C["Agente<br>cliente MCP"] -->|stdio| M["mcp.js"]
+    M -->|HTTP local| S["serve.js<br>127.0.0.1:18765"]
+    E["Extensão<br>no browser"] -->|long-poll| S
+    E -->|"lê e escreve<br>com a tua sessão"| T["Folha de Horas<br>do Suite"]
+    E --- P["Painel: pré-visualização<br>e Aplicar"]
 ```
 
 1. O cliente MCP arranca o `mcp.js`. Se o serviço local (`serve.js`) não estiver a correr, o
@@ -165,7 +260,8 @@ Com o serviço gerido à mão, arranca-o **antes** de abrir a Folha de Horas, ou
 depois: a extensão só publica o contexto quando a página carrega ou muda de mês.
 
 As tools aceitam `timeout_s` até 290 s (útil em `resultado` com lotes grandes). Se o cliente
-cortar a chamada antes disso, aumenta o timeout do cliente MCP (no Claude Code, 60 s por defeito).
+cortar a chamada antes disso, aumenta o timeout do cliente MCP (muitos cortam aos 60 s por
+defeito).
 
 ## Atualizar
 
@@ -192,7 +288,7 @@ node --test
 
 Para usar a cópia local num cliente, troca o comando `npx …` por
 `node /caminho/para/suite-timesheet-mcp/mcp.js`. Também dá para instalar diretamente de uma tag do
-GitHub, sem npm: `npx -y github:williansaez/suite-timesheet-mcp#v1.0.0` (precisa de `git`).
+GitHub, sem npm: `npx -y github:williansaez/suite-timesheet-mcp#v1.1.0` (precisa de `git`).
 
 ## Licença
 
@@ -200,3 +296,7 @@ Código disponível para consulta, **não open source**. Podes instalar e usar o
 alterações, para uso pessoal ou interno da tua organização. Não é permitido alterá-lo,
 redistribuí-lo nem publicar cópias ou forks. Os termos completos (em inglês, com tradução para
 português) estão em [LICENSE](LICENSE).
+
+<p align="center">
+  <img src="docs/media/fecho.png" alt="Suite Timesheet Importer 1.1.0 e suite-timesheet-mcp 1.1.0. O Suite de sempre, a tecnologia de hoje." width="820">
+</p>

package/SECURITY.md

@@ -5,9 +5,9 @@ ele faz, o que nunca faz, e como verificar cada afirmação.
 
 ## Em uma frase
 
-Um processo local (`serve.js`) que guarda em memória uma fila de comandos entre o Claude e a
+Um processo local (`serve.js`) que guarda em memória uma fila de comandos entre o agente e a
 extensão Suite Timesheet Importer, e um servidor MCP por stdio (`mcp.js`) que expõe seis tools ao
-Claude. Este pacote **nunca fala com o Suite**: quem lê e escreve no Suite é a extensão, dentro do
+agente. Este pacote **nunca fala com o Suite**: quem lê e escreve no Suite é a extensão, dentro do
 browser, com a sessão do utilizador, e só depois de o utilizador clicar Aplicar no painel ou de
 aprovar a tool `aplicar` no cliente MCP (ver a tabela abaixo).
 
@@ -17,7 +17,7 @@ aprovar a tool `aplicar` no cliente MCP (ver a tabela abaixo).
 |---|---|
 | Nunca contacta o Suite nem qualquer host externo | o código não contém nenhum URL além de `127.0.0.1` (guard no CI); o único `listen` é em `127.0.0.1`; o `mcp.js` só chama o `serve` local |
 | Nunca escreve no Suite, nem submete meses | não tem sessão, cookies nem endpoints do Suite; o endpoint de submissão não existe no código (guard no CI) |
-| Nunca provoca uma escrita sem confirmação humana | a tool `propor` só enfileira; a escrita só acontece com o clique em Aplicar no painel **ou** com a aprovação da tool `aplicar` no cliente MCP (ex.: Claude Code a pedir confirmação antes de correr a tool) — uma das duas é sempre exigida |
+| Nunca provoca uma escrita sem confirmação humana | a tool `propor` só enfileira; a escrita só acontece com o clique em Aplicar no painel **ou** com a aprovação da tool `aplicar` no cliente MCP (o cliente a pedir confirmação antes de correr a tool) — uma das duas é sempre exigida |
 | Nunca guarda dados em disco | fila, contexto e propostas vivem em memória; reiniciar o `serve` esquece tudo |
 | Nunca aceita pedidos de páginas web | recusa `Origin` que não seja `chrome-extension://`, `Host` que não seja `127.0.0.1`/`localhost`, e POST sem `application/json` |
 | Nunca contém dados reais | testes e exemplos só com projetos, ids e horas fictícios (guard de nomes de cliente no CI) |
@@ -42,7 +42,7 @@ não encontra nada a responder em `/health`; nunca arranca nem chama nenhum outr
 ## Dados
 
 Em memória: o mês visível e a lista de projetos que a extensão publica, as propostas enviadas
-pelo Claude, e os resultados que a extensão devolve (prévia e resultado final). Resultados expiram
+pelo agente, e os resultados que a extensão devolve (prévia e resultado final). Resultados expiram
 ao fim de 1 h; comandos sem resposta expiram com `ERR_EXPIRADO`. Nada é registado além de uma
 linha por comando em `stderr` (tipo e mês, sem horas).
 
@@ -64,7 +64,7 @@ Uma, declarada e fixada em `package-lock.json`: `@modelcontextprotocol/sdk` (só
 
 ```bash
 npm ci
-node --test                       # 73 testes, sem rede além de loopback
+node --test                       # 85 testes, sem rede além de loopback
 npm audit --omit=dev              # dependências conhecidas
 grep -rnoE "https?://[a-zA-Z0-9.-]+" --include='*.js' --exclude-dir=node_modules --exclude-dir=test .   # esperado: só 127.0.0.1
 grep -rniE "submitaction" --include='*.js' . --exclude-dir=node_modules | grep -v '/test/'      # esperado: vazio

package/lib/ferramentas.js

@@ -2,11 +2,11 @@
 
 import { validarProposta } from './validar.js';
 
-const AVISO = 'Opera só no mês que a Folha de Horas mostra no Chrome. Nunca submete o mês, nunca muda o mês.';
+const AVISO = 'Escreve horas só no mês que a Folha de Horas mostra no Chrome. Nunca submete as horas, nunca troca o mês selecionado.';
 const WAIT_MAX_S = 290;
 // O cliente por defeito do SDK do MCP corta a chamada aos 60 s; 50 dá margem para a
-// tool responder antes disso. timeout_s continua a poder ser pedido até WAIT_MAX_S (o
-// Claude Code permite subir o timeout do cliente MCP quando isso for preciso).
+// tool responder antes disso. timeout_s continua a poder ser pedido até WAIT_MAX_S (alguns
+// clientes MCP deixam subir esse timeout quando isso for preciso).
 const TIMEOUT_TOOL_S = 50;
 // aplicar escreve linha a linha no Suite: pode demorar bem mais do que as outras tools.
 const TIMEOUT_APLICAR_S = 120;
@@ -24,12 +24,12 @@ export const FERRAMENTAS = [
   },
   {
     name: 'ler_mes',
-    description: `Lê as horas já lançadas no mês visível: uma linha por projeto com os dias preenchidos, o status e os totais por dia. ${AVISO}`,
+    description: `Lê as horas já lançadas no mês visível: uma linha por projeto com os dias preenchidos, o status, as Observações (comentario) e os totais por dia. ${AVISO}`,
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
   },
   {
     name: 'propor',
-    description: `Propõe lançamentos para o mês visível. A extensão calcula o plano (criar/atualizar/apagar), abre o painel com a pré-visualização e devolve-a aqui; nada é escrito até o utilizador clicar Aplicar no painel. Depois chama "resultado" com o id. Com espelho: true, as linhas do Suite que não vierem na proposta são apagadas. ${AVISO}`,
+    description: `Propõe lançamentos para o mês visível. A extensão calcula o plano (criar/atualizar/apagar), abre o painel com a pré-visualização e devolve-a aqui; nada é escrito até o utilizador clicar Aplicar no painel. Depois chama "resultado" com o id. Modo (defeito "normal"): normal escreve os valores das linhas (preenche ou substitui) e nunca apaga o que não vier; somar soma às horas do Suite (negativos subtraem; propor duas vezes duplica); sobregravar deixa o mês igual às linhas (apaga dias e projetos que não vierem). Mais de 8 h num dia é só aviso. ${AVISO}`,
     inputSchema: {
       type: 'object',
       required: ['linhas'],
@@ -46,11 +46,20 @@ export const FERRAMENTAS = [
               option_id: { type: 'integer', description: 'id do projeto no dropdown (usa "projetos"). Exclusivo com project.' },
               project: { type: 'string', description: 'nome do projeto como aparece no dropdown. Exclusivo com option_id.' },
               date: { type: 'string', description: 'YYYY-MM-DD, dentro do mês visível' },
-              hours: { type: 'number', description: 'de 0,5 a 23,5 em passo de 0,5' },
+              hours: { type: 'number', description: 'de 0,5 a 23,5 em passo de 0,5 (em modo somar pode ser negativo, para subtrair)' },
+              comment: {
+                type: 'string',
+                description: 'opcional: vai para as Observações do projeto no mês (uma por projeto). Comentários diferentes do mesmo projeto são juntos com "; ". Sem comment, as Observações que o Suite já tem ficam.',
+              },
             },
           },
         },
-        espelho: { type: 'boolean', description: 'apaga do Suite o que não vier nas linhas (defeito: false)' },
+        modo: {
+          type: 'string',
+          enum: ['normal', 'somar', 'sobregravar'],
+          description: 'normal (defeito): escreve as células das linhas, nunca apaga; somar: soma ao Suite, negativos subtraem; sobregravar: o mês fica igual às linhas',
+        },
+        espelho: { type: 'boolean', description: 'obsoleto: espelho: true é o mesmo que modo: "sobregravar"' },
         nome: { type: 'string', description: 'rótulo que aparece no painel (ex.: "sprint 12")' },
       },
     },
@@ -111,6 +120,27 @@ const finalDe = (id, dados) => {
   return { id, estado, report, motivo };
 };
 
+// A extensão 1.0 descarta o comment sem avisar: antes de propor comentários, confirma a versão
+// que ela publicou no contexto. Nunca falha por isto — no pior caso avisa sem precisar.
+const menorQue = (a, b) => {
+  const [x, y] = [a, b].map((v) => String(v).split('.').map(Number));
+  for (let i = 0; i < 3; i += 1) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) < (y[i] ?? 0);
+  return false;
+};
+
+// A versão vem do contexto que a extensão publicou. Sem contexto (serve reiniciado, estado em
+// baixo) não se sabe: deixa seguir, o comando falha sozinho se não houver ponte. Com contexto
+// sem versaoExtensao é uma extensão 1.0.
+async function extensaoAntiga(cliente) {
+  let contexto = null;
+  try { contexto = (await cliente.estado())?.contexto ?? null; } catch { contexto = null; }
+  if (!contexto) return { antiga: false, versao: null };
+  const versao = contexto.versaoExtensao ?? null;
+  return { antiga: !versao || menorQue(versao, '1.1.0'), versao };
+}
+
+const textoVersao = (versao) => (versao ? `está na ${versao}` : 'é anterior à 1.1.0');
+
 export async function executar(nome, args = {}, cliente, { estadoServe } = {}) {
   switch (nome) {
     case 'estado': {
@@ -121,7 +151,7 @@ export async function executar(nome, args = {}, cliente, { estadoServe } = {}) {
         // O auto-arranque do mcp.js (ver lib/autoarranque.js) já tentou pôr o serve a
         // responder antes disto. Se não conseguiu, por a porta estar ocupada por outro
         // programa ou por o arranque ter falhado, esta tool não deve lançar: devolve o
-        // porquê para o Claude poder explicar ao utilizador em vez de um erro seco.
+        // porquê para o agente poder explicar ao utilizador em vez de um erro seco.
         if (err.code === 'ERR_SERVE_EM_BAIXO' && (estadoServe?.estado === 'porta-ocupada' || estadoServe?.estado === 'falhou')) {
           return { ponte: 'sem-serve', serve: estadoServe.estado, detalhe: estadoServe.detalhe };
         }
@@ -148,15 +178,24 @@ export async function executar(nome, args = {}, cliente, { estadoServe } = {}) {
     case 'ler_mes': return (await dadosDe(cliente, { tipo: 'ler', timeout_s: TIMEOUT_TOOL_S })).dados;
     case 'propor': {
       const proposta = validarProposta(args); // erro imediato e legível; o serve valida com o mês
+      const { antiga, versao } = await extensaoAntiga(cliente);
+      // A 1.0 não conhece normal nem somar: trataria as linhas como "substituir o projeto".
+      if (antiga && proposta.modo !== 'sobregravar') {
+        throw erro('ERR_EXTENSAO_ANTIGA', `A extensão ${textoVersao(versao)} e só conhece o modo sobregravar. Atualiza a extensão para a 1.1.0 (ou usa modo: "sobregravar").`);
+      }
+      const aviso = antiga && proposta.linhas.some((l) => l.comment)
+        ? `A extensão ${textoVersao(versao)}: os comentários (Observações) só são escritos a partir da 1.1.0 e vão ser ignorados.`
+        : null;
+      const comAviso = (resposta) => (aviso ? { ...resposta, aviso } : resposta);
       const r = await cliente.comando({ tipo: 'propor', ...proposta, timeout_s: TIMEOUT_TOOL_S });
-      if (!r.resultado) return { id: r.id, estado: 'pendente' };
+      if (!r.resultado) return comAviso({ id: r.id, estado: 'pendente' });
       if (!r.resultado.ok) throw erro(r.resultado.erro.code, r.resultado.erro.message);
       const { dados } = r.resultado;
       // Normalmente chega logo a previa; se a previa se perdeu (ex.: o worker publicou logo o
       // final) dados.fase já vem 'final' — devolve o estado final em vez de fingir "previa".
-      if (dados.fase !== 'previa') return finalDe(r.id, dados);
+      if (dados.fase !== 'previa') return comAviso(finalDe(r.id, dados));
       const { previa } = dados;
-      return { id: r.id, estado: 'previa', previa, bloqueio: previa?.bloqueio ?? null };
+      return comAviso({ id: r.id, estado: 'previa', previa, bloqueio: previa?.bloqueio ?? null });
     }
     case 'aplicar': {
       const id = String(args.id);

package/lib/rotas.js

@@ -20,7 +20,7 @@ const limitar = (v, max) => Math.max(0, Math.min(inteiro(v, max), max));
 export function criarRotas({ fila, contexto, log = () => {}, versao, agora = Date.now }) {
   // Timestamp ISO do último pedido a qualquer rota /mcp/*, ou null se ainda não houve nenhum
   // desde que este `serve` arrancou. É o que /health e /mcp/estado mostram como "ultimoMcp",
-  // para a extensão (painel) saber se o Claude ainda está a falar com o serviço.
+  // para a extensão (painel) saber se o agente ainda está a falar com o serviço.
   let ultimoMcp = null;
   const marcarMcp = () => { ultimoMcp = new Date(agora()).toISOString(); };
 

package/lib/validar.js

@@ -1,4 +1,4 @@
-// Puro. Primeira validação de uma proposta, para o Claude ter um erro imediato e legível.
+// Puro. Primeira validação de uma proposta, para o agente ter um erro imediato e legível.
 // A extensão volta a validar (normalize/match): esta é a rede, aquela é a verdade.
 
 const DATA_ISO = /^(\d{4})-(\d{2})-(\d{2})$/;
@@ -17,11 +17,16 @@ function dataValida(texto) {
   return { ano, mes, dia };
 }
 
-export function validarProposta({ linhas, espelho = false, nome } = {}, mesVisivel = null) {
+export const MODOS = ['normal', 'somar', 'sobregravar'];
+
+// modo (extensão 1.1): normal | somar | sobregravar. espelho: true é o nome da 1.0 para sobregravar.
+export function validarProposta({ linhas, espelho = false, modo: pedido, nome } = {}, mesVisivel = null) {
+  const modo = pedido ?? (espelho === true ? 'sobregravar' : 'normal');
   const problemas = [];
+  if (!MODOS.includes(modo)) problemas.push(`modo tem de ser ${MODOS.join(', ')}.`);
   const lista = Array.isArray(linhas) ? linhas : [];
   if (!Array.isArray(linhas)) problemas.push('"linhas" tem de ser um array.');
-  else if (linhas.length === 0 && espelho !== true) problemas.push('Sem linhas. Para limpar o mês usa espelho: true.');
+  else if (linhas.length === 0 && modo !== 'sobregravar') problemas.push('Sem linhas. Para limpar o mês usa modo: "sobregravar".');
 
   const normalizadas = lista.map((linha, i) => {
     const n = i + 1;
@@ -37,21 +42,40 @@ export function validarProposta({ linhas, espelho = false, nome } = {}, mesVisiv
       problemas.push(`linha ${n}: ${linha.date} está fora do mês visível ${mesVisivel.ano}-${String(mesVisivel.mes).padStart(2, '0')}.`);
     }
     const horas = Number(linha?.hours);
-    if (!Number.isFinite(horas) || horas <= 0 || horas > 23.5 || Math.round(horas * 2) !== horas * 2) {
-      problemas.push(`linha ${n}: hours tem de estar entre 0,5 e 23,5 em passo de 0,5.`);
+    // Em somar um negativo subtrai: a extensão valida o resultado (0 a 23,5) contra o Suite.
+    const noIntervalo = modo === 'somar'
+      ? horas !== 0 && Math.abs(horas) <= 23.5
+      : horas > 0 && horas <= 23.5;
+    if (!Number.isFinite(horas) || !noIntervalo || Math.round(horas * 2) !== horas * 2) {
+      problemas.push(modo === 'somar'
+        ? `linha ${n}: hours em somar tem de ser diferente de 0, entre -23,5 e 23,5, em passo de 0,5.`
+        : `linha ${n}: hours tem de estar entre 0,5 e 23,5 em passo de 0,5.`);
+    }
+    // comment (Observações do Suite) é opcional; vazio fica de fora e o Suite mantém o que tem.
+    const comentario = linha?.comment;
+    if (comentario !== undefined && comentario !== null && typeof comentario !== 'string') {
+      problemas.push(`linha ${n}: comment tem de ser texto.`);
+    }
+    const textoComentario = typeof comentario === 'string' ? comentario.trim() : '';
+    // O Suite (validação de pedidos do ASP.NET) responde 200 sem gravar estes padrões.
+    if (/<[A-Za-z!/?]|&#/.test(textoComentario)) {
+      problemas.push(`linha ${n}: comment não pode ter "<" seguido de letra nem "&#" (o Suite ignora-o sem avisar).`);
     }
     return {
       option_id: temId ? Number(linha.option_id) : '',
       project: temNome ? linha.project.trim() : '',
       date: String(linha?.date ?? ''),
       hours: horas,
+      ...(textoComentario ? { comment: textoComentario } : {}),
     };
   });
 
   if (problemas.length > 0) throw erroProposta(problemas);
   return {
     linhas: normalizadas,
-    espelho: espelho === true,
+    modo,
+    // Enviado também para uma extensão 1.0, que só conhece espelho.
+    espelho: modo === 'sobregravar',
     nome: typeof nome === 'string' && nome.trim() ? nome.trim() : 'proposta do Claude',
   };
 }

package/mcp.js

@@ -27,7 +27,7 @@ if (process.env.SUITE_TIMESHEET_SEM_AUTOARRANQUE !== '1') {
 }
 
 const server = new Server(
-  { name: 'suite-timesheet', version: '1.0.0' },
+  { name: 'suite-timesheet', version: '1.1.0' },
   { capabilities: { tools: {} } },
 );
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "suite-timesheet-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
-  "description": "Servidor MCP para o Suite Timesheet Importer: um assistente (Claude, Copilot…) lê e propõe horas; a extensão escreve depois de confirmação humana.",
+  "description": "Servidor MCP para o Suite Timesheet Importer: um agente de IA lê e propõe horas; a extensão escreve depois de confirmação humana.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Willian Saez",
   "homepage": "https://github.com/williansaez/suite-timesheet-mcp#readme",