forjajs 1.7.3 → 2.0.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 +31 -0
- package/README.md +223 -217
- package/README.pt-BR.md +323 -0
- package/dist/apps/dashboard/app/api/forja/[...path]/route.d.ts +10 -0
- package/dist/apps/dashboard/app/api/forja/[...path]/route.js +36 -0
- package/dist/apps/dashboard/app/api/forja/approval.d.ts +1 -0
- package/dist/apps/dashboard/app/api/forja/approval.js +8 -0
- package/dist/apps/dashboard/app/dashboard-client.d.ts +1 -0
- package/dist/apps/dashboard/app/dashboard-client.jsx +62 -0
- package/dist/apps/dashboard/app/layout.d.ts +9 -0
- package/dist/apps/dashboard/app/layout.jsx +7 -0
- package/dist/apps/dashboard/app/page.d.ts +1 -0
- package/dist/apps/dashboard/app/page.jsx +5 -0
- package/dist/apps/dashboard/app/providers.d.ts +4 -0
- package/dist/apps/dashboard/app/providers.jsx +7 -0
- package/dist/apps/dashboard/next.config.d.mts +6 -0
- package/dist/apps/dashboard/next.config.mjs +8 -0
- package/dist/apps/dashboard/src/index.d.ts +14 -0
- package/dist/apps/dashboard/src/index.js +16 -0
- package/dist/apps/server/src/app.module.d.ts +5 -0
- package/dist/apps/server/src/app.module.js +16 -0
- package/dist/apps/server/src/forja-nest.module.d.ts +59 -0
- package/dist/apps/server/src/forja-nest.module.js +316 -0
- package/dist/apps/server/src/index.d.ts +15 -0
- package/dist/apps/server/src/index.js +7 -0
- package/dist/apps/server/src/main.d.ts +12 -0
- package/dist/apps/server/src/main.js +105 -0
- package/dist/apps/worker/src/main.d.ts +12 -0
- package/dist/apps/worker/src/main.js +18 -0
- package/dist/lib/core/health.js +1 -1
- package/dist/packages/adapter-git/src/index.d.ts +27 -0
- package/dist/packages/adapter-git/src/index.js +53 -0
- package/dist/packages/adapter-nest/src/index.d.ts +71 -0
- package/dist/packages/adapter-nest/src/index.js +142 -0
- package/dist/packages/adapter-sqlite/src/index.d.ts +99 -0
- package/dist/packages/adapter-sqlite/src/index.js +108 -0
- package/dist/packages/context/src/index.d.ts +52 -0
- package/dist/packages/context/src/index.js +108 -0
- package/dist/packages/contracts/src/index.d.ts +368 -0
- package/dist/packages/contracts/src/index.js +27 -0
- package/dist/packages/core/src/index.d.ts +68 -0
- package/dist/packages/core/src/index.js +141 -0
- package/dist/packages/evals/src/index.d.ts +22 -0
- package/dist/packages/evals/src/index.js +65 -0
- package/dist/packages/events/src/index.d.ts +47 -0
- package/dist/packages/events/src/index.js +96 -0
- package/dist/packages/graph/src/index.d.ts +80 -0
- package/dist/packages/graph/src/index.js +163 -0
- package/dist/packages/mcp/src/index.d.ts +119 -0
- package/dist/packages/mcp/src/index.js +153 -0
- package/dist/packages/observability/src/index.d.ts +132 -0
- package/dist/packages/observability/src/index.js +86 -0
- package/dist/packages/orchestration/src/index.d.ts +122 -0
- package/dist/packages/orchestration/src/index.js +178 -0
- package/dist/packages/planner/src/index.d.ts +22 -0
- package/dist/packages/planner/src/index.js +70 -0
- package/dist/packages/plugin-sdk/src/index.d.ts +56 -0
- package/dist/packages/plugin-sdk/src/index.js +55 -0
- package/dist/packages/policy/src/index.d.ts +80 -0
- package/dist/packages/policy/src/index.js +136 -0
- package/dist/packages/runtime/src/index.d.ts +91 -0
- package/dist/packages/runtime/src/index.js +217 -0
- package/dist/packages/sandbox/src/index.d.ts +64 -0
- package/dist/packages/sandbox/src/index.js +108 -0
- package/dist/packages/scheduler/src/index.d.ts +56 -0
- package/dist/packages/scheduler/src/index.js +123 -0
- package/dist/packages/sdk/src/index.d.ts +122 -0
- package/dist/packages/sdk/src/index.js +40 -0
- package/dist/packages/validator/src/index.d.ts +36 -0
- package/dist/packages/validator/src/index.js +60 -0
- package/docs/architecture/FORJA-2.0-ARCHITECTURE.md +109 -0
- package/docs/architecture/FORJA-2.0-IMPACT-FOUNDATION.md +273 -0
- package/docs/security/FORJA-2.0-RELEASE-AUDIT-2026-08-01.md +95 -0
- package/docs/vision/FORJA-2.0-VISION.md +72 -0
- package/memory/50-orchestration/handoffs/2026-07-31_architect_foundation-contracts.md +15 -0
- package/memory/50-orchestration/handoffs/2026-07-31_backend-nest.md +22 -0
- package/memory/50-orchestration/handoffs/2026-07-31_context-engine.md +16 -0
- package/memory/50-orchestration/handoffs/2026-07-31_control-plane.md +28 -0
- package/memory/50-orchestration/handoffs/2026-07-31_core-capability-registry.md +15 -0
- package/memory/50-orchestration/handoffs/2026-07-31_evals-plugin-sdk.md +22 -0
- package/memory/50-orchestration/handoffs/2026-07-31_events-scheduler.md +16 -0
- package/memory/50-orchestration/handoffs/2026-07-31_graphloop.md +16 -0
- package/memory/50-orchestration/handoffs/2026-07-31_mcp.md +21 -0
- package/memory/50-orchestration/handoffs/2026-07-31_nest-bootstrap.md +28 -0
- package/memory/50-orchestration/handoffs/2026-07-31_next-dashboard.md +22 -0
- package/memory/50-orchestration/handoffs/2026-07-31_observability.md +27 -0
- package/memory/50-orchestration/handoffs/2026-07-31_orchestration.md +21 -0
- package/memory/50-orchestration/handoffs/2026-07-31_planner-validator.md +16 -0
- package/memory/50-orchestration/handoffs/2026-07-31_policy-engine.md +14 -0
- package/memory/50-orchestration/handoffs/2026-07-31_runtime-control-plane.md +23 -0
- package/memory/50-orchestration/handoffs/2026-07-31_runtime-controlado.md +15 -0
- package/memory/50-orchestration/handoffs/2026-07-31_sandbox.md +21 -0
- package/memory/50-orchestration/handoffs/2026-07-31_sdk.md +27 -0
- package/memory/50-orchestration/handoffs/2026-07-31_sqlite-adapter.md +21 -0
- package/memory/50-orchestration/handoffs/2026-07-31_worker-dashboard-boundary.md +23 -0
- package/memory/50-orchestration/handoffs/2026-08-01_approval-server-identity.md +23 -0
- package/memory/50-orchestration/handoffs/2026-08-01_dashboard-auth-query.md +24 -0
- package/memory/50-orchestration/handoffs/2026-08-01_graphloop-approvals.md +23 -0
- package/memory/90-decisions/0034-forja-2-core-e-contratos.md +29 -0
- package/memory/90-decisions/0035-forja-2-local-first-e-autonomia.md +23 -0
- package/memory/90-decisions/0036-forja-2-capability-registry.md +30 -0
- package/memory/90-decisions/0037-forja-2-policy-engine-obrigatorio.md +28 -0
- package/memory/90-decisions/0038-forja-2-runtime-controlado.md +28 -0
- package/memory/90-decisions/0039-forja-2-event-bus-scheduler-local-first.md +31 -0
- package/memory/90-decisions/0040-forja-2-context-engine-budget-cache.md +32 -0
- package/memory/90-decisions/0041-forja-2-graphloop-separado-codegraph.md +32 -0
- package/memory/90-decisions/0042-forja-2-planner-validator-independentes.md +29 -0
- package/memory/90-decisions/0043-forja-2-orchestration-entities.md +16 -0
- package/memory/90-decisions/0044-forja-2-sandbox-worktree.md +19 -0
- package/memory/90-decisions/0045-forja-2-sqlite-adapter.md +19 -0
- package/memory/90-decisions/0046-forja-2-mcp-adapter.md +18 -0
- package/memory/90-decisions/0047-forja-2-backend-nest-adapter.md +19 -0
- package/memory/90-decisions/0048-forja-2-sdk-transport.md +18 -0
- package/memory/90-decisions/0049-forja-2-observability-control-plane.md +18 -0
- package/memory/90-decisions/0050-forja-2-control-plane-application-ports.md +18 -0
- package/memory/90-decisions/0051-forja-2-runtime-control-plane-composition.md +18 -0
- package/memory/90-decisions/0052-forja-2-deterministic-evaluation.md +15 -0
- package/memory/90-decisions/0053-forja-2-plugin-sdk-permissionado.md +16 -0
- package/memory/90-decisions/0054-forja-2-worker-dashboard-boundary.md +15 -0
- package/memory/90-decisions/0055-forja-2-next-dashboard-distribution.md +16 -0
- package/memory/90-decisions/0056-forja-2-dashboard-proxy-auth-query.md +16 -0
- package/memory/90-decisions/0057-forja-2-graphloop-approvals-dashboard.md +15 -0
- package/memory/90-decisions/0058-forja-2-approval-server-identity.md +15 -0
- package/package.json +26 -2
- package/README.en.md +0 -329
|
@@ -0,0 +1,368 @@
|
|
|
1
|
+
/** Versioned, framework-independent contracts for ForjaJS 2.0. */
|
|
2
|
+
export declare const CONTRACT_VERSION = "2.0";
|
|
3
|
+
export type Brand<T, B extends string> = T & {
|
|
4
|
+
readonly __brand: B;
|
|
5
|
+
};
|
|
6
|
+
export type EntityId = Brand<string, 'EntityId'>;
|
|
7
|
+
export type CapabilityId = Brand<string, 'CapabilityId'>;
|
|
8
|
+
export type RunId = Brand<string, 'RunId'>;
|
|
9
|
+
export type ISO8601 = string & {
|
|
10
|
+
readonly __iso8601: unique symbol;
|
|
11
|
+
};
|
|
12
|
+
export type KnowledgeStatus = 'verified' | 'inferred' | 'hypothesis' | 'contradicted' | 'unknown';
|
|
13
|
+
export type RiskLevel = 'low' | 'medium' | 'high' | 'critical';
|
|
14
|
+
export type PolicyEffect = 'ALLOW' | 'DENY' | 'REQUIRE_APPROVAL' | 'ALLOW_WITH_LIMITS';
|
|
15
|
+
export type ExecutionState = 'created' | 'planning' | 'awaiting_approval' | 'running' | 'validating' | 'paused' | 'blocked' | 'failed' | 'completed' | 'cancelled' | 'rolled_back';
|
|
16
|
+
export type SandboxState = 'created' | 'prepared' | 'executing' | 'validating' | 'ready_to_promote' | 'promoted' | 'rejected' | 'destroyed' | 'failed';
|
|
17
|
+
export interface AuditFields {
|
|
18
|
+
readonly schemaVersion: typeof CONTRACT_VERSION;
|
|
19
|
+
readonly createdAt: ISO8601;
|
|
20
|
+
readonly updatedAt: ISO8601;
|
|
21
|
+
readonly correlationId: string;
|
|
22
|
+
}
|
|
23
|
+
export interface Evidence {
|
|
24
|
+
readonly id: EntityId;
|
|
25
|
+
readonly source: string;
|
|
26
|
+
readonly locator: string;
|
|
27
|
+
readonly checksum?: string;
|
|
28
|
+
readonly capturedAt: ISO8601;
|
|
29
|
+
readonly status: KnowledgeStatus;
|
|
30
|
+
}
|
|
31
|
+
export interface Claim {
|
|
32
|
+
readonly id: EntityId;
|
|
33
|
+
readonly statement: string;
|
|
34
|
+
readonly status: KnowledgeStatus;
|
|
35
|
+
readonly confidence: number;
|
|
36
|
+
readonly evidenceIds: readonly EntityId[];
|
|
37
|
+
}
|
|
38
|
+
export interface CapabilityDefinition extends AuditFields {
|
|
39
|
+
readonly id: CapabilityId;
|
|
40
|
+
readonly version: string;
|
|
41
|
+
readonly description: string;
|
|
42
|
+
readonly permissions: readonly string[];
|
|
43
|
+
readonly risk: RiskLevel;
|
|
44
|
+
readonly sideEffects: readonly string[];
|
|
45
|
+
readonly requirements: readonly string[];
|
|
46
|
+
readonly supportsAutonomy: boolean;
|
|
47
|
+
readonly idempotent: boolean;
|
|
48
|
+
readonly timeoutMs: number;
|
|
49
|
+
readonly retry: {
|
|
50
|
+
readonly maxAttempts: number;
|
|
51
|
+
readonly backoffMs: number;
|
|
52
|
+
};
|
|
53
|
+
readonly aliases: readonly string[];
|
|
54
|
+
readonly deprecated?: {
|
|
55
|
+
readonly since: string;
|
|
56
|
+
readonly replacement?: CapabilityId;
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
export interface CapabilityInput {
|
|
60
|
+
readonly capabilityId: CapabilityId;
|
|
61
|
+
readonly payload: unknown;
|
|
62
|
+
}
|
|
63
|
+
export interface CapabilityOutput {
|
|
64
|
+
readonly capabilityId: CapabilityId;
|
|
65
|
+
readonly payload: unknown;
|
|
66
|
+
readonly evidence: readonly Evidence[];
|
|
67
|
+
}
|
|
68
|
+
export interface ExecutionError {
|
|
69
|
+
readonly code: string;
|
|
70
|
+
readonly message: string;
|
|
71
|
+
readonly retryable: boolean;
|
|
72
|
+
readonly details?: Readonly<Record<string, string>>;
|
|
73
|
+
}
|
|
74
|
+
export interface ExecutionResult extends AuditFields {
|
|
75
|
+
readonly runId: RunId;
|
|
76
|
+
readonly status: 'succeeded' | 'failed' | 'blocked' | 'cancelled';
|
|
77
|
+
readonly output?: CapabilityOutput;
|
|
78
|
+
readonly error?: ExecutionError;
|
|
79
|
+
readonly evidence: readonly Evidence[];
|
|
80
|
+
}
|
|
81
|
+
export interface AgentIdentity {
|
|
82
|
+
readonly id: EntityId;
|
|
83
|
+
readonly name: string;
|
|
84
|
+
readonly role: string;
|
|
85
|
+
readonly autonomy: 'consultive' | 'assisted' | 'supervised' | 'controlled_autonomous';
|
|
86
|
+
}
|
|
87
|
+
export interface AgentProfile extends AgentIdentity {
|
|
88
|
+
readonly capabilities: readonly CapabilityId[];
|
|
89
|
+
readonly permissions: readonly string[];
|
|
90
|
+
}
|
|
91
|
+
export interface PolicyDecision {
|
|
92
|
+
readonly effect: PolicyEffect;
|
|
93
|
+
readonly reason: string;
|
|
94
|
+
readonly policyId: string;
|
|
95
|
+
readonly limits?: Readonly<Record<string, number>>;
|
|
96
|
+
readonly approvalRequestId?: EntityId;
|
|
97
|
+
}
|
|
98
|
+
export interface ApprovalRequest extends AuditFields {
|
|
99
|
+
readonly id: EntityId;
|
|
100
|
+
readonly action: string;
|
|
101
|
+
readonly justification: string;
|
|
102
|
+
readonly impact: string;
|
|
103
|
+
readonly expectedDiff?: string;
|
|
104
|
+
readonly expiresAt: ISO8601;
|
|
105
|
+
readonly decision?: 'approved' | 'rejected' | 'expired';
|
|
106
|
+
readonly approverId?: EntityId;
|
|
107
|
+
}
|
|
108
|
+
export interface TokenBudget {
|
|
109
|
+
readonly inputTokens: number;
|
|
110
|
+
readonly outputTokens: number;
|
|
111
|
+
readonly totalTokens: number;
|
|
112
|
+
readonly usedTokens: number;
|
|
113
|
+
}
|
|
114
|
+
export interface Sprint extends AuditFields {
|
|
115
|
+
readonly id: EntityId;
|
|
116
|
+
readonly objective: string;
|
|
117
|
+
readonly includedScope: readonly string[];
|
|
118
|
+
readonly excludedScope: readonly string[];
|
|
119
|
+
readonly budget: TokenBudget;
|
|
120
|
+
readonly completionCriteria: readonly string[];
|
|
121
|
+
readonly risks: readonly string[];
|
|
122
|
+
readonly taskIds: readonly EntityId[];
|
|
123
|
+
readonly evidenceIds: readonly EntityId[];
|
|
124
|
+
readonly status: 'planned' | 'active' | 'paused' | 'completed' | 'cancelled';
|
|
125
|
+
}
|
|
126
|
+
export interface Task extends AuditFields {
|
|
127
|
+
readonly id: EntityId;
|
|
128
|
+
readonly sprintId: EntityId;
|
|
129
|
+
readonly objective: string;
|
|
130
|
+
readonly acceptanceCriteria: readonly string[];
|
|
131
|
+
readonly allowedFiles: readonly string[];
|
|
132
|
+
readonly dependencyIds: readonly EntityId[];
|
|
133
|
+
readonly evidenceIds: readonly EntityId[];
|
|
134
|
+
readonly budget: TokenBudget;
|
|
135
|
+
readonly status: 'todo' | 'in_progress' | 'blocked' | 'done' | 'cancelled';
|
|
136
|
+
}
|
|
137
|
+
export interface Handoff extends AuditFields {
|
|
138
|
+
readonly id: EntityId;
|
|
139
|
+
readonly from: string;
|
|
140
|
+
readonly to: string;
|
|
141
|
+
readonly intent: string;
|
|
142
|
+
readonly objective: string;
|
|
143
|
+
readonly completedWork: readonly string[];
|
|
144
|
+
readonly decisions: readonly string[];
|
|
145
|
+
readonly constraints: readonly string[];
|
|
146
|
+
readonly pending: readonly string[];
|
|
147
|
+
readonly evidenceIds: readonly EntityId[];
|
|
148
|
+
readonly acceptance: readonly string[];
|
|
149
|
+
readonly blockers: readonly string[];
|
|
150
|
+
readonly nextAgent: string;
|
|
151
|
+
}
|
|
152
|
+
export interface Checkpoint extends AuditFields {
|
|
153
|
+
readonly id: EntityId;
|
|
154
|
+
readonly runId: RunId;
|
|
155
|
+
readonly step: number;
|
|
156
|
+
readonly state: ExecutionState;
|
|
157
|
+
readonly checksum: string;
|
|
158
|
+
readonly resumable: boolean;
|
|
159
|
+
}
|
|
160
|
+
export interface RuntimeMetrics {
|
|
161
|
+
readonly attempts: number;
|
|
162
|
+
readonly retries: number;
|
|
163
|
+
readonly durationMs: number;
|
|
164
|
+
readonly inputTokens: number;
|
|
165
|
+
readonly outputTokens: number;
|
|
166
|
+
}
|
|
167
|
+
export interface RuntimeRun extends AuditFields {
|
|
168
|
+
readonly runId: RunId;
|
|
169
|
+
readonly objective: string;
|
|
170
|
+
readonly agent: AgentIdentity;
|
|
171
|
+
readonly sprintId?: EntityId;
|
|
172
|
+
readonly taskId?: EntityId;
|
|
173
|
+
readonly policy: PolicyDecision;
|
|
174
|
+
readonly budget: TokenBudget;
|
|
175
|
+
readonly state: ExecutionState;
|
|
176
|
+
readonly steps: number;
|
|
177
|
+
readonly evidence: readonly Evidence[];
|
|
178
|
+
readonly changedFiles: readonly string[];
|
|
179
|
+
readonly metrics: RuntimeMetrics;
|
|
180
|
+
readonly error?: ExecutionError;
|
|
181
|
+
readonly validation?: EvaluationResult;
|
|
182
|
+
}
|
|
183
|
+
export interface DomainEvent extends AuditFields {
|
|
184
|
+
readonly id: EntityId;
|
|
185
|
+
readonly type: string;
|
|
186
|
+
readonly aggregateId: EntityId;
|
|
187
|
+
readonly sequence: number;
|
|
188
|
+
readonly payload: unknown;
|
|
189
|
+
readonly idempotencyKey: string;
|
|
190
|
+
}
|
|
191
|
+
export interface GraphNode extends AuditFields {
|
|
192
|
+
readonly id: EntityId;
|
|
193
|
+
readonly type: string;
|
|
194
|
+
readonly label: string;
|
|
195
|
+
readonly status: KnowledgeStatus;
|
|
196
|
+
readonly validFrom?: ISO8601;
|
|
197
|
+
readonly validTo?: ISO8601;
|
|
198
|
+
}
|
|
199
|
+
export interface GraphEdge extends AuditFields {
|
|
200
|
+
readonly id: EntityId;
|
|
201
|
+
readonly from: EntityId;
|
|
202
|
+
readonly to: EntityId;
|
|
203
|
+
readonly type: string;
|
|
204
|
+
readonly status: KnowledgeStatus;
|
|
205
|
+
readonly confidence: number;
|
|
206
|
+
readonly evidenceIds: readonly EntityId[];
|
|
207
|
+
readonly validFrom?: ISO8601;
|
|
208
|
+
readonly validTo?: ISO8601;
|
|
209
|
+
}
|
|
210
|
+
export interface GraphEvidence {
|
|
211
|
+
readonly edgeId: EntityId;
|
|
212
|
+
readonly evidence: readonly Evidence[];
|
|
213
|
+
}
|
|
214
|
+
export interface Contradiction {
|
|
215
|
+
readonly id: EntityId;
|
|
216
|
+
readonly claimIds: readonly EntityId[];
|
|
217
|
+
readonly reason: string;
|
|
218
|
+
readonly evidenceIds: readonly EntityId[];
|
|
219
|
+
}
|
|
220
|
+
export interface ContextMetrics {
|
|
221
|
+
readonly candidateCount: number;
|
|
222
|
+
readonly selectedCount: number;
|
|
223
|
+
readonly deduplicatedCount: number;
|
|
224
|
+
readonly cacheHits: number;
|
|
225
|
+
readonly selectedTokens: number;
|
|
226
|
+
readonly unusedTokens: number;
|
|
227
|
+
}
|
|
228
|
+
export interface ContextPackage extends AuditFields {
|
|
229
|
+
readonly id: EntityId;
|
|
230
|
+
readonly references: readonly Evidence[];
|
|
231
|
+
readonly content: readonly string[];
|
|
232
|
+
readonly budget: TokenBudget;
|
|
233
|
+
readonly checksum: string;
|
|
234
|
+
readonly metrics: ContextMetrics;
|
|
235
|
+
}
|
|
236
|
+
export interface SuggestedAction {
|
|
237
|
+
readonly id: EntityId;
|
|
238
|
+
readonly reason: string;
|
|
239
|
+
readonly priority: number;
|
|
240
|
+
readonly risk: RiskLevel;
|
|
241
|
+
readonly capabilityId?: CapabilityId;
|
|
242
|
+
readonly dependencyIds: readonly EntityId[];
|
|
243
|
+
readonly evidenceIds: readonly EntityId[];
|
|
244
|
+
readonly approvalRequired: boolean;
|
|
245
|
+
}
|
|
246
|
+
export interface PlanStep extends AuditFields {
|
|
247
|
+
readonly id: EntityId;
|
|
248
|
+
readonly objective: string;
|
|
249
|
+
readonly acceptanceCriteria: readonly string[];
|
|
250
|
+
readonly allowedFiles: readonly string[];
|
|
251
|
+
readonly dependencyIds: readonly EntityId[];
|
|
252
|
+
readonly evidenceIds: readonly EntityId[];
|
|
253
|
+
readonly risk: RiskLevel;
|
|
254
|
+
readonly budget: TokenBudget;
|
|
255
|
+
readonly status: 'planned' | 'ready' | 'completed' | 'blocked';
|
|
256
|
+
}
|
|
257
|
+
export interface ExecutionPlan extends AuditFields {
|
|
258
|
+
readonly id: EntityId;
|
|
259
|
+
readonly objective: string;
|
|
260
|
+
readonly steps: readonly PlanStep[];
|
|
261
|
+
readonly budget: TokenBudget;
|
|
262
|
+
readonly risk: RiskLevel;
|
|
263
|
+
readonly evidenceIds: readonly EntityId[];
|
|
264
|
+
}
|
|
265
|
+
export interface EvaluationResult extends AuditFields {
|
|
266
|
+
readonly status: 'accepted' | 'rejected' | 'inconclusive' | 'blocked';
|
|
267
|
+
readonly checks: readonly {
|
|
268
|
+
readonly name: string;
|
|
269
|
+
readonly passed: boolean;
|
|
270
|
+
readonly evidenceIds: readonly EntityId[];
|
|
271
|
+
}[];
|
|
272
|
+
readonly summary: string;
|
|
273
|
+
}
|
|
274
|
+
export interface SandboxSession extends AuditFields {
|
|
275
|
+
readonly id: EntityId;
|
|
276
|
+
readonly runId: RunId;
|
|
277
|
+
readonly backend: 'git_worktree' | 'temporary_directory' | 'docker';
|
|
278
|
+
readonly root: string;
|
|
279
|
+
readonly state: SandboxState;
|
|
280
|
+
readonly promoted: boolean;
|
|
281
|
+
}
|
|
282
|
+
export interface SandboxCommand {
|
|
283
|
+
readonly executable: string;
|
|
284
|
+
readonly args: readonly string[];
|
|
285
|
+
readonly cwd?: string;
|
|
286
|
+
readonly env?: Readonly<Record<string, string>>;
|
|
287
|
+
}
|
|
288
|
+
export interface SandboxExecution extends AuditFields {
|
|
289
|
+
readonly sessionId: EntityId;
|
|
290
|
+
readonly command: SandboxCommand;
|
|
291
|
+
readonly exitCode: number;
|
|
292
|
+
readonly stdout: string;
|
|
293
|
+
readonly stderr: string;
|
|
294
|
+
readonly durationMs: number;
|
|
295
|
+
readonly evidenceIds: readonly EntityId[];
|
|
296
|
+
}
|
|
297
|
+
export interface SandboxDiff extends AuditFields {
|
|
298
|
+
readonly sessionId: EntityId;
|
|
299
|
+
readonly checksum: string;
|
|
300
|
+
readonly files: readonly string[];
|
|
301
|
+
readonly additions: number;
|
|
302
|
+
readonly deletions: number;
|
|
303
|
+
readonly evidenceIds: readonly EntityId[];
|
|
304
|
+
}
|
|
305
|
+
export interface AuditRecord extends AuditFields {
|
|
306
|
+
readonly id: EntityId;
|
|
307
|
+
readonly action: string;
|
|
308
|
+
readonly aggregateId: EntityId;
|
|
309
|
+
readonly outcome: 'success' | 'failure' | 'blocked';
|
|
310
|
+
readonly evidenceIds: readonly EntityId[];
|
|
311
|
+
readonly details: Readonly<Record<string, string>>;
|
|
312
|
+
}
|
|
313
|
+
export interface Observation extends AuditFields {
|
|
314
|
+
readonly id: EntityId;
|
|
315
|
+
readonly traceId: string;
|
|
316
|
+
readonly runId?: RunId;
|
|
317
|
+
readonly agentId?: EntityId;
|
|
318
|
+
readonly taskId?: EntityId;
|
|
319
|
+
readonly sprintId?: EntityId;
|
|
320
|
+
readonly capabilityId?: CapabilityId;
|
|
321
|
+
readonly model?: string;
|
|
322
|
+
readonly inputHash?: string;
|
|
323
|
+
readonly contextRefs: readonly string[];
|
|
324
|
+
readonly inputTokens: number;
|
|
325
|
+
readonly outputTokens: number;
|
|
326
|
+
readonly durationMs: number;
|
|
327
|
+
readonly cost?: number;
|
|
328
|
+
readonly tools: readonly string[];
|
|
329
|
+
readonly files: readonly string[];
|
|
330
|
+
readonly commands: readonly string[];
|
|
331
|
+
readonly validationStatus?: EvaluationResult['status'];
|
|
332
|
+
readonly outcome: 'succeeded' | 'failed' | 'blocked' | 'inconclusive';
|
|
333
|
+
readonly errorCode?: string;
|
|
334
|
+
}
|
|
335
|
+
export interface ControlPlaneMetrics {
|
|
336
|
+
readonly observationCount: number;
|
|
337
|
+
readonly runCount: number;
|
|
338
|
+
readonly successfulRuns: number;
|
|
339
|
+
readonly failedRuns: number;
|
|
340
|
+
readonly blockedRuns: number;
|
|
341
|
+
readonly successRate: number;
|
|
342
|
+
readonly totalInputTokens: number;
|
|
343
|
+
readonly totalOutputTokens: number;
|
|
344
|
+
readonly totalDurationMs: number;
|
|
345
|
+
readonly totalCost: number;
|
|
346
|
+
readonly cacheHitRate?: number;
|
|
347
|
+
readonly evidenceCoverageRate: number;
|
|
348
|
+
}
|
|
349
|
+
export type EvaluationScope = 'run' | 'agent' | 'task' | 'sprint' | 'capability' | 'model' | 'strategy' | 'workspace';
|
|
350
|
+
export interface EvaluationReport extends AuditFields {
|
|
351
|
+
readonly id: EntityId;
|
|
352
|
+
readonly scope: EvaluationScope;
|
|
353
|
+
readonly scopeId?: string;
|
|
354
|
+
readonly observationIds: readonly EntityId[];
|
|
355
|
+
readonly metrics: Readonly<Record<string, number>>;
|
|
356
|
+
readonly findings: readonly {
|
|
357
|
+
readonly name: string;
|
|
358
|
+
readonly value: number;
|
|
359
|
+
readonly evidenceIds: readonly EntityId[];
|
|
360
|
+
}[];
|
|
361
|
+
}
|
|
362
|
+
export declare class ContractValidationError extends Error {
|
|
363
|
+
readonly path: string;
|
|
364
|
+
constructor(path: string, message: string);
|
|
365
|
+
}
|
|
366
|
+
export declare function assertContract(condition: boolean, path: string, message: string): asserts condition;
|
|
367
|
+
export declare function validateTokenBudget(value: TokenBudget): TokenBudget;
|
|
368
|
+
export declare function validateCapabilityDefinition(value: CapabilityDefinition): CapabilityDefinition;
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/** Versioned, framework-independent contracts for ForjaJS 2.0. */
|
|
2
|
+
export const CONTRACT_VERSION = '2.0';
|
|
3
|
+
export class ContractValidationError extends Error {
|
|
4
|
+
path;
|
|
5
|
+
constructor(path, message) { super(`${path}: ${message}`); this.name = 'ContractValidationError'; this.path = path; }
|
|
6
|
+
}
|
|
7
|
+
export function assertContract(condition, path, message) {
|
|
8
|
+
if (!condition)
|
|
9
|
+
throw new ContractValidationError(path, message);
|
|
10
|
+
}
|
|
11
|
+
export function validateTokenBudget(value) {
|
|
12
|
+
assertContract(Number.isInteger(value.inputTokens) && value.inputTokens >= 0, 'budget.inputTokens', 'must be a non-negative integer');
|
|
13
|
+
assertContract(Number.isInteger(value.outputTokens) && value.outputTokens >= 0, 'budget.outputTokens', 'must be a non-negative integer');
|
|
14
|
+
assertContract(value.totalTokens === value.inputTokens + value.outputTokens, 'budget.totalTokens', 'must equal inputTokens + outputTokens');
|
|
15
|
+
assertContract(Number.isInteger(value.usedTokens) && value.usedTokens >= 0 && value.usedTokens <= value.totalTokens, 'budget.usedTokens', 'must be within totalTokens');
|
|
16
|
+
return value;
|
|
17
|
+
}
|
|
18
|
+
export function validateCapabilityDefinition(value) {
|
|
19
|
+
assertContract(value.schemaVersion === CONTRACT_VERSION, 'schemaVersion', `must be ${CONTRACT_VERSION}`);
|
|
20
|
+
assertContract(/^[-a-z0-9]+(?:\.[-a-z0-9]+)+$/.test(value.id), 'id', 'must be a namespaced capability id');
|
|
21
|
+
assertContract(value.version.length > 0, 'version', 'is required');
|
|
22
|
+
assertContract(value.description.trim().length > 0, 'description', 'is required');
|
|
23
|
+
assertContract(Number.isInteger(value.timeoutMs) && value.timeoutMs > 0, 'timeoutMs', 'must be a positive integer');
|
|
24
|
+
assertContract(Number.isInteger(value.retry.maxAttempts) && value.retry.maxAttempts >= 1, 'retry.maxAttempts', 'must be at least 1');
|
|
25
|
+
assertContract(Number.isInteger(value.retry.backoffMs) && value.retry.backoffMs >= 0, 'retry.backoffMs', 'must be non-negative');
|
|
26
|
+
return value;
|
|
27
|
+
}
|
|
@@ -0,0 +1,68 @@
|
|
|
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';
|
|
2
|
+
export interface CapabilityExecutionContext {
|
|
3
|
+
readonly runId: RunId;
|
|
4
|
+
readonly agent: AgentIdentity;
|
|
5
|
+
readonly definition: CapabilityDefinition;
|
|
6
|
+
}
|
|
7
|
+
export interface CapabilityRegistration<Input, Output> {
|
|
8
|
+
readonly definition: CapabilityDefinition;
|
|
9
|
+
readonly validateInput: (value: unknown) => Input;
|
|
10
|
+
readonly validateOutput: (value: unknown) => Output;
|
|
11
|
+
readonly handler: (input: Input, context: CapabilityExecutionContext) => CapabilityOutput | Promise<CapabilityOutput>;
|
|
12
|
+
}
|
|
13
|
+
export interface CapabilityAuthorizationRequest {
|
|
14
|
+
readonly definition: CapabilityDefinition;
|
|
15
|
+
readonly input: CapabilityInput;
|
|
16
|
+
readonly agent: AgentIdentity;
|
|
17
|
+
readonly projectId?: string;
|
|
18
|
+
readonly environment: string;
|
|
19
|
+
readonly categories: readonly string[];
|
|
20
|
+
readonly files: readonly string[];
|
|
21
|
+
readonly budget?: TokenBudget;
|
|
22
|
+
readonly now: ISO8601;
|
|
23
|
+
readonly approval?: {
|
|
24
|
+
readonly action: string;
|
|
25
|
+
readonly justification: string;
|
|
26
|
+
readonly impact: string;
|
|
27
|
+
readonly expectedDiff?: string;
|
|
28
|
+
readonly expiresAt: ISO8601;
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
export interface CapabilityPolicy {
|
|
32
|
+
authorize(request: CapabilityAuthorizationRequest): PolicyDecision;
|
|
33
|
+
canDiscover?(definition: CapabilityDefinition, agent?: AgentProfile): boolean;
|
|
34
|
+
}
|
|
35
|
+
export interface CapabilityListFilter {
|
|
36
|
+
readonly agent?: AgentProfile;
|
|
37
|
+
readonly policy?: CapabilityPolicy;
|
|
38
|
+
}
|
|
39
|
+
export interface CapabilityExecutionRequest {
|
|
40
|
+
readonly input: CapabilityInput;
|
|
41
|
+
readonly agent: AgentIdentity;
|
|
42
|
+
readonly policy: CapabilityPolicy;
|
|
43
|
+
readonly correlationId?: string;
|
|
44
|
+
readonly projectId?: string;
|
|
45
|
+
readonly environment?: string;
|
|
46
|
+
readonly categories?: readonly string[];
|
|
47
|
+
readonly files?: readonly string[];
|
|
48
|
+
readonly budget?: TokenBudget;
|
|
49
|
+
readonly approval?: CapabilityAuthorizationRequest['approval'];
|
|
50
|
+
}
|
|
51
|
+
export declare class CapabilityRegistryError extends Error {
|
|
52
|
+
constructor(message: string);
|
|
53
|
+
}
|
|
54
|
+
export declare class CapabilityRegistry {
|
|
55
|
+
private readonly registrations;
|
|
56
|
+
private readonly aliases;
|
|
57
|
+
register<Input, Output>(registration: CapabilityRegistration<Input, Output>): void;
|
|
58
|
+
list(filter?: CapabilityListFilter): readonly CapabilityDefinition[];
|
|
59
|
+
describe(idOrAlias: string, filter?: CapabilityListFilter): CapabilityDefinition;
|
|
60
|
+
execute(request: CapabilityExecutionRequest): Promise<ExecutionResult>;
|
|
61
|
+
private resolve;
|
|
62
|
+
private tryResolve;
|
|
63
|
+
private isVisible;
|
|
64
|
+
private createRunId;
|
|
65
|
+
private auditFields;
|
|
66
|
+
private failure;
|
|
67
|
+
private toExecutionError;
|
|
68
|
+
}
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
import { randomUUID } from 'node:crypto';
|
|
2
|
+
import { CONTRACT_VERSION, validateCapabilityDefinition, } from "../../contracts/src/index.js";
|
|
3
|
+
export class CapabilityRegistryError extends Error {
|
|
4
|
+
constructor(message) {
|
|
5
|
+
super(message);
|
|
6
|
+
this.name = 'CapabilityRegistryError';
|
|
7
|
+
}
|
|
8
|
+
}
|
|
9
|
+
export class CapabilityRegistry {
|
|
10
|
+
registrations = new Map();
|
|
11
|
+
aliases = new Map();
|
|
12
|
+
register(registration) {
|
|
13
|
+
const definition = validateCapabilityDefinition(registration.definition);
|
|
14
|
+
const id = definition.id;
|
|
15
|
+
if (this.registrations.has(id)) {
|
|
16
|
+
throw new CapabilityRegistryError(`Capability already registered: ${id}`);
|
|
17
|
+
}
|
|
18
|
+
const names = [id, ...definition.aliases];
|
|
19
|
+
for (const name of names) {
|
|
20
|
+
const existing = this.aliases.get(name);
|
|
21
|
+
if (existing !== undefined) {
|
|
22
|
+
throw new CapabilityRegistryError(`Capability name already registered: ${name}`);
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
const stored = {
|
|
26
|
+
definition,
|
|
27
|
+
validateInput: registration.validateInput,
|
|
28
|
+
validateOutput: registration.validateOutput,
|
|
29
|
+
handler: registration.handler,
|
|
30
|
+
};
|
|
31
|
+
this.registrations.set(id, stored);
|
|
32
|
+
for (const name of names)
|
|
33
|
+
this.aliases.set(name, id);
|
|
34
|
+
}
|
|
35
|
+
list(filter = {}) {
|
|
36
|
+
return [...this.registrations.values()]
|
|
37
|
+
.map((registration) => registration.definition)
|
|
38
|
+
.filter((definition) => this.isVisible(definition, filter))
|
|
39
|
+
.sort((left, right) => left.id.localeCompare(right.id));
|
|
40
|
+
}
|
|
41
|
+
describe(idOrAlias, filter = {}) {
|
|
42
|
+
const definition = this.resolve(idOrAlias).definition;
|
|
43
|
+
if (!this.isVisible(definition, filter)) {
|
|
44
|
+
throw new CapabilityRegistryError(`Capability not discoverable: ${idOrAlias}`);
|
|
45
|
+
}
|
|
46
|
+
return definition;
|
|
47
|
+
}
|
|
48
|
+
async execute(request) {
|
|
49
|
+
const runId = this.createRunId();
|
|
50
|
+
const timestamps = this.auditFields(request.correlationId ?? runId);
|
|
51
|
+
const resolved = this.tryResolve(request.input.capabilityId);
|
|
52
|
+
if (resolved.error !== undefined) {
|
|
53
|
+
return this.failure(runId, timestamps, resolved.error);
|
|
54
|
+
}
|
|
55
|
+
const registration = resolved.registration;
|
|
56
|
+
let input;
|
|
57
|
+
try {
|
|
58
|
+
input = registration.validateInput(request.input.payload);
|
|
59
|
+
}
|
|
60
|
+
catch (error) {
|
|
61
|
+
return this.failure(runId, timestamps, this.toExecutionError('INVALID_INPUT', error, false));
|
|
62
|
+
}
|
|
63
|
+
let decision;
|
|
64
|
+
try {
|
|
65
|
+
decision = request.policy.authorize({
|
|
66
|
+
definition: registration.definition,
|
|
67
|
+
input: request.input,
|
|
68
|
+
agent: request.agent,
|
|
69
|
+
projectId: request.projectId,
|
|
70
|
+
environment: request.environment ?? 'local',
|
|
71
|
+
categories: request.categories ?? [],
|
|
72
|
+
files: request.files ?? [],
|
|
73
|
+
budget: request.budget,
|
|
74
|
+
now: timestamps.createdAt,
|
|
75
|
+
approval: request.approval,
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
catch (error) {
|
|
79
|
+
return this.failure(runId, timestamps, this.toExecutionError('POLICY_ERROR', error, false));
|
|
80
|
+
}
|
|
81
|
+
if (decision.effect === 'DENY' || decision.effect === 'REQUIRE_APPROVAL') {
|
|
82
|
+
return {
|
|
83
|
+
...timestamps,
|
|
84
|
+
runId,
|
|
85
|
+
status: 'blocked',
|
|
86
|
+
error: {
|
|
87
|
+
code: decision.effect === 'DENY' ? 'POLICY_DENIED' : 'APPROVAL_REQUIRED',
|
|
88
|
+
message: decision.reason,
|
|
89
|
+
retryable: false,
|
|
90
|
+
},
|
|
91
|
+
evidence: [],
|
|
92
|
+
};
|
|
93
|
+
}
|
|
94
|
+
try {
|
|
95
|
+
const output = await registration.handler(input, { runId, agent: request.agent, definition: registration.definition });
|
|
96
|
+
registration.validateOutput(output.payload);
|
|
97
|
+
if (output.capabilityId !== registration.definition.id)
|
|
98
|
+
throw new Error('Handler output capabilityId does not match definition');
|
|
99
|
+
return { ...timestamps, runId, status: 'succeeded', output, evidence: output.evidence };
|
|
100
|
+
}
|
|
101
|
+
catch (error) {
|
|
102
|
+
return this.failure(runId, timestamps, this.toExecutionError('HANDLER_FAILED', error, true));
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
resolve(idOrAlias) {
|
|
106
|
+
const id = this.aliases.get(idOrAlias);
|
|
107
|
+
if (id === undefined)
|
|
108
|
+
throw new CapabilityRegistryError(`Capability not found: ${idOrAlias}`);
|
|
109
|
+
const registration = this.registrations.get(id);
|
|
110
|
+
if (registration === undefined)
|
|
111
|
+
throw new CapabilityRegistryError(`Capability registry is inconsistent: ${id}`);
|
|
112
|
+
return registration;
|
|
113
|
+
}
|
|
114
|
+
tryResolve(idOrAlias) {
|
|
115
|
+
try {
|
|
116
|
+
return { registration: this.resolve(idOrAlias) };
|
|
117
|
+
}
|
|
118
|
+
catch (error) {
|
|
119
|
+
return { error: this.toExecutionError('CAPABILITY_NOT_FOUND', error, false) };
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
isVisible(definition, filter) {
|
|
123
|
+
if (filter.agent !== undefined && !definition.permissions.every((permission) => filter.agent?.permissions.includes(permission)))
|
|
124
|
+
return false;
|
|
125
|
+
return filter.policy?.canDiscover?.(definition, filter.agent) ?? true;
|
|
126
|
+
}
|
|
127
|
+
createRunId() {
|
|
128
|
+
return randomUUID();
|
|
129
|
+
}
|
|
130
|
+
auditFields(correlationId) {
|
|
131
|
+
const now = new Date().toISOString();
|
|
132
|
+
return { schemaVersion: CONTRACT_VERSION, createdAt: now, updatedAt: now, correlationId };
|
|
133
|
+
}
|
|
134
|
+
failure(runId, fields, error) {
|
|
135
|
+
return { ...fields, runId, status: 'failed', error, evidence: [] };
|
|
136
|
+
}
|
|
137
|
+
toExecutionError(code, error, retryable) {
|
|
138
|
+
const message = error instanceof Error ? error.message : 'Unknown capability error';
|
|
139
|
+
return { code, message, retryable };
|
|
140
|
+
}
|
|
141
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { type EvaluationReport, type EvaluationScope, type Observation } from '../../contracts/src/index.ts';
|
|
2
|
+
export interface EvaluationRequest {
|
|
3
|
+
readonly scope: EvaluationScope;
|
|
4
|
+
readonly scopeId?: string;
|
|
5
|
+
readonly observations?: readonly Observation[];
|
|
6
|
+
readonly correlationId?: string;
|
|
7
|
+
}
|
|
8
|
+
export interface EvaluationObservationSource {
|
|
9
|
+
list(): readonly Observation[] | Promise<readonly Observation[]>;
|
|
10
|
+
}
|
|
11
|
+
export declare class EvaluationError extends Error {
|
|
12
|
+
constructor(message: string);
|
|
13
|
+
}
|
|
14
|
+
export declare class EvaluationEngine {
|
|
15
|
+
private readonly source;
|
|
16
|
+
constructor(source: EvaluationObservationSource);
|
|
17
|
+
evaluate(input: EvaluationRequest): Promise<EvaluationReport>;
|
|
18
|
+
private matches;
|
|
19
|
+
private metrics;
|
|
20
|
+
private repeatedInputCount;
|
|
21
|
+
private rate;
|
|
22
|
+
}
|