@orkastery/cli 0.2.0 → 0.4.1

package/adapters/openclaw/src/hitl-ingress.ts

@@ -0,0 +1,180 @@
+/** Native inbound_claim hook only. Never register this callback as a model tool. */
+/** D12: this host is the `openclaw` channel, and the channel is signed, not labelled. */
+import { createHash, createHmac } from 'node:crypto';
+import { execFile } from 'node:child_process';
+
+interface NativeEvent {
+  content: string; channel: string; commandAuthorized?: boolean; accountId?: string;
+  senderId?: string; conversationId?: string; messageId?: string; timestamp?: number;
+  sessionKey?: string; senderIsOwner?: boolean;
+}
+interface NativeContext { channelId: string; accountId?: string; senderId?: string; conversationId?: string; messageId?: string; sessionKey?: string }
+interface NativeApi { on: (name: 'inbound_claim', handler: (event: NativeEvent, ctx: NativeContext) => unknown) => void }
+
+/**
+ * I-41 (GO-FIX 1): the two shapes of an answer to the pulse summary, typed with no slash and no
+ * identifier: "P4EJ a" answers the summary and "1a 2c" answers the questions. The SAME sources
+ * live in the core (GRAMATICA_DO_PULSE, core/src/pulse-resposta.ts) and a core test checks they
+ * stay equal. The code starts with a letter and has a digit: ordinary chat never has this shape,
+ * and it never reads as an answer to the batch, which starts with the question number.
+ */
+const PULSE_CONSENT = new RegExp("^[ \\t]*(?=[A-HJKMNP-TV-Z][2-9A-HJKMNP-TV-Z]{0,2}[2-9])[A-HJKMNP-TV-Z][2-9A-HJKMNP-TV-Z]{3}[ \\t]+[^\\r\\n]{1,40}$", 'i');
+const PULSE_LOTE = new RegExp("^[ \\t]*[0-9]{1,2}[ \\t]*[a-zA-Z](?:[ \\t,;]*[0-9]{1,2}[ \\t]*[a-zA-Z])*[ \\t]*[.!]?[ \\t]*$");
+/** I-50 (RM-039): the pulse cadence tag, alone in the message. It starts with '#', so it never reads as the other two. */
+const PULSE_CADENCIA = new RegExp("^[ \\t]*#OrkPulse(?:On(?:-(?:15|30|60)m)?|Off)[ \\t]*[.!]?[ \\t]*$", 'i');
+/** The pulse address inside the signed body: neither a thread nor a request. The core translates. */
+const PULSE_ALVO = 'pulse', PULSE_ENDERECO = 'resposta';
+export function isPulseAnswer(text: string): boolean {
+  return !text.includes('\0') && (PULSE_CONSENT.test(text) || PULSE_LOTE.test(text) || PULSE_CADENCIA.test(text));
+}
+
+export function registerHitlIngress(api: NativeApi, bin: string): void {
+  api.on('inbound_claim', async (event, ctx) => {
+    if (typeof event.content !== 'string') return { handled: false };
+    const pulse = !event.content.startsWith('/ork ') && isPulseAnswer(event.content);
+    if (!event.content.startsWith('/ork ') && !pulse) return { handled: false };
+    const denied = { handled: true, reply: { text: 'Resposta HITL não confirmada. Confira ingresso e ledger do pedido.' } };
+    // The pulse summary goes out on Telegram; only there is an answer to it recognized.
+    if (event.channel !== 'telegram') return pulse ? { handled: false } : nativeIngress(event, ctx, bin).catch(() => denied);
+    try {
+      const env = process.env, user = event.senderId ?? '', chat = event.conversationId ?? '', message = event.messageId ?? '';
+      const allowed = (key: string, value: string) => (env[key] ?? '').split(',').map(s => s.trim()).filter(Boolean).includes(value);
+      const age = Date.now() - Number(event.timestamp);
+      if (event.channel !== 'telegram' || ctx.channelId !== 'telegram' || event.commandAuthorized !== true ||
+          !env.ORK_HITL_OPENCLAW_ACCOUNT || event.accountId !== env.ORK_HITL_OPENCLAW_ACCOUNT || event.accountId !== ctx.accountId ||
+          !env.ORK_HITL_TELEGRAM_BOT_ID || user === env.ORK_HITL_TELEGRAM_BOT_ID ||
+          !/^\d+$/.test(user) || !/^-?\d+$/.test(chat) || !/^\d+$/.test(message) ||
+          user !== ctx.senderId || chat !== ctx.conversationId || message !== ctx.messageId ||
+          !allowed('ORK_HITL_TELEGRAM_USERS', user) || !allowed('ORK_HITL_TELEGRAM_CHATS', chat) ||
+          !Number.isFinite(age) || age < 0 || age > 60000) return denied;
+      const match = /^\/ork (gate|session) ([a-zA-Z0-9][a-zA-Z0-9._-]{0,79}) ([a-zA-Z0-9][a-zA-Z0-9._-]{0,79}) ([\s\S]{1,4096})$/.exec(event.content);
+      // FX1: this channel signs with ITS OWN key. The shared ORK_HITL_INGRESS_KEY is kept
+      // for the legacy v1 envelope only, which this adapter no longer produces.
+      const key = env.ORK_HITL_INGRESS_KEY_OPENCLAW, root = env.ORK_HITL_ROOT;
+      if ((!pulse && !match) || event.content.includes('\0') || !key || Buffer.byteLength(key) < 32 || !root?.startsWith('/')) return denied;
+      if (pulse) return pulseIngress(event.content, { user, chat, message, key, root, bin, timestamp: Number(event.timestamp) }, denied);
+      const [, operation, thread, pedido, resposta] = match!;
+      const canal = 'openclaw';
+      // FX5: the authorized account goes INSIDE the signed body. Checking `accountId` only
+      // here left the durable receipt proving generic telegram transport and nothing else:
+      // nobody reading it later could tell which OpenClaw account the decision came from.
+      const conta = env.ORK_HITL_OPENCLAW_ACCOUNT;
+      const envelope = { resposta, canal, conta, origem: 'telegram', por: `telegram:${user}`, mensagem: `telegram:${chat}:${message}`,
+        recebidoEm: new Date(Number(event.timestamp)).toISOString(), prova: '' };
+      envelope.prova = createHmac('sha256', key).update(JSON.stringify(['ork.hitl-answer/v2', thread, pedido, canal, conta,
+        envelope.origem, envelope.por, envelope.mensagem, envelope.recebidoEm, resposta])).digest('hex');
+      // `gate answer` exige --resposta-stdin; `sessions answer` exige --stdin. A mesma flag
+      // para os dois fazia o CLI recusar toda resposta de sessao antes de conferir qualquer coisa.
+      const args = [operation === 'gate' ? 'gate' : 'sessions', 'answer', thread, pedido,
+        operation === 'gate' ? '--resposta-stdin' : '--stdin',
+        '--origem', 'telegram', '--canal', canal, '--conta', conta, '--por', envelope.por, '--mensagem', envelope.mensagem];
+      // FX5: `ok` alone was never a receipt. The core answers with the typed verdict, and a
+      // reply to the human must only claim what that verdict says: a gate lands in one of
+      // three states, a session answer lands `entregue` with the session it reached, and
+      // `repetida` says whether this call caused the effect or merely found it already done.
+      const estados = operation === 'gate' ? ['aprovado', 'recusado', 'aguardando'] : ['entregue'];
+      const ok = await new Promise<boolean>(resolve => {
+        const child = execFile(bin, args, { cwd: root, timeout: 10000, maxBuffer: 65536 }, (err, stdout) => {
+          try {
+            const r = JSON.parse(stdout);
+            resolve(!err && r.ok === true && r.pedidoId === pedido && estados.includes(r.estado) &&
+              typeof r.repetida === 'boolean' &&
+              (operation === 'gate' || typeof r.sessionId === 'string' && r.sessionId.length > 0));
+          } catch { resolve(false); }
+        });
+        child.stdin?.on('error', () => resolve(false));
+        child.stdin?.end(JSON.stringify(envelope));
+      });
+      return ok ? { handled: true, reply: { text: `Resposta recebida pelo núcleo para o pedido ${pedido}.` } } : denied;
+    } catch { return denied; }
+  });
+}
+
+/**
+ * I-41 (GO-FIX 1): the owner answered the pulse summary or its questions. The whole text is the
+ * answer and the signed address is the pulse's; this adapter knows no request and picks nothing.
+ * The reply is the text the core composed, transported as is.
+ */
+async function pulseIngress(texto: string, m: { user: string; chat: string; message: string; key: string; root: string;
+  bin: string; timestamp: number }, denied: { handled: boolean; reply: { text: string } }) {
+  const canal = 'openclaw', conta = process.env.ORK_HITL_OPENCLAW_ACCOUNT ?? '';
+  const envelope = { resposta: texto, canal, conta, origem: 'telegram', por: `telegram:${m.user}`,
+    mensagem: `telegram:${m.chat}:${m.message}`, recebidoEm: new Date(m.timestamp).toISOString(), prova: '' };
+  envelope.prova = createHmac('sha256', m.key).update(JSON.stringify(['ork.hitl-answer/v2', PULSE_ALVO, PULSE_ENDERECO, canal, conta,
+    envelope.origem, envelope.por, envelope.mensagem, envelope.recebidoEm, texto])).digest('hex');
+  const args = ['pulse', 'responder', '--resposta-stdin', '--origem', 'telegram', '--canal', canal, '--conta', conta,
+    '--por', envelope.por, '--mensagem', envelope.mensagem];
+  const receipt = await new Promise<any>(resolve => {
+    const child = execFile(m.bin, args, { cwd: m.root, timeout: 10000, maxBuffer: 65536 }, (err, stdout) => {
+      try { resolve(err ? null : JSON.parse(stdout)); } catch { resolve(null); }
+    });
+    child.stdin?.on('error', () => resolve(null));
+    child.stdin?.end(JSON.stringify(envelope));
+  });
+  if (!receipt || receipt.ok !== true || receipt.contrato !== 'ork.pulse-resposta/v1' ||
+      typeof receipt.mensagem !== 'string' || !receipt.mensagem || typeof receipt.repetida !== 'boolean') return denied;
+  // Same message already handled: never resend blindly.
+  return receipt.repetida ? { handled: true } : { handled: true, reply: { text: receipt.mensagem } };
+}
+
+/** SDK instalado: inbound_claim fornece commandAuthorized, senderIsOwner e sessionKey.
+ * Somente esta callback usa a chave privada; nenhuma tool registra nativeIngress. */
+async function nativeIngress(event: NativeEvent, ctx: NativeContext, bin: string) {
+  const denied = { handled: true, reply: { text: 'Ingresso nativo indisponível ou identidade não comprovada. O pedido permanece pendente.' } };
+  const env = process.env, root = env.ORK_HITL_ROOT, key = env.ORK_HITL_NATIVE_KEY_OPENCLAW;
+  const binding = JSON.parse(env.ORK_HITL_NATIVE_BINDING_OPENCLAW ?? 'null');
+  const age = Date.now() - Number(event.timestamp);
+  if (!binding || binding.host !== 'openclaw' || !root?.startsWith('/') || !key || Buffer.byteLength(key) < 32 ||
+      event.commandAuthorized !== true || event.senderIsOwner !== true ||
+      !event.sessionKey || event.sessionKey !== ctx.sessionKey || event.sessionKey !== binding.sessionId ||
+      !event.messageId || event.messageId !== ctx.messageId || !binding.installationId || !binding.connectionId ||
+      event.channel !== ctx.channelId || event.channel !== binding.channelId ||
+      event.accountId !== ctx.accountId || event.accountId !== binding.accountId ||
+      event.senderId !== ctx.senderId || event.senderId !== binding.personId ||
+      event.conversationId !== ctx.conversationId || event.conversationId !== binding.conversationId ||
+      !Number.isFinite(age) || age < 0 || age > 60000) return denied;
+  const match = /^\/ork (offer|gate|session) ([a-zA-Z0-9][a-zA-Z0-9._-]{0,79}) ([a-zA-Z0-9][a-zA-Z0-9._-]{0,79})(?: ([\s\S]{1,4096}))?$/.exec(event.content);
+  if (!match || event.content.includes('\0') || (match[1] === 'offer' ? match[4] !== undefined : !match[4])) return denied;
+  const [, operation, thread, pedido, resposta] = match;
+  const call = (args: string[], input?: unknown) => new Promise<any>((resolve, reject) => {
+    const child = execFile(bin, args, { cwd: root, timeout: 10000, maxBuffer: 65536 }, (error, stdout) => {
+      if (error) { reject(Error('native.core.unavailable')); return; }
+      try { resolve(JSON.parse(stdout)); } catch { reject(Error('native.core.invalid')); }
+    });
+    child.stdin?.on('error', () => reject(Error('native.core.unavailable')));
+    if (input !== undefined) child.stdin?.end(JSON.stringify(input));
+  });
+  const offer = { native: { ...binding, messageId: event.messageId }, recebidoEm: new Date(Number(event.timestamp)).toISOString(), prova: '' };
+  const b = offer.native;
+  offer.prova = createHmac('sha256', key).update(JSON.stringify(['ork.hitl-native-offer/v1', thread, pedido,
+    b.host, b.installationId, b.connectionId, b.sessionId, b.accountId, b.channelId,
+    b.conversationId, b.personId, b.messageId, offer.recebidoEm])).digest('hex');
+  const view = await call(['gate', 'context', thread, pedido, '--native-offer-stdin'], offer);
+  if (view.pedido?.id !== pedido || view.pedido?.thread !== thread || (operation !== 'offer' && view.pedido?.alvo?.tipo !== operation) ||
+      !view.canais?.some((c: any) => c.canal === 'openclaw' && c.transporte === 'native' && c.estado === 'disponivel') ||
+      !/^[a-f0-9]{64}$/.test(view.contexto) || !/^[a-f0-9]{64}$/.test(view.pedidoSha256)) return denied;
+  if (operation === 'offer') {
+    if (typeof view.apresentacao?.mensagem !== 'string') return denied;
+    // I-35: o prazo chega ao dono no fuso dele; núcleo de outra versão pode não ter posto o
+    // prazo local na mensagem, então o campo local vai junto.
+    const prazo = typeof view.prazoLocal === 'string' && view.prazoLocal && !view.apresentacao.mensagem.includes(view.prazoLocal)
+      ? `\nPrazo (fuso do dono): ${view.prazoLocal}` : '';
+    return { handled: true, reply: { text: view.apresentacao.mensagem + prazo + '\nCanal nativo OpenClaw disponível nesta conversa.' } };
+  }
+  const n = { ...binding, messageId: event.messageId, context: view.contexto,
+    pedidoSha256: view.pedidoSha256, expiresAt: view.pedido.prazo };
+  const message = 'native:' + createHash('sha256').update(JSON.stringify([n.host, n.installationId, n.connectionId,
+    n.sessionId, n.channelId, n.accountId, n.conversationId, n.messageId])).digest('hex');
+  const r = { origem: 'native', canal: 'openclaw', conta: n.accountId, native: n, por: `native:openclaw:${n.personId}`,
+    mensagem: message, recebidoEm: new Date(Number(event.timestamp)).toISOString(), resposta, prova: '' };
+  r.prova = createHmac('sha256', key).update(JSON.stringify(['ork.hitl-native/v1', thread, pedido,
+    n.host, n.installationId, n.connectionId, n.sessionId, n.accountId, n.channelId, n.conversationId, n.personId,
+    n.messageId, n.context, n.pedidoSha256, n.expiresAt, r.origem, r.canal, r.conta, r.por, r.mensagem, r.recebidoEm, resposta])).digest('hex');
+  const receipt = await call([operation === 'gate' ? 'gate' : 'sessions', 'answer', thread, pedido,
+    operation === 'gate' ? '--resposta-stdin' : '--stdin', '--origem', 'native', '--canal', 'openclaw',
+    '--conta', r.conta, '--por', r.por, '--mensagem', message], r);
+  if (receipt.ok !== true || receipt.pedidoId !== pedido || typeof receipt.repetida !== 'boolean' ||
+      !(operation === 'gate' ? ['aprovado', 'recusado', 'aguardando'] : ['entregue']).includes(receipt.estado) ||
+      (operation === 'session' && !receipt.sessionId)) return denied;
+  return receipt.repetida ? { handled: true } : { handled: true, reply: { text: 'Resposta nativa confirmada pelo núcleo.' } };
+}

package/adapters/openclaw/src/index.ts

@@ -0,0 +1,460 @@
+/**
+ * Plugin Orkastery para OpenClaw, no formato de extensao 2026.7.1.
+ *
+ * Zero regra de negocio no host: cada tool monta um VETOR argv e chama o CLI
+ * `ork`. O parse da #TAG, a validacao de modo, gates e verificacao vivem no
+ * nucleo, com teste. Tool nova que precisa de logica e sinal de que a logica
+ * pertence ao `ork`.
+ */
+import { registerHitlIngress } from './hitl-ingress.js';
+import { execFile } from 'node:child_process';
+import { defineToolPlugin } from 'openclaw/plugin-sdk/tool-plugin';
+
+/**
+ * Renderizado pelo `ork adapter install openclaw` para o caminho absoluto do
+ * `ork` desta maquina. Se a copia nao passou pelo instalador, o placeholder
+ * sobrevive e o fallback abaixo usa ORK_BIN do ambiente ou o `ork` do PATH.
+ */
+const ORK_RENDERIZADO = '{{ork_bin}}';
+
+/**
+ * Abre-chaves duplo montado por concatenacao: o arquivo instalado nao pode
+ * conter o par literal fora do placeholder, porque a prova do pitfall 1 e o
+ * grep pelo par devolvendo 0 no dist renderizado.
+ */
+const MARCA_DE_PLACEHOLDER = '{' + '{';
+
+function resolverOrkBin(): string {
+  if (!ORK_RENDERIZADO.startsWith(MARCA_DE_PLACEHOLDER)) return ORK_RENDERIZADO;
+  const doAmbiente = process.env.ORK_BIN;
+  if (doAmbiente && doAmbiente.trim() !== '') return doAmbiente;
+  return 'ork';
+}
+
+/** Limite generoso para saidas de board/ledger sem estourar o buffer padrao. */
+const MAX_BUFFER = 16 * 1024 * 1024;
+
+/**
+ * Roda o `ork` com argv em vetor (nunca string de shell: um pedido com espaco,
+ * aspas ou quebra de linha chega inteiro em --prompt). Devolve stdout+stderr
+ * como texto; exit diferente de zero vira texto prefixado, nunca excecao, para
+ * o agente ler o erro tipado do nucleo em vez de um stack trace do host.
+ */
+async function rodarOrk(args: string[], signal?: AbortSignal, entrada?: string): Promise<string> {
+  const bin = resolverOrkBin();
+  const parentEnv = { ...process.env };
+  const hasPrivateHitlAuthority = Object.keys(parentEnv).some((name) => /^ORK_HITL_(?:INGRESS_KEY|NATIVE_KEY)/.test(name));
+  // O núcleo prepara recibos legados do ORK_HITL_ROOT confiável e deriva a raiz
+  // pública antes de sanitizar. Nenhum argumento do modelo chega ao helper.
+  let verifiers: string | undefined;
+  try {
+    verifiers = await new Promise<string | undefined>((resolve, reject) => {
+      execFile(bin, ['receipt-verifiers', '--json'], { env: parentEnv, signal, timeout: 5000, maxBuffer: 4096 },
+        (error, stdout) => {
+          if (error) return reject(error);
+          try {
+            const value = JSON.parse(stdout);
+            if (value !== null && value.schema !== 'ork.hitl-verifiers/v1') throw Error('invalid');
+            if (hasPrivateHitlAuthority && (!value || !value.verifiers || !Object.keys(value.verifiers).length)) throw Error('missing');
+            resolve(value === null ? undefined : JSON.stringify(value));
+          } catch (error) { reject(error); }
+        });
+    });
+  } catch {
+    // Sem autoridade HITL não há segredo a transformar: comandos comuns seguem
+    // com o ambiente sanitizado. Com autoridade presente, falhamos fechado para
+    // nunca entregar ao executor uma sessão incapaz de verificar seus recibos.
+    if (hasPrivateHitlAuthority) return '[ork recusou] hitl.receipt.verifiers-unavailable';
+  }
+  // Tools do modelo não herdam a autoridade da callback humana no mesmo host.
+  const env = Object.fromEntries(Object.entries(parentEnv).filter(([name]) => !name.startsWith('ORK_HITL_') && name !== 'ORK_RECEIPT_VERIFIERS'));
+  if (verifiers) env.ORK_RECEIPT_VERIFIERS = verifiers;
+  // I-36 (D6): o adaptador declara o proprio canal de conducao. Descreve a porta, nao concede autoridade.
+  env.ORK_CANAL = 'openclaw';
+  return new Promise((resolve) => {
+    const filho = execFile(bin, args, { maxBuffer: MAX_BUFFER, signal, env }, (erro, stdout, stderr) => {
+      const partes = [stdout, stderr].map((t) => (t ?? '').trim()).filter((t) => t !== '');
+      const saida = partes.join('\n');
+      if (!erro) {
+        resolve(saida === '' ? 'ok (sem saida)' : saida);
+        return;
+      }
+      const codigo = typeof (erro as NodeJS.ErrnoException).code === 'string'
+        ? (erro as NodeJS.ErrnoException).code
+        : ((erro as unknown as { code?: number }).code ?? 'desconhecido');
+      if (codigo === 'ENOENT') {
+        resolve(
+          `ork nao encontrado em "${bin}". Instale o adapter com ` +
+            '`ork adapter install openclaw` (que renderiza o caminho) ou exporte ORK_BIN.'
+        );
+        return;
+      }
+      resolve(`[ork saiu com ${String(codigo)}]\n${saida}`);
+    });
+    if (entrada !== undefined) filho.stdin?.end(entrada);
+  });
+}
+
+/** Schema de objeto JSON com todas as propriedades obrigatorias. */
+function schema(
+  propriedades: Record<string, Record<string, unknown>>
+): Record<string, unknown> {
+  return {
+    type: 'object',
+    properties: propriedades,
+    required: Object.keys(propriedades),
+    additionalProperties: false,
+  };
+}
+
+function texto(params: Record<string, unknown>, chave: string): string {
+  const valor = params[chave];
+  if (typeof valor === 'string') return valor;
+  return String(valor ?? '');
+}
+
+/** O gateway fornece o update original; o agente não pode sintetizar evidência humana. */
+function argvDaResposta(p: Record<string, unknown>, alvo: 'gate' | 'sessions'): string[] {
+  const update = p.updateTelegram as Record<string, any> | undefined;
+  const callback = update?.callback_query;
+  const mensagem = callback?.message ?? update?.message;
+  const remetente = callback?.from ?? mensagem?.from;
+  const usuario = String(remetente?.id ?? '');
+  const chat = String(mensagem?.chat?.id ?? '');
+  const permitidos = (nome: string) => (process.env[nome] ?? '').split(',').map(v => v.trim()).filter(Boolean);
+  if (!usuario || !chat || remetente?.is_bot !== false || mensagem?.forward_origin ||
+      !permitidos('ORK_HITL_TELEGRAM_USERS').includes(usuario) ||
+      !permitidos('ORK_HITL_TELEGRAM_CHATS').includes(chat)) {
+    throw new Error('origem humana não autorizada pelo gateway');
+  }
+  const thread = texto(p, 'thread'), pedido = texto(p, 'pedido');
+  if (![thread, pedido].every(v => /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/.test(v))) {
+    throw new Error('thread ou pedido inválido');
+  }
+  let resposta: unknown, referencia: unknown;
+  if (callback) {
+    const prefixo = `ork:${thread}:${pedido}:`;
+    if (typeof callback.data !== 'string' || !callback.data.startsWith(prefixo)) {
+      throw new Error('callback não corresponde ao pedido');
+    }
+    resposta = callback.data.slice(prefixo.length);
+    if (!/^[1-9][0-9]?$/.test(String(resposta))) throw new Error('opção inválida');
+    referencia = callback.id;
+  } else {
+    const origem = mensagem?.reply_to_message?.text;
+    if (typeof origem !== 'string' || !origem.split('\n').includes(`ork-hitl ${thread} ${pedido}`)) {
+      throw new Error('responda à mensagem do pedido HITL');
+    }
+    resposta = mensagem.text;
+    referencia = mensagem.message_id;
+  }
+  if (typeof resposta !== 'string' || !resposta.trim() || resposta.length > 4096 ||
+      resposta.includes('\0') || !referencia) throw new Error('resposta ou mensagem inválida');
+  return [alvo, 'answer', thread, pedido, '--resposta-stdin', '--por', `telegram:${usuario}`,
+    '--mensagem', `telegram:${chat}:${referencia}`, '--origem', 'telegram'];
+}
+
+/** Catálogo em paridade nome a nome com o manifesto; aprovação genérica legada aposentada. */
+interface FerramentaOrk {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  argv: (params: Record<string, unknown>) => string[];
+  entrada?: (params: Record<string, unknown>) => string;
+}
+
+const FERRAMENTAS: FerramentaOrk[] = [
+  {
+    name: 'ork_maestro',
+    description: 'Ao receber a frase exata orkastery maestro, consulte o panorama somente leitura. Não cria thread. Apresente fontes, lacunas e HITL com recomendação e opções claras; horários para o dono vêm dos campos *Local (fuso do dono), nunca do ISO. Ação posterior exige operação autorizada e readback.',
+    parameters: { type: 'object', additionalProperties: false, properties: {
+      thread: { type: 'string' }, section: { type: 'string', enum: ['portfolio','demands','threads','sessions','blockers','leases','retries','hitl','ship','master','nextActions'] },
+      offset: { type: 'integer', minimum: 0, maximum: 100000 },
+    } },
+    argv: p => {
+      if (Object.keys(p).some(k => !['thread', 'section', 'offset'].includes(k)) ||
+          (p.thread !== undefined && (typeof p.thread !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/.test(p.thread))) ||
+          (p.section === undefined) !== (p.offset === undefined) ||
+          (p.offset !== undefined && (!Number.isSafeInteger(p.offset) || Number(p.offset) < 0 || Number(p.offset) > 100000)))
+        throw Error('maestro.arguments.invalid');
+      return ['maestro', '--json', ...(p.thread === undefined ? [] : ['--thread', String(p.thread)]),
+        ...(p.section === undefined ? [] : ['--section', String(p.section), '--offset', String(p.offset)])];
+    },
+  },
+  {
+    name: 'ork_onboarding',
+    description: 'Consulta a pauta do núcleo e registra respostas públicas. Credenciais somente como nomes de variáveis; valores ficam em ~/.hermes/.env. Sync publica opcionalmente e relata degradação.',
+    parameters: {
+      type: 'object', additionalProperties: false, required: ['acao'],
+      properties: {
+        acao: { type: 'string', enum: ['show', 'set', 'reset', 'sync'] },
+        etapa: { type: 'string', description: 'Etapa devolvida pela pauta do CLI; omita para reset total.' },
+        conteudo: { type: 'string', description: 'JSON público serializado; nunca valores secretos.' },
+        por: { type: 'string', description: 'Autoria da resposta; omitido usa owner.' },
+      },
+    },
+    argv: (p) => ['onboarding', texto(p, 'acao'),
+      ...(p.etapa === undefined ? [] : [texto(p, 'etapa')]),
+      ...(p.conteudo === undefined ? [] : ['--conteudo', texto(p, 'conteudo')]),
+      ...(p.por === undefined ? [] : ['--por', texto(p, 'por')]), '--json'],
+  },
+  {
+    name: 'ork_doctor',
+    description:
+      'O que vale nesta maquina agora: runtime, assinatura, provider de custo. Sai diferente de zero quando o despacho nao vale.',
+    parameters: schema({}),
+    argv: () => ['doctor'],
+  },
+  {
+    name: 'ork_modo_do_pedido',
+    description:
+      'Le a #TAG de conducao do pedido do builder (#Classic, #Maestro, #Auto, #Fast) e devolve o modo. #TAG aposentada (#Look, #Ork) recebe recusa tipada modo.aposentado, com saida != 0, em vez de virar o default em silencio. Sem tag, devolve o conduction.default_mode do manifesto. Use SEMPRE este tool em vez de reconhecer a tag no host.',
+    parameters: schema({
+      pedido: { type: 'string', description: 'O texto inteiro do pedido do builder' },
+    }),
+    argv: (p) => ['modos', '--do-pedido', texto(p, 'pedido'), '--json'],
+  },
+  {
+    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.',
+    parameters: schema({
+      nome: { type: 'string', description: 'Nome curto da demanda' },
+      modo: {
+        type: 'string',
+        description: 'classic|maestro|auto|fast, vindo de ork_modo_do_pedido',
+      },
+    }),
+    argv: (p) => [
+      'thread',
+      'new',
+      texto(p, 'nome'),
+      '--mode',
+      texto(p, 'modo'),
+      '--worktree',
+      'auto',
+    ],
+  },
+  {
+    name: 'ork_thread_status',
+    description: 'Estado da thread lido do disco e cruzado com o runtime real.',
+    parameters: schema({ thread: { type: 'string' } }),
+    argv: (p) => ['thread', 'status', texto(p, 'thread')],
+  },
+  {
+    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.',
+    parameters: schema({
+      thread: { type: 'string' },
+      fase: { type: 'string', enum: ['GOAL', 'PLAN', 'GO', 'CHECK', 'SHIP', 'MASTER'] },
+      prompt: { type: 'string', description: 'O pedido do builder para esta fase' },
+    }),
+    argv: (p) => [
+      'phase',
+      'run',
+      texto(p, 'thread'),
+      texto(p, 'fase'),
+      '--prompt',
+      texto(p, 'prompt'),
+    ],
+  },
+  {
+    name: 'ork_phase_list',
+    description: 'O ledger da thread, evento a evento, com quem decidiu e a evidencia.',
+    parameters: schema({ thread: { type: 'string' } }),
+    argv: (p) => ['phase', 'list', texto(p, 'thread')],
+  },
+  {
+    name: 'ork_objective_status',
+    description:
+      'Aposentado na I-43 junto com ork objective: devolve a recusa tipada objective.aposentado, com saida != 0. Estado de uma entrega: ork_thread_status. Ciclos ligados a um produto, projeto ou iniciativa: ork portfolio inspect <id> --json.',
+    parameters: schema({ objective: { type: 'string', description: 'ID obj-* do ticket' } }),
+    argv: (p) => ['objective', 'status', texto(p, 'objective'), '--json'],
+  },
+  {
+    name: 'ork_objective_message',
+    description:
+      'Aposentado na I-43 junto com ork objective: devolve a recusa tipada objective.aposentado, com saida != 0, e nao grava nada. Resposta do dono a uma pausa vai por ork_gate_answer ou ork_session_answer.',
+    parameters: schema({
+      objective: { type: 'string', description: 'ID obj-* do ticket' },
+      author: { type: 'string', description: 'Identidade fornecida pelo gateway autenticado' },
+      message: { type: 'string', description: 'Texto integral recebido do dono' },
+    }),
+    argv: (p) => [
+      'objective', 'message', texto(p, 'objective'),
+      '--text', texto(p, 'message'), '--por', texto(p, 'author'), '--role', 'human',
+    ],
+  },
+  {
+    name: 'ork_portfolio_list',
+    description: 'Lista produtos, projetos e iniciativas do catálogo canônico usado pelo Kanban.',
+    parameters: schema({}),
+    argv: () => ['portfolio', 'list', '--json'],
+  },
+  {
+    name: 'ork_brain_status',
+    description: 'Confere contrato, disponibilidade e tenant do Company Brain sem aceitar identidade ou DSN nos argumentos.',
+    parameters: schema({ thread: { type: 'string' } }),
+    argv: (p) => ['brain', 'status', '--thread', texto(p, 'thread')],
+  },
+  {
+    name: 'ork_brain_query',
+    description: 'Consulta a ontologia do Company Brain pela identidade autenticada no transporte.',
+    parameters: schema({
+      thread: { type: 'string' },
+      kinds: { type: 'string', description: 'prod,proj,init,assertion' },
+    }),
+    argv: (p) => ['brain', 'query', '--thread', texto(p, 'thread'), '--kinds', texto(p, 'kinds'), '--limit', '50'],
+  },
+  {
+    name: 'ork_brain_get',
+    description: 'Lê uma entidade exata do Company Brain; ausência e retenção permanecem explícitas.',
+    parameters: schema({ thread: { type: 'string' }, id: { type: 'string' } }),
+    argv: (p) => ['brain', 'get', texto(p, 'id'), '--thread', texto(p, 'thread')],
+  },
+  {
+    name: 'ork_claims_add',
+    description:
+      'Registra uma alegacao verificavel com o comando que a comprova. Toda citacao de arquivo ou teste vira claim.',
+    parameters: schema({
+      thread: { type: 'string' },
+      arquivo: { type: 'string' },
+      alegacao: { type: 'string' },
+      comando: { type: 'string' },
+    }),
+    argv: (p) => [
+      'claims',
+      'add',
+      texto(p, 'thread'),
+      texto(p, 'arquivo'),
+      '--claim',
+      texto(p, 'alegacao'),
+      '--verificar',
+      texto(p, 'comando'),
+    ],
+  },
+  {
+    name: 'ork_verify',
+    description:
+      'Reexecuta claims e comandos do manifesto no HEAD real e compara com a baseline. Passagem relatada nao e passagem.',
+    parameters: schema({ thread: { type: 'string' } }),
+    argv: (p) => ['verify', texto(p, 'thread')],
+  },
+  {
+    name: 'ork_verify_baseline',
+    description:
+      'Grava a baseline: o estado do mundo ANTES do GO, que separa regressao de divida pre-existente.',
+    parameters: schema({ thread: { type: 'string' } }),
+    argv: (p) => ['verify', texto(p, 'thread'), '--baseline'],
+  },
+  {
+    name: 'ork_worktree_ensure',
+    description: 'Garante a worktree isolada da thread, com a base resolvida pelo nucleo.',
+    parameters: schema({ thread: { type: 'string' } }),
+    argv: (p) => ['worktree', 'ensure', texto(p, 'thread')],
+  },
+  {
+    name: 'ork_worktree_audit',
+    description:
+      'Confere a worktree no proprio git. Sai diferente de zero quando ela divergiu ou a base avancou.',
+    parameters: schema({ thread: { type: 'string' } }),
+    argv: (p) => ['worktree', 'audit', texto(p, 'thread')],
+  },
+  ...(['gate', 'sessions'] as const).map((alvo): FerramentaOrk => ({
+    name: alvo === 'gate' ? 'ork_gate_answer' : 'ork_session_answer',
+    description: 'Transporta uma resposta humana do Telegram ao pedido HITL correlacionado. Use o update original do gateway autenticado; nunca crie update em nome do builder. O núcleo verifica modo, prazo e idempotência.',
+    parameters: schema({
+      thread: { type: 'string' },
+      pedido: { type: 'string' },
+      updateTelegram: { type: 'object', description: 'Update original recebido pelo gateway Telegram autenticado' },
+    }),
+    argv: p => argvDaResposta(p, alvo),
+    entrada: p => {
+      const update = p.updateTelegram as Record<string, any>;
+      return update.callback_query ? update.callback_query.data.split(':').at(-1) : update.message.text;
+    },
+  })),
+  {
+    name: 'ork_ship',
+    description:
+      'Merge serializado por lease e push PROVADO comparando o sha local com o que o remoto reporta.',
+    parameters: schema({
+      thread: { type: 'string' },
+      base: { type: 'string' },
+      quem: { type: 'string' },
+    }),
+    argv: (p) => [
+      'ship',
+      texto(p, 'thread'),
+      '--para',
+      texto(p, 'base'),
+      '--autorizar-push',
+      texto(p, 'quem'),
+    ],
+  },
+  {
+    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.',
+    parameters: schema({
+      thread: { type: 'string' },
+      score: { type: 'string', description: 'inteiro de 0 a 5, dado pelo humano' },
+      justificativa: { type: 'string' },
+      quem: { type: 'string' },
+    }),
+    argv: (p) => [
+      'master',
+      texto(p, 'thread'),
+      '--score',
+      texto(p, 'score'),
+      '--justificativa',
+      texto(p, 'justificativa'),
+      '--por',
+      texto(p, 'quem'),
+    ],
+  },
+  {
+    name: 'ork_board',
+    description:
+      'Todas as threads em uma visao, e o escalonador dizendo quem avanca agora e quem espera.',
+    parameters: schema({}),
+    argv: () => ['board', 'plan'],
+  },
+  {
+    name: 'ork_master_batch',
+    description:
+      'Todas as entregas em JSON, com o indice derivado do ledger, as ja pontuadas e as aceitas por omissao. Roda ork master --todas; o nome e da antiga fila de score (ork master --batch), aposentada na I-43.',
+    parameters: schema({}),
+    argv: () => ['master', '--todas', '--json'],
+  },
+];
+
+const plugin = defineToolPlugin({
+  id: 'orkastery',
+  name: 'Orkastery',
+  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.',
+  tools: (tool) =>
+    FERRAMENTAS.map((f) =>
+      tool({
+        name: f.name,
+        description: f.description,
+        parameters: f.parameters,
+        execute: (params, _config, contexto) => {
+          try { return rodarOrk(f.argv(params), contexto.signal, f.entrada?.(params)); }
+          catch { return '[ork recusou] resposta humana não confirmada; confira origem e correlação do pedido'; }
+        },
+      })
+    ),
+});
+
+// Preserve SDK metadata and its tool registration; add only a native ingress hook.
+const entry = plugin as { register?: (api: unknown) => unknown };
+const registerTools = entry.register;
+entry.register = (api: unknown) => {
+  const result = registerTools?.(api);
+  registerHitlIngress(api as Parameters<typeof registerHitlIngress>[0], resolverOrkBin());
+  return result;
+};
+export default plugin;