file-ipc - SKILL.md Agent Skill

name: file-ipc description: > Sistema de comunicação entre processos via filesystem (IPC file-based), inspirado pelo simulation_ipc.py do MiroFish. Permite que agentes OpenCode se comuniquem com ferramentas externas (MCPs, scripts, subprocessos) de forma assíncrona, sem depender de message brokers (Redis, RabbitMQ). Use quando precisar de comunicação simples e confiável entre processos, especialmente em cenários onde MCPs síncronos não são adequados. license: MIT compatibility: opencode allowed-tools: Read, Write, Glob, Bash metadata: author: Reversa Engine (padrão MiroFish) version: "1.0.0" domain: infrastructure triggers: ipc, communication, async communication, file-based ipc role: infrastructure scope: communication output-format: json related-skills: agent-smith, devops-engineer inspired-by: MiroFish simulation_ipc.py (protocolo de comunicação file-based)

File IPC — Comunicação entre Processos via Filesystem

Inspirado pelo simulation_ipc.py do MiroFish, que implementa comunicação assíncrona entre o servidor Flask e os subprocessos de simulação (Twitter + Reddit) usando apenas arquivos JSON em disco.

Arquitetura (Padrão MiroFish)

┌──────────────┐     Commands/     ┌──────────────────┐
│              │ ─────────────────►│                  │
│   Cliente    │   command_001.json │   Servidor       │
│   (emissor)  │   command_002.json │   (processador)  │
│              │◄───────────────── │                  │
└──────────────┘     Responses/    └──────────────────┘
                     response_001.json
                     response_002.json

Quando Usar

Cenário	Alternativa	File IPC
MCP síncrono demora	Aumentar timeout	Usar File IPC async
MCP não disponível	Esperar	Usar script autônomo via File IPC
Teste/desenvolvimento	Setup complexo	File IPC zero-config
Pipeline multi-etapas	Orquestrador caro	File IPC simples

Protocolo

Formato do Comando

{
  "id": "cmd-uuid",
  "type": "analyze_file | search_pattern | run_query | custom",
  "args": {
    "target": "path/to/file",
    "params": {}
  },
  "timestamp": "2026-05-17T00:00:00Z",
  "ttl": 300
}

Formato da Resposta

{
  "id": "cmd-uuid",
  "status": "completed | failed | running",
  "result": {},
  "error": null,
  "timestamp": "2026-05-17T00:00:10Z",
  "duration_ms": 10000
}

Diretórios

.ipc/
├── commands/          ← Comandos pendentes (cliente escreve)
│   ├── cmd-001.json
│   └── cmd-002.json
├── responses/         ← Respostas (servidor escreve)
│   ├── cmd-001.json
│   └── cmd-002.json
├── archive/           ← Comandos/respostas processados
└── locks/             ← Lock files para evitar race conditions

Workflow

Cliente (quem envia o comando)

Gera UUID para o comando
Escreve JSON em .ipc/commands/{uuid}.json
Polla .ipc/responses/{uuid}.json em intervalos de 200ms
Timeout após TTL configurado (padrão 300s)
Lê resposta e processa

Servidor (quem executa o comando)

Monitora .ipc/commands/ por novos arquivos
Lê comando, executa ação correspondente
Escreve resposta em .ipc/responses/{uuid}.json
Move comando para .ipc/archive/

Comandos Suportados

Tipo	Descrição	Args
`analyze_file`	Analisa arquivo	`target`, `depth`
`search_pattern`	Busca padrão	`pattern`, `path`
`run_query`	Executa SQL	`query`, `params`
`execute_script`	Roda script	`script`, `args`
`ping`	Health check	—

Tratamento de Erros

Timeout: Cliente marca como failed após TTL
Lock: Arquivos .lock previnem leitura concorrente
Stale: Comandos não processados após 1h são arquivados automaticamente
Orphan: Respostas sem comando correspondente são ignoradas

Output

Resultados retornados como JSON e registrados em .ipc/log/.

Regras

MUST DO

Sempre usar UUIDs únicos para comandos
Implementar polling com backoff (200ms → 500ms → 1s)
Respeitar TTL configurado
Limpar comandos/respostas após processamento
Usar lock files para evitar race conditions

MUST NOT DO

Processar comandos sem UUID
Ignorar TTL (comandos podem ficar órfãos)
Escrever diretamente nos diretórios do servidor
Usar File IPC para comunicação intra-sessão (preferir variáveis locais)