@orkastery/cli 0.2.0

package/adapters/openclaw/openclaw.plugin.json

@@ -0,0 +1,138 @@
+{
+  "name": "orkastery",
+  "displayName": "Orkastery",
+  "version": "{{versao}}",
+  "description": "Conducao de looping threads em 6 fases pelo nucleo `ork`, exposta ao OpenClaw como tools `ork_*`. Zero regra de negocio no host: cada tool e uma chamada de CLI.",
+  "license": "MIT",
+  "runtime": { "type": "cli", "command": "{{ork_bin}}" },
+  "conduction": {
+    "tags": ["#Look", "#Ork", "#Classic", "#Maestro", "#Auto"],
+    "parse": "ork_modo_do_pedido",
+    "nota": "O host transporta a tag. A validacao contra conduction.allowed_modes e do nucleo, no ork thread new."
+  },
+  "tools": [
+    {
+      "name": "ork_doctor",
+      "description": "O que vale nesta maquina agora: runtime, assinatura, provider de custo. Sai diferente de zero quando o despacho nao vale.",
+      "command": ["{{ork_bin}}", "doctor"],
+      "parameters": {}
+    },
+    {
+      "name": "ork_modo_do_pedido",
+      "description": "Le a #TAG de conducao do pedido do builder (#Look, #Ork, #Classic, #Maestro, #Auto) e devolve o modo. Sem tag, devolve o conduction.default_mode do manifesto. Use SEMPRE este tool em vez de reconhecer a tag no host.",
+      "command": ["{{ork_bin}}", "modos", "--do-pedido", "{pedido}", "--json"],
+      "parameters": {
+        "pedido": { "type": "string", "required": true, "description": "O texto inteiro do pedido do builder" }
+      }
+    },
+    {
+      "name": "ork_thread_new",
+      "description": "Cria a thread, o slug de 3 partes e o ledger. O modo vem de ork_modo_do_pedido; o nucleo valida contra conduction.allowed_modes e recusa o que o projeto nao permite.",
+      "command": ["{{ork_bin}}", "thread", "new", "{nome}", "--mode", "{modo}", "--worktree", "auto"],
+      "parameters": {
+        "nome": { "type": "string", "required": true, "description": "Nome curto da demanda" },
+        "modo": { "type": "string", "required": true, "description": "look|default|ork|maestro|auto, vindo de ork_modo_do_pedido" }
+      }
+    },
+    {
+      "name": "ork_thread_status",
+      "description": "Estado da thread lido do disco e cruzado com o runtime real.",
+      "command": ["{{ork_bin}}", "thread", "status", "{thread}"],
+      "parameters": { "thread": { "type": "string", "required": true } }
+    },
+    {
+      "name": "ork_phase_run",
+      "description": "Despacha uma fase (GOAL PLAN GO CHECK SHIP MASTER) pelo runtime adapter, gravando o prompt exato com sha256 no ledger.",
+      "command": ["{{ork_bin}}", "phase", "run", "{thread}", "{fase}", "--prompt", "{prompt}"],
+      "parameters": {
+        "thread": { "type": "string", "required": true },
+        "fase": { "type": "string", "required": true, "enum": ["GOAL", "PLAN", "GO", "CHECK", "SHIP", "MASTER"] },
+        "prompt": { "type": "string", "required": true, "description": "O pedido do builder para esta fase" }
+      }
+    },
+    {
+      "name": "ork_phase_list",
+      "description": "O ledger da thread, evento a evento, com quem decidiu e a evidencia.",
+      "command": ["{{ork_bin}}", "phase", "list", "{thread}"],
+      "parameters": { "thread": { "type": "string", "required": true } }
+    },
+    {
+      "name": "ork_claims_add",
+      "description": "Registra uma alegacao verificavel com o comando que a comprova. Toda citacao de arquivo ou teste vira claim.",
+      "command": ["{{ork_bin}}", "claims", "add", "{thread}", "{arquivo}", "--claim", "{alegacao}", "--verificar", "{comando}"],
+      "parameters": {
+        "thread": { "type": "string", "required": true },
+        "arquivo": { "type": "string", "required": true },
+        "alegacao": { "type": "string", "required": true },
+        "comando": { "type": "string", "required": true }
+      }
+    },
+    {
+      "name": "ork_verify",
+      "description": "Reexecuta claims e comandos do manifesto no HEAD real e compara com a baseline. Passagem relatada nao e passagem.",
+      "command": ["{{ork_bin}}", "verify", "{thread}"],
+      "parameters": { "thread": { "type": "string", "required": true } }
+    },
+    {
+      "name": "ork_verify_baseline",
+      "description": "Grava a baseline: o estado do mundo ANTES do GO, que separa regressao de divida pre-existente.",
+      "command": ["{{ork_bin}}", "verify", "{thread}", "--baseline"],
+      "parameters": { "thread": { "type": "string", "required": true } }
+    },
+    {
+      "name": "ork_worktree_ensure",
+      "description": "Garante a worktree isolada da thread, com a base resolvida pelo nucleo.",
+      "command": ["{{ork_bin}}", "worktree", "ensure", "{thread}"],
+      "parameters": { "thread": { "type": "string", "required": true } }
+    },
+    {
+      "name": "ork_worktree_audit",
+      "description": "Confere a worktree no proprio git. Sai diferente de zero quando ela divergiu ou a base avancou.",
+      "command": ["{{ork_bin}}", "worktree", "audit", "{thread}"],
+      "parameters": { "thread": { "type": "string", "required": true } }
+    },
+    {
+      "name": "ork_gate_approve",
+      "description": "Registra no ledger a autorizacao humana de um gate (objetivo, premissas, evidencias, push, score).",
+      "command": ["{{ork_bin}}", "gate", "approve", "{thread}", "{sobre}", "--por", "{quem}"],
+      "parameters": {
+        "thread": { "type": "string", "required": true },
+        "sobre": { "type": "string", "required": true },
+        "quem": { "type": "string", "required": true }
+      }
+    },
+    {
+      "name": "ork_ship",
+      "description": "Merge serializado por lease e push PROVADO comparando o sha local com o que o remoto reporta.",
+      "command": ["{{ork_bin}}", "ship", "{thread}", "--para", "{base}", "--autorizar-push", "{quem}"],
+      "parameters": {
+        "thread": { "type": "string", "required": true },
+        "base": { "type": "string", "required": true },
+        "quem": { "type": "string", "required": true }
+      }
+    },
+    {
+      "name": "ork_master",
+      "description": "Fecha a thread: POSTMORTEM tipado, MASTER log no contrato congelado e o score HUMANO de 0 a 5 com justificativa. Nunca invente a nota.",
+      "command": ["{{ork_bin}}", "master", "{thread}", "--score", "{score}", "--justificativa", "{justificativa}", "--por", "{quem}"],
+      "parameters": {
+        "thread": { "type": "string", "required": true },
+        "score": { "type": "string", "required": true, "description": "inteiro de 0 a 5, dado pelo humano" },
+        "justificativa": { "type": "string", "required": true },
+        "quem": { "type": "string", "required": true }
+      }
+    },
+    {
+      "name": "ork_board",
+      "description": "Todas as threads em uma visao, e o escalonador dizendo quem avanca agora e quem espera.",
+      "command": ["{{ork_bin}}", "board", "plan"],
+      "parameters": {}
+    },
+    {
+      "name": "ork_master_batch",
+      "description": "A fila de score dos modos sem pausa de MASTER. Fila que ninguem passa e score que nao existe.",
+      "command": ["{{ork_bin}}", "master", "--batch"],
+      "parameters": {}
+    }
+  ]
+}

package/dist/adapters/claude-bg.js

@@ -0,0 +1,308 @@
+"use strict";
+/**
+ * Adapter de runtime `claude-bg`: despacha fases como BACKGROUND AGENT do Claude Code.
+ *
+ * Mecanismo validado em producao (02/09) e os dois pitfalls que ele evita:
+ *   - `claude -p` e efemero e invisivel no app e no `claude agents`. NUNCA usar.
+ *   - `claude remote-control --spawn=session` trava sem registrar a sessao. NUNCA usar.
+ * O que vale: `claude --bg "<prompt>" --name <slug>` rodando com cwd no diretorio do projeto,
+ * o que deixa a sessao visivel no app Claude e no `claude agents --json`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOME_ADAPTER = void 0;
+exports.disponivel = disponivel;
+exports.versao = versao;
+exports.montarComando = montarComando;
+exports.extrairSessionId = extrairSessionId;
+exports.listarSessoes = listarSessoes;
+exports.acharSessao = acharSessao;
+exports.despachar = despachar;
+exports.parseRateLimit = parseRateLimit;
+exports.comandoAttach = comandoAttach;
+exports.limparAnsi = limparAnsi;
+exports.logs = logs;
+exports.parar = parar;
+exports.ocupacaoDeContexto = ocupacaoDeContexto;
+const util_1 = require("../util");
+exports.NOME_ADAPTER = 'claude-bg';
+/** O runtime esta disponivel nesta maquina? */
+function disponivel() {
+    return (0, util_1.noPath)('claude');
+}
+/** Versao do runtime, para o `ork doctor`. */
+function versao() {
+    const r = (0, util_1.exec)('claude', ['--version'], undefined, 30000);
+    return r.ok ? r.stdout.trim() : null;
+}
+/** Monta a linha de comando exata do despacho (usada tambem pelo `--dry-run`). */
+function montarComando(pedido) {
+    const args = ['--bg', pedido.prompt, '--name', pedido.nome];
+    if (pedido.model)
+        args.push('--model', pedido.model);
+    if (pedido.effort)
+        args.push('--effort', pedido.effort);
+    return ['claude', ...args];
+}
+/**
+ * Extrai o identificador da sessao da saida do `claude --bg`.
+ * Aceita UUID completo ou o id curto que o CLI imprime.
+ */
+function extrairSessionId(saida) {
+    const uuid = saida.match(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i);
+    if (uuid)
+        return uuid[0];
+    const curto = saida.match(/\b[0-9a-f]{8}\b/i);
+    return curto ? curto[0] : null;
+}
+/**
+ * Lista as sessoes vivas do runtime. Fonte da verdade externa, nunca self-report.
+ *
+ * O filtro por diretorio e feito aqui, e nao pelo `--cwd` do `claude agents`: medido
+ * em 02/09/2026 na versao 2.1.259, `claude agents --json --cwd <raiz>` devolve lista
+ * vazia mesmo com sessoes vivas naquele diretorio.
+ */
+function listarSessoes(cwd, todas = false) {
+    const args = ['agents', '--json'];
+    if (todas)
+        args.push('--all');
+    const r = (0, util_1.exec)('claude', args, undefined, 60000);
+    if (!r.ok)
+        return [];
+    let dados;
+    try {
+        const bruto = JSON.parse(r.stdout);
+        dados = Array.isArray(bruto) ? bruto : [];
+    }
+    catch {
+        return [];
+    }
+    if (!cwd)
+        return dados;
+    const raiz = cwd.replace(/\/$/, '');
+    return dados.filter((s) => s.cwd === raiz || (s.cwd ?? '').startsWith(raiz + '/'));
+}
+/** Procura uma sessao pelo id curto, id completo ou nome. */
+function acharSessao(chave, sessoes) {
+    const lista = sessoes ?? listarSessoes(undefined, true);
+    return (lista.find((s) => s.sessionId === chave || s.id === chave || s.name === chave) ??
+        lista.find((s) => s.sessionId?.startsWith(chave)) ??
+        null);
+}
+/**
+ * Despacha a fase e RE-VERIFICA no runtime que a sessao existe de fato.
+ * Nao confiar no self-report do despacho e a regra 4 da paridade.
+ */
+function despachar(pedido) {
+    const comando = montarComando(pedido);
+    if (pedido.dryRun) {
+        return { ok: true, comando, sessionId: null, verificada: false, stdout: '', stderr: '' };
+    }
+    if (!disponivel()) {
+        return {
+            ok: false,
+            comando,
+            sessionId: null,
+            verificada: false,
+            stdout: '',
+            stderr: '',
+            erro: 'binario `claude` nao encontrado no PATH',
+        };
+    }
+    const r = (0, util_1.exec)(comando[0], comando.slice(1), pedido.cwd, 180000);
+    const saida = r.stdout + '\n' + r.stderr;
+    const sessionId = extrairSessionId(saida);
+    if (!r.ok || !sessionId) {
+        // Bloco B3: rate limit nao e "runtime indisponivel". Ele tem horario de reset, e por
+        // isso volta tipado daqui para virar pedido na fila duravel em vez de falha seca.
+        const rateLimit = parseRateLimit(saida);
+        return {
+            ok: false,
+            comando,
+            sessionId,
+            verificada: false,
+            stdout: r.stdout,
+            stderr: r.stderr,
+            rateLimit,
+            erro: rateLimit
+                ? `limite de uso do runtime atingido: ${rateLimit.trecho}`
+                : `despacho falhou (code ${r.code})`,
+        };
+    }
+    const achada = acharSessao(sessionId);
+    const verificada = achada !== null || acharSessao(pedido.nome) !== null;
+    return {
+        ok: true,
+        comando,
+        sessionId: achada?.sessionId ?? sessionId,
+        verificada,
+        stdout: r.stdout,
+        stderr: r.stderr,
+    };
+}
+/**
+ * O texto diz que o limite de uso da assinatura foi atingido?
+ *
+ * Reconhecimento por FRASE do runtime, nao por codigo de saida: o `claude --bg` sai com
+ * codigo generico e a unica evidencia do rate limit e o texto no stderr.
+ */
+const FRASES_DE_RATE_LIMIT = [
+    /usage limit reached/i,
+    /\brate[ _-]?limit(?:ed|s)?\b/i,
+    /too many requests/i,
+    /\b429\b/,
+    /quota exceeded/i,
+    /out of (?:usage|weekly|session) limit/i,
+];
+/**
+ * Padroes de horario de reset, do mais preciso para o menos.
+ *
+ * A ordem importa: epoch e ISO sao horario ABSOLUTO dito pelo runtime; relogio e
+ * duracao precisam da hora de agora para virar carimbo. Nenhum deles inventa nada.
+ */
+function casarEpoch(texto) {
+    // Formato real do CLI: `Claude AI usage limit reached|1757012400`.
+    const m = texto.match(/(?:limit reached|reset[^\n|]*)\|\s*(\d{10,13})\b/i);
+    if (!m)
+        return null;
+    const bruto = Number(m[1]);
+    const ms = m[1].length >= 13 ? bruto : bruto * 1000;
+    return { resetEm: new Date(ms).toISOString(), trecho: m[0].trim() };
+}
+function casarIso(texto) {
+    const m = texto.match(/(?:reset|available|try again|retry)[^\n]{0,40}?(\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2})?(?:Z|[+-]\d{2}:?\d{2})?)/i);
+    if (!m)
+        return null;
+    const data = new Date(m[1].replace(' ', 'T'));
+    if (isNaN(data.getTime()))
+        return null;
+    return { resetEm: data.toISOString(), trecho: m[0].trim() };
+}
+function casarDuracao(texto, agoraMs) {
+    const m = texto.match(
+    // A unidade aceita plural (`25 minutes`): fechar em `\b` sem o `s?` fazia o padrao
+    // inteiro falhar justamente na forma que o runtime mais usa.
+    /(?:try again|retry|reset[a-z]*|available|wait)[^\n]{0,20}?\bin\b\s*(\d+)\s*(seconds?|secs?|minutes?|mins?|hours?|hrs?|s|m|h)\b|retry[- ]after[:\s]+(\d+)/i);
+    if (!m)
+        return null;
+    if (m[3] !== undefined) {
+        // `Retry-After: 3600` e sempre em segundos.
+        return {
+            resetEm: new Date(agoraMs + Number(m[3]) * 1000).toISOString(),
+            trecho: m[0].trim(),
+        };
+    }
+    const valor = Number(m[1]);
+    const unidade = (m[2] ?? '').toLowerCase();
+    const segundos = unidade.startsWith('h')
+        ? valor * 3600
+        : unidade.startsWith('m')
+            ? valor * 60
+            : valor;
+    return { resetEm: new Date(agoraMs + segundos * 1000).toISOString(), trecho: m[0].trim() };
+}
+function casarRelogio(texto, agoraMs) {
+    const m = texto.match(/reset[a-z]*\s*(?:at|em|as)?\s*(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\b/i);
+    if (!m)
+        return null;
+    let hora = Number(m[1]);
+    const minuto = Number(m[2] ?? '0');
+    const sufixo = (m[3] ?? '').toLowerCase();
+    if (sufixo === 'pm' && hora < 12)
+        hora += 12;
+    if (sufixo === 'am' && hora === 12)
+        hora = 0;
+    if (hora > 23 || minuto > 59)
+        return null;
+    // Proxima ocorrencia daquela hora de relogio a partir de agora, no fuso da maquina.
+    const base = new Date(agoraMs);
+    const alvo = new Date(base.getFullYear(), base.getMonth(), base.getDate(), hora, minuto, 0, 0);
+    if (alvo.getTime() <= agoraMs)
+        alvo.setDate(alvo.getDate() + 1);
+    return { resetEm: alvo.toISOString(), trecho: m[0].trim() };
+}
+/**
+ * Extrai o sinal de rate limit da saida real do runtime (stdout + stderr).
+ *
+ * Devolve `null` quando o texto nao fala de limite de uso. Quando fala mas NAO diz a
+ * hora, devolve `resetEm: null` com fonte `sem-horario`: quem decide a janela padrao e
+ * a fila do B3, com a estimativa declarada. Chutar um horario aqui seria o mesmo defeito
+ * de inventar ocupacao de janela no gate de tokens.
+ */
+function parseRateLimit(saida, agoraMs = Date.now()) {
+    const texto = saida ?? '';
+    const frase = FRASES_DE_RATE_LIMIT.find((r) => r.test(texto));
+    if (!frase)
+        return null;
+    const epoch = casarEpoch(texto);
+    if (epoch)
+        return { resetEm: epoch.resetEm, fonte: 'epoch', trecho: epoch.trecho };
+    const iso = casarIso(texto);
+    if (iso)
+        return { resetEm: iso.resetEm, fonte: 'iso', trecho: iso.trecho };
+    const duracao = casarDuracao(texto, agoraMs);
+    if (duracao)
+        return { resetEm: duracao.resetEm, fonte: 'duracao', trecho: duracao.trecho };
+    const relogio = casarRelogio(texto, agoraMs);
+    if (relogio)
+        return { resetEm: relogio.resetEm, fonte: 'relogio', trecho: relogio.trecho };
+    const linha = texto.split('\n').find((l) => frase.test(l)) ?? texto;
+    return { resetEm: null, fonte: 'sem-horario', trecho: linha.trim().slice(0, 200) };
+}
+/** Comando de anexar a sessao (precisa de TTY, entao o CLI imprime em vez de executar). */
+function comandoAttach(sessionId) {
+    return `claude attach ${sessionId}`;
+}
+/**
+ * Transforma o dump de tela que o `claude logs` devolve em texto legivel.
+ *
+ * O dump e uma gravacao de terminal: as linhas sao separadas por movimento de cursor,
+ * nao por quebra de linha. Por isso o movimento vira quebra ANTES de as demais
+ * sequencias ANSI serem removidas, senao a saida inteira colapsa numa linha so.
+ */
+function limparAnsi(bruto) {
+    return bruto
+        .replace(/\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g, '')
+        .replace(/\u001b\[[0-9;]*[HfABEd]/g, '\n')
+        .replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, '')
+        .replace(/\u001b[()][A-Za-z0-9]/g, '')
+        .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '')
+        .replace(/[ \t]+$/gm, '')
+        .replace(/\n{3,}/g, '\n\n');
+}
+/**
+ * Le os logs de uma sessao.
+ *
+ * O `claude logs` aceita o id CURTO da sessao (o campo `id` de `claude agents --json`),
+ * nao o UUID completo: passar o UUID responde "No job matching". Por isso a chave e
+ * resolvida antes, e a saida (dump de tela com ANSI) e limpa aqui.
+ */
+function logs(chave, linhas = 60) {
+    const sessao = acharSessao(chave);
+    const id = sessao?.id ?? (sessao?.sessionId ?? chave).slice(0, 8);
+    const r = (0, util_1.exec)('claude', ['logs', id], undefined, 60000);
+    const bruto = limparAnsi(r.ok ? r.stdout : r.stdout + r.stderr);
+    const uteis = bruto.split('\n').filter((l) => l.trim() !== '');
+    return { ok: r.ok, texto: uteis.slice(-linhas).join('\n') };
+}
+/** Para uma sessao em background (o `claude stop` tambem trabalha com o id curto). */
+function parar(chave) {
+    const sessao = acharSessao(chave);
+    const id = sessao?.id ?? (sessao?.sessionId ?? chave).slice(0, 8);
+    const r = (0, util_1.exec)('claude', ['stop', id], undefined, 60000);
+    return { ok: r.ok, texto: limparAnsi(r.stdout + r.stderr).trim() };
+}
+/**
+ * Ocupacao da janela de contexto de uma sessao, entre 0 e 1.
+ *
+ * MEDIDO em 02/09/2026 na versao 2.1.259 do Claude Code: nem `claude agents --json` nem
+ * `claude logs` expoem uso de contexto da sessao. Entao este adapter responde `null`, e o
+ * gate de tokens declara a fonte como `unavailable`.
+ *
+ * Retornar um numero estimado aqui seria inventar dado e contaminar uma decisao real de
+ * rotacao de sessao. Quando o runtime passar a expor a metrica, e SO aqui que muda: o
+ * gate ja sabe reportar `runtime_reported` no dia em que esta funcao devolver um numero.
+ */
+function ocupacaoDeContexto(chave) {
+    void chave;
+    return null;
+}