MeatSpace

MeatSpace

Serviço com intervenção humana para agentes de IA. Quando um agente enfrenta uma decisão subjetiva, de alto risco ou ambígua, o MeatSpace a encaminha para um humano que escolhe uma entre 2 a 4 opções e retorna um resultado estruturado.

Disponível em meatspace.run

O que faz

Um agente envia um título, conteúdo opcional (texto, markdown, HTML ou imagem) e 2 a 4 escolhas rotuladas. Um revisor humano vê a solicitação, escolhe uma, e a API retorna o id e o label selecionados. O agente aguarda via long-poll ou webhook.

Casos de uso típicos:

• Portões de aprovação antes de ações destrutivas ou irreversíveis (deploys, exclusões, pagamentos).
• Desempates subjetivos quando o modelo está abaixo do seu limite de confiança.
• Decisões de bom senso — opções de texto, preferências de design, empates em rankings.
• Escalonamento quando um agente esgotou as verificações determinísticas.

Não use quando a tarefa for determinística, automaticamente verificável ou de baixo risco e facilmente reversível.

Três métodos de integração

Método	Endpoint	Melhor para
API REST	POST /api/requests	Qualquer cliente HTTP, frameworks de agentes personalizados, servidor a servidor.
MCP	POST /api/mcp (HTTP Streamable)	Claude, Claude Code, clientes compatíveis com MCP.
SDK para navegador	/sdk/meatspace.js	Agentes executados em uma aba do navegador.

Todos os três usam a mesma API de suporte e aceitam o mesmo token Bearer.

Fluxo de autoatendimento sem configuração

Um novo agente pode se integrar totalmente em três chamadas — sem página de cadastro, sem fila de aprovação, sem humano no loop de configuração:

1. POST /api/keys com {"name": "your-agent", "email": "owner@example.com"} → retorna uma chave de API instantaneamente. Limitado a 5 chaves por e-mail.
2. POST /api/requests com o token Bearer, seu título e as escolhas → cria a solicitação de revisão.
3. GET /api/requests/{id}/wait → bloqueia até o humano responder, ou expira e retorna pending com um review_url e um poll_url.

O mesmo fluxo está disponível via MCP: initialize → tools/list → provision_api_key → ask_human. As ferramentas provision_api_key e get_service_status não exigem autenticação, então um cliente MCP novo pode conectar sem credenciais e se autoconfigurar.

Início rápido com REST

Provisione uma chave:

curl -X POST https://meatspace.run/api/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "email": "you@example.com"}'

A resposta inclui api_key — mostrado uma única vez, salve-o. Todas as chamadas subsequentes usam Authorization: Bearer <token>.

Crie uma solicitação:

curl -X POST https://meatspace.run/api/requests \
  -H "Authorization: Bearer $MEATSPACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "my-agent",
    "title": "Ship v2.0 to production?",
    "content": "All tests pass. Staging looks good. 2 minor lint warnings.",
    "choices": [
      { "id": "ship", "label": "Ship it" },
      { "id": "wait", "label": "Wait for next cycle" }
    ],
    "confidence": 0.7,
    "consequence_of_wrong_choice": "Premature ship affects ~50k users"
  }'

Resposta:

{
  "success": true,
  "data": {
    "id": "uuid",
    "status": "pending",
    "review_url": "https://meatspace.run/review/uuid?token=opaque-review-token",
    "poll_url": "/api/requests/uuid",
    "expires_at": "2026-04-23T19:00:00.000Z"
  }
}

Long-poll pelo resultado:

curl https://meatspace.run/api/requests/{id}/wait?timeout=25000 \
  -H "Authorization: Bearer $MEATSPACE_API_KEY"

Retorna { status: "completed", selected, selected_label, responded_at } quando o humano responde, ou 202 se ainda estiver pendente.

Campos opcionais em POST /api/requests: content_type (padrão text, markdown, html, image), decision_reason, confidence (0–1), consequence_of_wrong_choice, recommended_option, callback_url (deve ser HTTPS e com host na lista de permissões), metadata (repassado ao webhook), run_id, trace_id, timeout_seconds (padrão 3600, máximo 86400).

MCP

O MeatSpace implementa MCP sobre HTTP Streamable em https://meatspace.run/api/mcp. O servidor expõe três ferramentas:

• get_service_status — disponibilidade e orientação de escalonamento. Sem autenticação.
• provision_api_key — emite um token Bearer. Sem autenticação, com limite de taxa.
• ask_human — envia uma decisão. Requer autenticação Bearer.

Configuração do Claude Code:

{
  "mcpServers": {
    "meatspace": {
      "type": "url",
      "url": "https://meatspace.run/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

ask_human faz long-poll por até 20 segundos. Se o humano não responder até lá, a ferramenta retorna status: "pending" com um review_url (para o humano) e um poll_url (para o agente).

SDK para navegador

Para agentes executados em contextos de navegador:

<script type="module">
  import { MeatSpace } from 'https://meatspace.run/sdk/meatspace.js';

  const ms = new MeatSpace();
  await ms.getKey({ name: 'browser-agent', email: 'agent@example.com' });

  const result = await ms.ask({
    agentName: 'browser-agent',
    title: 'Which option?',
    choices: [
      { id: 'a', label: 'A' },
      { id: 'b', label: 'B' },
    ],
  });
  console.log(result.selected);
</script>

Métodos: getKey(), createRequest(), pollResult(), waitForResult(), ask() (criar + aguardar).

Webhooks

Se callback_url estiver definido na solicitação, o MeatSpace envia via POST o resultado quando o humano responde:

{
  "event": "request.completed",
  "request_id": "uuid",
  "selected": "ship",
  "selected_label": "Ship it",
  "responded_at": "2026-04-23T18:10:00.000Z",
  "metadata": {}
}

callback_url deve ser https:// e o nome do host deve estar explicitamente na lista de permissões do operador. Se nenhuma lista de permissões estiver configurada, a criação da solicitação rejeita URLs de callback. Cada entrega é assinada com os cabeçalhos X-HITL-Timestamp e X-HITL-Signature.

Endpoints de descoberta

Caminho	Formato	Finalidade
/.well-known/mcp.json	JSON	Manifesto do servidor MCP
/.well-known/agent.json	JSON	A2A Agent Card
/api/openapi	JSON	Especificação OpenAPI 3.1
/api/mcp (GET)	JSON	Informações do servidor MCP, sem autenticação
/api/status	JSON	Verificação de saúde + orientação para agentes
/sdk/meatspace.js	JavaScript	SDK para navegador
/llms.txt	Texto	Resumo legível por LLM
/llms-full.txt	Texto	Documentação completa da API
/agents.md	Markdown	Guia completo de integração
/sitemap.xml	XML	Sitemap
/robots.txt	Texto	Diretrizes para crawlers + ponteiros de descoberta

Erros

Todos os erros retornam:

{
  "success": false,
  "error": "Human-readable message",
  "code": "machine_readable_code"
}

Códigos comuns: agent_name_required, invalid_choice_count, content_too_large, callback_url_not_allowed, request_create_failed.

Desenvolvimento local

Este repositório é um aplicativo Next.js 14 implantado no Cloudflare Pages.

npm install
npm run dev          # local dev at http://localhost:3000
npm run test         # integration tests
npm run build:cf     # build for Cloudflare Pages
npm run deploy:cf    # build and deploy

O Supabase é o sistema de registro para chaves e solicitações; o Resend cuida do e-mail transacional.

Licença

MIT