@softize/opus 25.7.0 → 26.0.0

package/CHANGELOG.md

@@ -7,6 +7,80 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 26.0.0 — 2026-10-09
+
+A conversa com a IA pode levar imagens (ADR 0058). Uma mensagem passa a aceitar texto e imagem
+juntos, o driver Anthropic envia as imagens ao modelo, e o `Composer` e o `Chat` recebem imagens
+coladas, soltas ou escolhidas pelo botão **Anexar imagem**. O pacote não guarda imagem: enviar,
+guardar, expirar e mostrar de novo são do aplicativo, que mantém o estado dos anexos.
+
+- **Mensagem com imagem.** `AiMessage.content` aceita `string | AiContentPart[]`, em que cada parte é
+  `{ type: 'text', text }` ou `{ type: 'image', mediaType, data }`, com PNG, JPEG ou WebP em base64.
+  Os tipos `AiContentPart` e `AiImageMediaType` saem de `@softize/opus` e de `@softize/opus/ai`.
+- **`aiMessageText(message)`.** Devolve o texto de uma mensagem: o próprio `content` quando é texto,
+  ou as partes de texto unidas por uma linha em branco, sem as imagens. Sai de `@softize/opus` e de
+  `@softize/opus/ai`.
+- **Driver Anthropic.** `run` e `runStream` convertem cada parte no bloco da API (`text`, ou `image`
+  com `source.type: 'base64'`). Uma parte desconhecida, uma lista de partes vazia, uma parte de texto
+  vazia, uma imagem fora dos três formatos ou uma imagem numa mensagem `assistant` fazem a chamada
+  lançar erro antes de chegar ao provedor, dizendo qual mensagem e qual parte.
+  `complete` e `extract` continuam recebendo texto.
+- **`Composer` com imagens.** A propriedade `attachments` liga o botão **Anexar imagem**, a faixa
+  acima do campo (miniatura, nome, estado `uploading`, `ready` ou `failed` e remover), colar e
+  soltar. A triagem aceita PNG, JPEG e WebP, até 4 por mensagem (`max` muda o limite, e `accept`,
+  tipado como `readonly AiImageMediaType[]`, escolhe um subconjunto dos três, sem curinga), e
+  explica a recusa acima do campo, ou a entrega a `onReject`. O envio passa com texto ou com uma
+  imagem pronta; espera enquanto alguma imagem está em envio e fica bloqueado com uma imagem em
+  falha, até ela ser removida ou reenviada. Uma região viva anuncia a imagem que fica pronta ou
+  falha, e o foco volta ao campo quando o botão de anexar fica desabilitado pelo limite. Colar
+  texto continua colando texto; a imagem colada sem texto recebe "Imagem colada 1.png", com um
+  número que não se repete no mesmo composer. O soltar que o composer consome não sobe para os
+  contêineres do aplicativo.
+- **`Chat` com imagens.** No modo controlado, `composerAttachments` liga as imagens no composer e o
+  soltar sobre a conversa inteira; `onSend(text, attachments)` recebe as imagens prontas, e a
+  mensagem pode ter só imagem. Sem `composerAttachments`, `onSend` continua sendo chamado só com o
+  texto. O item `user` do transcript aceita `attachments` (`ChatAttachment`,
+  com `id`, `name`, `mediaType`, dimensões, `status: 'available' | 'expired'` e o `url` dado pelo
+  aplicativo): a fala mostra as miniaturas acima do texto, com o nome como texto alternativo, e a
+  imagem expirada como um cartão com o nome e "Imagem expirada". O modo autogerenciado (`send`) não
+  aceita imagem. Com `composerAttachments`, o arraste de arquivos sobre o Chat é consumido nele
+  (`stopPropagation` em `dragenter`, `dragover`, `dragleave` e `drop`) e não chega a um contêiner do
+  aplicativo com o próprio soltar; sem ele, o arraste segue como antes.
+- **`prepareImage(file, options)`**, de `@softize/opus/ui/react`, prepara a imagem no navegador antes
+  do envio: lê só o cabeçalho para conferir o formato pelos bytes e as dimensões, recusa GIF, SVG,
+  imagem animada e, antes de decodificar, a imagem acima de `maxPixels` (padrão 40 megapixels);
+  reduz o lado maior a `maxEdge` (padrão 1568) respeitando a orientação EXIF
+  (`imageOrientation: 'from-image'`) e codifica de novo, descartando metadados. PNG continua PNG quando cabe em
+  `maxBytes` (padrão 3 MB); o resto vira JPEG com qualidade 0,85. Devolve o arquivo com tipo,
+  dimensões e tamanho, ou a recusa com o motivo e a mensagem em pt-BR.
+
+Sem as propriedades novas, o `Composer` e o `Chat` se comportam como antes.
+
+### Breaking
+
+**`AiMessage.content` passa a ser `string | AiContentPart[]`.** Código que lê `content` como texto
+deixa de compilar: `message.content.length`, `message.content.trim()`, uma função que recebe
+`string`, um driver de IA próprio que repassa `content` ao provedor. Migração: leia o texto com
+`aiMessageText(message)` e, num driver próprio, converta cada parte para o formato do provedor e
+recuse com erro a parte que ele não conhece.
+
+```ts
+import { aiMessageText } from '@softize/opus/ai'
+
+const title = aiMessageText(message).slice(0, 80) // antes: message.content.slice(0, 80)
+```
+
+O compilador não aponta o texto montado por interpolação (`${message.content}`) nem o que passa por
+`as`: com uma mensagem com imagem, esses pontos produzem "[object Object]" sem erro. Procure-os à
+parte (`grep -rn '\${[^}]*content' src`) e troque por `aiMessageText`. Um `ChatMessage` do `Chat`
+autogerenciado continua com `content: string` e segue atribuível a `AiMessage`.
+
+**`Chat.onSend` ganha o segundo parâmetro opcional `attachments?: ComposerAttachment[]`.** Em tempo de
+execução nada muda sem `composerAttachments`: a chamada continua `onSend(text)`. Um handler que já
+declarava um segundo parâmetro opcional de outro tipo, como `(text, options?) => …`, deixa de
+compilar ao ser passado direto. Migração: envolva-o (`onSend={(text) => runTurn(text)}`) ou, ao ligar
+as imagens, receba `attachments` explicitamente.
+
 ## 25.7.0 — 2026-10-07
 
 Portais de documentação podem manter o mesmo mapa lateral em guias, ADRs e changelog. A superfície

package/docs/adr/0058-mensagem-da-ia-aceita-imagem-e-o-chat-recebe-anexos.md

@@ -0,0 +1,201 @@
+# ADR 0058 — A mensagem da IA aceita imagem, e o Chat recebe anexos que o app guarda
+
+- **Status:** aceita.
+- **Data:** 2026-10-09.
+- **Complementa:** a regra de crescimento por reincidência do `AiAdapter` (`core/types.ts`, nota do
+  contrato) e da entrada `@softize/opus/ai`; ADR 0050 (o `Markdown` não carrega imagem externa).
+- **Origem:** ADR 0122 da plataforma Grand Brasil, "A imagem anexada à conversa com a IA fica
+  guardada com a conversa", que pede ao pacote o corte 1 do plano dela.
+
+## Contexto
+
+A plataforma Grand Brasil decidiu que a pessoa pode colar, soltar ou escolher uma imagem na conversa
+com a IA, e que a IA a vê no mesmo turno. O caso que motivou a decisão é pedir ao assistente de
+Relatórios que reproduza um relatório a partir de um print. É o primeiro caso real de entrada que não
+é texto, e a superfície de IA do pacote cresce por reincidência: este é o caso que a cobra.
+
+Hoje o pacote só conhece texto em três pontos:
+
+- **O tipo da mensagem.** `AiMessage` é `{ role, content: string }`. `run` e `runStream` recebem
+  `string | AiMessage[]`.
+- **O driver Anthropic.** Ele monta as mensagens com `content: m.content`, sem conferir a forma. Uma
+  lista de blocos no formato da Anthropic passaria por acaso, forçada com um `as`, e qualquer outro
+  provedor do consumidor receberia uma forma que não conhece.
+- **A interface.** O `Composer` só habilita o envio com texto, e o `Chat` guarda `content: string` em
+  cada item. O modo controlado recebe o texto em `onSend(text)`.
+
+A guarda da imagem não é do pacote. Na Grand Brasil, o motor de IA guarda os bytes junto com a
+conversa, com retenção, governança e uma rota própria de envio. Outro consumidor pode guardar em
+outro lugar, ou não guardar. O que se repete em qualquer consumidor é a forma de levar a imagem ao
+modelo, a caixa de escrever com anexos e a preparação da imagem no navegador.
+
+## Decisão
+
+### 1. Conteúdo neutro na mensagem
+
+O núcleo ganha um tipo de conteúdo que não tem a forma de nenhum provedor:
+
+```ts
+type AiImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp'
+
+type AiContentPart =
+  | { type: 'text'; text: string }
+  | { type: 'image'; mediaType: AiImageMediaType; data: string } // base64, sem o prefixo data:
+
+interface AiMessage {
+  role: 'user' | 'assistant'
+  content: string | AiContentPart[]
+}
+```
+
+- Os formatos são PNG, JPEG e WebP, os três que os provedores conhecidos aceitam. GIF fica de fora.
+- A parte de imagem não leva nome. O rótulo que a pessoa e o modelo usam ("Imagem 1: print.png") é
+  uma parte de texto que o consumidor monta antes da imagem, como a Grand Brasil faz.
+- `content: string` continua válido. Quem só manda texto não muda nada na escrita.
+
+### 2. `aiMessageText` lê o texto de qualquer mensagem
+
+`aiMessageText(message)` devolve o texto de uma mensagem: o próprio `content` quando ele é texto, ou
+as partes de texto unidas por uma linha em branco. As imagens não entram. Serve para quem precisa só
+do texto, como título de conversa, contagem de caracteres ou um bloco de contexto montado por
+interpolação. Sai de `@softize/opus` e de `@softize/opus/ai`.
+
+### 3. O driver Anthropic converte cada parte
+
+- A parte `text` vira o bloco `text`, e a parte `image` vira o bloco `image` com
+  `source: { type: 'base64', media_type, data }`, em `run` e em `runStream`.
+- Uma parte de tipo desconhecido, uma lista de partes vazia, uma parte de texto vazia, uma imagem num
+  formato fora da lista ou uma imagem numa mensagem `assistant` fazem o driver lançar erro antes de
+  qualquer chamada, dizendo qual mensagem e qual parte. Nunca há descarte silencioso.
+- `complete` e `extract` continuam recebendo texto.
+
+### 4. A guarda é do consumidor
+
+O pacote não guarda imagem, não envia bytes a um servidor e não gera endereço. O `StorageAdapter`
+existente não entra nesta decisão. O consumidor escolhe o transporte (a Grand Brasil manda a imagem
+por uma rota própria, antes do turno) e entrega ao `Chat` o estado dos anexos e o endereço de cada
+imagem. Assim, retenção, expiração, governança e dado pessoal ficam com quem guarda.
+
+### 5. Composer e Chat recebem anexos controlados pelo app
+
+- O `Composer` ganha a propriedade `attachments`, e o `Chat`, a `composerAttachments`, com a mesma
+  forma: os anexos pendentes (`id`, nome, estado `uploading`, `ready` ou `failed`, miniatura e motivo
+  da falha), `onAddFiles`, `onRemove`, o limite por mensagem (padrão 4), os formatos aceitos
+  (`readonly AiImageMediaType[]`, padrão PNG, JPEG e WebP, sem curinga: um formato que a mensagem
+  não leva não pode ser aceito na faixa) e `onReject` opcional. Sem essa propriedade, não há faixa, botão, colar nem soltar
+  de arquivos: o composer é o de sempre.
+- Com a propriedade, o composer mostra a faixa de anexos acima do texto, com miniatura, nome, estado
+  e o botão de remover, e o botão **Anexar imagem** na barra. Colar uma imagem no campo, soltá-la
+  sobre a conversa ou escolhê-la pelo botão entregam os arquivos aceitos a `onAddFiles`. A imagem
+  colada recebe um nome gerado ("Imagem colada 1.png"), com um contador da instância que não volta
+  atrás, para que dois anexos da mesma conversa não tenham o mesmo nome. Colar texto continua colando texto, mesmo
+  quando a área de transferência também traz uma imagem, como acontece ao copiar células de uma
+  planilha.
+- A triagem recusa o que não está na lista de tipos e o que passaria do limite. Sem `onReject`, o
+  composer explica a recusa logo acima do campo; com `onReject`, a explicação é do app.
+- Uma região viva anuncia a imagem que fica pronta ou falha, porque a mudança na faixa é só visual.
+  Quando o botão de anexar fica desabilitado por atingir o limite, o foco volta ao campo.
+- O arraste de arquivos que o `Chat` (ou o `Composer` sozinho) consome não sobe para os contêineres
+  do app, que podem ter o próprio soltar, como o envio de arquivos a um acervo.
+- O envio passa com texto ou com pelo menos um anexo pronto. Ele espera os anexos em envio e não
+  passa com um anexo em falha: a pessoa remove o anexo, ou o app tenta de novo, para que nada do que
+  está na faixa fique de fora sem aviso.
+- O modo controlado recebe `onSend(text, attachments)`, com os anexos prontos, quando há
+  `composerAttachments`. Sem eles, a chamada continua `onSend(text)`: um handler que já tinha um
+  segundo parâmetro opcional, com outro significado, não recebe uma lista inesperada. Limpar a faixa
+  depois do envio é do app, que é o dono do estado. Retornar `false` devolve o texto ao campo, e os
+  anexos continuam na faixa.
+- O item `user` do transcript ganha `attachments`, com `id`, nome, tipo, dimensões, estado
+  (`available` ou `expired`) e o endereço da imagem fornecido pelo app. A fala da pessoa mostra as
+  miniaturas acima do texto, com o nome como texto alternativo. O anexo expirado aparece como um
+  cartão com o nome e "Imagem expirada". Uma fala só com imagem não mostra balão de texto vazio.
+- As miniaturas são um componente próprio, e não `![]()` no Markdown da mensagem: a fala da pessoa
+  continua sendo o que ela escreveu. O endereço vem do app, que deve servi-lo pela própria origem ou
+  como `data:`, como a ADR 0050 já recomenda.
+- O modo autogerenciado do `Chat` (`send(messages)`) não ganha anexo. Ele não tem transporte para a
+  imagem, e `ChatMessage` continua só com texto. Se um consumidor precisar, uma nova decisão define
+  como.
+
+### 6. Preparação da imagem no navegador
+
+`prepareImage(file, options)` prepara a imagem antes do envio, com os tetos que o app passa:
+
+- lê só o cabeçalho do arquivo, sem carregá-lo inteiro, para conferir o formato pelos primeiros
+  bytes, não pela extensão nem pelo tipo declarado, e recusa o que não está em `accept` (padrão PNG,
+  JPEG e WebP);
+- recusa PNG e WebP animados, que o modelo leria só pelo primeiro quadro;
+- lê largura e altura do cabeçalho e recusa, antes de decodificar, a imagem acima de `maxPixels`
+  (padrão 40 megapixels): decodificá-la ocuparia centenas de megabytes de memória do navegador;
+- reduz para que o lado maior não passe de `maxEdge` (padrão 1568 px), mantendo a proporção e a
+  orientação gravada pela câmera (EXIF), e codifica de novo sempre, o que descarta metadados como a
+  localização;
+- mantém PNG como PNG quando cabe em `maxBytes` (padrão 3 MB) e converte o resto para JPEG com
+  qualidade 0,85, sobre fundo branco; o que continua acima do teto é recusado;
+- devolve o arquivo preparado com tipo, dimensões e tamanho, ou a recusa com o motivo e uma mensagem
+  em pt-BR para a pessoa.
+
+Os padrões repetem os tetos da ADR 0122 da Grand Brasil, mas o consumidor deve passar os seus: o
+utilitário não decide teto de produto.
+
+## Por que é major
+
+`AiMessage.content` passa de `string` para `string | AiContentPart[]`. Quem lê `content` como texto
+deixa de compilar, e é de propósito: o compilador aponta os consumidores e os drivers que usam o
+conteúdo como texto, em vez de deixar a imagem sumir em silêncio. A migração é ler o texto com
+`aiMessageText(message)`.
+
+O compilador não aponta o texto montado por interpolação (`${message.content}`) nem o que passa por um
+`as`. Com uma lista de partes, esses pontos produziriam "[object Object]" sem erro. Dentro do pacote
+não há nenhum; nos consumidores, a migração precisa procurá-los à parte e cobri-los com teste.
+
+As mudanças de `Composer` e `Chat` preservam o comportamento de quem não usa anexo: sem as
+propriedades novas, a interface é a mesma, e `onSend` continua sendo chamado só com o texto. O tipo de
+`onSend` ganha o segundo parâmetro opcional; um handler que já declarava um segundo parâmetro
+opcional de outro tipo deixa de compilar e precisa ser envolvido, como `(text) => run(text)`.
+
+## Consequências
+
+- Um driver de IA do consumidor que repassava `content` sem conferir passa a receber partes neutras
+  quando o consumidor manda imagem. Cada driver converte as partes, ou recusa com erro claro.
+- O pacote cresce com a faixa de anexos e a preparação da imagem, usadas por um consumidor só por
+  enquanto. Ficam no pacote porque o `Chat` e o `Composer` são dele, e cada consumidor reconstruiria
+  a sua por cima de `composerActions`.
+- A redução no navegador limita tamanho e custo, mas não garante que o provedor não reduza de novo:
+  no nível padrão do Claude, uma imagem retangular de 1568 px ainda passa por redução na API.
+- O tipo e o estado de cada anexo continuam como texto no pacote. A plataforma que adota declara o
+  próprio vocabulário (na Grand Brasil, um `t.dict` no protocolo da IA).
+
+## Alternativas descartadas
+
+- **Campo opcional só para imagens em `AiMessage`.** Não quebraria ninguém, mas um driver que não o
+  conhece descartaria a imagem sem aviso, e o compilador não apontaria nada.
+- **Partes no formato da Anthropic.** Funcionaria só com esse driver. Os demais provedores, que a
+  Grand Brasil também usa, receberiam uma forma que não conhecem.
+- **Nome na parte de imagem.** A API da Anthropic não tem onde pôr o nome, e o rótulo em texto antes
+  da imagem já permite que a pessoa e o modelo falem de "imagem 2".
+- **O `Composer` envia e guarda a imagem.** Prenderia o pacote a um transporte e a uma guarda que
+  são do consumidor, com retenção e governança próprias.
+- **Anexo no modo autogerenciado.** Exigiria levar os bytes no histórico enviado a `send`, que é o
+  que a Grand Brasil recusou para o corpo do chat. Fica para quando um consumidor trouxer o caso.
+- **Aceitar a imagem animada e mandar só o primeiro quadro.** A pessoa acharia que o modelo viu a
+  animação; recusar com o motivo é mais honesto.
+
+## Verificação
+
+- Teste do driver: uma mensagem com texto e imagem chega ao client falso como bloco `text` e bloco
+  `image` com `source.type: 'base64'`, no `run` e no `runStream`; uma parte desconhecida, uma lista
+  vazia, uma parte de texto vazia, uma imagem num formato fora da lista e uma imagem em mensagem
+  `assistant` lançam erro sem chamar o client.
+- Teste de `aiMessageText` com texto puro e com partes.
+- Testes do `Composer` e do `Chat`: colar, soltar e escolher entregam o arquivo a `onAddFiles`;
+  colar texto continua colando; o envio passa só com imagem pronta e não passa com imagem em envio
+  ou em falha; tipo e limite são recusados com o motivo; o `Chat` mostra as miniaturas e o cartão de
+  imagem expirada, entrega `onSend(text, attachments)` e, sem `composerAttachments` ou no modo
+  autogerenciado, não mostra a faixa; o nome da imagem colada não se repete depois de remover uma;
+  a região viva anuncia pronta e falha; o foco volta ao campo no limite; o soltar consumido não
+  chega ao contêiner do app.
+- Testes de `prepareImage` com canvas simulado e em navegador real: uma imagem de 4000 px sai com
+  lado maior de 1568 px, o PNG que cabe continua PNG, o que passa vira JPEG, e GIF, SVG e imagem
+  animada são recusados com o motivo; as dimensões vêm do cabeçalho de PNG, JPEG e WebP (com e sem
+  perdas e estendido), sem ler o arquivo inteiro, e a imagem acima do teto de pixels é recusada sem
+  decodificar; um JPEG com EXIF de rotação sai em pé.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "25.7.0",
+  "version": "26.0.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/src/ai/drivers/anthropic.ts

@@ -17,6 +17,7 @@ import { declaredJsonSchema } from '../../core/index.ts'
 import type {
   AiAdapter,
   AiCompleteOptions,
+  AiContentPart,
   AiMessage,
   AiRunOptions,
   AiRunResult,
@@ -101,6 +102,50 @@ function defaultToJsonSchema(schema: unknown): unknown {
   return zodToJsonSchema(schema as Parameters<typeof zodToJsonSchema>[0], { $refStrategy: 'none' })
 }
 
+const IMAGE_MEDIA_TYPES: ReadonlySet<string> = new Set(['image/png', 'image/jpeg', 'image/webp'])
+
+/** Converte o conteúdo neutro da mensagem (ADR 0058) para os blocos da API da Anthropic. Uma
+ *  parte desconhecida, uma parte de texto vazia, uma lista vazia, uma imagem fora dos formatos
+ *  aceitos ou uma imagem na fala do assistente lançam erro: nada é descartado em silêncio, e nada
+ *  chega a ser enviado. */
+function toAnthropicContent(message: AiMessage, index: number): unknown {
+  const { content } = message
+  if (typeof content === 'string') return content
+  // A API recusa lista vazia e bloco de texto sem texto; o erro aqui diz qual mensagem é.
+  if (content.length === 0) {
+    throw new Error(`ai/anthropic: mensagem ${index + 1} sem conteúdo (lista de partes vazia).`)
+  }
+  return content.map((part: AiContentPart, partIndex) => {
+    const where = `mensagem ${index + 1}, parte ${partIndex + 1}`
+    if (part.type === 'text') {
+      if (part.text.trim() === '') {
+        throw new Error(`ai/anthropic: parte de texto vazia (${where}).`)
+      }
+      return { type: 'text', text: part.text }
+    }
+    if (part.type === 'image') {
+      if (message.role !== 'user') {
+        throw new Error(`ai/anthropic: imagem só pode ir numa mensagem 'user' (${where}).`)
+      }
+      if (!IMAGE_MEDIA_TYPES.has(part.mediaType)) {
+        throw new Error(
+          `ai/anthropic: formato de imagem não aceito: "${String(part.mediaType)}" (${where}). ` +
+            'Use image/png, image/jpeg ou image/webp.',
+        )
+      }
+      return { type: 'image', source: { type: 'base64', media_type: part.mediaType, data: part.data } }
+    }
+    const unknownType = (part as { type?: unknown }).type
+    throw new Error(`ai/anthropic: parte de conteúdo desconhecida: "${String(unknownType)}" (${where}).`)
+  })
+}
+
+/** O histórico de entrada no formato da API, convertido antes da primeira chamada. */
+function toAnthropicMessages(input: string | AiMessage[]): Array<{ role: string; content: unknown }> {
+  if (typeof input === 'string') return [{ role: 'user', content: input }]
+  return input.map((m, i) => ({ role: m.role, content: toAnthropicContent(m, i) }))
+}
+
 interface ContentBlock {
   type: string
   text?: string
@@ -183,6 +228,9 @@ export function anthropicAi(options: AnthropicAiOptions = {}): AiAdapter {
     },
 
     async run(input: string | AiMessage[], opts: AiRunOptions): Promise<AiRunResult> {
+      // Mensagens no formato Anthropic — convertidas antes de tudo (uma parte inválida falha sem
+      // chamar a API) e crescem com tool_use/tool_result a cada passo.
+      const messages = toAnthropicMessages(input)
       const c = await client()
       const tools = withAskTool(
         opts.tools.map((t) => ({
@@ -192,11 +240,6 @@ export function anthropicAi(options: AnthropicAiOptions = {}): AiAdapter {
         })),
         opts,
       )
-      // Mensagens no formato Anthropic — crescem com tool_use/tool_result a cada passo.
-      const messages: Array<{ role: string; content: unknown }> =
-        typeof input === 'string'
-          ? [{ role: 'user', content: input }]
-          : input.map((m) => ({ role: m.role, content: m.content }))
 
       const maxSteps = opts.maxSteps ?? 8
       const calls: Array<{ name: string; input: unknown }> = []
@@ -242,6 +285,7 @@ export function anthropicAi(options: AnthropicAiOptions = {}): AiAdapter {
     },
 
     async *runStream(input: string | AiMessage[], opts: AiRunOptions): AsyncIterable<ChatEvent> {
+      const messages = toAnthropicMessages(input)
       const c = await client()
       const tools = withAskTool(
         opts.tools.map((t) => ({
@@ -251,10 +295,6 @@ export function anthropicAi(options: AnthropicAiOptions = {}): AiAdapter {
         })),
         opts,
       )
-      const messages: Array<{ role: string; content: unknown }> =
-        typeof input === 'string'
-          ? [{ role: 'user', content: input }]
-          : input.map((m) => ({ role: m.role, content: m.content }))
 
       const maxSteps = opts.maxSteps ?? 8
 

package/src/ai/index.ts

@@ -5,11 +5,14 @@
  * (texto → objeto VALIDADO por um `Schema` do protocolo — o mesmo tipo de schema
  * das actions vira o contrato da resposta do modelo). Driver em `ai/anthropic`.
  * A superfície é a mínima de backoffice e cresce por reincidência — não por
- * especulação (streaming, chat multi-turn e tools livres entram quando um caso
- * real cobrar).
+ * especulação. Streaming, chat multi-turn e mensagem com imagem (ADR 0058) já
+ * entraram assim; o resto espera um caso real.
  */
 
 export type { AiAdapter, AiCompleteOptions } from '../core/index.ts'
+// Mensagem com texto e imagem (ADR 0058): o tipo neutro de conteúdo e a leitura só do texto.
+export type { AiContentPart, AiImageMediaType, AiMessage } from '../core/index.ts'
+export { aiMessageText } from '../core/index.ts'
 // Elicitação — perguntar à pessoa no meio do turno (round-trip via `AiRunOptions.onAsk`).
 // O contrato (tipos) mora no core; aqui saem o nome reservado, o schema/descrição da tool e
 // o formatador. É o ponto de consistência pra qualquer consumidor (chat, copilot, MCP externo).

package/src/core/ai-message.ts

@@ -0,0 +1,20 @@
+import type { AiMessage } from './types.ts'
+
+/** Separa as partes de texto de uma mensagem na leitura: cada parte continua um parágrafo. */
+const TEXT_PART_SEPARATOR = '\n\n'
+
+/**
+ * O texto de uma mensagem da IA (ADR 0058): o próprio `content` quando ele é texto, ou as partes
+ * de texto unidas por uma linha em branco. As imagens não entram.
+ *
+ * Use onde só o texto importa — título de conversa, contagem de caracteres, bloco de contexto
+ * montado por interpolação. Interpolar `content` direto produz "[object Object]" quando a
+ * mensagem tem partes, e o compilador não aponta esse uso.
+ */
+export function aiMessageText(message: Pick<AiMessage, 'content'>): string {
+  const { content } = message
+  if (typeof content === 'string') return content
+  return content
+    .flatMap((part) => (part.type === 'text' ? [part.text] : []))
+    .join(TEXT_PART_SEPARATOR)
+}

package/src/core/index.ts

@@ -113,6 +113,8 @@ export type {
   AiCompleteOptions,
   AiTool,
   AiMessage,
+  AiContentPart,
+  AiImageMediaType,
   AiRunOptions,
   AiRunResult,
   BoundAi,
@@ -243,6 +245,9 @@ export type {
 } from './runtime.ts'
 export { countReturnedRecords, hasInvalidEffect, resolveActionEffect } from './action-nature.ts'
 
+// — Mensagem da IA (ADR 0058) ———————————————————————————————————————————————————
+export { aiMessageText } from './ai-message.ts'
+
 // — Assistente do recurso (ADR 0053) ————————————————————————————————————————————
 export {
   ASSISTANT_CONTEXT_DEFAULT_CHARS,

package/src/core/types.ts

@@ -1383,10 +1383,33 @@ export interface AiTool {
   }
 }
 
-/** Turno de conversa (histórico multi-turn do chat). */
+/** Formatos de imagem que a mensagem aceita: os três que os provedores conhecidos leem (ADR 0058). */
+export type AiImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp'
+
+/**
+ * Parte de conteúdo de uma mensagem, sem a forma de nenhum provedor (ADR 0058). Cada driver
+ * converte as partes para o formato da sua API e recusa com erro o que não conhece.
+ *
+ * A imagem não leva nome: o rótulo que a pessoa e o modelo usam ("Imagem 1: print.png") é uma
+ * parte de texto que o consumidor monta antes dela.
+ */
+export type AiContentPart =
+  | { type: 'text'; text: string }
+  | {
+      type: 'image'
+      mediaType: AiImageMediaType
+      /** Bytes da imagem em base64, sem o prefixo `data:`. */
+      data: string
+    }
+
+/**
+ * Turno de conversa (histórico multi-turn do chat). `content` é texto ou uma lista de partes
+ * com texto e imagem (ADR 0058). Para ler só o texto, use `aiMessageText(message)`: interpolar
+ * `content` direto num template produz "[object Object]" quando a mensagem tem partes.
+ */
 export interface AiMessage {
   role: 'user' | 'assistant'
-  content: string
+  content: string | AiContentPart[]
 }
 
 /** Uma opção de resposta de uma pergunta de esclarecimento (`ask_user`). */