forjajs 5.1.0 → 5.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +76 -0
- package/README.md +37 -4
- package/README.pt-BR.md +39 -4
- package/dist/apps/cli/src/index.d.ts +0 -1
- package/dist/apps/cli/src/index.js +43 -32
- package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
- package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
- package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
- package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
- package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
- package/dist/apps/server/src/forja-nest.module.js +55 -0
- package/dist/apps/server/src/main.d.ts +21 -4
- package/dist/apps/server/src/main.js +79 -57
- package/dist/apps/server/src/task-planning-service.d.ts +29 -0
- package/dist/apps/server/src/task-planning-service.js +195 -0
- package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
- package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
- package/dist/bin/forja.js +3 -2
- package/dist/lib/agent-evals.d.ts +138 -0
- package/dist/lib/agent-evals.js +349 -0
- package/dist/lib/cli-output.js +14 -2
- package/dist/lib/code-context.d.ts +33 -5
- package/dist/lib/code-context.js +70 -5
- package/dist/lib/context-builder.d.ts +49 -4
- package/dist/lib/context-builder.js +114 -47
- package/dist/lib/core/coverage-gate.d.ts +59 -0
- package/dist/lib/core/coverage-gate.js +58 -0
- package/dist/lib/core/doc-graph.d.ts +38 -0
- package/dist/lib/core/doc-graph.js +83 -0
- package/dist/lib/core/health.js +286 -5
- package/dist/lib/core/journey.js +26 -0
- package/dist/lib/core/registry.js +81 -6
- package/dist/lib/docs-reference.d.ts +35 -0
- package/dist/lib/docs-reference.js +57 -0
- package/dist/lib/project-wiring.js +6 -2
- package/dist/lib/session-memory.d.ts +38 -0
- package/dist/lib/session-memory.js +206 -0
- package/dist/lib/spec-trace.d.ts +46 -0
- package/dist/lib/spec-trace.js +184 -0
- package/dist/packages/adapter-nest/src/index.d.ts +2 -1
- package/dist/packages/adapter-nest/src/index.js +59 -1
- package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
- package/dist/packages/adapter-sqlite/src/index.js +61 -1
- package/dist/packages/context/src/index.d.ts +2 -0
- package/dist/packages/context/src/index.js +36 -15
- package/dist/packages/contracts/src/index.d.ts +64 -0
- package/dist/packages/core/src/index.d.ts +9 -1
- package/dist/packages/core/src/index.js +28 -3
- package/dist/packages/graph/src/index.js +14 -5
- package/dist/packages/mcp/src/index.d.ts +8 -0
- package/dist/packages/mcp/src/index.js +12 -1
- package/dist/packages/observability/src/index.d.ts +11 -0
- package/dist/packages/observability/src/index.js +3 -0
- package/dist/packages/orchestration/src/index.d.ts +15 -1
- package/dist/packages/orchestration/src/index.js +127 -21
- package/dist/packages/planner/src/index.d.ts +7 -1
- package/dist/packages/planner/src/index.js +67 -10
- package/dist/packages/planner/src/proposal-store.d.ts +30 -0
- package/dist/packages/planner/src/proposal-store.js +109 -0
- package/dist/packages/policy/src/index.d.ts +9 -16
- package/dist/packages/policy/src/index.js +114 -31
- package/dist/packages/runtime/src/index.d.ts +16 -2
- package/dist/packages/runtime/src/index.js +176 -61
- package/dist/scripts/build-smart-context.d.ts +2 -0
- package/dist/scripts/build-smart-context.js +12 -3
- package/dist/scripts/code-context.d.ts +3 -1
- package/dist/scripts/code-context.js +13 -3
- package/dist/scripts/coverage-gate.d.ts +2 -0
- package/dist/scripts/coverage-gate.js +101 -0
- package/dist/scripts/eval-agents.d.ts +11 -0
- package/dist/scripts/eval-agents.js +96 -0
- package/dist/scripts/gen-commands-doc.d.ts +2 -0
- package/dist/scripts/gen-commands-doc.js +18 -0
- package/dist/scripts/hook-session-memory.d.ts +9 -0
- package/dist/scripts/hook-session-memory.js +20 -0
- package/dist/scripts/hook-session-start.js +34 -0
- package/dist/scripts/spec-trace.d.ts +10 -0
- package/dist/scripts/spec-trace.js +73 -0
- package/dist/scripts/sync-universal-memory.js +69 -4
- package/dist/scripts/token-benchmark.d.ts +33 -1
- package/dist/scripts/token-benchmark.js +179 -5
- package/dist/scripts/token-economy.js +3 -1
- package/dist/scripts/tools-doctor.d.ts +16 -1
- package/dist/scripts/tools-doctor.js +58 -17
- package/docs/commands.md +155 -0
- package/docs/fluxo.md +11 -7
- package/docs/init-project.md +3 -1
- package/docs/llm-fit-loop.md +20 -0
- package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
- package/docs/produto/factsheet-marketing.md +7 -5
- package/docs/produto/roteiro-demo.md +14 -5
- package/docs/quick-reference.md +3 -3
- package/docs/token-optimization.md +10 -6
- package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
- package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
- package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
- package/package.json +4 -2
- package/specs/avaliacoes-de-agentes/spec.md +52 -0
- package/specs/criterios-ligados-a-testes/spec.md +42 -0
- package/specs/memoria-de-sessao/spec.md +48 -0
- package/specs/v6-agent-runtime-portable/spec.md +83 -0
- package/specs/v6-core-consolidation/spec.md +70 -0
- package/specs/v6-docs-drift/spec.md +85 -0
- package/specs/v6-quality-gates/spec.md +99 -0
- package/specs/v6-token-economy/spec.md +84 -0
- package/templates/evals/agents/adr.json +25 -0
- package/templates/evals/agents/memoria.json +32 -0
- package/templates/evals/agents/proxima-acao.json +29 -0
- package/templates/evals/agents/spec-nova.json +26 -0
- package/templates/evals/agents/teste-do-criterio.json +29 -0
- package/templates/project/AGENTS.md +7 -0
- package/templates/project/CLAUDE.md +3 -2
- package/templates/project/skills/testing/SKILL.md +1 -1
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import type { AgentIdentity, EntityId, EvaluationResult, ExecutionResult, Handoff, RunId, RuntimeRun, Task, TokenBudget } from '../../../packages/contracts/src/index.ts';
|
|
2
|
+
import type { CapabilityPolicy } from '../../../packages/core/src/index.ts';
|
|
3
|
+
import { OrchestrationError, type OrchestrationStore, type TaskEngine } from '../../../packages/orchestration/src/index.ts';
|
|
4
|
+
import { type RuntimeEngine, type RuntimePersistence, type RuntimePlanStep } from '../../../packages/runtime/src/index.ts';
|
|
5
|
+
export interface TaskRuntimeInput {
|
|
6
|
+
readonly objective: string;
|
|
7
|
+
readonly agent: AgentIdentity;
|
|
8
|
+
readonly budget: TokenBudget;
|
|
9
|
+
readonly steps: readonly RuntimePlanStep[];
|
|
10
|
+
readonly taskId?: EntityId;
|
|
11
|
+
readonly sprintId?: EntityId;
|
|
12
|
+
readonly handoffId?: EntityId;
|
|
13
|
+
readonly correlationId?: string;
|
|
14
|
+
}
|
|
15
|
+
export interface TaskValidationContext {
|
|
16
|
+
readonly task: Task;
|
|
17
|
+
readonly handoff?: Handoff;
|
|
18
|
+
}
|
|
19
|
+
export interface TaskRuntimeValidator {
|
|
20
|
+
validate(run: RuntimeRun, results: readonly ExecutionResult[], context?: TaskValidationContext): EvaluationResult | Promise<EvaluationResult>;
|
|
21
|
+
}
|
|
22
|
+
export declare class TaskCoordinationError extends OrchestrationError {
|
|
23
|
+
readonly code: string;
|
|
24
|
+
readonly runId?: RunId | undefined;
|
|
25
|
+
constructor(code: string, message: string, runId?: RunId | undefined);
|
|
26
|
+
}
|
|
27
|
+
export declare class TaskRuntimeCoordinator {
|
|
28
|
+
private readonly runtime;
|
|
29
|
+
private readonly policy;
|
|
30
|
+
private readonly store;
|
|
31
|
+
private readonly tasks;
|
|
32
|
+
private readonly persistence?;
|
|
33
|
+
private readonly projections;
|
|
34
|
+
private readonly invalidBindings;
|
|
35
|
+
constructor(runtime: RuntimeEngine, policy: CapabilityPolicy, store: OrchestrationStore, tasks: TaskEngine, persistence?: RuntimePersistence | undefined);
|
|
36
|
+
initialize(): Promise<void>;
|
|
37
|
+
start(input: TaskRuntimeInput, context: unknown): Promise<RuntimeRun>;
|
|
38
|
+
get(runId: RunId): Promise<RuntimeRun>;
|
|
39
|
+
execute(runId: RunId): Promise<RuntimeRun>;
|
|
40
|
+
resume(runId: RunId): Promise<RuntimeRun>;
|
|
41
|
+
pause(runId: RunId): Promise<RuntimeRun>;
|
|
42
|
+
cancel(runId: RunId): Promise<RuntimeRun>;
|
|
43
|
+
executionStarted(run: RuntimeRun): Promise<void>;
|
|
44
|
+
validationContext(run: RuntimeRun): Promise<TaskValidationContext | undefined>;
|
|
45
|
+
private load;
|
|
46
|
+
private assertBinding;
|
|
47
|
+
private project;
|
|
48
|
+
private projectOnce;
|
|
49
|
+
private blockRecovery;
|
|
50
|
+
private scopeHash;
|
|
51
|
+
private validateScope;
|
|
52
|
+
private relativePath;
|
|
53
|
+
private terminal;
|
|
54
|
+
private equal;
|
|
55
|
+
private error;
|
|
56
|
+
private now;
|
|
57
|
+
}
|
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
import { createHash, randomUUID } from 'node:crypto';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { isDeepStrictEqual } from 'node:util';
|
|
4
|
+
import { OrchestrationError } from '../../../packages/orchestration/src/index.js';
|
|
5
|
+
import { RuntimeError } from '../../../packages/runtime/src/index.js';
|
|
6
|
+
export class TaskCoordinationError extends OrchestrationError {
|
|
7
|
+
code;
|
|
8
|
+
runId;
|
|
9
|
+
constructor(code, message, runId) {
|
|
10
|
+
super(message);
|
|
11
|
+
this.code = code;
|
|
12
|
+
this.runId = runId;
|
|
13
|
+
this.name = 'TaskCoordinationError';
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
export class TaskRuntimeCoordinator {
|
|
17
|
+
runtime;
|
|
18
|
+
policy;
|
|
19
|
+
store;
|
|
20
|
+
tasks;
|
|
21
|
+
persistence;
|
|
22
|
+
projections = new Map();
|
|
23
|
+
invalidBindings = new Set();
|
|
24
|
+
constructor(runtime, policy, store, tasks, persistence) {
|
|
25
|
+
this.runtime = runtime;
|
|
26
|
+
this.policy = policy;
|
|
27
|
+
this.store = store;
|
|
28
|
+
this.tasks = tasks;
|
|
29
|
+
this.persistence = persistence;
|
|
30
|
+
}
|
|
31
|
+
async initialize() {
|
|
32
|
+
for (const task of await this.store.listTasks()) {
|
|
33
|
+
if (task.runtimeRunId === undefined)
|
|
34
|
+
continue;
|
|
35
|
+
let run = await this.persistence?.getRun(task.runtimeRunId);
|
|
36
|
+
if (run === undefined) {
|
|
37
|
+
await this.blockRecovery(task, 'RECOVERY_INCOMPLETE', 'Reserved execution is missing');
|
|
38
|
+
continue;
|
|
39
|
+
}
|
|
40
|
+
if (run.runId !== task.runtimeRunId || run.taskId !== task.id || run.sprintId !== task.sprintId || run.handoffId !== task.handoffId) {
|
|
41
|
+
await this.blockRecovery(task, 'BINDING_MISMATCH', 'Persisted execution does not match its reserving task');
|
|
42
|
+
continue;
|
|
43
|
+
}
|
|
44
|
+
if (run.state === 'running' || run.state === 'validating') {
|
|
45
|
+
run = { ...run, state: 'blocked', validation: undefined, error: this.error('RECOVERY_INTERRUPTED', 'Interrupted execution requires review before any further work'), updatedAt: this.now() };
|
|
46
|
+
await this.persistence?.saveRun(run);
|
|
47
|
+
}
|
|
48
|
+
try {
|
|
49
|
+
await this.runtime.recover(run.runId, this.policy);
|
|
50
|
+
}
|
|
51
|
+
catch (error) {
|
|
52
|
+
if (!(error instanceof RuntimeError) || !['RECOVERY_INCOMPLETE', 'RUN_NOT_FOUND'].includes(error.code))
|
|
53
|
+
throw error;
|
|
54
|
+
await this.blockRecovery(task, 'RECOVERY_INCOMPLETE', 'Persisted execution cannot be recovered safely');
|
|
55
|
+
continue;
|
|
56
|
+
}
|
|
57
|
+
try {
|
|
58
|
+
await this.project(run);
|
|
59
|
+
}
|
|
60
|
+
catch (error) {
|
|
61
|
+
if (!(error instanceof TaskCoordinationError) || error.code !== 'BINDING_MISMATCH')
|
|
62
|
+
throw error;
|
|
63
|
+
await this.blockRecovery(task, error.code, error.message);
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
async start(input, context) {
|
|
68
|
+
const runId = randomUUID();
|
|
69
|
+
let sprintId = input.sprintId;
|
|
70
|
+
if (input.handoffId !== undefined && input.taskId === undefined)
|
|
71
|
+
throw new TaskCoordinationError('INVALID_BINDING', 'Handoff requires a task');
|
|
72
|
+
if (input.taskId !== undefined) {
|
|
73
|
+
const task = await this.store.getTask(input.taskId);
|
|
74
|
+
if (task === undefined)
|
|
75
|
+
throw new TaskCoordinationError('TASK_NOT_FOUND', 'Task does not exist');
|
|
76
|
+
if (task.runtimeRunId !== undefined)
|
|
77
|
+
throw new TaskCoordinationError('TASK_ALREADY_BOUND', 'Task already has an execution', task.runtimeRunId);
|
|
78
|
+
if (task.status !== 'todo' && task.status !== 'in_progress')
|
|
79
|
+
throw new TaskCoordinationError('TASK_NOT_READY', 'Task is not ready for execution');
|
|
80
|
+
await this.tasks.assertEligible(task);
|
|
81
|
+
if (sprintId !== undefined && sprintId !== task.sprintId)
|
|
82
|
+
throw new TaskCoordinationError('INVALID_BINDING', 'Task and sprint do not match');
|
|
83
|
+
sprintId = task.sprintId;
|
|
84
|
+
this.validateScope(task, input);
|
|
85
|
+
const handoff = input.handoffId === undefined ? undefined : await this.store.getHandoff(input.handoffId);
|
|
86
|
+
if (input.handoffId !== undefined && (handoff === undefined || handoff.taskId !== task.id || handoff.runId !== undefined || handoff.status !== 'pending' || handoff.blockers.length > 0 || handoff.nextAgent !== input.agent.id)) {
|
|
87
|
+
throw new TaskCoordinationError('INVALID_BINDING', 'Handoff is not available for this task and agent');
|
|
88
|
+
}
|
|
89
|
+
await this.store.transitionExecution({
|
|
90
|
+
beforeTask: task,
|
|
91
|
+
task: { ...task, runtimeRunId: runId, handoffId: handoff?.id, executionScopeHash: this.scopeHash(task, handoff), status: 'in_progress', executionError: undefined, updatedAt: this.now() },
|
|
92
|
+
beforeHandoff: handoff,
|
|
93
|
+
handoff: handoff === undefined ? undefined : { ...handoff, runId, status: 'in_progress', updatedAt: this.now() },
|
|
94
|
+
});
|
|
95
|
+
}
|
|
96
|
+
const run = await this.runtime.start({ ...input, runId, sprintId, policy: this.policy, context });
|
|
97
|
+
await this.project(run);
|
|
98
|
+
return run;
|
|
99
|
+
}
|
|
100
|
+
async get(runId) {
|
|
101
|
+
await this.load(runId);
|
|
102
|
+
return this.runtime.get(runId);
|
|
103
|
+
}
|
|
104
|
+
async execute(runId) {
|
|
105
|
+
await this.load(runId);
|
|
106
|
+
const current = this.runtime.get(runId);
|
|
107
|
+
const linked = await this.assertBinding(current);
|
|
108
|
+
if (linked !== undefined && !this.terminal(current))
|
|
109
|
+
await this.tasks.assertEligible(linked.task);
|
|
110
|
+
const run = await this.runtime.execute(runId);
|
|
111
|
+
await this.project(run);
|
|
112
|
+
return run;
|
|
113
|
+
}
|
|
114
|
+
async resume(runId) {
|
|
115
|
+
await this.load(runId);
|
|
116
|
+
const current = this.runtime.get(runId);
|
|
117
|
+
const linked = await this.assertBinding(current);
|
|
118
|
+
if (linked !== undefined && !this.terminal(current))
|
|
119
|
+
await this.tasks.assertEligible(linked.task);
|
|
120
|
+
const run = this.terminal(current) ? current : await this.runtime.resume(runId, this.policy);
|
|
121
|
+
await this.project(run);
|
|
122
|
+
return run;
|
|
123
|
+
}
|
|
124
|
+
async pause(runId) {
|
|
125
|
+
await this.load(runId);
|
|
126
|
+
await this.assertBinding(this.runtime.get(runId));
|
|
127
|
+
const run = this.runtime.pause(runId);
|
|
128
|
+
await this.project(run);
|
|
129
|
+
return run;
|
|
130
|
+
}
|
|
131
|
+
async cancel(runId) {
|
|
132
|
+
await this.load(runId);
|
|
133
|
+
await this.assertBinding(this.runtime.get(runId));
|
|
134
|
+
const run = await this.runtime.cancel(runId);
|
|
135
|
+
await this.project(run);
|
|
136
|
+
return run;
|
|
137
|
+
}
|
|
138
|
+
executionStarted(run) { return this.project(run); }
|
|
139
|
+
async validationContext(run) {
|
|
140
|
+
return this.assertBinding(run);
|
|
141
|
+
}
|
|
142
|
+
async load(runId) {
|
|
143
|
+
if (this.invalidBindings.has(runId))
|
|
144
|
+
throw new TaskCoordinationError('BINDING_MISMATCH', 'Execution binding requires review', runId);
|
|
145
|
+
if (!this.runtime.has(runId))
|
|
146
|
+
await this.runtime.recover(runId, this.policy);
|
|
147
|
+
}
|
|
148
|
+
async assertBinding(run) {
|
|
149
|
+
if (run.taskId === undefined)
|
|
150
|
+
return undefined;
|
|
151
|
+
const task = await this.store.getTask(run.taskId);
|
|
152
|
+
if (task !== undefined && task.runtimeRunId === undefined)
|
|
153
|
+
return undefined;
|
|
154
|
+
if (task === undefined || task.runtimeRunId !== run.runId || task.sprintId !== run.sprintId || task.handoffId !== run.handoffId || task.objective !== run.objective) {
|
|
155
|
+
throw new TaskCoordinationError('BINDING_MISMATCH', 'Execution does not match its task binding', run.runId);
|
|
156
|
+
}
|
|
157
|
+
if (task.executionError?.code === 'RECOVERY_INCOMPLETE' || task.executionError?.code === 'BINDING_MISMATCH')
|
|
158
|
+
throw new TaskCoordinationError('BINDING_MISMATCH', 'Task recovery requires review', run.runId);
|
|
159
|
+
const handoff = task.handoffId === undefined ? undefined : await this.store.getHandoff(task.handoffId);
|
|
160
|
+
if (task.handoffId !== undefined && (handoff === undefined || handoff.taskId !== task.id || handoff.runId !== run.runId || handoff.nextAgent !== run.agent.id)) {
|
|
161
|
+
throw new TaskCoordinationError('BINDING_MISMATCH', 'Execution does not match its handoff binding', run.runId);
|
|
162
|
+
}
|
|
163
|
+
if (task.executionScopeHash !== this.scopeHash(task, handoff))
|
|
164
|
+
throw new TaskCoordinationError('BINDING_MISMATCH', 'Task or handoff scope changed after execution was reserved', run.runId);
|
|
165
|
+
return { task, handoff };
|
|
166
|
+
}
|
|
167
|
+
project(run) {
|
|
168
|
+
const previous = this.projections.get(run.runId) ?? Promise.resolve();
|
|
169
|
+
const operation = previous.then(() => this.projectOnce(run), () => this.projectOnce(run));
|
|
170
|
+
this.projections.set(run.runId, operation);
|
|
171
|
+
return operation.finally(() => { if (this.projections.get(run.runId) === operation)
|
|
172
|
+
this.projections.delete(run.runId); });
|
|
173
|
+
}
|
|
174
|
+
async projectOnce(result) {
|
|
175
|
+
// A store can expose a write before its promise/checkpoint has confirmed the transition.
|
|
176
|
+
const run = this.runtime.get(result.runId);
|
|
177
|
+
const linked = await this.assertBinding(run);
|
|
178
|
+
if (linked === undefined)
|
|
179
|
+
return;
|
|
180
|
+
const { task, handoff } = linked;
|
|
181
|
+
if (run.state === 'completed' && run.validation?.status !== 'accepted')
|
|
182
|
+
throw new TaskCoordinationError('BINDING_MISMATCH', 'Completed execution lacks accepted validation', run.runId);
|
|
183
|
+
const status = run.state === 'completed' ? 'done' : run.state === 'cancelled' ? 'cancelled' : ['failed', 'blocked', 'paused', 'awaiting_approval', 'rolled_back'].includes(run.state) ? 'blocked' : 'in_progress';
|
|
184
|
+
const evidenceIds = [...new Set([...task.evidenceIds, ...(run.validation?.checks.flatMap((check) => check.evidenceIds) ?? [])])];
|
|
185
|
+
const executionError = run.error ?? (status === 'blocked' && run.validation !== undefined ? this.error(`VALIDATION_${run.validation.status.toUpperCase()}`, run.validation.summary) : undefined);
|
|
186
|
+
const nextTask = { ...task, status, evidenceIds, executionError };
|
|
187
|
+
const nextHandoff = handoff === undefined ? undefined : { ...handoff, status: status === 'done' ? 'completed' : status, evidenceIds: [...new Set([...handoff.evidenceIds, ...(run.validation?.checks.flatMap((check) => check.evidenceIds) ?? [])])] };
|
|
188
|
+
if (this.equal(task, nextTask) && this.equal(handoff, nextHandoff))
|
|
189
|
+
return;
|
|
190
|
+
try {
|
|
191
|
+
await this.store.transitionExecution({ beforeTask: task, task: { ...nextTask, updatedAt: this.now() }, beforeHandoff: handoff, handoff: nextHandoff === undefined ? undefined : { ...nextHandoff, updatedAt: this.now() } });
|
|
192
|
+
}
|
|
193
|
+
catch (error) {
|
|
194
|
+
throw new TaskCoordinationError('PROJECTION_PENDING', error instanceof Error ? error.message : 'Task projection failed', run.runId);
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
async blockRecovery(task, code, message) {
|
|
198
|
+
if (task.runtimeRunId !== undefined)
|
|
199
|
+
this.invalidBindings.add(task.runtimeRunId);
|
|
200
|
+
const handoff = task.handoffId === undefined ? undefined : await this.store.getHandoff(task.handoffId);
|
|
201
|
+
const ownedHandoff = handoff?.taskId === task.id && handoff.runId === task.runtimeRunId ? handoff : undefined;
|
|
202
|
+
await this.store.transitionExecution({ recoveryBlock: true, beforeTask: task, task: { ...task, status: 'blocked', executionError: this.error(code, message), updatedAt: this.now() }, beforeHandoff: ownedHandoff, handoff: ownedHandoff === undefined ? undefined : { ...ownedHandoff, status: 'blocked', updatedAt: this.now() } });
|
|
203
|
+
}
|
|
204
|
+
scopeHash(task, handoff) {
|
|
205
|
+
const scope = {
|
|
206
|
+
objective: task.objective, acceptanceCriteria: task.acceptanceCriteria, allowedFiles: task.allowedFiles, dependencyIds: task.dependencyIds,
|
|
207
|
+
budget: { inputTokens: task.budget.inputTokens, outputTokens: task.budget.outputTokens, totalTokens: task.budget.totalTokens },
|
|
208
|
+
handoff: handoff === undefined ? undefined : { from: handoff.from, to: handoff.to, nextAgent: handoff.nextAgent, intent: handoff.intent, objective: handoff.objective, completedWork: handoff.completedWork, decisions: handoff.decisions, constraints: handoff.constraints, pending: handoff.pending, acceptance: handoff.acceptance, blockers: handoff.blockers },
|
|
209
|
+
};
|
|
210
|
+
return `v1:${createHash('sha256').update(JSON.stringify(scope)).digest('hex')}`;
|
|
211
|
+
}
|
|
212
|
+
validateScope(task, input) {
|
|
213
|
+
if (input.objective !== task.objective)
|
|
214
|
+
throw new TaskCoordinationError('TASK_SCOPE_MISMATCH', 'Execution objective must match the task');
|
|
215
|
+
if (input.budget.inputTokens > task.budget.inputTokens || input.budget.outputTokens > task.budget.outputTokens || input.budget.totalTokens > task.budget.totalTokens || input.budget.usedTokens !== task.budget.usedTokens) {
|
|
216
|
+
throw new TaskCoordinationError('TASK_SCOPE_MISMATCH', 'Execution budget exceeds task scope');
|
|
217
|
+
}
|
|
218
|
+
for (const file of input.steps.flatMap((step) => step.files ?? [])) {
|
|
219
|
+
if (!this.relativePath(file) || !task.allowedFiles.some((allowed) => allowed === '*' || (this.relativePath(allowed) && (file === allowed || (allowed.endsWith('/') && file.startsWith(allowed)))))) {
|
|
220
|
+
throw new TaskCoordinationError('TASK_SCOPE_MISMATCH', 'Execution files exceed task scope');
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
relativePath(value) { return value.length > 0 && !value.includes('\\') && !path.posix.isAbsolute(value) && !value.split('/').includes('..') && path.posix.normalize(value) === value; }
|
|
225
|
+
terminal(run) { return ['completed', 'failed', 'blocked', 'cancelled', 'rolled_back'].includes(run.state); }
|
|
226
|
+
equal(left, right) { return isDeepStrictEqual(left === undefined ? left : JSON.parse(JSON.stringify(left)), right === undefined ? right : JSON.parse(JSON.stringify(right))); }
|
|
227
|
+
error(code, message) { return { code, message, retryable: false }; }
|
|
228
|
+
now() { return new Date().toISOString(); }
|
|
229
|
+
}
|
package/dist/bin/forja.js
CHANGED
|
@@ -561,8 +561,9 @@ if (gateErrors.length) {
|
|
|
561
561
|
}
|
|
562
562
|
// SPEC-046: alguns comandos são capability (para o MCP) mas têm script próprio que já trata
|
|
563
563
|
// `--json` e a saída de texto (`status`, `next`, `engineer`). No CLI eles rodam direto — a
|
|
564
|
-
// camada de capability só serve o MCP e os comandos sem `--json` nativo.
|
|
565
|
-
|
|
564
|
+
// camada de capability só serve o MCP e os comandos sem `--json` nativo. Passar um desses pelo
|
|
565
|
+
// roteador embrulha o JSON do script num `{stdout: "..."}` e quebra o contrato do ADR-0082.
|
|
566
|
+
const NATIVE_JSON_CAPABILITIES = new Set(['status', 'next', 'engineer', 'tools:doctor', 'spec:trace', 'cost:economy']);
|
|
566
567
|
if (capabilityIdForCommand(name) !== undefined && !NATIVE_JSON_CAPABILITIES.has(name)) {
|
|
567
568
|
process.exit(await runCapabilityCommand(name, rest));
|
|
568
569
|
}
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/agent-evals.ts — avaliações com agentes reais em projeto descartável (SPEC-054, ADR-0093).
|
|
3
|
+
*
|
|
4
|
+
* Cada caso é um dado (`templates/evals/agents/*.json`): prompt, semente e checks determinísticos.
|
|
5
|
+
* O runner cria workspace e projeto num diretório temporário, aplica a semente, roda o agente
|
|
6
|
+
* (Claude Code ou Codex) com escrita confinada a esses diretórios e corrige pelo que ficou no disco,
|
|
7
|
+
* pelos comandos executados e pela resposta. Nunca roda no projeto do usuário.
|
|
8
|
+
*/
|
|
9
|
+
export type Check = {
|
|
10
|
+
type: 'file';
|
|
11
|
+
desc: string;
|
|
12
|
+
glob: string;
|
|
13
|
+
contains?: string[];
|
|
14
|
+
exclude?: string[];
|
|
15
|
+
} | {
|
|
16
|
+
type: 'answer';
|
|
17
|
+
desc: string;
|
|
18
|
+
matches: string[];
|
|
19
|
+
} | {
|
|
20
|
+
type: 'ran';
|
|
21
|
+
desc: string;
|
|
22
|
+
matches: string;
|
|
23
|
+
} | {
|
|
24
|
+
type: 'criterion';
|
|
25
|
+
desc: string;
|
|
26
|
+
spec: string;
|
|
27
|
+
ac: string;
|
|
28
|
+
} | {
|
|
29
|
+
type: 'command';
|
|
30
|
+
desc: string;
|
|
31
|
+
run: string;
|
|
32
|
+
expectExit?: number;
|
|
33
|
+
} | {
|
|
34
|
+
type: 'unchanged';
|
|
35
|
+
desc: string;
|
|
36
|
+
glob: string;
|
|
37
|
+
};
|
|
38
|
+
export interface EvalCase {
|
|
39
|
+
readonly id: string;
|
|
40
|
+
readonly title: string;
|
|
41
|
+
readonly prompt: string;
|
|
42
|
+
readonly seed?: {
|
|
43
|
+
readonly files?: Readonly<Record<string, string>>;
|
|
44
|
+
};
|
|
45
|
+
readonly checks: readonly Check[];
|
|
46
|
+
}
|
|
47
|
+
export declare function validateCase(c: any, source?: string): EvalCase;
|
|
48
|
+
export declare function loadCases(dir: string): EvalCase[];
|
|
49
|
+
/** Glob mínimo: `**` atravessa pastas, `*` não; o resto é literal. */
|
|
50
|
+
export declare function globToRegExp(glob: string): RegExp;
|
|
51
|
+
export declare function snapshot(dir: string): Map<string, string>;
|
|
52
|
+
export interface AgentRun {
|
|
53
|
+
readonly answer: string;
|
|
54
|
+
/** Comandos que de fato rodaram (Bash), e ferramentas MCP como `tool:<nome>`. */
|
|
55
|
+
readonly commands: readonly string[];
|
|
56
|
+
readonly costUsd: number | null;
|
|
57
|
+
readonly tokens: {
|
|
58
|
+
input: number;
|
|
59
|
+
output: number;
|
|
60
|
+
} | null;
|
|
61
|
+
readonly durationMs: number;
|
|
62
|
+
readonly exitCode: number;
|
|
63
|
+
readonly error?: string;
|
|
64
|
+
}
|
|
65
|
+
export interface AgentContext {
|
|
66
|
+
readonly projectDir: string;
|
|
67
|
+
readonly workspaceDir: string;
|
|
68
|
+
readonly prompt: string;
|
|
69
|
+
readonly env: NodeJS.ProcessEnv;
|
|
70
|
+
readonly model?: string;
|
|
71
|
+
readonly budgetUsd: number;
|
|
72
|
+
readonly timeoutMs: number;
|
|
73
|
+
}
|
|
74
|
+
export interface AgentAdapter {
|
|
75
|
+
readonly name: string;
|
|
76
|
+
version(): string | null;
|
|
77
|
+
run(ctx: AgentContext): AgentRun;
|
|
78
|
+
}
|
|
79
|
+
/** Comandos que o Claude pode rodar sem perguntar. Fora disso, `-p` nega (e o caso mostra). */
|
|
80
|
+
export declare const CLAUDE_ALLOWED_TOOLS: string[];
|
|
81
|
+
export declare function parseClaudeStream(stdout: string): Omit<AgentRun, 'durationMs' | 'exitCode'>;
|
|
82
|
+
export declare function parseCodexJson(stdout: string): Omit<AgentRun, 'durationMs' | 'exitCode'>;
|
|
83
|
+
export declare const claudeAdapter: (bin?: string) => AgentAdapter;
|
|
84
|
+
export declare const codexAdapter: (bin?: string) => AgentAdapter;
|
|
85
|
+
export declare const ADAPTERS: Readonly<Record<string, () => AgentAdapter>>;
|
|
86
|
+
export interface CheckResult {
|
|
87
|
+
readonly desc: string;
|
|
88
|
+
readonly type: Check['type'];
|
|
89
|
+
readonly ok: boolean;
|
|
90
|
+
readonly detail: string;
|
|
91
|
+
}
|
|
92
|
+
export declare function grade(check: Check, projectDir: string, run: AgentRun, before: Map<string, string>, env: NodeJS.ProcessEnv): CheckResult;
|
|
93
|
+
export interface CaseResult {
|
|
94
|
+
readonly id: string;
|
|
95
|
+
readonly title: string;
|
|
96
|
+
readonly pass: boolean;
|
|
97
|
+
readonly checks: readonly CheckResult[];
|
|
98
|
+
readonly costUsd: number | null;
|
|
99
|
+
readonly durationMs: number;
|
|
100
|
+
readonly commands: number;
|
|
101
|
+
/** Início da resposta final do agente, para diagnosticar a falha sem rodar de novo. */
|
|
102
|
+
readonly answer: string;
|
|
103
|
+
readonly error?: string;
|
|
104
|
+
}
|
|
105
|
+
export interface SuiteOptions {
|
|
106
|
+
/** Entry point do forja em teste: é o que o agente chama via PATH. */
|
|
107
|
+
readonly forjaBin: string;
|
|
108
|
+
readonly model?: string;
|
|
109
|
+
readonly budgetUsd: number;
|
|
110
|
+
readonly timeoutMs: number;
|
|
111
|
+
readonly keep?: boolean;
|
|
112
|
+
readonly onCase?: (c: EvalCase, r: CaseResult) => void;
|
|
113
|
+
}
|
|
114
|
+
/** Workspace + projeto descartáveis, com um `forja` no PATH apontando para a instalação em teste. */
|
|
115
|
+
export declare function prepareProject(baseDir: string, name: string, forjaBin: string): {
|
|
116
|
+
ws: string;
|
|
117
|
+
proj: string;
|
|
118
|
+
env: NodeJS.ProcessEnv;
|
|
119
|
+
};
|
|
120
|
+
export declare function runCase(c: EvalCase, adapter: AgentAdapter, baseDir: string, opts: SuiteOptions): CaseResult;
|
|
121
|
+
export interface SuiteResult {
|
|
122
|
+
readonly ts: string;
|
|
123
|
+
readonly agent: string;
|
|
124
|
+
readonly agentVersion: string | null;
|
|
125
|
+
readonly model: string | null;
|
|
126
|
+
readonly forjaVersion: string;
|
|
127
|
+
readonly cases: readonly CaseResult[];
|
|
128
|
+
readonly passed: number;
|
|
129
|
+
readonly costUsd: number | null;
|
|
130
|
+
}
|
|
131
|
+
export declare function runSuite(cases: readonly EvalCase[], adapter: AgentAdapter, forjaVersion: string, opts: SuiteOptions): SuiteResult;
|
|
132
|
+
export declare function appendHistory(file: string, result: SuiteResult): void;
|
|
133
|
+
/** Última execução do mesmo agente e modelo, para comparar. */
|
|
134
|
+
export declare function previousRun(file: string, agent: string, model: string | null): SuiteResult | null;
|
|
135
|
+
export declare function compareRuns(prev: SuiteResult | null, cur: SuiteResult): {
|
|
136
|
+
regressed: string[];
|
|
137
|
+
fixed: string[];
|
|
138
|
+
};
|