oxe-cc 1.7.0 → 1.8.3

package/oxe/templates/SPEC.template.md

@@ -15,16 +15,31 @@ inputs: []
 
 > Substitua os placeholders. Remova seções vazias se não se aplicarem.
 
-## Objetivo
-
-(Uma frase: o que entregar.)
-
-## Contexto
-
-- Repositório / produto: …
-- Links úteis: …
-- Tipo de demanda: feature | bugfix | refactor | research | ops | mixed
-- Incertezas estruturadas: …
+## Objetivo
+
+(Uma frase: o que entregar.)
+
+## Outcome esperado
+
+- Usuário ou operador principal: …
+- Resultado observável ao final da entrega: …
+- Medida de sucesso principal: …
+
+## Contexto
+
+- Repositório / produto: …
+- Links úteis: …
+- Tipo de demanda: feature | bugfix | refactor | research | ops | mixed
+- Incertezas estruturadas: …
+- Restrições técnicas obrigatórias: …
+- Tecnologias proibidas ou evitadas: …
+
+## Público e experiência
+
+- Público-alvo primário: …
+- Nível de conhecimento esperado: iniciante | intermediário | avançado
+- Contexto de uso: desktop | mobile | ambos | CLI | backoffice | batch
+- Tom ou padrão de experiência esperado: …
 
 ## Escopo
 
@@ -36,26 +51,44 @@ inputs: []
 
 - …
 
-## Critérios de aceite
-
-Use **IDs estáveis** (A1, A2, …) para o plano e o verify vincularem cada tarefa a um critério. Cada critério deve ser **testável ou observável** (comando, checklist ou critério objetivo).
+## Critérios de aceite
+
+Use **IDs estáveis** (A1, A2, …) para o plano e o verify vincularem cada tarefa a um critério. Cada critério deve ser **testável ou observável** (comando, checklist ou critério objetivo).
 
 | ID | Critério | Como verificar |
 |----|----------|----------------|
-| A1 | (ex.: Dado … quando … então …) | (ex.: `npm test`, teste manual X) |
-| A2 | … | … |
-
-## Suposições
-
-- …
+| A1 | (ex.: Dado … quando … então …) | (ex.: `npm test`, teste manual X) |
+| A2 | … | … |
+
+## Setup externo e pré-condições
+
+- Contas, variáveis de ambiente, filas, bancos, VPN, dashboards ou recursos cloud necessários: …
+- Pré-condições bloqueantes para executar ou validar: …
+
+## Conteúdo e fluxos obrigatórios
+
+- Fluxos obrigatórios da v1: …
+- Estados obrigatórios: loading | empty | error | success | disabled | not_applicable
+- Conteúdo mínimo obrigatório por área/módulo: …
+- Exemplos concretos que devem existir na entrega: …
+
+## Suposições
+
+- …
 
 ## Riscos
 
 - …
 
-## Referências no código
-
-- Caminhos / módulos: …
+## Referências no código
+
+- Caminhos / módulos: …
+
+## Contratos esperados para o plano
+
+- Arquivos ou áreas que o plano deverá fechar com write-set explícito: …
+- Fixtures, anchors ou exemplos locais obrigatórios antes de executar: …
+- Decisões que não podem ser deixadas para o executor: …
 
 ---
 

package/oxe/workflows/plan.md

@@ -48,11 +48,16 @@ Fixtures mínimos por fluxo/tarefa de risco:
 - queries/checks de validação e smoke commands.
 - negative cases mínimos para validação de erro, limite ou regressão principal.
 
-Regra de readiness:
-- `IMPLEMENTATION-PACK` precisa estar `ready`;
-- `REFERENCE-ANCHORS` não pode ter âncora crítica em `missing|stale|conflicting`;
-- `FIXTURE-PACK` é obrigatório para tarefas mutáveis com parser/layout/integração/transformação/fila/migração/builder;
-- qualquer `critical_gap` aberto derruba a prontidão executável do plano.
+Regra de readiness:
+- `IMPLEMENTATION-PACK` precisa estar `ready`;
+- `REFERENCE-ANCHORS` não pode ter âncora crítica em `missing|stale|conflicting`;
+- `FIXTURE-PACK` é obrigatório para tarefas mutáveis com parser/layout/integração/transformação/fila/migração/builder;
+- qualquer `critical_gap` aberto derruba a prontidão executável do plano.
+
+**Contrato adicional para app/UI estático:** quando a trilha for página HTML/CSS/JS, dashboard, microsite, app sem framework ou experiência educacional:
+- o `IMPLEMENTATION-PACK` deve fechar seções obrigatórias da interface, comportamento por interação, estado persistido e modelo de conteúdo;
+- o `REFERENCE-ANCHORS` deve apontar para snippets, predecessores ou contratos locais/materializados que reduzam improviso visual e estrutural;
+- o `FIXTURE-PACK` deve incluir ao menos exemplos de conteúdo, estados da interface e checks de responsividade/console limpo quando a UI for parte central do aceite.
 </execution_rational_artifacts>
 
 <plan_iteration_contract>
@@ -177,7 +182,14 @@ Depois do resumo e antes das tarefas, o `PLAN.md` deve conter também:
 
 **Princípio test-first:** escreva o `Verificar` antes de escrever o `Implementar`. A pergunta é: "Como saberei que está pronto?" — a resposta define o target; `Implementar` é o caminho mínimo até esse target.
 
-**Contrato racional por tarefa:** se a tarefa for mutável ou tecnicamente relevante, o `PLAN.md` sozinho não basta. O `IMPLEMENTATION-PACK` deve fechar o write-set, os symbols e os checks; o `REFERENCE-ANCHORS` deve materializar evidência externa; o `FIXTURE-PACK` deve reduzir improviso em parsing/integração/transformação.
+**Contrato racional por tarefa:** se a tarefa for mutável ou tecnicamente relevante, o `PLAN.md` sozinho não basta. O `IMPLEMENTATION-PACK` deve fechar o write-set, os symbols e os checks; o `REFERENCE-ANCHORS` deve materializar evidência externa; o `FIXTURE-PACK` deve reduzir improviso em parsing/integração/transformação.
+
+**Contrato racional de densidade operacional:** plano com tarefa mutável ainda vaga (`...`, "ajustar onde necessário", "melhorar interface", "organizar conteúdo") não sustenta `Confiança > 90%`. Para passar do gate, o plano precisa fechar:
+- arquivos alvo exatos ou padrão restrito;
+- symbols/estruturas esperadas;
+- sequência mínima de implementação;
+- verificação observável por tarefa;
+- fixture ou anchor quando o risco for de UI, integração, parsing, contrato ou transformação.
 
 **Projetos sem suíte de testes única (legado):** o bloco **Verificar** pode usar `Comando: —` e **Manual** com Grep, leitura de paths ou checklist — ver exemplos em **`oxe/workflows/references/legacy-brownfield.md`**. Todo critério **A*** da SPEC deve aparecer em **Aceite vinculado** de alguma tarefa ou como gap explícito.
 

package/oxe/workflows/spec.md

@@ -30,9 +30,24 @@ Se **`.oxe/config.json`** tiver `discuss_before_plan: true`: mencionar no final
 
 **Discovery adaptativo:** antes da primeira pergunta, aplicar `oxe/workflows/references/adaptive-discovery.md`. Classificar a demanda, modular os blocos de perguntas conforme o domínio, limitar rodadas e consolidar incertezas estruturadas que depois alimentarão a confiança do plano.
 
-**Rastreabilidade forte:** todo requisito `R-ID` precisa apontar para pelo menos um critério `A*` verificável, ou aparecer como v2/fora com justificativa. Critério sem método de verificação não entra como v1.
-
-**Setup externo:** quando o sucesso depender de conta, variável de ambiente, dashboard, fila, banco, credencial, VPN ou recurso cloud, registrar em SPEC a seção **Setup externo e pré-condições**. O plano deve transformar isso em checkpoint ou tarefa explícita; não deixar como suposição solta.
+**Rastreabilidade forte:** todo requisito `R-ID` precisa apontar para pelo menos um critério `A*` verificável, ou aparecer como v2/fora com justificativa. Critério sem método de verificação não entra como v1.
+
+**Setup externo:** quando o sucesso depender de conta, variável de ambiente, dashboard, fila, banco, credencial, VPN ou recurso cloud, registrar em SPEC a seção **Setup externo e pré-condições**. O plano deve transformar isso em checkpoint ou tarefa explícita; não deixar como suposição solta.
+
+**Contrato de indução da SPEC:** a SPEC deve sair forte o suficiente para que o usuário não precise compensar lacunas "no braço" durante o PLAN. Sempre extrair ou materializar explicitamente:
+- público-alvo primário;
+- outcome esperado observável;
+- restrições técnicas obrigatórias e proibições relevantes;
+- fluxos obrigatórios da v1;
+- conteúdo mínimo exigido por área;
+- exemplos mínimos esperados quando o pedido tocar UI, app, material didático, integração ou contrato público.
+
+**Demandas de produto/app/UI:** quando o pedido for uma aplicação, página, dashboard, fluxo visual ou experiência educacional, a SPEC deve congelar antes do PLAN:
+- blocos obrigatórios da interface;
+- estados principais (`loading`, `empty`, `error`, `success` quando aplicável);
+- interações mínimas esperadas;
+- regras objetivas de responsividade e acessibilidade;
+- critérios de aceite verificáveis por comportamento visível, não só por intenção narrativa.
 
 **Resolução de sessão:** antes de ler ou escrever artefatos desta trilha, resolver `active_session` em `.oxe/STATE.md` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa:
 - `SPEC.md`, `ROADMAP.md` e `DISCUSS.md` vivem em `.oxe/<active_session>/spec/`
@@ -183,7 +198,7 @@ Complemento adaptativo para a Fase 1. Quando o domínio for confirmado (via scan
 
 ---
 
-### Domínio: UI e Frontend
+### Domínio: UI e Frontend
 
 *Adicionar ao Bloco B quando o escopo toca interface de usuário:*
 
@@ -195,11 +210,18 @@ Complemento adaptativo para a Fase 1. Quando o domínio for confirmado (via scan
 - Há internacionalização (i18n) ou múltiplos idiomas a suportar?
 - Qual a estratégia de tratamento de erros visível ao usuário?
 
-*Critérios A* a sugerir:*
-- `A-N: Componente exibe loading state enquanto dados carregam`
-- `A-N: Erro de API exibe mensagem legível, não stack trace`
-- `A-N: Formulário desabilita submit enquanto request está em andamento`
-- `A-N: Todos os campos de formulário têm label associada (WCAG básico)`
+*Critérios A* a sugerir:*
+- `A-N: Componente exibe loading state enquanto dados carregam`
+- `A-N: Erro de API exibe mensagem legível, não stack trace`
+- `A-N: Formulário desabilita submit enquanto request está em andamento`
+- `A-N: Todos os campos de formulário têm label associada (WCAG básico)`
+
+*Para páginas estáticas, apps sem framework ou experiências didáticas, também perguntar:*
+- Quais blocos da página são obrigatórios acima da dobra e abaixo da dobra?
+- O conteúdo é mais exploratório, guiado passo a passo, ou ambos?
+- Quais interações precisam existir obrigatoriamente na v1?
+- O progresso do usuário precisa persistir entre reloads?
+- Há exemplos de conteúdo, visualização ou exercícios mínimos que a aplicação precisa materializar?
 
 ---
 

package/package.json

@@ -1,100 +1,103 @@
-{
-	"name": "oxe-cc",
-	"version": "1.7.0",
-	"description": "OXE — spec-driven workflows in .oxe/ with runtime enterprise, evidence-first verification and multi-runtime integrations (npx)",
-	"license": "MIT",
-	"author": "",
-	"homepage": "https://www.npmjs.com/package/oxe-cc",
-	"bugs": {
-		"url": "https://github.com/propagno/oxe-build/issues"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/propagno/oxe-build.git"
-	},
-	"keywords": [
-		"cursor",
-		"github-copilot",
-		"copilot",
-		"claude",
-		"claude-code",
-		"opencode",
-		"gemini-cli",
-		"codex",
-		"windsurf",
-		"antigravity",
-		"spec-driven",
-		"context-engineering",
-		"ai-agents",
-		"oxe"
-	],
-	"engines": {
-		"node": ">=18.0.0"
-	},
-	"main": "lib/sdk/index.cjs",
-	"exports": {
-		".": "./lib/sdk/index.cjs",
-		"./package.json": "./package.json"
-	},
-	"types": "lib/sdk/index.d.ts",
-	"bin": {
-		"oxe-cc": "bin/oxe-cc.js",
-		"oxe": "bin/oxe-cc.js"
-	},
-	"files": [
-		"bin",
-		"lib",
-		"oxe",
-		"assets",
-		".cursor",
-		".github",
-		"commands",
-		"vscode-extension",
-		"docs",
-		"QUICKSTART.md",
-		"packages/runtime/src",
-		"packages/runtime/package.json",
-		"packages/runtime/tsconfig.json",
-		"AGENTS.md",
-		"README.md",
-		"CHANGELOG.md"
-	],
-	"scripts": {
-		"build:runtime": "cd packages/runtime && npm run build",
-		"sync:runtime-metadata": "node scripts/sync-runtime-metadata.cjs",
-		"sync:cursor": "node scripts/sync-cursor-from-prompts.cjs",
-		"release:doctor": "node scripts/release-doctor.cjs",
-		"release:manifest": "node scripts/release-doctor.cjs --write-manifest",
-		"test:root": "node --test tests/install.test.cjs tests/oxe-project-health.test.cjs tests/oxe-dashboard.test.cjs tests/oxe-operational.test.cjs tests/oxe-azure.test.cjs tests/oxe-sdk.test.cjs tests/oxe-manifest.test.cjs tests/oxe-agent-install.test.cjs tests/oxe-install-resolve-full.test.cjs tests/oxe-health-extended.test.cjs tests/oxe-workflows-edge.test.cjs tests/oxe-sdk-edge.test.cjs tests/oxe-cli-edge.test.cjs tests/oxe-npm-version.test.cjs tests/oxe-scripts.test.cjs tests/oxe-retro-health.test.cjs tests/oxe-security-permissions.test.cjs tests/oxe-runtime-semantics.test.cjs tests/oxe-plugins.test.cjs",
-		"test:runtime": "cd packages/runtime && npm test",
-		"test:runtime-smoke": "node scripts/runtime-smoke-matrix.cjs",
-		"test:recovery-fixtures": "node scripts/run-recovery-fixtures.cjs",
-		"test:multi-agent-soak": "node scripts/run-multi-agent-soak.cjs",
-		"test": "npm run build:runtime && npm run test:root && npm run test:runtime && npm run test:runtime-smoke && npm run test:recovery-fixtures && npm run test:multi-agent-soak",
-		"test:coverage": "c8 --check-coverage --lines 82 --functions 85 --branches 58 --statements 82 npm test",
-		"scan:assets": "node scripts/oxe-assets-scan.cjs",
-		"build:vscode-ext": "cd vscode-extension && npx @vscode/vsce package --no-yarn --allow-missing-repository",
-		"prepublishOnly": "npm test && npm run scan:assets && npm run build:vscode-ext && npm run release:manifest && node bin/oxe-cc.js --version"
-	},
-	"c8": {
-		"all": true,
-		"include": [
-			"bin/oxe-cc.js",
-			"bin/lib/**/*.cjs",
-			"lib/**/*.cjs",
-			"scripts/**/*.cjs"
-		],
-		"exclude": [
-			"**/node_modules/**"
-		],
-		"reporter": [
-			"text-summary"
-		]
-	},
-	"devDependencies": {
-		"c8": "^11.0.0"
-	},
-	"dependencies": {
-		"semver": "^7.7.4"
-	}
-}
+{
+  "name": "oxe-cc",
+  "version": "1.8.3",
+  "description": "OXE — spec-driven workflows in .oxe/ with runtime enterprise, evidence-first verification and multi-runtime integrations (npx)",
+  "license": "MIT",
+  "author": "",
+  "homepage": "https://www.npmjs.com/package/oxe-cc",
+  "bugs": {
+    "url": "https://github.com/propagno/oxe-build/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/propagno/oxe-build.git"
+  },
+  "keywords": [
+    "cursor",
+    "github-copilot",
+    "copilot",
+    "claude",
+    "claude-code",
+    "opencode",
+    "gemini-cli",
+    "codex",
+    "windsurf",
+    "antigravity",
+    "spec-driven",
+    "context-engineering",
+    "ai-agents",
+    "oxe"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "lib/sdk/index.cjs",
+  "exports": {
+    ".": "./lib/sdk/index.cjs",
+    "./package.json": "./package.json"
+  },
+  "types": "lib/sdk/index.d.ts",
+  "bin": {
+    "oxe-cc": "bin/oxe-cc.js",
+    "oxe": "bin/oxe-cc.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "oxe",
+    "assets",
+    ".cursor",
+    ".github",
+    "commands",
+    "vscode-extension/package.json",
+    "vscode-extension/.vscodeignore",
+    "vscode-extension/LICENSE",
+    "vscode-extension/src",
+    "docs",
+    "QUICKSTART.md",
+    "packages/runtime/src",
+    "packages/runtime/package.json",
+    "packages/runtime/tsconfig.json",
+    "AGENTS.md",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build:runtime": "cd packages/runtime && npm run build",
+    "sync:runtime-metadata": "node scripts/sync-runtime-metadata.cjs",
+    "sync:cursor": "node scripts/sync-cursor-from-prompts.cjs",
+    "release:doctor": "node scripts/release-doctor.cjs",
+    "release:manifest": "node scripts/release-doctor.cjs --write-manifest",
+    "test:root": "node --test tests/install.test.cjs tests/oxe-project-health.test.cjs tests/oxe-dashboard.test.cjs tests/oxe-operational.test.cjs tests/oxe-azure.test.cjs tests/oxe-sdk.test.cjs tests/oxe-manifest.test.cjs tests/oxe-agent-install.test.cjs tests/oxe-install-resolve-full.test.cjs tests/oxe-health-extended.test.cjs tests/oxe-workflows-edge.test.cjs tests/oxe-sdk-edge.test.cjs tests/oxe-cli-edge.test.cjs tests/oxe-npm-version.test.cjs tests/oxe-scripts.test.cjs tests/oxe-retro-health.test.cjs tests/oxe-security-permissions.test.cjs tests/oxe-runtime-semantics.test.cjs tests/oxe-plugins.test.cjs",
+    "test:runtime": "cd packages/runtime && npm test",
+    "test:runtime-smoke": "node scripts/runtime-smoke-matrix.cjs",
+    "test:recovery-fixtures": "node scripts/run-recovery-fixtures.cjs",
+    "test:multi-agent-soak": "node scripts/run-multi-agent-soak.cjs",
+    "test": "npm run build:runtime && npm run test:root && npm run test:runtime && npm run test:runtime-smoke && npm run test:recovery-fixtures && npm run test:multi-agent-soak",
+    "test:coverage": "c8 --check-coverage --lines 82 --functions 85 --branches 58 --statements 82 npm test",
+    "scan:assets": "node scripts/oxe-assets-scan.cjs",
+    "build:vscode-ext": "cd vscode-extension && npx @vscode/vsce package --no-yarn --allow-missing-repository",
+    "prepublishOnly": "npm test && npm run scan:assets && npm run build:vscode-ext && npm run release:manifest && node bin/oxe-cc.js --version"
+  },
+  "c8": {
+    "all": true,
+    "include": [
+      "bin/oxe-cc.js",
+      "bin/lib/**/*.cjs",
+      "lib/**/*.cjs",
+      "scripts/**/*.cjs"
+    ],
+    "exclude": [
+      "**/node_modules/**"
+    ],
+    "reporter": [
+      "text-summary"
+    ]
+  },
+  "devDependencies": {
+    "c8": "^11.0.0"
+  },
+  "dependencies": {
+    "semver": "^7.7.4"
+  }
+}

package/packages/runtime/package.json

@@ -1,18 +1,18 @@
-{
+{
   "name": "@oxe/runtime",
-  "version": "1.7.0",
+  "version": "1.8.3",
   "private": true,
   "license": "MIT",
   "description": "OXE agentic execution engine — enterprise runtime core",
-  "main": "../../lib/runtime/index.js",
-  "types": "../../lib/runtime/index.d.ts",
-  "scripts": {
-    "build": "tsc",
-    "test": "tsc --project tsconfig.test.json && node --test dist-tests/tests/*.test.js",
-    "clean": "node -e \"const fs=require('fs');['../../lib/runtime','dist-tests'].forEach(d=>{try{fs.rmSync(d,{recursive:true})}catch{}});\""
-  },
-  "devDependencies": {
-    "@types/node": "^25.6.0",
-    "typescript": "^5.4.5"
-  }
-}
+  "main": "../../lib/runtime/index.js",
+  "types": "../../lib/runtime/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc --project tsconfig.test.json && node --test dist-tests/tests/*.test.js",
+    "clean": "node -e \"const fs=require('fs');['../../lib/runtime','dist-tests'].forEach(d=>{try{fs.rmSync(d,{recursive:true})}catch{}});\""
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^5.4.5"
+  }
+}

package/packages/runtime/src/compiler/graph-compiler.ts

@@ -123,7 +123,7 @@ export function compile(
       mutation_scope: task.files,
       actions: buildActions(task),
       verify: {
-        must_pass: task.verifyCommand ? ['tests'] : [],
+        must_pass: task.verifyCommand ? (task.aceite.length > 0 ? task.aceite : ['tests']) : [],
         acceptance_refs: task.aceite,
         command: task.verifyCommand,
       },

package/packages/runtime/src/evidence/evidence-store.ts

@@ -75,8 +75,8 @@ export class EvidenceStore {
     const ext = EXT_MAP[type] ?? 'bin';
 
     const existing = this.readIndex(run_id, work_item_id, attempt_number);
-    const seq = existing.filter((e) => e.type === type).length + 1;
-    const filename = seq === 1 ? `${type}.${ext}` : `${type}-${seq}.${ext}`;
+    const seq = existing.filter((e) => e.type === type).length + 1;
+    const filename = seq === 1 ? `${type}.${ext}` : `${type}-${seq}.${ext}`;
     const filePath = path.join(dir, filename);
 
     fs.writeFileSync(filePath, buf);

package/packages/runtime/src/executor/action-tool-map.ts

@@ -42,5 +42,9 @@ export function selectToolsForActions(actions: Action[]): ToolSchema[] {
       }
     }
   }
+  // finish_task is always available so the LLM can signal authoritative completion
+  if (!seen.has('finish_task') && BUILT_IN_TOOLS.finish_task) {
+    result.push(BUILT_IN_TOOLS.finish_task.schema);
+  }
   return result;
 }

package/packages/runtime/src/executor/built-in-tools.ts

@@ -262,6 +262,34 @@ function runShell(command: string, cwd: string, timeoutMs: number): Promise<stri
   });
 }
 
+// ─── finish_task ──────────────────────────────────────────────────────────────
+
+const finishTask: BuiltInToolHandler = {
+  idempotent: true,
+  schema: {
+    type: 'function',
+    function: {
+      name: 'finish_task',
+      description: 'Signal that the task is complete. Call this when ALL required actions have been performed.',
+      parameters: {
+        type: 'object',
+        properties: {
+          summary: { type: 'string', description: 'Summary of what was accomplished' },
+          evidence_paths: { type: 'array', items: { type: 'string' }, description: 'Paths to files created or modified' },
+        },
+        required: ['summary'],
+      },
+    },
+  },
+  async execute(args, _cwd) {
+    return JSON.stringify({
+      __finish_task__: true,
+      summary: String(args.summary || ''),
+      evidence_paths: Array.isArray(args.evidence_paths) ? args.evidence_paths : [],
+    });
+  },
+};
+
 // ─── Registry ─────────────────────────────────────────────────────────────────
 
 export const BUILT_IN_TOOLS: Record<string, BuiltInToolHandler> = {
@@ -271,6 +299,7 @@ export const BUILT_IN_TOOLS: Record<string, BuiltInToolHandler> = {
   glob,
   grep,
   run_command: runCommand,
+  finish_task: finishTask,
 };
 
 export const ALL_BUILT_IN_SCHEMAS: ToolSchema[] = Object.values(BUILT_IN_TOOLS).map((t) => t.schema);

package/packages/runtime/src/executor/llm-task-executor.ts

@@ -32,9 +32,13 @@ export interface LlmExecutorEvent {
   detail?: Record<string, unknown>;
 }
 
+export interface LlmExecuteOptions {
+  previousError?: string | null;
+}
+
 const DEFAULT_SYSTEM_PROMPT =
   'You are a precise software engineering agent. Use the tools provided to complete the task. ' +
-  'When the task is done, summarize what was accomplished in your final message without calling any tools.';
+  'When all actions are done, call finish_task with a summary of what was accomplished.';
 
 export class LlmTaskExecutor implements TaskExecutor {
   constructor(
@@ -48,8 +52,9 @@ export class LlmTaskExecutor implements TaskExecutor {
     lease: WorkspaceLease,
     runId: string,
     attempt: number,
+    options: LlmExecuteOptions = {},
   ): Promise<TaskResult> {
-    const prompt = buildNodePrompt(node, lease, runId, attempt);
+    const prompt = buildNodePrompt(node, lease, runId, attempt, { previousError: options.previousError ?? null });
     const tools = selectToolsForActions(node.actions);
     const cwd = lease.root_path;
     const maxTurns = this.provider.maxTurns ?? 10;
@@ -62,8 +67,11 @@ export class LlmTaskExecutor implements TaskExecutor {
 
     let finalOutput = '';
     const evidencePaths: string[] = [];
+    let completedByFinishTask = false;
+    let finishTaskSummary = '';
 
-    for (let turn = 0; turn < maxTurns; turn++) {
+    let turn = 0;
+    for (; turn < maxTurns; turn++) {
       this.emit({ type: 'turn_start', nodeId: node.id, attempt, detail: { turn } });
 
       let response;
@@ -105,13 +113,47 @@ export class LlmTaskExecutor implements TaskExecutor {
       }
 
       messages.push(...concurrentResults, ...serialResults);
+
+      // Detect finish_task call — authoritative completion signal
+      const allResults = [...concurrentResults, ...serialResults];
+      const finishResult = allResults.find((r) => r.name === 'finish_task');
+      if (finishResult) {
+        try {
+          const parsed = JSON.parse(finishResult.content as string);
+          if (parsed.__finish_task__) {
+            completedByFinishTask = true;
+            finishTaskSummary = parsed.summary || '';
+            if (Array.isArray(parsed.evidence_paths)) {
+              evidencePaths.push(...parsed.evidence_paths.filter((p: unknown) => typeof p === 'string'));
+            }
+          }
+        } catch { /* ignore parse errors */ }
+        if (completedByFinishTask) break;
+      }
+    }
+
+    const completedBy = completedByFinishTask
+      ? 'finish_task'
+      : turn < maxTurns
+        ? 'no_tool_call'
+        : 'turn_limit_exhausted';
+
+    if (completedBy === 'turn_limit_exhausted') {
+      return {
+        success: false,
+        failure_class: 'llm',
+        evidence: evidencePaths,
+        output: finalOutput || `Task exhausted ${maxTurns} turns without calling finish_task`,
+        completed_by: completedBy,
+      };
     }
 
     return {
       success: true,
       failure_class: null,
       evidence: evidencePaths,
-      output: finalOutput,
+      output: completedByFinishTask ? (finishTaskSummary || finalOutput) : finalOutput,
+      completed_by: completedBy,
     };
   }
 

package/packages/runtime/src/executor/node-prompt-builder.ts

@@ -1,11 +1,16 @@
 import type { GraphNode } from '../compiler/graph-compiler';
 import type { WorkspaceLease } from '../models/workspace';
 
+export interface NodePromptOptions {
+  previousError?: string | null;
+}
+
 export function buildNodePrompt(
   node: GraphNode,
   lease: WorkspaceLease,
   runId: string,
   attempt: number,
+  options: NodePromptOptions = {},
 ): string {
   const lines: string[] = [
     `# Tarefa: ${node.title}`,
@@ -18,6 +23,15 @@ export function buildNodePrompt(
     lines.push(`**Escopo de mutação:** ${node.mutation_scope.join(', ')}`);
   }
 
+  if (attempt > 1 && options.previousError) {
+    lines.push('', '## Contexto da tentativa anterior');
+    lines.push(`Esta é a tentativa **${attempt}**. A tentativa anterior falhou:`);
+    lines.push('', '```');
+    lines.push(String(options.previousError).slice(0, 2000));
+    lines.push('```', '');
+    lines.push('Analise o erro e tente uma abordagem diferente.');
+  }
+
   if (node.actions.length > 0) {
     lines.push('', '## Ações requeridas');
     for (const action of node.actions) {
@@ -39,7 +53,10 @@ export function buildNodePrompt(
     lines.push('', `**Verificação:** \`${node.verify.command}\``);
   }
 
-  lines.push('', 'Execute as ações acima usando as ferramentas disponíveis e confirme o resultado.');
+  lines.push('', '## Conclusão da tarefa');
+  lines.push('Quando **todas** as ações estiverem concluídas, chame `finish_task` com um resumo do que foi realizado.');
+  lines.push('NÃO chame `finish_task` antes de completar todas as ações requeridas.');
+  lines.push('', 'Execute as ações acima usando as ferramentas disponíveis.');
 
   return lines.join('\n');
 }