⏱️ Trabalho fora do dispatch

O session.start dispara uma vez por mod quando a sessão fica pronta, antes do primeiro prompt, e o engine espera por ele. Tudo o que você registra ali já existe no turno 1: um comando, uma ferramenta para o modelo, um timer.

Ele dispara de novo quando o mod é ligado no meio da sessão e quando ele recarrega (só os módulos que mudaram). Não dispara no /clear: ali chega um session.end com reason: 'clear', e nenhum session.start depois.

on("session.start", ($, e, next) => $.tool.register(t).then(() => next(e)))

claude -p "/readcount" --plugin-dir templates/starter-mod

read-counter-example: Successful reads observed: 0

Dois timers. $.clock.every(ms, fn) chama fn a cada período. $.clock.after(ms, fn) chama uma vez. Os dois devolvem um objeto com cancel(). Eles rodam até você cancelar ou até o mod recarregar.

No reload os timers morrem junto com o ambiente antigo. Como o session.start dispara de novo para o módulo que mudou (segundo os tipos), quem liga o timer ali o religa sozinho. Esse é o motivo de não ligar timer em nenhum outro lugar.

export const register: Register = (on, options) => {
  const fixa = String(options.pasta ?? '').trim()
  const seg = Number(options.intervalo)
  const intervalo = (Number.isFinite(seg) && seg >= 5 ? seg : 30) * 1000

  on('session.start', async ($, e, next) => {
    await update($, cwdAtom, () => e.cwd)
    await $.command.register({
      name: 'longrun',
      description: 'Painel da execução longa (args: todas | atualizar)',
    })
    await atualizar($, fixa).catch(() => null)
    $.clock.every(intervalo, () => {
      void atualizar($, fixa).catch(() => null)
    })
    return next(e)
  })

Como ler o desenho: os pontos são as chamadas de fn. Na linha amarela tudo para. O segundo bloco azul é o mesmo hook rodando outra vez, no ambiente novo, e por isso os ticks voltam.

O mod não tem fs do Node. Tem o $.fs, que lê, escreve, lista e examina caminhos. Caminho relativo é relativo à pasta de trabalho da sessão. Quase todo método rejeita quando o arquivo não existe, então o .catch é parte da chamada.

O painel de execução longa do Rafa lê os arquivos de uma pasta longrun/ a cada ciclo. Repare que nenhuma leitura derruba o painel: faltou o arquivo, vira texto vazio ou lista vazia.

async function lerTexto($: EngineInterface, caminho: string) {
  return $.fs.read(caminho).catch(() => '')
}

/** A pasta da execução: a fixada nas opções, ou a mais recente (pelo nome) em <cwd>/longrun/. */
async function acharPasta($: EngineInterface, cwd: string, fixa: string): Promise<string | null> {
  const base = fixa !== '' ? fixa : cwd
  if (fixa !== '' && (await $.fs.exists(juntar(fixa, 'goal.md')).catch(() => false))) return fixa
  const dir = juntar(base, 'longrun')
  const itens = await $.fs.list(dir).catch(() => [])
  // ... filtra kind === 'dir' e escolhe a mais recente pelo nome ...

$.process.run roda um programa da máquina, como o usuário da sessão, e devolve { exitCode, stdout, stderr } quando ele termina. O comando vai como lista de argumentos (argv), sem shell no meio.

Sem shell quer dizer: nada de |, && ou * interpretados, e nada de um texto do modelo virar comando por engano. Cada argumento chega ao programa exatamente como você escreveu.

async function git($: EngineInterface, cwd: string, args: string[]) {
  const r = await $.process.run(['git', ...args], { cwd, timeoutMs: 5_000 }).catch(() => undefined)
  return r && r.exitCode === 0 ? r.stdout.trim() : ''
}

Um timer descobriu algo e o Claude está parado esperando. O mod pode acordar a sessão: $.prompt.submit({ text }) põe um prompt na fila, que vira um turno próprio assim que a sessão fica livre.

Ele nunca entra no meio de um turno que está rodando. E a promessa resolve quando o turno começa, não quando termina. Por isso os tipos usam void na frente: o mod pede e segue.

// do comentário de prompt.submit nos tipos: começa um turno (gasta modelo)
void $.prompt.submit({ text: "List the TODOs you just mentioned." })

// da referência (comando /quote): só preenche a caixa; a pessoa decide
await $.prompt.fill({ text: quoted + '\n\n', mode: 'insert' })

O $ tem um noun model. $.model.complete({ model, prompt }) faz uma pergunta avulsa, sem histórico. $.model.fork({ prompt }) pergunta sobre a própria conversa, aproveitando o cache. As duas usam o cliente da sessão: gastam a cota da pessoa.

Elas sempre resolvem com um resultado, nunca com texto solto: isAnswered com text e usage, ou isAnswered: false com um reason (api-error, empty-reply, aborted; no fork, também nothing-to-fork).

Como ler o desenho: comece em cima. A maior parte dos mods para no ramo da esquerda. Gastar modelo só aparece quando a pessoa pediu, e mesmo assim por um caminho que ela vê. A linha vermelha é a regra do kit INEMA: um mod nunca chama o modelo por conta própria.

claude plugin validate templates/starter-mod

Validating plugin manifest: .../templates/starter-mod/.claude-plugin/plugin.json

Validating hooks: .../templates/starter-mod/hooks/hooks.json

  ❯ ./starter.mjs hooks: session.start, tool.call{tool=Read}, command.run{command=readcount}
  ❯ ./starter.mjs calls: $.command.register

✔ Validation passed