oxe-cc 1.8.0 → 1.9.1

package/package.json

@@ -1,100 +1,106 @@
-{
-	"name": "oxe-cc",
-	"version": "1.8.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.9.1",
+  "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:runtime-real": "node scripts/runtime-real-suite.cjs",
+    "test:recovery-fixtures": "node scripts/run-recovery-fixtures.cjs",
+    "test:multi-agent-soak": "node scripts/run-multi-agent-soak.cjs",
+    "test:multi-agent-real": "node scripts/run-multi-agent-real.cjs",
+    "test": "npm run build:runtime && npm run test:root && npm run test:runtime && npm run test:runtime-smoke && npm run test:runtime-real && npm run test:recovery-fixtures && npm run test:multi-agent-soak && npm run test:multi-agent-real",
+    "test:coverage": "c8 --check-coverage --lines 82 --functions 85 --branches 58 --statements 82 npm test",
+    "scan:assets": "node scripts/oxe-assets-scan.cjs",
+    "release:pack-check": "node scripts/release-pack-check.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 && npm run release:pack-check && 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.8.0",
-  "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"
-  }
-}
+{
+  "name": "@oxe/runtime",
+  "version": "1.9.1",
+  "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"
+  }
+}

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');
 }

package/packages/runtime/src/models/failure.ts

@@ -8,4 +8,6 @@ export type FailureClass =
   | 'test'             // verification / acceptance test failed
   | 'timeout'          // task or run exceeded time budget
   | 'evidence_missing' // required evidence was not collected
+  | 'verify'           // inline verification command failed after execution
+  | 'llm'              // LLM exhausted turn budget without calling finish_task
   | null;              // success — no failure