[JoaoLuisQuirino]

Fecha #121.

O que muda

Com a box fria, o Copilot atende o canal ele mesmo enquanto a box sobe (canal provisório), emitindo exatamente os frames da box viva, sem sequence. Quando a box fica pronta, ele manda o aviso handover e fecha com 4100 só 15 s depois, como rede de segurança. A box então drena a lista e repete o messageQueued e o stepStart do mesmo prompt, agora com a sequence do log dela. A SDK recebe só o mínimo de protocolo:

1. Opt-in. No modo websocket, o POST /tasks/{id}/channel manda { "standIn": true }; no modo http segue sem corpo e o Copilot segura o pedido até a box subir, como hoje. agentTasks.channel(id, { standIn }) e AgentTaskChannel.provisional?: boolean, lido no expectAgentTaskChannel.

2. Cursor pela identidade do log. Abrir o provisório não pede replay (ele não tem log). Na troca para a box, o cursor fica onde o histórico termina se o boxLog da box é o esperado, vai a 0 se é outro, e o hello ainda zera se o lastSequence dele é menor que o cursor. Provisório para provisório não pede replay.

3. Sair do provisório não fecha o turno. Sem lostTurnFrame na troca para a box, e o provisório que cai sempre pede o canal de novo (menos 4409 e abort), com ou sem turno. Um turno que começou numa box antes de cair no provisório segue a regra do redial comum contra aquela box: a mesma box e thread seguem do cursor; outra fecha o turno como interrompido.

4. Mesmo turno na box. O messageQueued e o stepStart que a box repete para o mesmo clientMessageId e turnId não abrem turno novo nem bolha duplicada. A sessão já fazia isso (o stepStart com turno rodando não abre outro, e a pergunta é deduplicada pelo clientMessageId); o PR prova com teste.

5. Fila repetida na troca. Um messageQueued que repete um item da fila igual ao que a sessão já tem (mesmo texto, posição e queueHeld) não emite queueChange. Visto na dev: a box que assume põe no log a fila segura que o provisório mostrou, e o replay emitia um queueChange idêntico, um evento a mais que a box viva. Teste: "announces a queued message once when the box takes over the queue the stand-in showed".

6. Troca sem buraco (abrir antes de fechar). No aviso handover, a sessão pede /channel, abre o socket da box com a mesma decisão de replay do redial e só então fecha o provisório; até lá tudo segue pelo provisório. O 4100 que vem depois é ignorado; um 4100 no meio da troca não abre um segundo socket; uma troca que ainda encontra o provisório deixa o 4100 fazer o redial.

7. Stop com o socket caído dá erro. Com o canal direto aberto e o socket em redial, o Stop é recusado com erro em vez de ir ao Copilot pelo REST, como cancel e edit já eram. Sem canal direto, o Stop segue pelo REST.

A SDK não tem fila, admissão nem Stop próprios para o boot: isso tudo vem dos frames.

Mudança de comportamento

• No modo websocket o pedido do canal passa a levar corpo { "standIn": true }. Copilot sem o canal provisório ignora o corpo e responde como hoje, então com ele tudo fica igual à 0.3.7 (fixtures session-parity sem mudança).
• Stop com o socket do canal direto em redial passa a dar erro, em vez de ir pelo REST.

Dependência e release

• Depende do PR do copilot com o canal provisório e o aviso handover (mitralab-dev/mitra-copilot#550). Sem ele, nada muda.
• Rebaseada sobre a main com a 0.3.7 (86dfa19). Versão 0.3.8-beta.0 só no package.json, para a réplica pessoal de teste da fila; sem corpus nem current no manifest, que entram quando a fila for para uma release oficial. contracts/ igual ao da main.

Testes

npm test: 763 de 763 (16 arquivos). Em agentChannel.test.ts, bloco do canal provisório com 18 testes:

• turno mostrado pelo provisório segue na box com uma bolha só e um turnStart;
• 4100 sem nada em voo pede o canal de novo;
• cursor: mesmo boxLog pede replay do fim do histórico, outro boxLog pede 0, hello menor que o cursor zera, provisório para provisório não pede replay;
• turno que começou na box, passando pelo provisório: a mesma box segue do cursor, outra fecha o turno como interrompido; turno que a box tomou do provisório e perdeu numa queda fecha como interrompido quando outra box assume, e a mensagem seguinte abre turno próprio;
• paridade lado a lado (box fria com provisório e troca x box viva desde o começo), com os mesmos eventos da sessão, os mesmos itens de history e a mesma queue, fora a sequence que o provisório não tem: (a) enviar, enfileirar dois, editar, cancelar e promover para steer no boot; (b) Stop no boot com a fila segura (queueHeld) e nova mensagem que roda na box. Os frames seguem o contrato do sidecar (mitralab-dev/mitra-sandbox#767): turnId é o id do prompt, o provisório manda activityId e turnSequence nulos e a box os preenche;
• sessão http não pede standIn; módulo manda o corpo só quando pedido;
• troca pelo aviso: a box abre antes de o provisório fechar, sem channelReconnecting; mensagem durante a troca vai pelo provisório e depois pela box; 4100 no meio da troca não abre segundo socket; troca que ainda encontra o provisório deixa o 4100 fazer o redial; Stop com o socket caído dá erro, sem REST.

Contra a main, sem a mudança em agentChannel.ts, 6 desses testes falham (os dois de paridade incluídos). typecheck, lint, format:check, build, check:exports, check:contracts e smoke:package verdes.

🤖 Generated with Claude Code

[JoaoLuisQuirino]

/gandalf

[gandalf-the-grey-bot]

Gandalf, análise 1 · commit 150766f

Pega-rápido: Hoje, o Copilot espera a box iniciar e abrir o canal da task. Esta mudança permite usar um canal provisório durante o boot para aceitar e administrar mensagens enfileiradas.

Insights: O mérito está sustentado: o problema e o usuário afetado estão descritos na issue #121. O fallback atual por /inputs e /events não permite editar ou cancelar itens individuais da fila, então não é equivalente; faltou registrar por que ampliar esse fallback perdeu para o canal provisório.

Forma da implementação: Aprovada com ressalvas. askChannel centraliza a diferença entre socket e HTTP, e a resposta aditiva preserva os consumidores atuais. A política de replay precisa considerar também se o destino é provisório, não só a origem.

Findings

• 🟢 minor src/agentChannel.ts:786-792: na reconexão de box para canal provisório, o fluxo pode continuar até enviar replay com fromSequence: 0, apesar de o contrato da issue dizer que o canal provisório não tem log. Tratar o destino provisório independentemente da origem e testar box → provisório → box. Comentário inline
• 🟢 minor src/agentChannel.test.ts:3144-3151: o teste de Stop não prova a remoção da mensagem da fila: o frame simulado não tem clientMessageId nem turnId. Usar a sequência real do produtor e afirmar que só o item parado saiu. Comentário inline
• 💬 question src/agentChannel.ts:665-668: por que preferir o canal provisório a ampliar /inputs e /events durante o boot? A resposta fecha a comparação de alternativas, mas não é pré-condição de merge. Comentário inline
• 💬 question src/agentChannel.ts:802: o produtor pode devolver provisório enquanto a box anterior está apenas temporariamente indisponível e ainda tem turno/log? Se sim, o turno precisa ser preservado até o canal definitivo; se não, vale testar essa garantia. Comentário inline

Confiança: Alta no comportamento demonstrável pela SDK; a integração com o produtor novo não pôde ser confirmada porque o contrato correspondente não está disponível neste recorte.

Testes e CI: O CI deste SHA terminou verde, com build, compatibilidade Node 18/22 e 729 testes em 16 arquivos. Ainda faltam provas de box → provisório → box, redial com 4409/aborto, recuperação após queda antes de messageQueued e Stop removendo apenas o item correto.

Standards verificados: Discussions #5, #35 e #93; nenhuma divergência relevante identificada no recorte.

Decisão: mergeável. Os achados são minor e as perguntas não são pré-condição; a branch exige o check gandalf/review e resolução das conversas inline.

Aqui o meu check é obrigatório: depois de um push, comente /gandalf para eu revisar o commit novo e liberar o merge.

[JoaoLuisQuirino]

/gandalf

[gandalf-the-grey-bot]

Gandalf, análise 1 · commit 150766f

Pega-rápido

Antes, era preciso esperar a box do agente iniciar para interagir com a fila. O PR adiciona um canal provisório e reaproveita o protocolo de fila existente, para permitir essa interação durante o boot, conforme a issue #121.

Insights

O problema está documentado: o fallback REST aceita mensagens, mas ações de fila exigem o canal direto. Reutilizar o protocolo existente tem valor técnico e evita criar outra API de sessão no Core. O mérito fica duvidoso porque a comparação com outra alternativa não foi registrada: a issue #541 do Copilot descreve fila fria por histórico e comandos, mas não foi verificado por que o stand-in oferece a experiência necessária em vez desse caminho. Qualidade pede os dois ajustes abaixo; não encontrei regressão de autenticação ou isolamento, e o diff não adiciona estado persistente ou varredura que cresça por tenant.

Forma da implementação

Aprovada com ressalvas. Separar HTTP, parser, tipo público e canal direto é coerente. A ressalva é a decisão de replay na transição entre uma box real e um canal provisório; a prova do Stop também não verifica o efeito na fila.

Findings

• major · src/agentChannel.ts:786: na reconexão de uma box real para um canal que responde provisional: true, a decisão de não enviar replay depende de link.provisional, que ainda está false. O fluxo pode enviar replay ao canal provisório, embora src/types.ts declare que ele não tem log e o requisito S6 da issue #121 proíba esse replay. Trate o destino provisório antes da decisão e teste box real → provisório → box real, incluindo a retomada do cursor real.
• major · src/agentChannel.test.ts:3148: a fixture injeta stepFinish interrompido sem clientMessageId ou turnId; assim, o consumidor não localiza o item e finishTurn não o remove. Como o teste não verifica session.queue nem queueChange, pode passar sem provar o contrato de Stop descrito em README.md:113. Use os frames reais do produtor e afirme que o item alvo saiu, que a retirada foi comunicada e que outro item permaneceu na fila.
• question · src/agentChannel.ts:665: qual PR ou issue do Copilot implementa standIn, provisional e /standin, e onde ficará registrada a validação dos frames de admissão, Stop e handoff? O contrato ainda não aparece no controller e DTO atuais do produtor. Isso não impede o merge da SDK, mas a ativação depende de um produtor compatível.
• question · package.json:3: como será coordenada a publicação com o PR fix(agent): sdk-core 0.3.2 com mensagem pendente no close pelo Copilot e provider no providerUsage (#119) #120, que ainda fixa 0.3.2, enquanto este fixa 0.3.3? Registre a ordem de merge/publicação ou a versão acordada, pois o release manual valida a versão do pacote contra o input.

Confiança, comentários e testes

Confiança 8/10: li o diff, o fluxo da máquina de estados, os testes, a issue e o contrato atual do produtor; não localizei o produtor futuro nem seus frames reais. O CI terminou verde no SHA revisado: build, test, compatibility_22, compatibility_18 e pr-convention.

Condição de ativação: habilitar a experiência nos consumidores somente depois que o produtor compatível estiver implantado e os frames de admissão, Stop e handoff forem validados. Registre essa condição no PR do produtor.

Decisão

Não aprovaria até os dois ajustes major serem corrigidos. As perguntas sobre produtor e publicação não são bloqueios de merge. O CI está verde; depois dos ajustes, peça nova análise para validar o commit atualizado.

Sugestões para próximas revisões: comparar a matriz de transições de canal por origem e destino, incluindo box → provisório; e, nos testes de comandos de fila, afirmar estado final e evento de atualização com mais de um item.

Aqui o meu check é obrigatório: depois de um push, comente /gandalf para eu revisar o commit novo e liberar o merge.

[gandalf-the-grey-bot]

Sem achados novos no delta desde a análise 1.

[gandalf-the-grey-bot]

Gandalf, análise 2 · commit 35ca714

Desde a análise 1: os dois pontos major foram corrigidos; seguem abertas duas perguntas: compatibilidade e validação do produtor e coordenação da versão com o PR #120. Nada novo.

Decisão: mergeável por código; CI verde. Para o GitHub liberar o merge, as conversas ainda abertas também precisam ser resolvidas.

Aqui o meu check é obrigatório: depois de um push, comente /gandalf para eu revisar o commit novo e liberar o merge.

[JoaoLuisQuirino]

/gandalf

[JoaoLuisQuirino]

/gandalf

[gandalf-the-grey-bot]

Gandalf, análise 3 · commit b0df785

Desde a análise 2: os dois pontos major anteriores foram corrigidos e as conversas antigas estão resolvidas. Novos: a marca do turno provisório persiste após a box assumir e a versão do pacote não acompanha o manifest do contrato, ambos major.

A integração real ainda não está demonstrada: o produtor mantém frames antigos de admissão, Stop e handoff. Isso não bloqueia por si só o merge desta SDK, mas os consumidores devem esperar um produtor compatível e a validação de integração antes do bump. O CI do SHA revisado terminou verde.

Decisão: não aprovaria até os dois ajustes major serem corrigidos.

Aqui o meu check é obrigatório: depois de um push, comente /gandalf para eu revisar o commit novo e liberar o merge.

[JoaoLuisQuirino]

/gandalf

[gandalf-the-grey-bot]

Sem findings novos nesta rodada; as duas majors da análise anterior foram corrigidas.

[gandalf-the-grey-bot]

Gandalf, análise 4 · commit a9c14a8

Desde a análise 3: 2 pontos corrigidos; nenhum ponto anterior segue aberto; nada novo.

Decisão: mergeável quando o CI terminar verde.

Aqui o meu check é obrigatório: depois de um push, comente /gandalf para eu revisar o commit novo e liberar o merge.

[JoaoLuisQuirino]

/gandalf

[gandalf-the-grey-bot]

Sem achados novos para comentar em linha nesta rodada.

[gandalf-the-grey-bot]

Gandalf, análise 5 · commit 89a31d3

Desde a análise 4: nenhum ponto anterior segue aberto e nenhum finding novo. A implementação principal não teve regressão identificada; pacote, lockfile e corpus estão alinhados em 0.3.4. O CI no SHA revisado terminou verde.

Sugestão documental, fora deste PR: atualizar no body do Copilot #550 as referências à SDK de 0.3.3 para 0.3.4, em especial “Ordem de release”.

Decisão: mergeável; o CI obrigatório está verde.

Aqui o meu check é obrigatório: depois de um push, comente /gandalf para eu revisar o commit novo e liberar o merge.

[JoaoLuisQuirino]

/gandalf

[gandalf-the-grey-bot]

Gandalf, análise 6 · commit 7fe2067

Desde a análise 5: nenhum ponto anterior segue aberto; novo: uma pergunta não bloqueante sobre se queueChange sinaliza mudanças dos metadados públicos (conversa). O CI deste SHA terminou verde: build, compatibilidade Node 18/22 e testes, com 746 testes em 16 arquivos.

Decisão: mergeável quanto ao código. O ruleset exige resolver a conversa inline; CI e gandalf/review são checks obrigatórios.

Aqui o meu check é obrigatório: depois de um push, comente /gandalf para eu revisar o commit novo e liberar o merge.

[JoaoLuisQuirino]

/gandalf

[gandalf-the-grey-bot]

Sem achados novos no delta desde a análise 6.

[gandalf-the-grey-bot]

Gandalf, análise 7 · commit e22be9f

Desde a análise 6: a pergunta sobre a semântica de queueChange foi esclarecida na documentação; nenhum ponto anterior segue aberto; nada novo.

Decisão: mergeável; o CI está verde e não restam conversas de revisão abertas.

Aqui o meu check é obrigatório: depois de um push, comente /gandalf para eu revisar o commit novo e liberar o merge.

[JoaoLuisQuirino]

/gandalf

[gandalf-the-grey-bot]

Gandalf, análise 8 · commit 97a51c0

Desde a análise 7: não encontrei regressão nova no comportamento do canal provisório. O bump reintroduz o desalinhamento entre pacote e corpus, e a descrição ainda cita 0.3.5. Segue aberto 1 major (conversa). O CI está verde no commit revisado.

Decisão: não aprovaria até alinhar a versão publicada e o corpus.

Aqui o meu check é obrigatório: depois de um push, comente /gandalf para eu revisar o commit novo e liberar o merge.

[JoaoLuisQuirino]

/gandalf

[gandalf-the-grey-bot]

Sem achados novos no delta desde a análise 8.

[gandalf-the-grey-bot]

Gandalf, análise 9 · commit c16a5c1

Desde a análise 8: o rebase não alinhou o pacote 0.3.8-beta.0 ao corpus/manifest, e a descrição ainda aponta para 0.3.5; segue aberto 1 major (conversa); nada novo. O CI deste SHA terminou verde.

Decisão: não aprovaria até alinhar o pacote à versão/corpus preparado e atualizar a descrição.

Aqui o meu check é obrigatório: depois de um push, comente /gandalf para eu revisar o commit novo e liberar o merge.

[JoaoLuisQuirino]

/gandalf

[gandalf-the-grey-bot]

Gandalf, análise 10 · commit 18ec944

Desde a análise 9: segue aberto o major de alinhamento entre pacote, manifest/corpus e descrição (conversa); há um novo major porque os testes e as garantias de handover não correspondem ao protocolo do produtor (conversa). O CI deste SHA terminou verde.

Decisão: não aprovaria até corrigir os dois majors.

Aqui o meu check é obrigatório: depois de um push, comente /gandalf para eu revisar o commit novo e liberar o merge.

[JoaoLuisQuirino]

/gandalf

[gandalf-the-grey-bot]

Sem novos findings de linha nesta rodada; os pontos anteriores foram resolvidos.

[gandalf-the-grey-bot]

Gandalf, análise 11 · commit 18ec944

Desde a análise 10: os dois pontos major foram resolvidos: a beta pessoal fica sem corpus/manifest, reservados à release oficial; o produtor do Copilot #550 implementa handover e fecha com 4100 após 15 segundos, com teste de integração. Nenhum finding novo e nenhuma conversa pendente. O CI mais recente deste SHA terminou verde.

Decisão: mergeável para a SDK beta. Ativar os consumidores somente após implantar o produtor compatível (PR #550).

Aqui o meu check é obrigatório: depois de um push, comente /gandalf para eu revisar o commit novo e liberar o merge.

[JoaoLuisQuirino]

/gandalf

[gandalf-the-grey-bot]

major holdForTheBox() inicia o prazo de admissão antes de enviar a mensagem e guarda uma closure na outbox. Se o prazo expirar, a promessa falha, mas a closure continua válida e replayComplete ainda pode executar wire.message(). Assim, a mensagem pode sair depois de o chamador receber falha; se ele reenviar, o efeito pode duplicar. Isso contraria a garantia local de agentSession.ts:1396-1398 e o prazo descrito em agentChannel.ts:25-29. Mantenha a admissão pendente até o envio efetivo e arme o prazo nesse momento, ou invalide/remova a entrada da fila em qualquer falha terminal. Teste uma mensagem retida por mais de 35 segundos e depois replay concluído, provando que não é enviada após a falha.

[gandalf-the-grey-bot]

major O resolve/reject dos comandos da outbox existe apenas dentro da closure. Fechar a sessão durante o handover aborta a conexão e falha as admissões de mensagem, mas não rejeita esse comando; o caminho de reconexão abortado também retorna sem liquidá-lo. Um session.cancel() pendente pode, portanto, ficar sem resolução indefinidamente. O contrato de send em agentChannel.ts:607 e a promessa documentada de cancel() no README exigem que a operação termine com erro quando o canal fecha antes da confirmação. Guarde cada operação como entrada rastreável e rejeite/remova toda a fila no fechamento, aborto ou falha terminal. Acrescente teste de fechamento durante handover com Stop pendente e confirme rejeição e ausência de frames posteriores.

[gandalf-the-grey-bot]

major Quando link.handingOver é verdadeiro, onLost() entra no ramo de reabertura imediata e retorna antes de tratar SUPERSEDED_CLOSE_CODE (4409). Se outro socket substituir este durante replay incompleto, as operações retidas escapam do tratamento terminal previsto. A issue #121, S4 exige rediscagem do provisório, exceto em 4409 e aborto. Trate 4409 antes do ramo de handover, rejeitando admissões e operações da outbox; cubra o caso de box adotada, replay incompleto e fechamento 4409.

[gandalf-the-grey-bot]

minor O SDK envia { type: "handover" }, mas o produtor consultado em mitra-copilot#550, SHA e8877a3, ainda rejeita esse tipo com INVALID_MESSAGE (StandInWebSocketHandler.java:76-88). O merge da beta não ativa consumidores por si só, mas a ativação é incompatível até o produtor aceitar essa resposta. Só adote esta SDK no consumidor depois de implantar o parser compatível e validar a troca, ou inclua esse suporte no produtor antes da ativação.

[gandalf-the-grey-bot]

Gandalf, análise 12 · commit 963e36e (head publicado do PR: 18ec944)

Desde a análise 11: nenhum ponto anterior segue aberto. No SHA auditado, há 3 novos major: a mensagem pode sair depois de a admissão falhar, o Stop pode ficar pendente ao fechar a sessão e o handover ignora o fechamento terminal 4409. Há também um minor de ativação: o produtor consultado ainda rejeita a resposta handover (conversa). A descrição do PR e os bullets de testes ainda contam o protocolo anterior; atualize-os para corresponder ao delta.

Condição de ativação: não adote esta SDK no consumidor até o produtor aceitar a resposta handover e a troca ser validada. O merge da beta, por si só, não ativa o consumidor.

Decisão: não aprovaria o SHA auditado até corrigir os 3 pontos major. O PR ainda aponta para 18ec944; este veredito e os comentários de linha se referem a 963e36e, não ao head publicado atual.

Não encontrei run de CI associado ao SHA auditado; o veredito não considera os testes.

Aqui o meu check é obrigatório: depois de um push, comente /gandalf para eu revisar o commit novo e liberar o merge.