@orkastery/cli 0.2.0

package/dist/ratelimit.js

@@ -0,0 +1,179 @@
+"use strict";
+/**
+ * Fila DURAVEL de rate limit (bloco B3).
+ *
+ * Quando o runtime da assinatura bate o limite de uso, a fase morre no meio. Ate aqui
+ * isso virava um `runtime.unavailable` seco e alguem tinha que lembrar de redespachar
+ * na mao, na janela seguinte, com o prompt certo. O B3 troca a lembranca por estado em
+ * disco: o sinal de rate limit vira um PEDIDO na fila, com o horario de reset que o
+ * proprio runtime disse, o caminho do prompt EXATO e o sha256 dele.
+ *
+ * Duas honestidades que mandam neste arquivo:
+ *
+ *   1. **Horario nunca e chutado.** Quando o stderr traz a hora (epoch, ISO, relogio ou
+ *      duracao), ela e o `liberaEm`. Quando nao traz, o `liberaEm` sai da janela padrao
+ *      do manifesto e o pedido carrega `janelaEstimada: true`. Estimativa declarada e
+ *      diferente de medida inventada, a mesma regra do gate de tokens.
+ *   2. **O prompt nao muda entre a morte e a retomada.** A retomada confere o sha256 do
+ *      arquivo antes de despachar. Prompt alterado nao e retomada, e outro despacho.
+ *
+ * Este modulo e FOLHA de proposito: ele guarda e le a fila. Quem redespacha e o
+ * `retry.ts`, que e quem pode importar o `phase.ts` sem criar ciclo.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRateLimit = void 0;
+exports.dirRetry = dirRetry;
+exports.caminhoDaFila = caminhoDaFila;
+exports.lerFilaDeRetomada = lerFilaDeRetomada;
+exports.janelaPadraoMs = janelaPadraoMs;
+exports.enfileirar = enfileirar;
+exports.gravarPedido = gravarPedido;
+exports.exigirPedido = exigirPedido;
+exports.aguardando = aguardando;
+exports.vencidos = vencidos;
+exports.faltaPara = faltaPara;
+exports.tabelaDaFila = tabelaDaFila;
+const path = __importStar(require("node:path"));
+const manifest_1 = require("./manifest");
+const util_1 = require("./util");
+var claude_bg_1 = require("./adapters/claude-bg");
+Object.defineProperty(exports, "parseRateLimit", { enumerable: true, get: function () { return claude_bg_1.parseRateLimit; } });
+/** Diretorio de estado da autonomia do B3. */
+function dirRetry(raiz) {
+    return path.join((0, manifest_1.dirEstado)(raiz), 'retry');
+}
+/**
+ * Fila duravel do projeto.
+ *
+ * Fica no projeto, e nao na thread, porque o limite de uso e da ASSINATURA: uma fase de
+ * outra thread que morre no mesmo minuto espera a mesma janela, e quem olha a fila
+ * precisa ver as duas de uma vez.
+ */
+function caminhoDaFila(raiz) {
+    return path.join(dirRetry(raiz), 'fila.jsonl');
+}
+/** Le a fila inteira (JSONL append-only: a ultima gravacao de um id vence). */
+function lerFilaDeRetomada(raiz) {
+    return (0, util_1.lerJsonl)(caminhoDaFila(raiz));
+}
+/** Janela padrao do manifesto, em ms, usada so quando o runtime nao disse a hora. */
+function janelaPadraoMs(manifesto) {
+    return manifesto.retry.janela_padrao_min * 60 * 1000;
+}
+/**
+ * Enfileira a fase morta por rate limit.
+ *
+ * `liberaEm` sai do horario que o runtime disse; sem horario, da janela padrao, e ai o
+ * pedido nasce com `janelaEstimada: true` para o `ork retry list` mostrar a diferenca.
+ */
+function enfileirar(carregado, novo, agoraMs = Date.now()) {
+    const { raiz, manifesto } = carregado;
+    const ids = lerFilaDeRetomada(raiz).map((p) => p.id);
+    const estimada = novo.sinal.resetEm === null;
+    const pedido = {
+        id: (0, util_1.proximoIdSequencial)(ids, 'R'),
+        thread: novo.thread,
+        fase: novo.fase,
+        slug: novo.slug,
+        promptPath: path.isAbsolute(novo.promptPath)
+            ? path.relative(raiz, novo.promptPath)
+            : novo.promptPath,
+        promptSha256: novo.promptSha256,
+        cwd: novo.cwd,
+        model: novo.model,
+        effort: novo.effort,
+        sinal: novo.sinal,
+        liberaEm: novo.sinal.resetEm ?? new Date(agoraMs + janelaPadraoMs(manifesto)).toISOString(),
+        janelaEstimada: estimada,
+        tentativas: 0,
+        estado: 'aguardando',
+        criadoEm: (0, util_1.agora)(),
+        atualizadoEm: (0, util_1.agora)(),
+        detalhe: novo.detalhe,
+    };
+    (0, util_1.anexarJsonl)(caminhoDaFila(raiz), pedido);
+    return pedido;
+}
+/** Regrava um pedido (append-only: a versao nova vence, o historico fica). */
+function gravarPedido(raiz, pedido) {
+    const atualizado = { ...pedido, atualizadoEm: (0, util_1.agora)() };
+    (0, util_1.anexarJsonl)(caminhoDaFila(raiz), atualizado);
+    return atualizado;
+}
+/** Um pedido pelo id, ou erro acionavel quando o id nao existe. */
+function exigirPedido(raiz, id) {
+    const achado = lerFilaDeRetomada(raiz).find((p) => p.id === id);
+    if (!achado) {
+        throw new Error(`pedido "${id}" nao existe na fila de rate limit (veja: ork retry list)`);
+    }
+    return achado;
+}
+/** Pedidos ainda aguardando, na ordem em que a janela libera. */
+function aguardando(raiz) {
+    return lerFilaDeRetomada(raiz)
+        .filter((p) => p.estado === 'aguardando')
+        .sort((a, b) => a.liberaEm.localeCompare(b.liberaEm));
+}
+/** Pedidos cuja janela JA liberou no instante informado (padrao: agora). */
+function vencidos(raiz, quando = (0, util_1.agora)()) {
+    return aguardando(raiz).filter((p) => p.liberaEm <= quando);
+}
+/** Quanto falta para a janela de um pedido, em texto curto para o CLI. */
+function faltaPara(pedido, quando = (0, util_1.agora)()) {
+    const ms = new Date(pedido.liberaEm).getTime() - new Date(quando).getTime();
+    if (ms <= 0)
+        return 'ja liberou';
+    const min = Math.ceil(ms / 60000);
+    return min < 60 ? `em ${min} min` : `em ${Math.floor(min / 60)}h${String(min % 60).padStart(2, '0')}`;
+}
+/** Tabela de `ork retry list`. */
+function tabelaDaFila(raiz, quando = (0, util_1.agora)()) {
+    const fila = lerFilaDeRetomada(raiz).sort((a, b) => a.id.localeCompare(b.id, 'en', { numeric: true }));
+    if (fila.length === 0) {
+        return 'Fila de rate limit vazia: nenhuma fase morreu por limite de uso neste projeto.';
+    }
+    const linhas = fila.map((p) => [
+        p.id,
+        p.thread,
+        p.fase,
+        p.estado,
+        p.liberaEm.replace('T', ' ').slice(0, 16),
+        p.janelaEstimada ? `estimada (${p.sinal.fonte})` : `dita pelo runtime (${p.sinal.fonte})`,
+        p.estado === 'aguardando' ? faltaPara(p, quando) : '',
+        String(p.tentativas),
+    ]);
+    return (0, util_1.tabela)(['ID', 'THREAD', 'FASE', 'ESTADO', 'LIBERA EM', 'ORIGEM DA HORA', 'FALTA', 'TENT'], linhas);
+}

package/dist/recall.js

@@ -0,0 +1,252 @@
+"use strict";
+/**
+ * `ork recall` (bloco B6): recuperacao TARDIA do que ficou fora do prompt.
+ *
+ * O problema que este comando resolve e o da janela queimada na abertura: uma sessao nova
+ * que recebe tudo o que a anterior sabia comeca cheia e sem espaco para trabalhar. O
+ * handoff do B1 ja separava CRITICO (inline) de IMPORTANTE (ponteiro); o que faltava era
+ * o outro lado da promessa, o momento de puxar o ponteiro.
+ *
+ * A regra e o campo `retrieve_when` do ponteiro:
+ *
+ *   - `ork recall <thread> --fase CHECK` resolve SO os ponteiros marcados para o CHECK;
+ *   - um ponteiro de CHECK pedido no GO volta como `fora-do-momento`, SEM conteudo: nao
+ *     adianta ter momento declarado se o comando entrega o texto de qualquer jeito;
+ *   - `--forcar` existe para o humano, e diz no resultado que o momento foi ignorado.
+ *
+ * A degradacao e a mesma do resto do bloco. Com OrkMind ligado, um ponteiro que tem
+ * endereco semantico (`orkmind://<colecao>/<id>`) resolve por tag. Com o OrkMind fora, o
+ * MESMO ponteiro resolve pelo `location` (`path#ancora`), por leitura dirigida, sem que o
+ * fluxo de quem le o handoff mude em nada.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.momentoCasa = momentoCasa;
+exports.lerHandoff = lerHandoff;
+exports.resolverPonteiro = resolverPonteiro;
+exports.recallDaThread = recallDaThread;
+exports.textoDoRecall = textoDoRecall;
+const fs = __importStar(require("node:fs"));
+const handoff_1 = require("./handoff");
+const ledger_1 = require("./ledger");
+const orkmind_1 = require("./orkmind");
+const thread_1 = require("./thread");
+const util_1 = require("./util");
+/** Momento do ponteiro e momento pedido casam? Comparacao exata, sem case. */
+function momentoCasa(ponteiro, momento) {
+    return ponteiro.retrieve_when.trim().toLowerCase() === momento.trim().toLowerCase();
+}
+/** Le o handoff mais recente da thread, com erro acionavel quando ele nao existe. */
+function lerHandoff(raiz, threadId) {
+    const caminho = (0, handoff_1.caminhoHandoff)(raiz, threadId);
+    if (!fs.existsSync(caminho)) {
+        throw new Error(`a thread ${threadId} nao tem handoff exportado (${caminho}). Rode: ork handoff export ${threadId}`);
+    }
+    return (0, util_1.lerJson)(caminho);
+}
+function naoResolvido(p, motivo, detalhe) {
+    return {
+        id: p.id,
+        titulo: p.titulo,
+        location: p.location,
+        orkmind: p.orkmind ?? null,
+        retrieve_when: p.retrieve_when,
+        resolvido: false,
+        motivo,
+        via: null,
+        conteudo: '',
+        metodo: '',
+        sha256: p.sha256,
+        intervalo: null,
+        detalhe,
+    };
+}
+/**
+ * Resolve UM ponteiro, escolhendo a via pelo regime efetivo.
+ *
+ * Preferencia pela memoria semantica quando ela existe e o ponteiro tem endereco; queda
+ * para o arquivo quando ela nao existe, quando o endereco nao resolve ou quando o
+ * ponteiro nunca teve endereco (todo handoff do regime `files`).
+ */
+function resolverPonteiro(carregado, memoria, threadId, p) {
+    if (memoria.ativo && p.orkmind) {
+        const endereco = (0, orkmind_1.lerEndereco)(p.orkmind);
+        const entrada = endereco ? memoria.porId(endereco.colecao, endereco.id) : null;
+        if (entrada) {
+            return {
+                id: p.id,
+                titulo: p.titulo,
+                location: p.location,
+                orkmind: p.orkmind,
+                retrieve_when: p.retrieve_when,
+                resolvido: true,
+                motivo: 'ok',
+                via: 'orkmind',
+                conteudo: entrada.content,
+                metodo: `entrada ${entrada.collection} recuperada por tag na memoria semantica`,
+                sha256: p.sha256,
+                intervalo: null,
+                detalhe: `orkmind://${entrada.collection}/${entrada.id}`,
+            };
+        }
+    }
+    try {
+        const r = (0, handoff_1.recall)(carregado, threadId, p.location);
+        return {
+            id: p.id,
+            titulo: p.titulo,
+            location: p.location,
+            orkmind: p.orkmind ?? null,
+            retrieve_when: p.retrieve_when,
+            resolvido: true,
+            motivo: 'ok',
+            via: 'files',
+            conteudo: r.conteudo,
+            metodo: r.metodo,
+            sha256: r.sha256,
+            intervalo: r.intervalo,
+            detalhe: memoria.ativo && p.orkmind
+                ? 'endereco semantico nao resolveu; o mesmo ponteiro caiu para path#ancora'
+                : 'leitura dirigida por path#ancora (regime files)',
+        };
+    }
+    catch (e) {
+        const semantico = memoria.estado.efetivo === 'files' && p.orkmind;
+        return naoResolvido(p, semantico ? 'orkmind-indisponivel' : 'nao-resolve', e.message);
+    }
+}
+/**
+ * `ork recall`: resolve os ponteiros do handoff que sao DESTE momento.
+ *
+ * O que nao e deste momento volta em `adiados`, com o momento declarado: a sessao sabe
+ * que existe, sabe onde esta e sabe quando puxar, sem gastar janela agora. E o item 4 da
+ * secao 6.1 da visao (rastreabilidade): nada some, nada entra sem hora marcada.
+ */
+function recallDaThread(carregado, memoria, threadId, opcoes = {}) {
+    const { raiz } = carregado;
+    // Thread inexistente e erro, nao lista vazia: o CLI precisa reprovar o id errado.
+    (0, thread_1.lerThread)(raiz, threadId);
+    const handoff = lerHandoff(raiz, threadId);
+    const momento = opcoes.momento ?? null;
+    const resolvidos = [];
+    const adiados = [];
+    const falhas = [];
+    for (const p of handoff.pointers) {
+        const pedidoPorId = opcoes.id !== undefined && (p.id === opcoes.id || p.location === opcoes.id);
+        if (opcoes.id !== undefined && !pedidoPorId)
+            continue;
+        const naHora = opcoes.forcar === true ||
+            opcoes.todos === true ||
+            pedidoPorId ||
+            (momento !== null && momentoCasa(p, momento));
+        if (!naHora) {
+            adiados.push(naoResolvido(p, 'fora-do-momento', momento === null
+                ? `sem momento pedido: este ponteiro e do momento "${p.retrieve_when}"`
+                : `este ponteiro e do momento "${p.retrieve_when}", e o pedido foi "${momento}"`));
+            continue;
+        }
+        const r = resolverPonteiro(carregado, memoria, threadId, p);
+        if (r.resolvido)
+            resolvidos.push(r);
+        else
+            falhas.push(r);
+    }
+    if (opcoes.id !== undefined && resolvidos.length === 0 && falhas.length === 0 && adiados.length === 0) {
+        throw new Error(`ponteiro "${opcoes.id}" nao existe no handoff da thread ${threadId} ` +
+            `(ids: ${handoff.pointers.map((p) => p.id).join(', ') || 'nenhum'})`);
+    }
+    const resultado = {
+        thread: threadId,
+        momento,
+        regime: memoria.regime,
+        regimeDoHandoff: handoff.memory,
+        resolvidos,
+        adiados,
+        falhas,
+        resolvidoEm: (0, util_1.agora)(),
+    };
+    (0, ledger_1.registrar)((0, thread_1.dirThread)(raiz, threadId), threadId, ledger_1.TIPOS_DE_EVENTO.recallResolvido, {
+        momento: momento ?? '(todos)',
+        regime: memoria.regime,
+        regimeDoHandoff: handoff.memory,
+        resolvidos: resolvidos.length,
+        adiados: adiados.length,
+        falhas: falhas.length,
+        forcado: opcoes.forcar === true,
+        vias: resolvidos.map((r) => `${r.id}:${r.via}`),
+        bytes: resolvidos.reduce((t, r) => t + Buffer.byteLength(r.conteudo, 'utf8'), 0),
+    });
+    return resultado;
+}
+/** Texto de `ork recall`. */
+function textoDoRecall(r, comConteudo = true) {
+    const linhas = [];
+    linhas.push(`Recall da thread ${r.thread} no momento ${r.momento ?? '(todos)'} ` +
+        `(regime efetivo ${r.regime}, handoff escrito em regime ${r.regimeDoHandoff})`);
+    linhas.push('');
+    linhas.push(`RESOLVIDOS (${r.resolvidos.length}, entram no contexto agora):`);
+    for (const p of r.resolvidos) {
+        linhas.push(`  ${p.id}  ${p.titulo}`);
+        linhas.push(`        via       ${p.via} (${p.metodo})`);
+        linhas.push(`        location  ${p.location}`);
+        if (p.orkmind)
+            linhas.push(`        orkmind   ${p.orkmind}`);
+        linhas.push(`        quando    ${p.retrieve_when}`);
+        if (comConteudo) {
+            linhas.push('');
+            for (const l of p.conteudo.split('\n'))
+                linhas.push(`        | ${l}`);
+            linhas.push('');
+        }
+    }
+    linhas.push('');
+    linhas.push(`ADIADOS (${r.adiados.length}, existem e NAO entram agora):`);
+    for (const p of r.adiados) {
+        linhas.push(`  ${p.id}  ${p.titulo}`);
+        linhas.push(`        quando    ${p.retrieve_when}`);
+        linhas.push(`        onde      ${p.location}`);
+        linhas.push(`        recuperar ork recall ${r.thread} --fase ${p.retrieve_when}`);
+    }
+    if (r.falhas.length > 0) {
+        linhas.push('');
+        linhas.push(`FALHAS (${r.falhas.length}):`);
+        for (const p of r.falhas) {
+            linhas.push(`  ${p.id}  ${p.titulo}`);
+            linhas.push(`        motivo    ${p.motivo}`);
+            linhas.push(`        detalhe   ${p.detalhe}`);
+        }
+    }
+    return linhas.join('\n');
+}