grahama1970/ask

O que ask faz?

Pare Primeiro

Se o usuário mencionar $ask, /ask, um modo ask, oráculo, revisão profunda, revisão paralela, mesa redonda, debate, revisão de lacunas CAE ou DAG ask, leia este arquivo inteiro antes de agir. Em seguida, use o ponto de entrada real do runtime, a menos que o usuário peça explicitamente um fallback ou o runtime esteja indisponível e esse fallback seja relatado.

Não substitua spawn_agent, uma chamada de modelo simples, uma pesquisa web simples, um resumo manual ou uma revisão inventada por $ask.

Ponto de Entrada do Runtime

Execute comandos a partir deste diretório. A sintaxe de skill-comando do Pi, como /skill:ask webgpt Quanto é 2 + 2?, é um atalho de primeira classe: o manipulador de navegador principal (webgpt, webclaude, webkimi, webgemini ou webgrok) roteia para um DAG de manipulador de navegador single-call do Tau com --execute --json. As referências inline de skill do Pi, como $ask webgpt Quanto é 2 + 2? e a grafia em linguagem natural com espaços $ask web gpt Quanto é 2 + 2? devem ser tratadas da mesma forma (web gpt normaliza para webgpt). Este é apenas um atalho de compatibilidade para usuários Pi; não deve usar o caminho removido do oráculo direto WebGPT.

./run.sh tau-dag "<requisicao>" mapeia para o subcomando tau-dag run do Typer internamente. ./run.sh team-plan "<requisicao>" --team <predefinido> renderiza um plano multiagente baseado em papéis e uma prévia do DAG Tau congelado; a execução requer --execute --live explícito (veja README "Team Orchestration").

cd skills/ask
./run.sh --help
./run.sh webgpt Quanto é 2 + 2?
./run.sh webgpt --compile-only Quanto é 2 + 2?
./run.sh ask --help
./run.sh tau-dag run --help

Toda execução não trivial deve preservar os artefatos do runtime. O conjunto de artefatos padrão é:

• <ask_id>.request.json
• <ask_id>.status.json
• <ask_id>.events.jsonl
• saídas específicas do modo, como review.md, review.json, manifestos DAG ou evidências do navegador

Os artefatos do runtime são padronizados para .ask_artifacts/runs/<ask_id> ou o --run-output-root fornecido. Para execuções longas, ativas ou geradas, prefira uma raiz com suporte a armazenamento como /mnt/storage12tb/skills/ask/outputs/.... Não commit artefatos ask gerados.

Toda chamada de manipulador executada (sucesso ou falha) é registrada na coleção ask_call_log em $memory no ponto de verificação de execução, com manipulador, status, failure_code e controlled_tab_id/URL da conversa quando presente, mais o método comprovado da última chamada bem-sucedida (seleção de raciocínio, vinculação de aba, modo de ciclo de vida, comando de despacho com segredos ocultos). Os IDs de modelo são validados em relação ao catálogo SciLLM ativo em tempo de compilação (invalid_scillm_model_id BLOQUEADO com alternativas válidas mais próximas); um assento de navegador com 3+ falhas consecutivas registradas é sinalizado como conhecidamente ruim antes do despacho com seus códigos de falha. Verifique um assento antes de confiar nele: python3 skills/ask/scripts/ask_call_history.py --handler webgemini imprime a última chamada bem-sucedida e falhas recentes; adicione --recommend para o método comprovado exato a ser reutilizado. Um manipulador sem sucesso registrado é um palpite cego — compile apenas ou teste primeiro de forma barata. Execuções históricas podem ser retroalimentadas: python3 skills/ask/scripts/backfill_call_log.py [diretorio-raiz-das-saidas] ingere todos os recibos de nó em disco de forma idempotente (chave _key determinística por execução+nó). O JSON de resultado de toda execução EXECUTADA (e execution-status.json) também carrega handler_last_success: por assento, o último método bem-sucedido da memória (URL da conversa, aba, ciclo de vida/layout), falhas consecutivas atuais e códigos de falha a serem evitados — retornados no contexto para que o agente do projeto nunca precise de uma consulta de histórico separada após consumir uma execução.

Referências Aprofundadas (leia sob demanda)

Antes de fazer isso	Leia
team-plan com um arquivo de plano; status --run --projection	references/plans-and-status.md
Alvo explícito de subagente nativo do Pi	references/pi-subagents.md
Transformar saída ask (one-shot/mesa redonda/competir/sala limpa) em pistas de subagente	references/lane-handoff.md
herdr list/who/send para o painel de outro agente	references/herdr.md
Escolher entre one-shot vs mesa redonda vs competir; seletores de modelo/esforço	references/modes.md
Auditorias de painel, lista de assentos, assentos com limite de taxa, política webclaude	references/seats-and-audits.md
Executar/supervisionar qualquer execução ativa (monitoramento, janelas, matriz de payload, desbloqueio, deriva)	references/operations.md
Qualquer falha de execução	references/diagnosis.md
Compilar/executar qualquer DAG multi-assento (mesa redonda/competir/criador-revisor)	references/workflows.md
Qualquer execução de manipulador de navegador	references/browser.md

Quatro Tipos de Alvo

/ask aborda quatro tipos de alvo pares. Eles diferem no transporte, não na importância:

Alvo	Exemplo	Proprietário do transporte
Sessão Herdr — um agente ativo em um painel	memory, w11:p13	$monitor-herdr via herdr pane run
Chamada de modelo — manipulador de API/modelo	gpt-5.5-high, Codex-opus-5-high, deepseek-ai/DeepSeek-V3.2-TEE	$tau (SciLLM é interno ao Tau)
Modelo web — revisor com suporte a navegador (aba de chat, NÃO o modelo agêntico; veja o aviso webclaude abaixo)	webgpt, webclaude, webkimi	$surf + $browser-oracle
Subagente nativo do Pi — consultor/trabalhador filho local do Pi	pi reviewer, subagent general-purpose, local coder	pi-subagents ferramenta nativa subagent

Um agente de projeto não deve se importar qual lado é navegador, modelo, sessão Herdr ou subagente nativo do Pi, além de nomear o alvo.

Guia Rápido para Agentes de Projeto

Comece aqui quando o usuário solicitar uma única chamada de modelo, mesa redonda, competição ou loop criador-revisor. Use uma destas formas; não invente um caminho de orquestração personalizado.

Intenção do usuário	Forma do comando
Um manipulador responde	./run.sh tau-dag "<tarefa>" --repo <repo> --target <target> --immutable-goal "<meta>" --handler <handler-ou-modelo> --execute --json
Mesa redonda	./run.sh tau-dag "<tarefa compartilhada>" --repo <repo> --target <target> --immutable-goal "<meta>" --dag-template roundtable --handler <a> --handler <b> --topology concurrent --execute --json
Competição	./run.sh compete "<tarefa isolada>" --repo <repo> --target <target> --immutable-goal "<meta>" --handler <a> --handler <b> --criterion <criterio> --execute --json
One-shot (respostas por assento, sem consenso)	./run.sh one-shot "<pergunta>" --handler <a> --handler <b> --handler <c> — N pistas independentes de chamada única são executadas concorrentemente; cada uma retorna sua própria resposta vinculada a nonce ou um bloqueador nomeado. Respostas parciais são DEGRADADO-mas-utilizável (exit 0 em ou acima de --min-answered); a recusa de quorum de uma mesa redonda nunca se aplica aqui.
Subagente nativo do Pi de dentro do Pi	subagent({ action: "list" }), depois subagent({ agent: "<agente>", task: "<tarefa>" }) ou um desdobramento workflowScript. Isso é apenas para alvos explícitos pi/subagent/local reviewer; não é um substituto para manipuladores Tau/navegador.
Criador depois revisor	./run.sh tau-dag "<tarefa do criador e depois veredito do revisor>" --repo <repo> --target <target> --immutable-goal "<meta>" --dag-template creator-reviewer --handler <criador> --handler <revisor> --topology sequential --execute --json
Diagnosticar/consertar/fechar issues do GitHub	./run.sh fix-issues --repo <dono/nome> --issue <N> [--issue <M>] [--handler gpt-5.5] [--execute] — coleta cada issue via gh, diagnostica através de um manipulador one-shot ativo em JSON estruturado de causa/correção com a portão da escada do depurador (needs_debugger recomenda $debugger apenas quando a transição com falha é o estado do runtime em processo que nenhum artefato explica), e é fail-closed: dry-run por padrão; --execute fecha um issue SOMENTE após seu comando de verificação nomeado (tipicamente um fixture $agentic-evals) realmente passar. Sem verificação → blocked; verificação falhada → verify-failed, issue permanece aberto. Recibos por issue em outputs/fix-issues/. Portão: fixtures/fix_issues.json.

Manipuladores são pares mesmo quando seus transportes diferem. Manipuladores de navegador (webgpt, webclaude, webkimi, webgemini, webgrok) são executados através de $surf e $browser-oracle. Manipuladores de API/modelo como gpt-5.5-high, gpt-5.5-xhigh, Codex-opus-5-high ou chutes deepseek-ai/DeepSeek-V3.2-TEE são roteados pelo Tau. Agentes de projeto não devem se importar qual lado é navegador ou API, além de nomear o manipulador.

Manipuladores são pares, sejam suportados por navegador (webgpt, webclaude, webkimi, webgemini, webgrok via $surf/$browser-oracle) ou suportados por API (gpt-5.5-high, claude-opus-5-high, chutes <provedor/modelo> via Tau). Antes de executar qualquer DAG multi-assento: compile primeiro (omitir --execute), mostre ao humano o gráfico ASCII impresso e execute apenas após confirmação. Exemplos completos de modo e regras de seletor: references/modes.md. Protocolos completos e tabelas fail-closed: references/workflows.md.

Itens Inegociáveis para Toda Execução

• Uma meta imutável explícita (--immutable-goal ou uma linha Immutable goal: rotulada) é necessária para mesa redonda, criador-revisor e competir; meta ausente falha na verificação prévia com NEEDS_INTERVIEW antes que qualquer manipulador seja contatado.
• Mesas redondas são SEMPRE --topology concurrent com um pacote idêntico para cada assento. Candidatos em competição são isolados e nunca se veem.
• DAGs executados devem ser monitorados até um veredito terminal através dos artefatos de stream JSON da execução (events.jsonl, dag-progress.json, recibos de nó, execution-status.json); não inicie e abandone.
• PASS é evidência de revisor/modelo apenas; o fechamento local requer prova local determinística. DEGRADED/NEEDS_ATTENTION/limites de taxa são específicos da pista: mantenha assentos utilizáveis, siga o pacote de recuperação da pista com falha.
• Completions de API não streaming devem passar na admissão tipada com finish_reason=stop antes que seu texto possa contar como evidência. Completions truncados, filtrados, sem finish_reason ou malformados emitem scillm_response_incomplete; retenha bytes brutos e erros de validação de response.meta.json. Não repare texto de veredito parcial ou tente novamente automaticamente. Casos retidos: completion-admission-rejects-truncation (replay capturado) e completion-admission-live-positive (leitura real do provedor).
• Falhas não são silenciosas: cada pista com falha expõe failure_code, um pacote de recuperação e instrução next_command/ticket. Em caso de falha, leia references/diagnosis.md e despache no recibo proprietário antes de teorizar.
• Roteamento direto do oráculo WebGPT ($ask chatgpt, --oracle-backend webgpt, --webgpt-*) falha fechado; manipuladores de navegador Tau permanecem suportados.
• Continuidade de acompanhamento: o recibo de nó / response.meta.json de cada pista de navegador deve carregar controlled_tab_id e a URL da conversa; um tab id nulo é uma entrega com falha. Quando o humano puder fazer perguntas esclarecedoras ou de acompanhamento, execute com --browser-tab-lifecycle fresh-keep (ou reuse-bound) — o padrão auto/fresh-temporary FECHA a janela após a execução, matando a conversa. Após a execução, relate o tab id + URL da conversa e vincule-os (skills/browser-oracle/run.sh bind <projeto> --backend <b> --tab-id <id> --url <url> --manual) para que o acompanhamento tenha como alvo a mesma sessão.
• Portão de visibilidade da aba (observado em 2026-09-15, webgemini): alguns provedores (Gemini confirmado) adiam o envio do composer enquanto a aba é um documento oculto — em uma janela compartilhada, apenas uma aba pode estar em primeiro plano, então N-1 de N pistas concorrentes estão sempre ocultas e travam como prompt_too_large_or_stalled ("O prompt permaneceu no composer após o envio"). Pistas de navegador concorrentes, portanto, padrão para janelas isoladas (uma janela por assento, colocada na área de trabalho do revisor) para que toda aba de pista seja um documento visível; --window-layout shared é opt-in. Um composer já digitado e travado é recuperável: skills/surf/run.sh tab.switch <id> torna a aba visível e o envio na fila é despachado. Verifique document.visibilityState antes de reduzir prompts para esta classe de falha. O método de trabalho verificado por assento é armazenado em $memory (chave ask_call_log ask:method:webgemini; veja ask_call_history.py --handler webgemini --recommend).
• webclaude é uma aba de chat do claude.ai, apenas para teste — NÃO é Claude agêntico. Prefira claude-fable-low, depois claude-opus-4-8-high (veja references/seats-and-audits.md).

Roteador de Modo

Use o modo mais restrito que corresponda à solicitação do usuário.

Solicitação	Padrão de runtime	Detalhes necessários
Pergunta com suporte de memória	./run.sh ask "<pergunta>" --json	Inclua o escopo quando relevante.
Resposta de oráculo	./run.sh ask "<pergunta>" --oracle ... --json	Escolha backend/modelo/persona explicitamente quando solicitado.
Atalho de manipulador de navegador Pi	./run.sh webgpt Quanto é 2 + 2? de /skill:ask webgpt Quanto é 2 + 2?	Reescreve para Tau single-call com --handler webgpt --execute --json; use --compile-only para emitir o DAG sem transporte de navegador ativo.
Único manipulador nomeado	./run.sh tau-dag "<requisicao>" --handler <handler-ou-modelo> --json	Manipuladores de navegador usam $surf; manipuladores não navegador são nomes de modelo $scillm roteados pelo Tau. Adicione --execute para transporte ativo.
Alvo de subagente nativo do Pi	Ferramenta subagent nativa do Pi, após subagent({ action: "list" })	Apenas quando executando dentro do Pi e o usuário nomeia explicitamente pi, subagent, pi-subagent, local reviewer ou local coder. Solicitações de navegador/modelo/Tau Ask não usam esta rota.
Mesa redonda multi-manipulador	./run.sh tau-dag "<requisicao>" --handler webclaude --handler gpt-5.5 ... --topology concurrent --execute --json	Mesa redonda é prompt-para-Tau-DAG. Manipuladores de navegador recebem uma janela nova de propriedade do Ask por padrão. Preserve browser-tab-lifecycle.json, dag.json, especificações de comando, recibos de manipulador e recibos de junção.
Competir / bakeoff	./run.sh compete "<tarefa>" --handler webgpt --handler webclaude --handler gpt-5.5-high --criterion deterministic-proof --execute --json	Candidatos isolados, mais scorecard de competição e solicitação de continuação do vencedor. Manipuladores de navegador/API são pares. O agente do projeto deve verificar localmente os recursos antes da promoção.
Loop criador-revisor	`./run.sh t

...

[truncado para tradução]