Habblaud: mensagens pelo escritório

1// Mensagens pelo escritório (Claude Code 2.1.287+): leva para a sessão o que você digita no Habblaud (no painel
2// do agente ou no terminal da tecla T), como se você tivesse digitado no terminal.
3//
4// O que faz, e `claude plugin validate` lista exatamente o que o módulo chama (a saída está no mod/README.md):
5//
6// 1. A cada 2 s, só onde a sessão desenha (`$.session.surfaces()` vazia = `claude -p`/SDK: nada a fazer) ou numa
7//    sessão do app desktop (CLAUDE_CODE_ENTRYPOINT=claude-desktop: SDK por baixo, sem superfície fora da tela), pergunta
8//    ao Habblaud local se há mensagens para ela: POST http://127.0.0.1:<HABBLAUD_PORT ou 4747>/api/mod/inbox com
9//    {session, account}. A pergunta também marca a presença da sessão: é ela que acende, no escritório, a caixa de
10//    mensagem deste agente. Fora do ar, ou respondendo qualquer coisa que não seja 2xx (403 = mensagens desligadas
11//    no Habblaud; 404 = uma versão sem a rota), passa a perguntar a cada 30 s até ele voltar.
12// 2. Cada mensagem, na ordem, vai para a sessão por `$.prompt.submit({ text, asUser: true })`: o modelo a lê como
13//    sua, sem o "The habblaud-mensagens plugin sent a message" (o registro da sessão ainda nomeia o plugin). O
14//    texto vai exatamente como chegou. `{drop}` (um hook recusou) ou exceção = falha, com o motivo.
15//    Com a sessão no meio de um turno, o Claude Code guarda o prompt até ela ficar livre e a chamada pode demorar a
16//    voltar: a espera por mensagem é de no máximo 2 s. Passou disso, a mensagem está na fila da sessão e conta
17//    como entregue, e as seguintes da mesma rodada vão em seguida, na ordem, sem esperar. Assim a rodada nunca
18//    passa de uns poucos segundos: a presença (10 s no servidor) e a confirmação (30 s) não vencem por uma
19//    sessão ocupada. O preço: um hook que recuse a mensagem depois desses 2 s não chega ao escritório.
20// 3. Um único POST /api/mod/inbox/ack com {session, results: [{id, ok, error?}]}. Sem mensagens, sem ack.
21//
22// Por que um plugin à parte do mod `habblaud`: aquele só observa (uso do plano, aviso embaixo do prompt,
23// /habblaud) e nunca muda o que a sessão faz. Este age: digita na sessão em seu nome. Separado, dá para ficar sem
24// ele (npm run mod:install -- --sem-mensagens) e a análise estática de cada um continua curta.
25//
26// Regras: nenhum hook lança (um hook que lança é pulado, mas o que ele deixou pela metade fica): cada passo tem seu
27// try/catch e falha = silêncio. Uma rodada por vez (um Habblaud lento não acumula perguntas). Nada de $.process,
28// $.model, $.fs, leitura da conversa nem decisão de ferramenta; a rede é só 127.0.0.1. O estado fica em variáveis
29// do módulo: um hot reload recomeça do zero (uma mensagem buscada e não confirmada falha no servidor em 30 s).
30// O Claude Code pode carregar o plugin de uma cópia só dele: os ajudantes de caminho são cópias dos de
31// mod/habblaud/hooks/register.ts, não importações.
32//
33// Análise estática do Claude Code: cada chamada é escrita por extenso ($.noun.método), o nome do evento é
34// sempre uma string literal e `$` só é passado para funções declaradas no topo deste arquivo.
35import type { EngineInterface, HttpResponse, Register } from 'claude-code'
36
37/** Porta padrão do Habblaud (a mesma do servidor, do mod e do docker-compose). */
38export const DEFAULT_PORT = 4747
39/** Intervalo das perguntas ao Habblaud; fora do ar, recua para o segundo até ele voltar. */
40export const POLL_MS = 2_000
41export const OFFLINE_POLL_MS = 30_000
42/** Quanto esperar o Habblaud local responder (`$.http.fetch` não aceita AbortSignal: a corrida é com um timer). */
43export const FETCH_TIMEOUT_MS = 2_000
44/** Quanto esperar `$.prompt.submit` voltar antes de dar a mensagem como na fila da sessão. */
45export const SUBMIT_WAIT_MS = 2_000
46/** Tamanho máximo do motivo de uma falha (vem de um hook ou de uma exceção; o texto da mensagem nunca é cortado). */
47export const MAX_REASON = 500
48
49/** Mensagem como POST /api/mod/inbox entrega (shared/types.ts, InboxMessage). */
50export interface InboxMessage {
51  id: string
52  /** O texto como foi digitado; vazio quando o servidor mandou algo que não é texto. */
53  text: string
54}
55
56/** Resultado de uma mensagem, como POST /api/mod/inbox/ack recebe. */
57export interface AckResult {
58  id: string
59  ok: boolean
60  error?: string
61}
62
63/** Desfecho de um `$.prompt.submit`. */
64type Submitted = { ok: true } | { ok: false; error: string }
65
66interface ModEnv {
67  /** Id da conta (o nome da pasta, como o servidor chama); ausente sem HOME (ou USERPROFILE) nem CLAUDE_CONFIG_DIR. */
68  accountId?: string
69  port: number
70  /** Sessão do app desktop do Claude (CLAUDE_CODE_ENTRYPOINT=claude-desktop): roda como SDK e só tem superfície
71   *  enquanto está na tela do app, mas é interativa e recebe prompts mesmo assim. */
72  desktop: boolean
73}
74
75// ---------------------------------------------------------------------------------------------
76// Funções puras (testadas em tests/habblaud-mensagens.test.ts)
77// ---------------------------------------------------------------------------------------------
78
79/**
80 * Normaliza um caminho (barras repetidas, `.`, `..` e a barra do fim): o ambiente do mod não tem node:path. Cópia
81 * de mod/habblaud: caminhos do Windows (com drive ou UNC) saem com `/` e o drive conta como raiz; nos outros, `\`
82 * é parte do nome.
83 */
84export function normalizePath(p: string): string {
85  const win = /^(?:[A-Za-z]:|\\\\)/.test(p)
86  const slashed = win ? p.replace(/\\/g, '/') : p
87  const drive = /^[A-Za-z]:(?=\/|$)/.exec(slashed)?.[0] ?? (win && slashed.startsWith('//') ? '/' : '')
88  const rest = slashed.slice(drive.length)
89  const abs = rest.startsWith('/')
90  const out: string[] = []
91  for (const seg of rest.split('/')) {
92    if (!seg || seg === '.') continue
93    if (seg === '..') {
94      if (out.length && out[out.length - 1] !== '..') out.pop()
95      else if (!abs) out.push(seg)
96      continue
97    }
98    out.push(seg)
99  }
100  const joined = out.join('/')
101  return drive + (abs ? `/${joined}` : joined || (drive ? '' : '.'))
102}
103
104/** `~` no começo vira o HOME. */
105function expandHome(p: string, home: string | undefined): string {
106  return home && /^~(?=[\\/]|$)/.test(p) ? home + p.slice(1) : p
107}
108
109/** Config dir da conta: o primeiro item de CLAUDE_CONFIG_DIR (com `~` expandido) ou ~/.claude. */
110export function configDirOf(claudeConfigDir: string | undefined, home: string | undefined): string | undefined {
111  const first = (claudeConfigDir ?? '').split(',')[0]?.trim() ?? ''
112  if (first) return normalizePath(expandHome(first, home))
113  return home ? normalizePath(`${home}/.claude`) : undefined
114}
115
116/** Id da conta = nome da pasta (AccountInfo.id do servidor, ex.: ".claude-conta2"). */
117export function accountIdOf(configDir: string): string | undefined {
118  const name = configDir.split('/').filter(Boolean).pop()
119  return name && name !== '.' && name !== '..' ? name : undefined
120}
121
122export function portOf(raw: string | undefined): number {
123  const n = Number.parseInt(raw ?? '', 10)
124  return Number.isInteger(n) && n > 0 && n < 65_536 ? n : DEFAULT_PORT
125}
126
127/** Corpo de POST /api/mod/inbox: a conta só quando se sabe qual é. */
128export function inboxBody(session: string, account: string | undefined): string {
129  return JSON.stringify(account ? { session, account } : { session })
130}
131
132/** Corpo de POST /api/mod/inbox/ack. */
133export function ackBody(session: string, results: readonly AckResult[]): string {
134  return JSON.stringify({ session, results })
135}
136
137/**
138 * Lê a resposta de POST /api/mod/inbox; fora do formato = undefined (vale "fora do ar"). Item sem id fica de fora
139 * (não há como confirmá-lo); com id e sem texto, entra com texto vazio, para ser confirmado como falha em vez de o
140 * servidor esperar 30 s.
141 */
142export function parseInbox(text: string): InboxMessage[] | undefined {
143  let j: unknown
144  try {
145    j = JSON.parse(text)
146  } catch {
147    return undefined
148  }
149  if (!j || typeof j !== 'object' || Array.isArray(j)) return undefined
150  const list = (j as Record<string, unknown>).messages
151  if (!Array.isArray(list)) return undefined
152  const out: InboxMessage[] = []
153  for (const item of list) {
154    if (!item || typeof item !== 'object') continue
155    const m = item as Record<string, unknown>
156    if (typeof m.id !== 'string' || !m.id) continue
157    out.push({ id: m.id, text: typeof m.text === 'string' ? m.text : '' })
158  }
159  return out
160}
161
162/** O motivo de uma falha numa linha só, com tamanho limitado: o texto de um `{drop}` ou a mensagem de uma exceção. */
163export function reasonText(raw: unknown, fallback: string): string {
164  const msg = typeof raw === 'string' ? raw : raw && typeof (raw as { message?: unknown }).message === 'string' ? (raw as { message: string }).message : ''
165  const line = msg.replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim()
166  if (!line) return fallback
167  return line.length > MAX_REASON ? `${line.slice(0, MAX_REASON - 1)}…` : line
168}
169
170// ---------------------------------------------------------------------------------------------
171// Estado do módulo (some num hot reload) e o que fala com o Claude Code
172// ---------------------------------------------------------------------------------------------
173
174let env: ModEnv | undefined
175let timer: { cancel: () => void } | undefined
176let timerMs = 0
177/** Uma rodada por vez: um Habblaud lento ou uma sessão ocupada não empilham rodadas. */
178let polling = false
179
180/** O ambiente da sessão, lido uma vez por carga (cada nome escrito por extenso, como a análise exige). */
181async function readEnv($: EngineInterface): Promise<ModEnv> {
182  if (env) return env
183  // No Windows, HOME só existe se alguém o definir: vale o USERPROFILE (a mesma ordem do mod habblaud).
184  const home = (await $.env.get('HOME'))?.trim() || (await $.env.get('USERPROFILE'))?.trim() || undefined
185  const configDir = configDirOf(await $.env.get('CLAUDE_CONFIG_DIR'), home)
186  const next: ModEnv = {
187    port: portOf(await $.env.get('HABBLAUD_PORT')),
188    desktop: (await $.env.get('CLAUDE_CODE_ENTRYPOINT'))?.trim() === 'claude-desktop',
189  }
190  const accountId = configDir ? accountIdOf(configDir) : undefined
191  if (accountId) next.accountId = accountId
192  env = next
193  return next
194}
195
196/** O que `promise` resolver em até `ms`; passou disso, undefined (a promessa segue sozinha). */
197async function waitAtMost<T>($: EngineInterface, promise: Promise<T>, ms: number): Promise<T | undefined> {
198  let wait: { cancel: () => void } | undefined
199  const timeout = new Promise<undefined>((resolve) => {
200    wait = $.clock.after(ms, () => resolve(undefined))
201  })
202  try {
203    return await Promise.race([promise, timeout])
204  } finally {
205    wait?.cancel()
206  }
207}
208
209/** POST de um JSON ao Habblaud local com prazo de 2 s: a resposta, ou undefined (fora do ar, travado). Nunca lança. */
210async function postJson($: EngineInterface, port: number, path: string, body: string): Promise<HttpResponse | undefined> {
211  try {
212    const request = $.http.fetch(`http://127.0.0.1:${port}${path}`, {
213      method: 'POST',
214      // Sem o Content-Type, o guarda do servidor recusa o POST (415).
215      headers: { 'content-type': 'application/json', accept: 'application/json' },
216      body,
217    })
218    return await waitAtMost($, request, FETCH_TIMEOUT_MS)
219  } catch {
220    return undefined
221  }
222}
223
224/** Uma mensagem para a sessão, como se você a tivesse digitado. Nunca lança. */
225async function submitOne($: EngineInterface, text: string): Promise<Submitted> {
226  try {
227    const r = await $.prompt.submit({ text, asUser: true })
228    if (typeof r?.drop === 'string') return { ok: false, error: reasonText(r.drop, 'um hook da sessão recusou a mensagem') }
229    return { ok: true }
230  } catch (err) {
231    return { ok: false, error: reasonText(err, 'a sessão não aceitou a mensagem') }
232  }
233}
234
235/** Manda as mensagens à sessão, na ordem, e devolve o resultado de cada uma. Nunca lança. */
236async function deliver($: EngineInterface, messages: readonly InboxMessage[]): Promise<AckResult[]> {
237  const results: AckResult[] = []
238  /** Uma chamada passou do prazo: a sessão está ocupada e as seguintes entram na fila atrás dela, sem esperar. */
239  let queued = false
240  for (const m of messages) {
241    if (!m.text.trim()) {
242      results.push({ id: m.id, ok: false, error: 'mensagem vazia' })
243      continue
244    }
245    const submitted = submitOne($, m.text)
246    if (queued) {
247      void submitted
248      results.push({ id: m.id, ok: true })
249      continue
250    }
251    const out = await waitAtMost($, submitted, SUBMIT_WAIT_MS)
252    if (!out) {
253      queued = true
254      results.push({ id: m.id, ok: true })
255    } else results.push(out.ok ? { id: m.id, ok: true } : { id: m.id, ok: false, error: out.error })
256  }
257  return results
258}
259
260/** (Re)agenda as rodadas: 2 s com o Habblaud no ar, 30 s fora do ar. */
261function schedule($: EngineInterface, ms: number): void {
262  if (timer && timerMs === ms) return
263  timer?.cancel()
264  timerMs = ms
265  timer = $.clock.every(ms, () => {
266    void round($)
267  })
268}
269
270/** Uma rodada: busca as mensagens desta sessão, manda cada uma e confirma. Nunca lança. */
271async function round($: EngineInterface): Promise<void> {
272  if (polling) return
273  polling = true
274  try {
275    const e = await readEnv($)
276    const surfaces = await $.session.surfaces()
277    if (!surfaces.length && !e.desktop) return
278    const session = await $.session.id()
279    const res = await postJson($, e.port, '/api/mod/inbox', inboxBody(session, e.accountId))
280    const messages = res?.ok ? parseInbox(res.text) : undefined
281    if (!messages) {
282      schedule($, OFFLINE_POLL_MS)
283      return
284    }
285    schedule($, POLL_MS)
286    if (!messages.length) return
287    const results = await deliver($, messages)
288    // Falhou a confirmação: o servidor dá as mensagens como falhas em 30 s ("a sessão não confirmou a entrega").
289    await postJson($, e.port, '/api/mod/inbox/ack', ackBody(session, results))
290  } catch {
291    // silêncio: a próxima rodada tenta de novo
292  } finally {
293    polling = false
294  }
295}
296
297export const register: Register = (on) => {
298  on('session.start', async ($, e, next) => {
299    try {
300      schedule($, POLL_MS)
301    } catch {
302      // sem as rodadas, a sessão segue como sempre
303    }
304    return next(e)
305  })
306}
307