Session Idle Reaper — Documento de Design

Status: Rascunho
Autor: qinqi
Data: 2026-06-08
Escopo: packages/acp-bridge/src/bridge.ts, packages/cli/src/serve/server.ts

1. Declaração do Problema

1.1 Comportamento atual

Uma vez criada, uma sessão da bridge permanece em memória (byId: Map<string, SessionEntry>) indefinidamente. Ela só é destruída quando:

1. Um cliente chama explicitamente DELETE /session/:id (closeSession)
2. O processo filho compartilhado qwen --acp falha (handler channel.exited)
3. O processo daemon recebe SIGTERM / SIGINT (shutdown)

Não há timeout automático de ociosidade para sessões. Os timestamps de heartbeat (sessionLastSeenAt, clientLastSeenAt) são registrados por recordHeartbeat, mas nunca são consumidos para fins de evicção (o comentário do campo referencia uma futura “política de revogação (PR 24)” que ainda não foi implementada).

1.2 Impacto

1.3 Por que agora

O daemon está sendo cada vez mais usado como um servidor de workspace de longa duração (app desktop, extensões IDE, web UI). Falhas de cliente e picos de rede são normais — depender de DELETE explícito para limpeza é insustentável.

2. Objetivos do Design

1. Reclamar automaticamente sessões ociosas cujos clientes desapareceram e que não têm trabalho em andamento ativo.
2. Nunca destruir uma sessão que tenha um prompt ativo — fazer isso mataria silenciosamente trabalho visível ao usuário.
3. Preservar dados de sessão persistidos — apenas o estado da bridge em memória é liberado; as transcrições em disco (SessionService) não são tocadas. Usuários podem usar session/load ou session/resume para restaurar.
4. Observável — emitir um evento SSE distinto para que os clientes saibam POR QUE a sessão foi fechada (timeout de ociosidade vs. fechamento explícito vs. falha).
5. Configurável — operadores e testes podem ajustar timeouts ou desabilitar o reaper completamente.
6. Zero novas dependências / componentes — implementar inteiramente dentro do closure da bridge existente.

Não-objetivos

• Gerenciamento de sessão entre workspaces (isso seria preocupação do gateway).
• Evicção LRU no limite de maxSessions (valioso, mas trabalho separado — registrado como follow-up).
• Compactação do ring buffer do EventBus para sessões ociosas (baixa prioridade dado o limite de 20 sessões; registrado como follow-up).
• Pressão adaptativa baseada em RSS (requer polling de process.memoryUsage() e design de política; registrado como follow-up).

3. Arquitetura

3.1 Visão Geral

Bridge closure (createHttpAcpBridge)
│
├─ byId: Map<sessionId, SessionEntry>     ← existente
├─ channelInfo: ChannelInfo               ← existente
├─ idleTimer (nível do canal)            ← existente
│
└─ sessionReaper: NodeJS.Timeout          ← NOVO
     │
     ├─ varre byId a cada REAP_INTERVAL_MS
     ├─ pula sessões com prompt ativo
     ├─ pula sessões com assinantes SSE ativos
     ├─ fecha sessões que excederam o TTL de ociosidade
     └─ emite session_closed { reason: 'idle_timeout' }

3.2 Relação com mecanismos existentes

Dois mecanismos trabalham juntos para cobrir o ciclo de vida da limpeza de sessões:

1. Fechar ao último desanexar (principal) — quando detachClient remove o último cliente registrado E não restam assinantes SSE, a sessão é fechada imediatamente via closeSessionImpl. Isso cobre o caminho normal: usuário fecha aba → limpeza React → POST /session/:id/detach.

2. Session idle reaper (garantia) — varredura periódica por sessões sem prompt ativo e sem assinantes SSE que não receberam heartbeat dentro do TTL configurado. Isso cobre o caminho de falha: navegador morto, rede perdida, kill -9 — a requisição de detach nunca foi enviada, então clientIds ainda mostra clientes registrados, mas a sessão está efetivamente órfã.

4. Design Detalhado

4.1 Novas opções de configuração (BridgeOptions)

interface BridgeOptions {
  // ... campos existentes ...
 
  /**
   * Com que frequência o session reaper varre `byId` em busca de sessões
   * ociosas, em milissegundos. Padrão: 60_000 (1 minuto). Defina como 0 ou
   * Infinity para desabilitar o reaper completamente. O timer é `.unref()`'d.
   */
  sessionReapIntervalMs?: number;
 
  /**
   * Uma sessão com ZERO assinantes SSE ativos E ZERO clientes registrados
   * que não recebeu um heartbeat por esta quantidade de milissegundos é
   * considerada ociosa e será recolhida.
   *
   * Padrão: 30 * 60_000 (30 minutos).
   * Defina como 0 ou Infinity para desabilitar a coleta por ociosidade.
   */
  sessionIdleTimeoutMs?: number;
}

Superfície CLI (flags do qwen serve):

--session-reap-interval-ms <ms>   Intervalo de varredura do reaper (padrão 60000, 0=desabilitar)
--session-idle-timeout-ms <ms>    Limite de ociosidade (padrão 1800000, 0=desabilitar)

4.2 Predicado de sessão ociosa

Uma sessão é elegível para coleta quando todas as seguintes condições forem verdadeiras:

1. Sem prompt ativo: entry.promptActive === false
2. Sem assinantes SSE ativos: entry.events.subscriberCount === 0
3. Duração de ociosidade excedida: now - lastActivity(entry) > sessionIdleTimeoutMs

Nota: o reaper intencionalmente NÃO verifica clientIds.size. Ele cobre o caminho de falha onde o detach nunca foi enviado — clientIds ainda mostra clientes registrados, mas a sessão está efetivamente órfã. O caminho normal (cliente envia detach) é tratado pelo fechamento ao último desanexar.

Onde lastActivity(entry) é definido como:

function lastActivity(entry: SessionEntry): number {
  // `sessionLastSeenAt` está em epoch-ms (de Date.now());
  // `createdAt` é uma string ISO 8601 — fazer parse para epoch-ms como fallback.
  return entry.sessionLastSeenAt ?? Date.parse(entry.createdAt);
}

Nota: entry.createdAt é tipado como string (ISO 8601), não um número. Date.parse é seguro aqui — o formato é sempre new Date().toISOString() (veja createSessionEntry, bridge.ts:1883).

Justificativa para cada guarda:

4.3 Ação de coleta

Para cada sessão que passa no predicado de ociosidade, o reaper chama:

await closeSession(sessionId, { reason: 'idle_timeout' });

Isso reutiliza o caminho closeSession existente que:

1. Remove de byId / defaultEntry
2. Cancela permissões pendentes via permissionMediator.forgetSession
3. Publica evento session_closed (com reason: 'idle_timeout')
4. Fecha o EventBus
5. Envia connection.cancel() para o filho ACP (melhor esforço)
6. Dispara startIdleTimer no canal se for a última sessão

Por que closeSession e não killSession?

killSession é o caminho interno de coleta forçada projetado para a condição de corrida do handshake de spawn (guarda requireZeroAttaches, túmulo spawnOwnerWantedKill). closeSession é o caminho documentado voltado ao cliente que publica session_closed (não session_died) e lida com telemetria corretamente. O reaper é um “fechamento gracioso em nome de um cliente ausente”, então closeSession é a semântica correta.

4.4 Estendendo closeSession para aceitar um motivo de fechamento

Atualmente, closeSession fixa reason: 'client_close' no evento session_closed. Precisamos tornar isso parametrizável.

Abordagem: Adicionar um novo parâmetro opts opcional a closeSession, em vez de sobrecarregar BridgeClientRequestContext (que é um tipo com escopo de requisição do cliente — adicionar reason a ele seria uma violação de camada, pois “motivo” é uma decisão do lado do servidor, não algo que um cliente passa em um cabeçalho).

// bridgeTypes.ts — novo tipo + mudança de assinatura:
export interface CloseSessionOpts {
  /** Substitui o 'client_close' padrão no evento session_closed. */
  reason?: string;
}
 
closeSession(
  sessionId: string,
  context?: BridgeClientRequestContext,
  opts?: CloseSessionOpts,
): Promise<void>;

// bridge.ts — mudança de implementação:
async closeSession(sessionId, context, opts) {
  // ...
  const reason = opts?.reason ?? 'client_close';
  entry.events.publish({
    type: 'session_closed',
    data: { sessionId, reason, ... },
  });
}

Os chamadores existentes (rota DELETE /session/:id) não passam opts, usando o padrão 'client_close'. O reaper passa { reason: 'idle_timeout' }.

4.5 Ciclo de vida do reaper

// Dentro do closure createHttpAcpBridge:
 
const resolvedReapIntervalMs = resolvePositiveMs(
  opts.sessionReapIntervalMs,
  60_000,
);
const resolvedIdleTimeoutMs = resolvePositiveMs(
  opts.sessionIdleTimeoutMs,
  30 * 60_000,
);
 
let sessionReaper: ReturnType<typeof setInterval> | undefined;
 
function startSessionReaper(): void {
  if (resolvedReapIntervalMs <= 0 || resolvedIdleTimeoutMs <= 0) return;
  sessionReaper = setInterval(() => {
    if (shuttingDown) return;
    const now = Date.now();
    for (const [id, entry] of byId) {
      if (entry.promptActive) continue;
      if (entry.events.subscriberCount > 0) continue;
      const lastActive = entry.sessionLastSeenAt ?? Date.parse(entry.createdAt);
      const idle = now - lastActive;
      if (idle < resolvedIdleTimeoutMs) continue;
      writeStderrLine(
        `qwen serve: reaping idle session ${JSON.stringify(id)} ` +
          `(idle for ${Math.round(idle / 1000)}s, threshold ${Math.round(resolvedIdleTimeoutMs / 1000)}s)`,
      );
      // Passar context `undefined` (sem cliente) e opts `{ reason }`.
      bridgeImpl
        .closeSession(id, undefined, { reason: 'idle_timeout' })
        .catch((err) => {
          writeStderrLine(
            `qwen serve: session reaper failed to close ${JSON.stringify(id)}: ${String(err)}`,
          );
        });
    }
  }, resolvedReapIntervalMs);
  sessionReaper.unref();
}
 
function stopSessionReaper(): void {
  if (sessionReaper !== undefined) {
    clearInterval(sessionReaper);
    sessionReaper = undefined;
  }
}

Nota: bridgeImpl refere-se ao objeto bridge retornado por createHttpAcpBridge, de modo que closeSession tenha acesso total ao estado do closure. Na prática, isso é implementado como uma chamada direta à função interna do closure closeSessionImpl.

Integração com o ciclo de vida:

• startSessionReaper() é chamado no momento da construção da bridge (após validação de opções, junto com a configuração existente de channelIdleTimeoutMs).
• stopSessionReaper() é chamado tanto em shutdown() quanto em killAllSync().

4.6 Interação com chamadores existentes de closeSession

4.7 Segurança de concorrência

O callback do reaper roda no event loop do Node.js. Considerações principais:

• A iteração for...of é síncrona. O reaper avalia o predicado de ociosidade de cada entrada sincronamente, então dispara closeSession(...).catch(...) para as entradas correspondentes. Sem await no corpo do loop — todos os fechamentos são despachados em um único limite de microtask, então o loop termina.
• byId.delete é adiado. Dentro de closeSession, byId.delete roda APÓS o primeiro await (notifyAgentSessionClose). Isso significa que as deleções ocorrem em microtasks após o loop for...of ter terminado. Como cada closeSession opera em uma chave distinta, não há aliasing. E for...of já terminou de iterar, então deleção no meio da iteração não é uma preocupação.
• Condição de corrida de fechamento duplo. Se um cliente chama DELETE /session/:id para a mesma sessão entre a verificação do predicado do reaper e a execução assíncrona de closeSession, o closeSession do reaper lançará SessionNotFoundError (capturado por .catch()). Seguro.
• Condição de corrida de reconexão. Se um cliente reconectar a uma sessão (registra clientId / abre SSE) entre a verificação do predicado do reaper e a execução de closeSession, closeSession ainda prosseguirá e fechará a sessão. O cliente recebe session_closed e deve recarregar. Essa janela é extremamente estreita (um tick síncrono de setInterval) e a consequência é benigna — nenhuma perda de dados, apenas um prompt de recarga. O TTL padrão de 30 minutos torna isso extremamente raro.
• Um spawnOrAttach concorrente que cria uma nova sessão enquanto o reaper está varrendo não será visto (iteramos as entradas de byId no início de cada tick). Isso é seguro — novas sessões estão frescas e não atingirão o limite de ociosidade.

4.8 Mudança no formato do wire

O campo data.reason do evento session_closed já existe com valor 'client_close'. Adicionamos dois novos valores:

• 'idle_timeout' — emitido pelo reaper de ociosidade (garantia para clientes que falharam)
• 'last_client_detached' — emitido pelo fechamento ao último desanexar (fechamento normal de aba)

Isso é compatível com versões anteriores — o código SDK existente que verifica reason === 'client_close' simplesmente não corresponderá aos novos valores, e o handler genérico de frame terminal (isTerminalLifecycleEvent) já lida com session_closed independentemente do motivo.

5. Plano de Testes

5.1 Testes unitários (bridge.test.ts)

5.2 Testes de integração (server.test.ts)

6. Padrões de Configuração

7. Observabilidade

• Log stderr: qwen serve: reapando sessão ociosa "<id>" (ociosa por Nms) a cada varredura, mantendo a convenção de prefixo qwen serve: existente.
• Evento de telemetria: session.close com operação qwen-code.daemon.bridge.operation: 'session.close' (reutiliza o caminho de telemetria closeSession existente).
• Métrica de telemetria: sessionLifecycle('close') (reutiliza contador existente).
• Evento SSE: session_closed com data.reason: 'idle_timeout'.

8. Trabalhos Futuros (Fora do Escopo)

9. Riscos e Mitigações