forjajs 5.1.0 → 5.3.1
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 +108 -0
- package/README.md +52 -4
- package/README.pt-BR.md +54 -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 +365 -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/exec.d.ts +55 -0
- package/dist/lib/exec.js +141 -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-git/src/index.js +13 -4
- 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/llm/src/index.js +7 -24
- 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/llm-fit.js +15 -6
- package/dist/scripts/simulate.js +16 -4
- 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 +104 -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
|
@@ -72,6 +72,7 @@ export interface ExecutionError {
|
|
|
72
72
|
readonly details?: Readonly<Record<string, string>>;
|
|
73
73
|
}
|
|
74
74
|
export interface ExecutionResult extends AuditFields {
|
|
75
|
+
readonly operationId?: string;
|
|
75
76
|
readonly runId: RunId;
|
|
76
77
|
readonly status: 'succeeded' | 'failed' | 'blocked' | 'cancelled';
|
|
77
78
|
readonly output?: CapabilityOutput;
|
|
@@ -118,6 +119,8 @@ export interface PolicyDecision {
|
|
|
118
119
|
readonly approvalRequestId?: EntityId;
|
|
119
120
|
}
|
|
120
121
|
export interface ApprovalRequest extends AuditFields {
|
|
122
|
+
readonly operationId?: string;
|
|
123
|
+
readonly fingerprint?: string;
|
|
121
124
|
readonly id: EntityId;
|
|
122
125
|
readonly action: string;
|
|
123
126
|
readonly justification: string;
|
|
@@ -147,6 +150,10 @@ export interface Sprint extends AuditFields {
|
|
|
147
150
|
}
|
|
148
151
|
export interface Task extends AuditFields {
|
|
149
152
|
readonly id: EntityId;
|
|
153
|
+
readonly runtimeRunId?: RunId;
|
|
154
|
+
readonly handoffId?: EntityId;
|
|
155
|
+
readonly executionScopeHash?: string;
|
|
156
|
+
readonly executionError?: ExecutionError;
|
|
150
157
|
readonly sprintId: EntityId;
|
|
151
158
|
readonly objective: string;
|
|
152
159
|
readonly acceptanceCriteria: readonly string[];
|
|
@@ -158,6 +165,9 @@ export interface Task extends AuditFields {
|
|
|
158
165
|
}
|
|
159
166
|
export interface Handoff extends AuditFields {
|
|
160
167
|
readonly id: EntityId;
|
|
168
|
+
readonly taskId?: EntityId;
|
|
169
|
+
readonly runId?: RunId;
|
|
170
|
+
readonly status?: 'pending' | 'in_progress' | 'blocked' | 'completed' | 'cancelled';
|
|
161
171
|
readonly from: string;
|
|
162
172
|
readonly to: string;
|
|
163
173
|
readonly intent: string;
|
|
@@ -192,6 +202,7 @@ export interface RuntimeRun extends AuditFields {
|
|
|
192
202
|
readonly agent: AgentIdentity;
|
|
193
203
|
readonly sprintId?: EntityId;
|
|
194
204
|
readonly taskId?: EntityId;
|
|
205
|
+
readonly handoffId?: EntityId;
|
|
195
206
|
readonly policy: PolicyDecision;
|
|
196
207
|
readonly budget: TokenBudget;
|
|
197
208
|
readonly state: ExecutionState;
|
|
@@ -251,10 +262,20 @@ export interface ContextMetrics {
|
|
|
251
262
|
readonly selectedTokens: number;
|
|
252
263
|
readonly unusedTokens: number;
|
|
253
264
|
}
|
|
265
|
+
export interface ContextItem {
|
|
266
|
+
readonly id: EntityId;
|
|
267
|
+
readonly source: 'memory' | 'graph';
|
|
268
|
+
readonly locator: string;
|
|
269
|
+
readonly content?: string;
|
|
270
|
+
readonly checksum: string;
|
|
271
|
+
readonly status: KnowledgeStatus;
|
|
272
|
+
readonly evidence: readonly Evidence[];
|
|
273
|
+
}
|
|
254
274
|
export interface ContextPackage extends AuditFields {
|
|
255
275
|
readonly id: EntityId;
|
|
256
276
|
readonly references: readonly Evidence[];
|
|
257
277
|
readonly content: readonly string[];
|
|
278
|
+
readonly items?: readonly ContextItem[];
|
|
258
279
|
readonly budget: TokenBudget;
|
|
259
280
|
readonly checksum: string;
|
|
260
281
|
readonly metrics: ContextMetrics;
|
|
@@ -275,6 +296,10 @@ export interface PlanStep extends AuditFields {
|
|
|
275
296
|
readonly acceptanceCriteria: readonly string[];
|
|
276
297
|
readonly allowedFiles: readonly string[];
|
|
277
298
|
readonly dependencyIds: readonly EntityId[];
|
|
299
|
+
readonly externalDependencyIds?: readonly EntityId[];
|
|
300
|
+
readonly contextItemId?: EntityId;
|
|
301
|
+
readonly rationale?: string;
|
|
302
|
+
readonly constraints?: readonly string[];
|
|
278
303
|
readonly evidenceIds: readonly EntityId[];
|
|
279
304
|
readonly risk: RiskLevel;
|
|
280
305
|
readonly budget: TokenBudget;
|
|
@@ -286,8 +311,47 @@ export interface ExecutionPlan extends AuditFields {
|
|
|
286
311
|
readonly steps: readonly PlanStep[];
|
|
287
312
|
readonly budget: TokenBudget;
|
|
288
313
|
readonly risk: RiskLevel;
|
|
314
|
+
readonly constraints?: readonly string[];
|
|
315
|
+
readonly decisions?: readonly string[];
|
|
289
316
|
readonly evidenceIds: readonly EntityId[];
|
|
290
317
|
}
|
|
318
|
+
export interface PlanningSnapshot {
|
|
319
|
+
readonly task: Task;
|
|
320
|
+
readonly sprint: Sprint;
|
|
321
|
+
readonly dependencies: readonly Task[];
|
|
322
|
+
readonly handoff?: Handoff;
|
|
323
|
+
}
|
|
324
|
+
export interface PlanningBudget {
|
|
325
|
+
readonly limit: TokenBudget;
|
|
326
|
+
readonly briefingTokens: number;
|
|
327
|
+
readonly contextTokens: number;
|
|
328
|
+
readonly allocation: TokenBudget;
|
|
329
|
+
}
|
|
330
|
+
export interface PlanningReview {
|
|
331
|
+
readonly decision: 'approved' | 'rejected';
|
|
332
|
+
readonly reviewerId: EntityId;
|
|
333
|
+
readonly reason: string;
|
|
334
|
+
readonly digest: string;
|
|
335
|
+
readonly decidedAt: ISO8601;
|
|
336
|
+
readonly sourcesVerifiedAt?: ISO8601;
|
|
337
|
+
}
|
|
338
|
+
export interface PlanningProposal extends AuditFields {
|
|
339
|
+
readonly id: EntityId;
|
|
340
|
+
readonly version: 1;
|
|
341
|
+
readonly digest: string;
|
|
342
|
+
readonly executor: AgentIdentity;
|
|
343
|
+
readonly snapshot: PlanningSnapshot;
|
|
344
|
+
readonly plan?: ExecutionPlan;
|
|
345
|
+
readonly context?: ContextPackage;
|
|
346
|
+
readonly status: 'draft' | 'approved' | 'rejected' | 'blocked';
|
|
347
|
+
readonly blockers: readonly {
|
|
348
|
+
readonly code: string;
|
|
349
|
+
readonly message: string;
|
|
350
|
+
}[];
|
|
351
|
+
readonly budget: PlanningBudget;
|
|
352
|
+
readonly declaredEvidenceIds: readonly EntityId[];
|
|
353
|
+
readonly review?: PlanningReview;
|
|
354
|
+
}
|
|
291
355
|
export interface EvaluationResult extends AuditFields {
|
|
292
356
|
readonly status: 'accepted' | 'rejected' | 'inconclusive' | 'blocked';
|
|
293
357
|
readonly checks: readonly {
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type AgentIdentity, type AgentProfile, type CapabilityDefinition, type CapabilityInput, type CapabilityOutput, type ExecutionResult, type PolicyDecision, type RunId, type ISO8601, type TokenBudget } from '../../contracts/src/index.ts';
|
|
1
|
+
import { type AgentIdentity, type AgentProfile, type CapabilityDefinition, type CapabilityInput, type CapabilityOutput, type ExecutionError, type ExecutionResult, type PolicyDecision, type RunId, type ISO8601, type TokenBudget } from '../../contracts/src/index.ts';
|
|
2
2
|
export interface CapabilityExecutionContext {
|
|
3
3
|
readonly runId: RunId;
|
|
4
4
|
readonly agent: AgentIdentity;
|
|
@@ -6,6 +6,7 @@ export interface CapabilityExecutionContext {
|
|
|
6
6
|
}
|
|
7
7
|
export interface CapabilityRegistration<Input, Output> {
|
|
8
8
|
readonly definition: CapabilityDefinition;
|
|
9
|
+
readonly categories?: readonly string[];
|
|
9
10
|
readonly validateInput: (value: unknown) => Input;
|
|
10
11
|
readonly validateOutput: (value: unknown) => Output;
|
|
11
12
|
readonly handler: (input: Input, context: CapabilityExecutionContext) => CapabilityOutput | Promise<CapabilityOutput>;
|
|
@@ -15,6 +16,7 @@ export interface CapabilityAuthorizationRequest {
|
|
|
15
16
|
readonly input: CapabilityInput;
|
|
16
17
|
readonly agent: AgentIdentity;
|
|
17
18
|
readonly correlationId?: string;
|
|
19
|
+
readonly operationId?: string;
|
|
18
20
|
readonly projectId?: string;
|
|
19
21
|
readonly environment: string;
|
|
20
22
|
readonly categories: readonly string[];
|
|
@@ -42,6 +44,7 @@ export interface CapabilityExecutionRequest {
|
|
|
42
44
|
readonly agent: AgentIdentity;
|
|
43
45
|
readonly policy: CapabilityPolicy;
|
|
44
46
|
readonly correlationId?: string;
|
|
47
|
+
readonly operationId?: string;
|
|
45
48
|
readonly projectId?: string;
|
|
46
49
|
readonly environment?: string;
|
|
47
50
|
readonly categories?: readonly string[];
|
|
@@ -62,6 +65,11 @@ export interface CapabilityExecutionRequest {
|
|
|
62
65
|
export declare class CapabilityRegistryError extends Error {
|
|
63
66
|
constructor(message: string);
|
|
64
67
|
}
|
|
68
|
+
export declare class CapabilityExecutionFailure extends Error {
|
|
69
|
+
readonly executionError: ExecutionError;
|
|
70
|
+
readonly output?: CapabilityOutput;
|
|
71
|
+
constructor(error: ExecutionError, output?: CapabilityOutput);
|
|
72
|
+
}
|
|
65
73
|
export declare class CapabilityRegistry {
|
|
66
74
|
private readonly registrations;
|
|
67
75
|
private readonly aliases;
|
|
@@ -6,6 +6,16 @@ export class CapabilityRegistryError extends Error {
|
|
|
6
6
|
this.name = 'CapabilityRegistryError';
|
|
7
7
|
}
|
|
8
8
|
}
|
|
9
|
+
export class CapabilityExecutionFailure extends Error {
|
|
10
|
+
executionError;
|
|
11
|
+
output;
|
|
12
|
+
constructor(error, output) {
|
|
13
|
+
super(error.message);
|
|
14
|
+
this.name = 'CapabilityExecutionFailure';
|
|
15
|
+
this.executionError = error;
|
|
16
|
+
this.output = output;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
9
19
|
export class CapabilityRegistry {
|
|
10
20
|
registrations = new Map();
|
|
11
21
|
aliases = new Map();
|
|
@@ -24,6 +34,7 @@ export class CapabilityRegistry {
|
|
|
24
34
|
}
|
|
25
35
|
const stored = {
|
|
26
36
|
definition,
|
|
37
|
+
categories: [...(registration.categories ?? definition.permissions)],
|
|
27
38
|
validateInput: registration.validateInput,
|
|
28
39
|
validateOutput: registration.validateOutput,
|
|
29
40
|
handler: registration.handler,
|
|
@@ -47,7 +58,7 @@ export class CapabilityRegistry {
|
|
|
47
58
|
}
|
|
48
59
|
async execute(request) {
|
|
49
60
|
const runId = this.createRunId();
|
|
50
|
-
const timestamps = this.auditFields(request.correlationId ?? runId);
|
|
61
|
+
const timestamps = { ...this.auditFields(request.correlationId ?? runId), operationId: request.operationId ?? request.correlationId ?? runId };
|
|
51
62
|
const resolved = this.tryResolve(request.input.capabilityId);
|
|
52
63
|
if (resolved.error !== undefined) {
|
|
53
64
|
return this.failure(runId, timestamps, resolved.error);
|
|
@@ -64,12 +75,13 @@ export class CapabilityRegistry {
|
|
|
64
75
|
try {
|
|
65
76
|
decision = request.policy.authorize({
|
|
66
77
|
definition: registration.definition,
|
|
67
|
-
input:
|
|
78
|
+
input: { capabilityId: registration.definition.id, payload: input },
|
|
68
79
|
agent: request.agent,
|
|
69
80
|
correlationId: request.correlationId ?? runId,
|
|
81
|
+
operationId: timestamps.operationId,
|
|
70
82
|
projectId: request.projectId,
|
|
71
83
|
environment: request.environment ?? 'local',
|
|
72
|
-
categories:
|
|
84
|
+
categories: registration.categories ?? registration.definition.permissions,
|
|
73
85
|
files: request.files ?? [],
|
|
74
86
|
budget: request.budget,
|
|
75
87
|
now: timestamps.createdAt,
|
|
@@ -108,6 +120,19 @@ export class CapabilityRegistry {
|
|
|
108
120
|
return { ...timestamps, runId, status: 'succeeded', output, evidence: output.evidence };
|
|
109
121
|
}
|
|
110
122
|
catch (error) {
|
|
123
|
+
if (error instanceof CapabilityExecutionFailure) {
|
|
124
|
+
if (error.output !== undefined) {
|
|
125
|
+
try {
|
|
126
|
+
registration.validateOutput(error.output.payload);
|
|
127
|
+
if (error.output.capabilityId !== registration.definition.id)
|
|
128
|
+
throw new Error('Handler output capabilityId does not match definition');
|
|
129
|
+
}
|
|
130
|
+
catch (invalidOutput) {
|
|
131
|
+
return this.failure(runId, timestamps, this.toExecutionError('HANDLER_FAILED', invalidOutput, false));
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
return { ...timestamps, runId, status: 'failed', error: error.executionError, output: error.output, evidence: error.output?.evidence ?? [] };
|
|
135
|
+
}
|
|
111
136
|
return this.failure(runId, timestamps, this.toExecutionError('HANDLER_FAILED', error, true));
|
|
112
137
|
}
|
|
113
138
|
}
|
|
@@ -169,21 +169,30 @@ export class GraphLoop {
|
|
|
169
169
|
}
|
|
170
170
|
contextRecords(objective) {
|
|
171
171
|
const terms = objective.toLowerCase().split(/[^a-z0-9_./-]+/).filter((term) => term.length > 1);
|
|
172
|
-
const
|
|
172
|
+
const at = new Date().toISOString();
|
|
173
|
+
const records = this.activeEdges(at)
|
|
173
174
|
.map((edge) => {
|
|
174
175
|
const from = this.store.getNode(edge.from);
|
|
175
176
|
const to = this.store.getNode(edge.to);
|
|
176
177
|
if (from === undefined || to === undefined)
|
|
177
178
|
return undefined;
|
|
178
|
-
|
|
179
|
-
|
|
179
|
+
if ([from, to].some((node) => node.status === 'contradicted' || !this.active(node.validFrom, node.validTo, at)))
|
|
180
|
+
return undefined;
|
|
181
|
+
const relation = `${from.label} ${edge.type} ${to.label}`;
|
|
182
|
+
const haystack = relation.toLowerCase();
|
|
180
183
|
const matches = terms.filter((term) => haystack.includes(term)).length;
|
|
181
184
|
if (matches === 0)
|
|
182
185
|
return undefined;
|
|
183
186
|
const evidence = edge.evidenceIds.map((id) => this.store.getEvidence(id)).filter((item) => item !== undefined);
|
|
184
|
-
if (evidence.length === 0)
|
|
187
|
+
if (evidence.length !== edge.evidenceIds.length || evidence.length === 0 || evidence.some((item) => item.status === 'contradicted'))
|
|
185
188
|
return undefined;
|
|
186
|
-
|
|
189
|
+
evidence.sort((left, right) => left.id.localeCompare(right.id));
|
|
190
|
+
const content = from.type === 'Execution' || to.type === 'Execution'
|
|
191
|
+
? `${relation} [Execution memory: handler attempt/result, not independent acceptance of the task.]`
|
|
192
|
+
: relation;
|
|
193
|
+
const statuses = [edge.status, from.status, to.status, ...evidence.map((item) => item.status)];
|
|
194
|
+
const status = ['unknown', 'hypothesis', 'inferred'].find((value) => statuses.includes(value)) ?? 'verified';
|
|
195
|
+
return { id: edge.id, locator: `graph:${edge.id}`, content, relevance: matches / Math.max(1, terms.length), status, evidence, checksum: createHash('sha256').update(`${edge.id}:${edge.updatedAt}:${content}`).digest('hex') };
|
|
187
196
|
});
|
|
188
197
|
return records
|
|
189
198
|
.filter((record) => record !== undefined)
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { spawnAgent, killTree } from '../../../lib/exec.js';
|
|
2
2
|
export const LLM_PROFILE_VERSION = 1;
|
|
3
3
|
export const DEFAULT_LLM_PROFILES = {
|
|
4
4
|
version: LLM_PROFILE_VERSION,
|
|
@@ -41,7 +41,7 @@ export function buildLlmExecution(profile, prompt, options = {}) {
|
|
|
41
41
|
if (profile.provider === 'codex')
|
|
42
42
|
return {
|
|
43
43
|
executable: profile.command,
|
|
44
|
-
args: ['exec',
|
|
44
|
+
args: [...base, 'exec', '--sandbox', 'read-only', '-c', 'approval_policy="never"',
|
|
45
45
|
...(options.resume ? ['resume', '-c', 'sandbox_mode="read-only"', '-c', 'approval_policy="never"'] : []),
|
|
46
46
|
...(profile.model === 'default' ? [] : ['--model', profile.model]),
|
|
47
47
|
...(profile.reasoningEffort ? ['-c', `model_reasoning_effort="${profile.reasoningEffort}"`] : []),
|
|
@@ -85,9 +85,7 @@ export async function runLlm(execution, cwd, timeoutMs = 120_000) {
|
|
|
85
85
|
settled = true;
|
|
86
86
|
resolve({ ...result, durationMs: Date.now() - started });
|
|
87
87
|
};
|
|
88
|
-
|
|
89
|
-
// reaching grandchildren the CLI tool itself spawned (not just the immediate child).
|
|
90
|
-
const child = spawn(execution.executable, execution.args, { cwd, shell: false, stdio: ['pipe', 'pipe', 'pipe'], detached: true });
|
|
88
|
+
const child = spawnAgent(execution.executable, execution.args, { cwd, stdio: ['pipe', 'pipe', 'pipe'] });
|
|
91
89
|
// A provider can close stdin early (e.g. invalid configuration). Its exit status is authoritative.
|
|
92
90
|
child.stdin.on('error', () => { });
|
|
93
91
|
child.stdin.end(execution.stdin);
|
|
@@ -95,28 +93,13 @@ export async function runLlm(execution, cwd, timeoutMs = 120_000) {
|
|
|
95
93
|
child.stderr.setEncoding('utf8');
|
|
96
94
|
child.stdout.on('data', (chunk) => { stdout += chunk; });
|
|
97
95
|
child.stderr.on('data', (chunk) => { stderr += chunk; });
|
|
98
|
-
const killGroup = (signal) => {
|
|
99
|
-
if (child.pid === undefined)
|
|
100
|
-
return;
|
|
101
|
-
try {
|
|
102
|
-
process.kill(-child.pid, signal);
|
|
103
|
-
}
|
|
104
|
-
catch {
|
|
105
|
-
// no process group (platform didn't support detached, or it's already gone) — fall back to the child alone
|
|
106
|
-
try {
|
|
107
|
-
child.kill(signal);
|
|
108
|
-
}
|
|
109
|
-
catch { /* already dead */ }
|
|
110
|
-
}
|
|
111
|
-
};
|
|
112
|
-
let killTimer;
|
|
113
96
|
const timer = setTimeout(() => {
|
|
114
|
-
|
|
115
|
-
|
|
97
|
+
if (child.pid !== undefined)
|
|
98
|
+
killTree(child.pid, SIGTERM_GRACE_MS);
|
|
116
99
|
finish({ exitCode: 124, stdout, stderr, errorCode: 'TIMEOUT' });
|
|
117
100
|
}, timeoutMs);
|
|
118
|
-
child.on('error', (error) => { clearTimeout(timer);
|
|
119
|
-
child.on('close', (code) => { clearTimeout(timer);
|
|
101
|
+
child.on('error', (error) => { clearTimeout(timer); finish({ exitCode: 127, stdout, stderr: `${stderr}${error.message}`, errorCode: 'SPAWN_FAILED' }); });
|
|
102
|
+
child.on('close', (code) => { clearTimeout(timer); finish({ exitCode: code ?? 1, stdout, stderr, ...(code === 0 ? {} : { errorCode: 'COMMAND_FAILED' }) }); });
|
|
120
103
|
});
|
|
121
104
|
}
|
|
122
105
|
function median(values) {
|
|
@@ -39,6 +39,10 @@ export interface McpAgentContext {
|
|
|
39
39
|
readonly permissions: readonly string[];
|
|
40
40
|
readonly capabilities: readonly CapabilityId[];
|
|
41
41
|
}
|
|
42
|
+
export interface McpPlanning {
|
|
43
|
+
propose(input: unknown): unknown | Promise<unknown>;
|
|
44
|
+
get(id: string): unknown | Promise<unknown>;
|
|
45
|
+
}
|
|
42
46
|
export interface McpMemoryQuery {
|
|
43
47
|
query(objective: string): unknown | Promise<unknown>;
|
|
44
48
|
}
|
|
@@ -76,6 +80,7 @@ export interface McpServerDependencies {
|
|
|
76
80
|
readonly policy: CapabilityPolicy;
|
|
77
81
|
readonly agent: McpAgentContext;
|
|
78
82
|
readonly context?: ContextEngine;
|
|
83
|
+
readonly planning?: McpPlanning;
|
|
79
84
|
readonly graph?: GraphLoop;
|
|
80
85
|
readonly memory?: McpMemoryQuery;
|
|
81
86
|
readonly taskEngine?: TaskEngine;
|
|
@@ -91,6 +96,8 @@ export interface McpServerDependencies {
|
|
|
91
96
|
export declare class McpAdapterError extends Error {
|
|
92
97
|
constructor(message: string);
|
|
93
98
|
}
|
|
99
|
+
export declare const PLANNING_PROPOSE_SCHEMA: McpInputSchema;
|
|
100
|
+
export declare const PLANNING_REVIEW_SCHEMA: McpInputSchema;
|
|
94
101
|
export declare const MCP_TOOLS: readonly McpToolDefinition[];
|
|
95
102
|
export declare class McpServer {
|
|
96
103
|
private readonly dependencies;
|
|
@@ -119,6 +126,7 @@ export declare class McpServer {
|
|
|
119
126
|
private entities;
|
|
120
127
|
private number;
|
|
121
128
|
private optionalStatus;
|
|
129
|
+
private requirePlanning;
|
|
122
130
|
private requireContext;
|
|
123
131
|
private requireGraph;
|
|
124
132
|
private requireMemory;
|
|
@@ -10,7 +10,11 @@ export const MCP_RESOURCE_URIS = [
|
|
|
10
10
|
export class McpAdapterError extends Error {
|
|
11
11
|
constructor(message) { super(message); this.name = 'McpAdapterError'; }
|
|
12
12
|
}
|
|
13
|
+
export const PLANNING_PROPOSE_SCHEMA = { type: 'object', properties: { taskId: { type: 'string', minLength: 1 }, handoffId: { type: 'string', minLength: 1 }, correlationId: { type: 'string', minLength: 1 }, budget: { type: 'object', properties: Object.fromEntries(['inputTokens', 'outputTokens', 'totalTokens', 'usedTokens'].map((field) => [field, { type: 'integer', minimum: 0, maximum: Number.MAX_SAFE_INTEGER }])), required: ['inputTokens', 'outputTokens', 'totalTokens', 'usedTokens'], additionalProperties: false } }, required: ['taskId'], additionalProperties: false };
|
|
14
|
+
export const PLANNING_REVIEW_SCHEMA = { type: 'object', properties: { decision: { type: 'string', enum: ['approved', 'rejected'] }, expectedDigest: { type: 'string', minLength: 1 }, reason: { type: 'string', minLength: 1 } }, required: ['decision', 'expectedDigest', 'reason'], additionalProperties: false };
|
|
13
15
|
export const MCP_TOOLS = [
|
|
16
|
+
{ name: 'forja_plan_propose', description: 'Gera proposta descritiva revisável sem executar capabilities.', inputSchema: PLANNING_PROPOSE_SCHEMA },
|
|
17
|
+
tool('forja_plan_get', 'Consulta uma proposta de planejamento persistida.', ['id']),
|
|
14
18
|
tool('forja_workspace_status', 'Retorna o estado operacional mínimo do workspace.', []),
|
|
15
19
|
tool('forja_capabilities_list', 'Lista capabilities visíveis para a identidade MCP.', []),
|
|
16
20
|
tool('forja_capability_describe', 'Descreve uma capability pelo Registry.', ['capabilityId']),
|
|
@@ -79,6 +83,11 @@ export class McpServer {
|
|
|
79
83
|
}
|
|
80
84
|
async dispatch(name, input) {
|
|
81
85
|
switch (name) {
|
|
86
|
+
case 'forja_plan_propose': return this.requirePlanning().propose(input);
|
|
87
|
+
case 'forja_plan_get':
|
|
88
|
+
if (Object.keys(input).some((key) => key !== 'id'))
|
|
89
|
+
throw new McpAdapterError('Unexpected planning input fields');
|
|
90
|
+
return this.requirePlanning().get(this.string(input, 'id'));
|
|
82
91
|
case 'forja_workspace_status': return { agent: this.dependencies.agent, capabilities: this.dependencies.registry.list({ agent: this.dependencies.agent }), resources: this.listResources().map((resource) => resource.uri) };
|
|
83
92
|
case 'forja_capabilities_list': return this.dependencies.registry.list({ agent: this.dependencies.agent, policy: this.dependencies.policy });
|
|
84
93
|
case 'forja_capability_describe': return this.dependencies.registry.describe(this.string(input, 'capabilityId'), { agent: this.dependencies.agent, policy: this.dependencies.policy });
|
|
@@ -125,7 +134,7 @@ export class McpServer {
|
|
|
125
134
|
this.authorize('forja_handoff_create', 'write', 'medium', []);
|
|
126
135
|
return this.requireHandoffs().create({
|
|
127
136
|
from: this.string(input, 'from'), to: this.string(input, 'to'), intent: this.string(input, 'intent'), objective: this.string(input, 'objective'),
|
|
128
|
-
completedWork: this.strings(input, 'completedWork'), decisions: this.strings(input, 'decisions'), constraints: this.strings(input, 'constraints'), pending: this.strings(input, 'pending'), evidenceIds: this.entities(input, 'evidenceIds'), acceptance: this.strings(input, 'acceptance'), blockers: this.strings(input, 'blockers'), nextAgent: this.string(input, 'nextAgent'), correlationId: this.optionalString(input, 'correlationId'),
|
|
137
|
+
completedWork: this.strings(input, 'completedWork'), decisions: this.strings(input, 'decisions'), constraints: this.strings(input, 'constraints'), pending: this.strings(input, 'pending'), evidenceIds: this.entities(input, 'evidenceIds'), acceptance: this.strings(input, 'acceptance'), blockers: this.strings(input, 'blockers'), nextAgent: this.string(input, 'nextAgent'), correlationId: this.optionalString(input, 'correlationId'), taskId: input.taskId === undefined ? undefined : this.entity(input, 'taskId'),
|
|
129
138
|
});
|
|
130
139
|
}
|
|
131
140
|
executeCapability(input) {
|
|
@@ -170,6 +179,8 @@ export class McpServer {
|
|
|
170
179
|
optionalStatus(input, field) { const value = input[field]; if (value === undefined)
|
|
171
180
|
return undefined; if (value !== 'verified' && value !== 'inferred' && value !== 'hypothesis' && value !== 'contradicted' && value !== 'unknown')
|
|
172
181
|
throw new McpAdapterError(`${field} is an invalid knowledge status`); return value; }
|
|
182
|
+
requirePlanning() { if (this.dependencies.planning === undefined)
|
|
183
|
+
throw new McpAdapterError('Planning service is not configured'); return this.dependencies.planning; }
|
|
173
184
|
requireContext() { if (this.dependencies.context === undefined)
|
|
174
185
|
throw new McpAdapterError('Context Engine is not configured'); return this.dependencies.context; }
|
|
175
186
|
requireGraph() { if (this.dependencies.graph === undefined)
|
|
@@ -29,6 +29,9 @@ export interface ObservationStore {
|
|
|
29
29
|
export interface ControlPlanePort {
|
|
30
30
|
metrics(): ControlPlaneMetrics | Promise<ControlPlaneMetrics>;
|
|
31
31
|
observations(): readonly Observation[] | Promise<readonly Observation[]>;
|
|
32
|
+
planPropose?(input: unknown): unknown | Promise<unknown>;
|
|
33
|
+
planGet?(id: string): unknown | Promise<unknown>;
|
|
34
|
+
planReview?(id: string, input: unknown): unknown | Promise<unknown>;
|
|
32
35
|
runtimeStart?(input: unknown): unknown | Promise<unknown>;
|
|
33
36
|
runtimeGet?(id: string): unknown | Promise<unknown>;
|
|
34
37
|
runtimeExecute?(id: string): unknown | Promise<unknown>;
|
|
@@ -57,6 +60,11 @@ export interface ControlPlaneEventSink {
|
|
|
57
60
|
publish(event: ControlPlaneEvent): void;
|
|
58
61
|
}
|
|
59
62
|
export interface ControlPlaneServices {
|
|
63
|
+
readonly planning?: {
|
|
64
|
+
readonly propose: (input: unknown) => unknown | Promise<unknown>;
|
|
65
|
+
readonly get: (id: string) => unknown | Promise<unknown>;
|
|
66
|
+
readonly review: (id: string, input: unknown) => unknown | Promise<unknown>;
|
|
67
|
+
};
|
|
60
68
|
readonly runtime?: {
|
|
61
69
|
readonly start: (input: unknown) => unknown | Promise<unknown>;
|
|
62
70
|
readonly get: (input: unknown) => unknown | Promise<unknown>;
|
|
@@ -110,6 +118,9 @@ export declare class ControlPlane implements ControlPlanePort {
|
|
|
110
118
|
metrics(): Promise<ControlPlaneMetrics>;
|
|
111
119
|
observations(): Promise<readonly Observation[]>;
|
|
112
120
|
record(input: ObservationInput): Promise<Observation>;
|
|
121
|
+
planPropose(input: unknown): Promise<unknown>;
|
|
122
|
+
planGet(id: string): Promise<unknown>;
|
|
123
|
+
planReview(id: string, input: unknown): Promise<unknown>;
|
|
113
124
|
runtimeStart(input: unknown): Promise<unknown>;
|
|
114
125
|
runtimeGet(id: string): Promise<unknown>;
|
|
115
126
|
runtimeExecute(id: string): Promise<unknown>;
|
|
@@ -47,6 +47,9 @@ export class ControlPlane {
|
|
|
47
47
|
metrics() { return this.recorder.metrics(); }
|
|
48
48
|
observations() { return this.recorder.observations(); }
|
|
49
49
|
async record(input) { const observation = await this.recorder.record(input); this.services.events?.publish({ id: observation.id, type: 'observation.recorded', aggregateId: observation.runId ?? observation.traceId, data: observation, correlationId: observation.correlationId }); return observation; }
|
|
50
|
+
planPropose(input) { return this.delegate(this.services.planning?.propose, input, 'planPropose'); }
|
|
51
|
+
planGet(id) { const service = this.services.planning; return this.delegate(service === undefined ? undefined : () => service.get(id), id, 'planGet'); }
|
|
52
|
+
planReview(id, input) { const service = this.services.planning; return this.delegate(service === undefined ? undefined : () => service.review(id, input), input, 'planReview'); }
|
|
50
53
|
runtimeStart(input) { return this.delegate(this.services.runtime?.start, input, 'runtimeStart'); }
|
|
51
54
|
runtimeGet(id) { return this.delegate(this.services.runtime?.get, id, 'runtimeGet'); }
|
|
52
55
|
runtimeExecute(id) { return this.delegate(this.services.runtime?.execute, id, 'runtimeExecute'); }
|
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
import { type EntityId, type EvaluationResult, type Handoff, type Sprint, type Task, type TokenBudget } from '../../contracts/src/index.ts';
|
|
2
|
+
export interface ExecutionTransition {
|
|
3
|
+
readonly recoveryBlock?: true;
|
|
4
|
+
readonly beforeTask: Task;
|
|
5
|
+
readonly task: Task;
|
|
6
|
+
readonly beforeHandoff?: Handoff;
|
|
7
|
+
readonly handoff?: Handoff;
|
|
8
|
+
}
|
|
2
9
|
export interface OrchestrationStore {
|
|
10
|
+
transitionExecution(input: ExecutionTransition): void | Promise<void>;
|
|
3
11
|
saveSprint(value: Sprint): void | Promise<void>;
|
|
4
12
|
getSprint(id: EntityId): Sprint | undefined | Promise<Sprint | undefined>;
|
|
5
13
|
listSprints(): readonly Sprint[] | Promise<readonly Sprint[]>;
|
|
@@ -43,6 +51,7 @@ export interface CreateTaskInput {
|
|
|
43
51
|
readonly correlationId?: string;
|
|
44
52
|
}
|
|
45
53
|
export interface CreateHandoffInput {
|
|
54
|
+
readonly taskId?: EntityId;
|
|
46
55
|
readonly from: string;
|
|
47
56
|
readonly to: string;
|
|
48
57
|
readonly intent: string;
|
|
@@ -60,6 +69,8 @@ export interface CreateHandoffInput {
|
|
|
60
69
|
export declare class OrchestrationError extends Error {
|
|
61
70
|
constructor(message: string);
|
|
62
71
|
}
|
|
72
|
+
/** Shared invariants for the two stores; callers must check and write without yielding. */
|
|
73
|
+
export declare function assertExecutionTransition(input: ExecutionTransition, currentTask: Task | undefined, currentHandoff?: Handoff): void;
|
|
63
74
|
export declare class InMemoryOrchestrationStore implements OrchestrationStore {
|
|
64
75
|
private readonly sprints;
|
|
65
76
|
private readonly tasks;
|
|
@@ -73,6 +84,7 @@ export declare class InMemoryOrchestrationStore implements OrchestrationStore {
|
|
|
73
84
|
saveHandoff(value: Handoff): void;
|
|
74
85
|
getHandoff(id: EntityId): Handoff | undefined;
|
|
75
86
|
listHandoffs(): readonly Handoff[];
|
|
87
|
+
transitionExecution(input: ExecutionTransition): void;
|
|
76
88
|
}
|
|
77
89
|
export declare class SprintEngine {
|
|
78
90
|
private readonly store;
|
|
@@ -109,11 +121,13 @@ export declare class TaskEngine {
|
|
|
109
121
|
private readonly graph?;
|
|
110
122
|
constructor(store: OrchestrationStore, sprintEngine: SprintEngine, graph?: GraphRecorder);
|
|
111
123
|
create(input: CreateTaskInput): Promise<Task>;
|
|
124
|
+
assertEligible(task: Task): Promise<void>;
|
|
112
125
|
next(sprintId: EntityId): Promise<Task | undefined>;
|
|
113
126
|
start(id: EntityId): Promise<Task>;
|
|
114
127
|
block(id: EntityId): Promise<Task>;
|
|
115
128
|
complete(id: EntityId, validator: CompletionValidator): Promise<Task>;
|
|
116
|
-
|
|
129
|
+
private assertDependencies;
|
|
130
|
+
private assertUnlinked;
|
|
117
131
|
private saveTaskGuarded;
|
|
118
132
|
private require;
|
|
119
133
|
private updated;
|