| name | create-pi-web-extension |
| description | Como criar/extender extensões web no pi com arquitetura determinística, segurança mínima e testes automatizados (smoke + e2e via pi-test-harness).
|
Criando Extensões Web para Pi (sem acoplamento frágil)
Use este skill quando o usuário quiser:
- expor estado da sessão em HTTP
- criar UI web para acompanhar trabalho do agente
- enviar ações da web para o pi de forma controlada
Princípios
- URL determinística por modo (
local | lan | public)
- Sem depender de domínio externo para UI essencial
- Health endpoint explícito (
/api/health)
- Estado por contrato (
/api/state)
- Ações autenticadas (
POST /api/prompt com token)
- Sem acoplar ao caso colony — colony é apenas um produtor de sinais
Referência first-party no lab
- Extensão:
packages/pi-stack/extensions/web-session-gateway.ts
- Guia:
docs/guides/web-session-gateway.md
- E2E harness:
packages/pi-stack/test/smoke/web-session-gateway-e2e-harness.test.ts
Processo recomendado
1) Definir contrato primeiro
Antes de codar, declarar:
- modos suportados (
local|lan|public)
- endpoints (
health, state, action)
- esquema mínimo de resposta (campos estáveis)
- requisito de autenticação (token/header/query)
2) Implementar mínimo vertical
- comando
/session-web start|status|open|stop
- tool
session_web_status
- backend HTTP mínimo
- UI web mínima (pode ser polling)
3) Testes obrigatórios
- Smoke: funções puras de resolução de host/url/config
- E2E (pi-test-harness):
- sobe servidor local
- valida
health 200
- valida
state sem token = 401
- valida atualização de estado com sinal fake
- valida integração com outra extensão por capability (não por suposição)
4) Só então evoluir UI
Evoluir para SSE/WebSocket, histórico rico, comandos avançados etc.
Checklist de qualidade
Anti-padrões
- Depender de
hosted UI sem fallback local
- Misturar observabilidade web com regra de negócio de colony
- Expor endpoint mutável sem token
- Declarar “deve funcionar” sem e2e automatizado
Snippet de direção para o agente
Use este framing ao delegar implementação:
"Implemente web gateway first-party com contrato estável (/api/health, /api/state, /api/prompt), URL determinística por modo, token auth e e2e em pi-test-harness. Não acople ao fluxo de colony; trate colony como produtor opcional de telemetria."
