dsh-plugin-image

Service Definition de geração de imagem para o DeepSeek Harness.

Este pacote é vocabulário. Ele diz o que é pedir uma imagem e o que é receber uma, e não sabe de onde a imagem vem. Quem sabe é um Service Provider, que é outro pacote.

O que ele expõe

| Símbolo | Papel | |---|---| | ImageService | A classe abstrata montável. Registrada em ctx.image | | IMAGE_SERVICE_NAME | A chave de contexto, para que ninguém repita a literal | | ImageRequest, ImageResult, GeneratedImage | O vocabulário do pedido e do resultado | | ImageModel, ImageParameter | O conjunto consultável de modelos e o que cada um aceita | | ImageFailure, ImageError, imageFailureCode | A união fechada de falhas e sua projeção estável | | findImageService, requireImageService | Descoberta explícita e falha nomeada |

Como um provedor o satisfaz

import { Context } from '@deepseek-ai/cordis'
import { ImageService } from 'dsh-plugin-image'

class MeuProvedor extends ImageService {
  constructor(ctx: Context) { super(ctx) }
  async generate(request, signal) { /* ... */ }
  async models(signal) { /* ... */ }
}

await ctx.plugin(MeuProvedor)

Montar é efeito: o registro vem do construtor de Service do cordis e é desfeito com a fiber dona. Não existe código de limpeza neste pacote.

Obrigações de quem implementa

A classe abstrata não tem como impô-las, então elas estão escritas aqui e são exercitadas pelo provedor falso em test/:

• generate resolve com exatamente count imagens, ou uma quando count está ausente. Quem não consegue honrar a contagem falha; não entrega a menos.
• Não existe sucesso parcial. Um lote em que um membro falhou é uma falha inteira, e images vazio nunca é sucesso — quem produziria zero lança provider-rejected.
• Sinal já abortado falha com cancelled sem contatar o backend.
• Toda falha é ImageError, e quem consome roteia por failure.kind, nunca por texto.

Como se descobre a ausência

ctx.image é undefined quando nenhum provedor está montado. findImageService devolve undefined e não lança; requireImageService lança ImageError com no-provider. Os dois existem porque são dois chamadores diferentes: quem quer checar, e quem já decidiu prosseguir e prefere a falha nomeada a um TypeError.

Por que os peers não são empacotados

@deepseek-ai/cordis, @deepseek-ai/dsh-attachment e @deepseek-ai/dsh-llm entram como peerDependencies com intervalo e como devDependencies pinadas em versão exata. dependencies fica vazio.

O intervalo em peer é o que deixa a instalação hospedeira prover versão mais nova sem recompilar. O pino exato em dev é o que faz o compilador enxergar somente a superfície publicada alvo. Um sem o outro não implementa a regra.

Empacotar uma cópia própria criaria duas classes de serviço para o mesmo contexto, e a falha apareceria como ausência inexplicável de serviço. Ver ADR-0011 do work item.

O que este contrato deliberadamente não expõe

• Nada de HTTP, cabeçalho, URL, base64 ou nome de serviço externo. Base64 é forma de transporte e morre no Provider (ADR-0012).
• Nada de credencial: resolvê-la é responsabilidade do provedor, por operação.
• Nada de anexo. Admitir bytes no store é papel do Consumer, numa fase posterior.
• Nada de streaming, imagem de entrada como referência, ou roteamento explícito por provedor. Todos estão fora do escopo declarado.

mediaType é ImageMediaType do harness — a união fechada image/png, image/jpeg, image/webp, image/gif. Reusá-la torna impossível o contrato prometer um formato que a admissão recusaria, e é por isso que modelos que produzem vetor ficam fora de qualquer allowlist de provedor.

Verificação

pnpm --filter dsh-plugin-image build
pnpm --filter dsh-plugin-image typecheck
pnpm --filter dsh-plugin-image test