Clarificação profunda — o ClarifyGateway, o T4 human-gate

Por que isto é interessante de portar

A fonte (tools/clarify_gateway.py, 278 LOC) bloqueia uma thread do agente num threading.Event e a resolve a partir do callback de botão / interceptação de texto da plataforma, com um timeout para que um usuário silencioso nunca prenda o guarda de agente-rodando para sempre. O Node não tem thread bloqueante: o event loop é único. O equivalente fiel é, portanto, uma Promise retornada (o que o chamador aguarda) + um Map<id, pending> que deixa um callback da plataforma resolver por id + um setTimeout que garante que nunca trava.

O estado vive na instância (espelhando o dict module-level _entries do Python) para que um adaptador de plataforma possa resolver por id sem uma referência de volta a quem perguntou. Em termos do Alembic, este é o caminho de dados do T4 human-gate (ADR-0005): a pausa fail-closed que por padrão faz T4-park.

const parsed = clarifyQuestionSchema.safeParse(question);
if (!parsed.success) return err(new Error(`Invalid clarify question: …`)); // falha-fechado SÍNCRONO
const id = this.mintId();
return new Promise((resolvePromise) => {
  const timer = setTimeout(() => {
    this.entries.delete(id);                       // descarta a entrada…
    resolvePromise(err(new Error('clarify timed out'))); // …nunca trava
  }, timeoutMs);
  timer.unref?.();                                  // deixa o processo sair enquanto pendente
  const settle = (result) => { clearTimeout(timer); this.entries.delete(id); resolvePromise(result); };
  this.entries.set(id, { id, question: valid, settle, timer });
});

Dois detalhes que importam

(1) Uma pergunta inválida falha fechado de forma síncrona — antes de qualquer entrada ser registrada, então uma pergunta malformada nunca deixa um pedido pendente pendurado (teste: "returns err for a >MAX_CHOICES question and registers nothing"). (2) timer.unref() deixa o processo Node sair mesmo com um clarify pendente — um prompt humano travado não mantém o runtime vivo para sempre.

const CHOICE_LABEL_KEYS = ['label', 'description', 'text', 'title'] as const; // name/value FORA
// string ⇒ trim; dict ⇒ 1ª chave canônica não vazia; senão ⇒ '' (descartado)
const flattenChoice = (raw) => {
  if (raw == null) return '';
  if (typeof raw === 'string') return raw.trim();
  for (const key of CHOICE_LABEL_KEYS) {
    const value = raw[key];
    if (typeof value === 'string' && value.trim().length > 0) return value.trim();
  }
  return '';
};

name/value são deliberadamente excluídos — eles carregam valores de enum / identificadores crus, não rótulos humanos, e um rótulo-lixo é pior que nenhuma opção (o dict colapsa para '' e é descartado). O teste prova: coerceChoices(['', ' ', null, undefined, {name:'n'}, {value:'v'}, {}]) retorna [].

if (value.kind !== question.kind)
  return err(new Error(`Response kind '${value.kind}' does not match question kind '${question.kind}'.`));
if (value.kind === 'choice' && question.kind === 'choice') {
  if (value.index >= question.choices.length)
    return err(new Error(`Choice index ${value.index} out of range …`));
}

Repare na guarda dupla value.kind === 'choice' && question.kind === 'choice': ela estreita os dois lados para que o TypeScript saiba que question.choices existe e value.index é um número. Pura, nunca lança.

const pending = gw.ask(choiceQ(['a', 'b']));
const r = gw.resolve('q-1', { kind: 'open', text: 'nope' });
expect(r.ok).toBe(false);                     // kind não bate
expect(gw.pending()).toEqual(['q-1']);      // FICA pendente
expect(gw.resolve('q-1', { kind: 'choice', index: 0 }).ok).toBe(true); // correção encerra

Por contraste, um id desconhecido ou já-encerrado é um err simples ("Unknown or already-resolved"), e um double-resolve falha porque o primeiro já removeu a entrada — a 1ª resposta é a que encerrou a promise.

export const monotonicIdFactory = (prefix = 'clarify') => {
  let n = 0;
  return () => { n += 1; return `${prefix}-${n}`; };
};

É o mesmo padrão do Clock injetado do curador (lição 9): troque um global não determinístico por um seam injetado. Os testes injetam monotonicIdFactory('q') para poderem afirmar sobre q-1, q-2.