oxe-cc 1.5.1 → 1.7.0

package/docs/CONTENT-MIGRATION-AUDIT.md

@@ -0,0 +1,49 @@
+# Content Migration Audit
+
+Este documento registra a triagem interna de conteúdo usado como insumo para fortalecer o OXE. Ele não é instalado em projetos de usuário e não deve ser referenciado por templates, workflows, comandos, README ou agentes finais.
+
+## Rules
+
+- Public artifacts must use OXE naming, paths, commands and runtime contracts only.
+- No public template/workflow/command/agent may reference legacy product names, paths, tool commands or command namespaces.
+- Source material is reauthored, not copied literally.
+
+## Templates
+
+| Source theme | Decision | OXE target |
+|--------------|----------|------------|
+| Detailed phase plan contract | merge | `PLAN.template.md`, `IMPLEMENTATION-PACK.*`, `/oxe-plan` |
+| Context and discovery templates | merge | context packs, `RESEARCH.template.md`, `INVESTIGATION.template.md`, `REFERENCE-ANCHORS.template.md` |
+| Requirements, project, roadmap, state | merge | `SPEC.template.md`, `ROADMAP.template.md`, `STATE.md` |
+| Validation, verification and UAT | merge | `/oxe-verify`, runtime evidence, `VERIFY.md` projection |
+| UI contract | merge | `/oxe-spec --ui`, `/oxe-ui-spec`, `/oxe-ui-review` |
+| Debug templates | merge | `/oxe-debug`, `/oxe-forensics`, `oxe-debugger` |
+| Session summaries and setup | merge | `SUMMARY.template.md`, `RESUME.template.md`, checkpoints |
+| Runtime-specific instruction files | inspiration_only | OXE multi-runtime generators |
+| Developer profile/preferences | reject | future consented profile feature only |
+
+## Workflows
+
+| Source theme | Decision | OXE target |
+|--------------|----------|------------|
+| New project and milestone discovery | merge | `/oxe-spec`, `/oxe-plan` |
+| Phase planning and review loop | merge | `/oxe-plan`, rationality gate |
+| Plan execution by wave/task | merge | `/oxe-execute` |
+| Verification, validation gaps and UAT | merge | `/oxe-verify` |
+| Codebase mapping and research | merge | `/oxe-scan`, `/oxe-spec --research` |
+| Debug and incident diagnosis | merge | `/oxe-debug`, `/oxe-forensics` |
+| UI design and review | merge | `/oxe-spec --ui`, `/oxe-ui-review` |
+| Progress, next, pause and resume | merge | `/oxe`, `/oxe-next`, `/oxe-session` |
+| Workstreams and isolated workspace concepts | merge | `/oxe-workstream`, runtime agents |
+| Autonomous workflow | reject | OXE keeps governed execution |
+| PR branch/ship workflow | inspiration_only | OXE keeps local commit and separate `runtime promote` |
+| Community/settings/update flows | reject | OXE already has administrative UX |
+
+## Commands
+
+Legacy command wrappers are not copied. They are used only as intent inventory and mapped into canonical OXE workflows before generated surfaces are regenerated.
+
+## Agents
+
+Specialized agents were reauthored as OXE-native contracts in `oxe/agents/`. They use `.oxe/`, OXE workflows, runtime enterprise, evidence store, personas and `plan-agents.json` only.
+

package/docs/RELEASE-READINESS.md

@@ -13,10 +13,13 @@ npx oxe-cc doctor --release --write-manifest
 
 O `doctor --release` deve bloquear a publicação quando encontrar:
 
+- árvore canónica `oxe/workflows/`, `oxe/workflows/references/` ou `commands/oxe/` ausente
+- `workflow-runtime-contracts.json` ausente ou inválido
 - drift de versão entre `package.json`, `packages/runtime/package.json`, `vscode-extension/package.json`, `README.md`, `CHANGELOG.md` e banner
 - topo do `CHANGELOG` ausente, sem data ou sem highlights
 - runtime não compilado em `lib/runtime/index.js`
 - wrappers dirty após `sync-runtime-metadata` e `sync:cursor`
+- drift semântico entre workflows canónicos e superfícies geradas
 - ausência ou falha dos relatórios obrigatórios da release
 
 ## Relatórios obrigatórios
@@ -44,3 +47,8 @@ O pipeline de CI e o pipeline de release devem rodar o mesmo gate:
 3. `npm run release:doctor`
 
 Se qualquer etapa falhar, a release não está pronta.
+
+## Observações operacionais
+
+- `status` e `status --full` distinguem agora `workspaceMode: product_package` de `workspaceMode: oxe_project`.
+- No repositório do pacote, readiness passa a ser de publicação; o CLI deixa de bloquear por ausência de `PLAN.md` executável quando não há ciclo ativo declarado.

package/docs/RUNTIME-SMOKE-MATRIX.md

@@ -1,6 +1,6 @@
 # OXE — Runtime Smoke Matrix
 
-> Estado de suporte por runtime de IA. Atualizado em v1.5.1.
+> Estado de suporte por runtime de IA. Atualizado em v1.7.0.
 >
 > `✓` = suportado e testado | `~` = suportado parcialmente | `✗` = não suportado | `?` = não testado
 
@@ -60,11 +60,18 @@ Este documento descreve a matrix estável da release. O artefato operacional con
 
 ### Codex CLI
 
-- Lê `.github/prompts/` via `--instructions` flag
+- Lê `.codex/prompts/` como entrypoint e depende também de skills em `.agents/skills/oxe/`
+- A smoke matrix desta release valida **prompts e skills**; falha se um dos dois lados estiver ausente ou sem a política de resolução de workflow
 - `verify` parcial: gera VERIFY.md mas evidências são menos detalhadas (sem análise de AST)
 - `runtime-first` não suportado: Codex CLI não tem acesso a subprocessos Node
 - **Limitação:** não suporta contexto multi-arquivo simultâneo em tasks longas
 
+### Escopo de instalação
+
+- `--local` define o layout do repositório (`oxe/` + `.oxe/` vs só `.oxe/`)
+- `--ide-local` define que a integração do runtime deve ser instalada no próprio projeto
+- Para Codex, `install --codex --ide-local` é o fluxo correto quando a intenção é materializar `.codex/` e `.agents/` no repositório atual
+
 ### Gemini CLI
 
 - `plan` e `execute` parciais: segue o fluxo mas pode divergir dos critérios A* do SPEC

package/lib/runtime/compiler/graph-compiler.js

@@ -95,6 +95,38 @@ function validateGraph(graph) {
             break;
         }
     }
+    // Validate mutation_scope conflicts between parallel nodes in the same wave
+    const waveMap = new Map();
+    for (const [id, node] of graph.nodes) {
+        const list = waveMap.get(node.wave) ?? [];
+        waveMap.set(node.wave, [...list, id]);
+    }
+    for (const [wave, waveNodeIds] of waveMap) {
+        for (let i = 0; i < waveNodeIds.length; i++) {
+            for (let j = i + 1; j < waveNodeIds.length; j++) {
+                const idA = waveNodeIds[i];
+                const idB = waveNodeIds[j];
+                const a = graph.nodes.get(idA);
+                const b = graph.nodes.get(idB);
+                const notDependent = !a.depends_on.includes(idB) && !b.depends_on.includes(idA);
+                if (notDependent && a.mutation_scope.length > 0 && b.mutation_scope.length > 0) {
+                    const overlap = a.mutation_scope.filter(p => b.mutation_scope.includes(p));
+                    if (overlap.length > 0) {
+                        errors.push(`Wave ${wave}: nodes "${idA}" and "${idB}" mutate the same paths in parallel: ${overlap.join(', ')}`);
+                    }
+                }
+            }
+        }
+    }
+    // Validate wave ordering: a node must only depend on nodes from earlier waves
+    for (const [id, node] of graph.nodes) {
+        for (const dep of node.depends_on) {
+            const depNode = graph.nodes.get(dep);
+            if (depNode && depNode.wave >= node.wave) {
+                errors.push(`Node "${id}" (wave ${node.wave}) depends on "${dep}" (wave ${depNode.wave}) — dependency must come from an earlier wave`);
+            }
+        }
+    }
     return errors;
 }
 function toSerializable(graph) {

package/lib/runtime/context/context-pack-builder.d.ts

@@ -43,6 +43,21 @@ export declare class ContextPackBuilder {
     build(workItem: WorkItem, state: RunState, evidenceItems: Evidence[], evidenceContents: Map<string, string>, lessons: LessonMetric[]): ContextPack;
     /** Convenience: build with no evidence, just lessons and state summary */
     buildLightweight(workItem: WorkItem, state: RunState, lessons: LessonMetric[]): ContextPack;
+    /**
+     * Remove artifacts with lowest relevance until the pack fits within targetTokens.
+     * Artifacts already sorted by relevance; we trim the tail.
+     */
+    compact(pack: ContextPack, targetTokens: number): ContextPack;
+    /**
+     * Merge groups of similar artifacts (cosine similarity >= threshold) into single
+     * combined artifacts to reduce redundancy without discarding information entirely.
+     */
+    microCompact(artifacts: ContextArtifact[], similarityThreshold?: number): ContextArtifact[];
+    /**
+     * Automatically compact a pack to fit within hardLimitTokens.
+     * First applies microCompact (lossless merging), then compact (trimming by relevance).
+     */
+    autoCompact(pack: ContextPack, hardLimitTokens: number): ContextPack;
     /**
      * Filter artifacts to those whose path-like tags are within mutation_scope.
      * L0/L1 tiers apply the filter; L2/L3 skip it (full access).

package/lib/runtime/context/context-pack-builder.js

@@ -159,6 +159,84 @@ class ContextPackBuilder {
     buildLightweight(workItem, state, lessons) {
         return this.build(workItem, state, [], new Map(), lessons);
     }
+    /**
+     * Remove artifacts with lowest relevance until the pack fits within targetTokens.
+     * Artifacts already sorted by relevance; we trim the tail.
+     */
+    compact(pack, targetTokens) {
+        if (estimateTokens(pack.artifacts.map((a) => a.content).join('\n')) <= targetTokens) {
+            return pack;
+        }
+        const sorted = [...pack.artifacts].sort((a, b) => b.relevanceScore - a.relevanceScore);
+        const trimmed = [];
+        let used = 0;
+        for (const artifact of sorted) {
+            const t = estimateTokens(artifact.content);
+            if (used + t > targetTokens)
+                break;
+            trimmed.push(artifact);
+            used += t;
+        }
+        return {
+            ...pack,
+            artifacts: trimmed,
+            redundancy_removed: pack.redundancy_removed + (pack.artifacts.length - trimmed.length),
+        };
+    }
+    /**
+     * Merge groups of similar artifacts (cosine similarity >= threshold) into single
+     * combined artifacts to reduce redundancy without discarding information entirely.
+     */
+    microCompact(artifacts, similarityThreshold = 0.7) {
+        const merged = [];
+        const used = new Set();
+        for (let i = 0; i < artifacts.length; i++) {
+            if (used.has(i))
+                continue;
+            const group = [artifacts[i]];
+            for (let j = i + 1; j < artifacts.length; j++) {
+                if (!used.has(j) && cosineSimilarity(artifacts[i], artifacts[j]) >= similarityThreshold) {
+                    group.push(artifacts[j]);
+                    used.add(j);
+                }
+            }
+            used.add(i);
+            if (group.length === 1) {
+                merged.push(group[0]);
+            }
+            else {
+                const combinedContent = group
+                    .map((a) => a.content)
+                    .join('\n---\n')
+                    .slice(0, 4000);
+                merged.push({
+                    id: group[0].id,
+                    kind: group[0].kind,
+                    content: combinedContent,
+                    relevanceScore: group.reduce((s, a) => s + a.relevanceScore, 0) / group.length,
+                    tags: [...new Set(group.flatMap((a) => a.tags))],
+                });
+            }
+        }
+        return merged;
+    }
+    /**
+     * Automatically compact a pack to fit within hardLimitTokens.
+     * First applies microCompact (lossless merging), then compact (trimming by relevance).
+     */
+    autoCompact(pack, hardLimitTokens) {
+        const currentTokens = estimateTokens(pack.artifacts.map((a) => a.content).join('\n'));
+        if (currentTokens <= hardLimitTokens)
+            return pack;
+        const microCompacted = this.microCompact(pack.artifacts);
+        const removedByMicro = pack.artifacts.length - microCompacted.length;
+        const interim = {
+            ...pack,
+            artifacts: microCompacted,
+            redundancy_removed: pack.redundancy_removed + removedByMicro,
+        };
+        return this.compact(interim, hardLimitTokens);
+    }
     /**
      * Filter artifacts to those whose path-like tags are within mutation_scope.
      * L0/L1 tiers apply the filter; L2/L3 skip it (full access).

package/lib/runtime/events/catalog.d.ts

@@ -1,3 +1,3 @@
-export declare const EVENT_TYPES: readonly ["SessionCreated", "RunStarted", "GraphCompiled", "WorkItemReady", "WorkspaceAllocated", "AttemptStarted", "ToolInvoked", "ToolCompleted", "ToolFailed", "EvidenceCollected", "PolicyEvaluated", "GateRequested", "GateResolved", "VerificationStarted", "VerificationCompleted", "RetryScheduled", "WorkItemCompleted", "WorkItemBlocked", "RunCompleted", "RetroPublished", "LessonPromoted"];
+export declare const EVENT_TYPES: readonly ["SessionCreated", "RunStarted", "GraphCompiled", "WorkItemReady", "WorkspaceAllocated", "AttemptStarted", "ToolInvoked", "ToolCompleted", "ToolFailed", "EvidenceCollected", "PolicyEvaluated", "GateRequested", "GateResolved", "VerificationStarted", "VerificationCompleted", "RetryScheduled", "WorkItemCompleted", "WorkItemBlocked", "RunCompleted", "RetroPublished", "LessonPromoted", "RunAborted", "RollbackExecuted", "RollbackFailed", "TaskErrorBoundaryTripped", "WorkspaceDisposeFailed"];
 export type EventType = (typeof EVENT_TYPES)[number];
 export declare function isValidEventType(type: string): type is EventType;

package/lib/runtime/events/catalog.js

@@ -24,6 +24,11 @@ exports.EVENT_TYPES = [
     'RunCompleted',
     'RetroPublished',
     'LessonPromoted',
+    'RunAborted',
+    'RollbackExecuted',
+    'RollbackFailed',
+    'TaskErrorBoundaryTripped',
+    'WorkspaceDisposeFailed',
 ];
 function isValidEventType(type) {
     return exports.EVENT_TYPES.includes(type);

package/lib/runtime/executor/action-tool-map.d.ts

@@ -0,0 +1,3 @@
+import type { Action } from '../compiler/graph-compiler';
+import type { ToolSchema } from './stream-completion';
+export declare function selectToolsForActions(actions: Action[]): ToolSchema[];

package/lib/runtime/executor/action-tool-map.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectToolsForActions = selectToolsForActions;
+const built_in_tools_1 = require("./built-in-tools");
+const READ_TOOLS = [
+    built_in_tools_1.BUILT_IN_TOOLS.read_file.schema,
+    built_in_tools_1.BUILT_IN_TOOLS.glob.schema,
+    built_in_tools_1.BUILT_IN_TOOLS.grep.schema,
+];
+const PATCH_TOOLS = [
+    built_in_tools_1.BUILT_IN_TOOLS.read_file.schema,
+    built_in_tools_1.BUILT_IN_TOOLS.write_file.schema,
+    built_in_tools_1.BUILT_IN_TOOLS.patch_file.schema,
+];
+const RUN_TOOLS = [built_in_tools_1.BUILT_IN_TOOLS.run_command.schema];
+const EVIDENCE_TOOLS = [
+    built_in_tools_1.BUILT_IN_TOOLS.read_file.schema,
+    built_in_tools_1.BUILT_IN_TOOLS.glob.schema,
+    built_in_tools_1.BUILT_IN_TOOLS.run_command.schema,
+];
+const ACTION_TOOL_MAP = {
+    read_code: READ_TOOLS,
+    generate_patch: PATCH_TOOLS,
+    run_tests: RUN_TOOLS,
+    run_lint: RUN_TOOLS,
+    collect_evidence: EVIDENCE_TOOLS,
+    custom: built_in_tools_1.ALL_BUILT_IN_SCHEMAS,
+};
+function selectToolsForActions(actions) {
+    const seen = new Set();
+    const result = [];
+    for (const action of actions) {
+        for (const tool of ACTION_TOOL_MAP[action.type] ?? built_in_tools_1.ALL_BUILT_IN_SCHEMAS) {
+            if (!seen.has(tool.function.name)) {
+                seen.add(tool.function.name);
+                result.push(tool);
+            }
+        }
+    }
+    return result;
+}

package/lib/runtime/executor/built-in-tools.d.ts

@@ -0,0 +1,8 @@
+import type { ToolSchema } from './stream-completion';
+export interface BuiltInToolHandler {
+    schema: ToolSchema;
+    idempotent: boolean;
+    execute(args: Record<string, unknown>, cwd: string): Promise<string>;
+}
+export declare const BUILT_IN_TOOLS: Record<string, BuiltInToolHandler>;
+export declare const ALL_BUILT_IN_SCHEMAS: ToolSchema[];

package/lib/runtime/executor/built-in-tools.js

@@ -0,0 +1,267 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALL_BUILT_IN_SCHEMAS = exports.BUILT_IN_TOOLS = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+// ─── read_file ────────────────────────────────────────────────────────────────
+const readFile = {
+    idempotent: true,
+    schema: {
+        type: 'function',
+        function: {
+            name: 'read_file',
+            description: 'Read the contents of a file',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', description: 'File path relative to workspace root' },
+                    offset: { type: 'integer', description: 'Line to start reading from (1-based)' },
+                    limit: { type: 'integer', description: 'Maximum number of lines to read' },
+                },
+                required: ['path'],
+            },
+        },
+    },
+    async execute(args, cwd) {
+        const filePath = path_1.default.resolve(cwd, String(args.path));
+        if (!fs_1.default.existsSync(filePath))
+            return `Error: file not found: ${args.path}`;
+        const content = fs_1.default.readFileSync(filePath, 'utf8');
+        const lines = content.split('\n');
+        const offset = typeof args.offset === 'number' ? args.offset - 1 : 0;
+        const limit = typeof args.limit === 'number' ? args.limit : lines.length;
+        return lines.slice(offset, offset + limit).join('\n');
+    },
+};
+// ─── write_file ───────────────────────────────────────────────────────────────
+const writeFile = {
+    idempotent: false,
+    schema: {
+        type: 'function',
+        function: {
+            name: 'write_file',
+            description: 'Write content to a file (creates or overwrites)',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', description: 'File path relative to workspace root' },
+                    content: { type: 'string', description: 'Content to write' },
+                },
+                required: ['path', 'content'],
+            },
+        },
+    },
+    async execute(args, cwd) {
+        const filePath = path_1.default.resolve(cwd, String(args.path));
+        fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
+        fs_1.default.writeFileSync(filePath, String(args.content), 'utf8');
+        return `Written ${String(args.content).length} bytes to ${args.path}`;
+    },
+};
+// ─── patch_file ───────────────────────────────────────────────────────────────
+const patchFile = {
+    idempotent: false,
+    schema: {
+        type: 'function',
+        function: {
+            name: 'patch_file',
+            description: 'Replace an exact string in a file with new content',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', description: 'File path relative to workspace root' },
+                    old_string: { type: 'string', description: 'Exact string to replace' },
+                    new_string: { type: 'string', description: 'Replacement string' },
+                },
+                required: ['path', 'old_string', 'new_string'],
+            },
+        },
+    },
+    async execute(args, cwd) {
+        const filePath = path_1.default.resolve(cwd, String(args.path));
+        if (!fs_1.default.existsSync(filePath))
+            return `Error: file not found: ${args.path}`;
+        const content = fs_1.default.readFileSync(filePath, 'utf8');
+        const oldStr = String(args.old_string);
+        if (!content.includes(oldStr))
+            return `Error: old_string not found in ${args.path}`;
+        const updated = content.replace(oldStr, String(args.new_string));
+        fs_1.default.writeFileSync(filePath, updated, 'utf8');
+        return `Patched ${args.path}`;
+    },
+};
+// ─── glob ─────────────────────────────────────────────────────────────────────
+const glob = {
+    idempotent: true,
+    schema: {
+        type: 'function',
+        function: {
+            name: 'glob',
+            description: 'List files matching a glob pattern within the workspace',
+            parameters: {
+                type: 'object',
+                properties: {
+                    pattern: { type: 'string', description: 'Glob pattern, e.g. src/**/*.ts' },
+                },
+                required: ['pattern'],
+            },
+        },
+    },
+    async execute(args, cwd) {
+        const results = globSync(String(args.pattern), cwd);
+        return results.length ? results.join('\n') : '(no files matched)';
+    },
+};
+function globSync(pattern, root) {
+    const results = [];
+    const parts = pattern.split('/');
+    function walk(dir, remaining) {
+        if (!fs_1.default.existsSync(dir))
+            return;
+        const [head, ...tail] = remaining;
+        if (!head)
+            return;
+        const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const matches = micromatch(entry.name, head);
+            if (!matches)
+                continue;
+            const full = path_1.default.join(dir, entry.name);
+            if (tail.length === 0) {
+                results.push(path_1.default.relative(root, full).replace(/\\/g, '/'));
+            }
+            else if (entry.isDirectory()) {
+                if (head === '**') {
+                    walk(full, remaining);
+                    walk(full, tail);
+                }
+                else {
+                    walk(full, tail);
+                }
+            }
+        }
+    }
+    walk(root, parts);
+    return results;
+}
+function micromatch(name, pattern) {
+    if (pattern === '**')
+        return true;
+    const regex = new RegExp('^' + pattern.replace(/\./g, '\\.').replace(/\*/g, '[^/]*').replace(/\?/g, '[^/]') + '$');
+    return regex.test(name);
+}
+// ─── grep ─────────────────────────────────────────────────────────────────────
+const grep = {
+    idempotent: true,
+    schema: {
+        type: 'function',
+        function: {
+            name: 'grep',
+            description: 'Search for a regex pattern in files',
+            parameters: {
+                type: 'object',
+                properties: {
+                    pattern: { type: 'string', description: 'Regex pattern to search for' },
+                    path: { type: 'string', description: 'File or directory to search in (relative to workspace)' },
+                },
+                required: ['pattern'],
+            },
+        },
+    },
+    async execute(args, cwd) {
+        const searchRoot = args.path ? path_1.default.resolve(cwd, String(args.path)) : cwd;
+        const regex = new RegExp(String(args.pattern));
+        const results = [];
+        grepDir(searchRoot, regex, cwd, results);
+        return results.length ? results.slice(0, 200).join('\n') : '(no matches)';
+    },
+};
+function grepDir(dir, regex, root, out) {
+    if (!fs_1.default.existsSync(dir))
+        return;
+    const stat = fs_1.default.statSync(dir);
+    if (stat.isFile()) {
+        grepFile(dir, regex, root, out);
+        return;
+    }
+    for (const entry of fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+        const full = path_1.default.join(dir, entry.name);
+        if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+            grepDir(full, regex, root, out);
+        }
+        else if (entry.isFile()) {
+            grepFile(full, regex, root, out);
+        }
+    }
+}
+function grepFile(filePath, regex, root, out) {
+    try {
+        const content = fs_1.default.readFileSync(filePath, 'utf8');
+        content.split('\n').forEach((line, i) => {
+            if (regex.test(line)) {
+                out.push(`${path_1.default.relative(root, filePath).replace(/\\/g, '/')}:${i + 1}: ${line}`);
+            }
+        });
+    }
+    catch { /* skip binary or unreadable files */ }
+}
+// ─── run_command ──────────────────────────────────────────────────────────────
+const runCommand = {
+    idempotent: false,
+    schema: {
+        type: 'function',
+        function: {
+            name: 'run_command',
+            description: 'Run a shell command in the workspace directory',
+            parameters: {
+                type: 'object',
+                properties: {
+                    command: { type: 'string', description: 'Shell command to execute' },
+                    timeout_ms: { type: 'integer', description: 'Timeout in milliseconds (default 30000)' },
+                },
+                required: ['command'],
+            },
+        },
+    },
+    async execute(args, cwd) {
+        const command = String(args.command);
+        const timeoutMs = typeof args.timeout_ms === 'number' ? args.timeout_ms : 30000;
+        return runShell(command, cwd, timeoutMs);
+    },
+};
+function runShell(command, cwd, timeoutMs) {
+    return new Promise((resolve) => {
+        const isWin = process.platform === 'win32';
+        const shell = isWin ? 'cmd' : 'sh';
+        const shellArgs = isWin ? ['/c', command] : ['-c', command];
+        const proc = (0, child_process_1.spawn)(shell, shellArgs, { cwd, stdio: 'pipe' });
+        const out = [];
+        let timedOut = false;
+        const timer = setTimeout(() => { timedOut = true; proc.kill('SIGTERM'); }, timeoutMs);
+        proc.stdout.on('data', (c) => out.push(c));
+        proc.stderr.on('data', (c) => out.push(c));
+        proc.on('close', (code) => {
+            clearTimeout(timer);
+            const text = Buffer.concat(out).toString('utf8').trim();
+            if (timedOut)
+                resolve(`[timed out after ${timeoutMs}ms]\n${text}`);
+            else
+                resolve(code === 0 ? text || '(no output)' : `[exit ${code}]\n${text}`);
+        });
+        proc.on('error', (err) => { clearTimeout(timer); resolve(`[error] ${err}`); });
+    });
+}
+// ─── Registry ─────────────────────────────────────────────────────────────────
+exports.BUILT_IN_TOOLS = {
+    read_file: readFile,
+    write_file: writeFile,
+    patch_file: patchFile,
+    glob,
+    grep,
+    run_command: runCommand,
+};
+exports.ALL_BUILT_IN_SCHEMAS = Object.values(exports.BUILT_IN_TOOLS).map((t) => t.schema);

package/lib/runtime/executor/index.d.ts

@@ -0,0 +1,6 @@
+export { LlmTaskExecutor } from './llm-task-executor';
+export type { LlmProviderConfig, LlmExecutorEvent, LlmExecutorEventType } from './llm-task-executor';
+export { buildNodePrompt } from './node-prompt-builder';
+export { selectToolsForActions } from './action-tool-map';
+export { BUILT_IN_TOOLS, ALL_BUILT_IN_SCHEMAS } from './built-in-tools';
+export type { BuiltInToolHandler } from './built-in-tools';

package/lib/runtime/executor/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALL_BUILT_IN_SCHEMAS = exports.BUILT_IN_TOOLS = exports.selectToolsForActions = exports.buildNodePrompt = exports.LlmTaskExecutor = void 0;
+var llm_task_executor_1 = require("./llm-task-executor");
+Object.defineProperty(exports, "LlmTaskExecutor", { enumerable: true, get: function () { return llm_task_executor_1.LlmTaskExecutor; } });
+var node_prompt_builder_1 = require("./node-prompt-builder");
+Object.defineProperty(exports, "buildNodePrompt", { enumerable: true, get: function () { return node_prompt_builder_1.buildNodePrompt; } });
+var action_tool_map_1 = require("./action-tool-map");
+Object.defineProperty(exports, "selectToolsForActions", { enumerable: true, get: function () { return action_tool_map_1.selectToolsForActions; } });
+var built_in_tools_1 = require("./built-in-tools");
+Object.defineProperty(exports, "BUILT_IN_TOOLS", { enumerable: true, get: function () { return built_in_tools_1.BUILT_IN_TOOLS; } });
+Object.defineProperty(exports, "ALL_BUILT_IN_SCHEMAS", { enumerable: true, get: function () { return built_in_tools_1.ALL_BUILT_IN_SCHEMAS; } });

package/lib/runtime/executor/llm-task-executor.d.ts

@@ -0,0 +1,29 @@
+import type { GraphNode } from '../compiler/graph-compiler';
+import type { WorkspaceLease } from '../models/workspace';
+import type { TaskExecutor, TaskResult } from '../scheduler/scheduler';
+import type { PluginRegistry } from '../plugins/plugin-registry';
+export interface LlmProviderConfig {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    maxTokens?: number;
+    maxTurns?: number;
+    timeoutMs?: number;
+    systemPrompt?: string;
+}
+export type LlmExecutorEventType = 'turn_start' | 'turn_complete' | 'tool_call' | 'tool_result' | 'executor_complete';
+export interface LlmExecutorEvent {
+    type: LlmExecutorEventType;
+    nodeId: string;
+    attempt: number;
+    detail?: Record<string, unknown>;
+}
+export declare class LlmTaskExecutor implements TaskExecutor {
+    private readonly provider;
+    private readonly registry?;
+    private readonly onProgress?;
+    constructor(provider: LlmProviderConfig, registry?: PluginRegistry | undefined, onProgress?: ((event: LlmExecutorEvent) => void) | undefined);
+    execute(node: GraphNode, lease: WorkspaceLease, runId: string, attempt: number): Promise<TaskResult>;
+    private invokeToolCall;
+    private emit;
+}