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,153 @@
|
|
|
1
|
+
export const MCP_RESOURCE_URIS = [
|
|
2
|
+
'forja://workspace/current',
|
|
3
|
+
'forja://project/current',
|
|
4
|
+
'forja://specs',
|
|
5
|
+
'forja://decisions',
|
|
6
|
+
'forja://graph',
|
|
7
|
+
'forja://agent/agenda',
|
|
8
|
+
'forja://executions',
|
|
9
|
+
];
|
|
10
|
+
export class McpAdapterError extends Error {
|
|
11
|
+
constructor(message) { super(message); this.name = 'McpAdapterError'; }
|
|
12
|
+
}
|
|
13
|
+
export const MCP_TOOLS = [
|
|
14
|
+
tool('forja_workspace_status', 'Retorna o estado operacional mínimo do workspace.', []),
|
|
15
|
+
tool('forja_capabilities_list', 'Lista capabilities visíveis para a identidade MCP.', []),
|
|
16
|
+
tool('forja_capability_execute', 'Executa uma capability pelo Registry com Policy e resultado auditável.', ['capabilityId']),
|
|
17
|
+
tool('forja_context_build', 'Constrói contexto mínimo com orçamento e evidências.', ['objective', 'budget']),
|
|
18
|
+
tool('forja_memory_query', 'Consulta memória por objetivo.', ['objective']),
|
|
19
|
+
tool('forja_graph_query', 'Consulta nós do GraphLoop.', []),
|
|
20
|
+
tool('forja_code_impact', 'Consulta impacto de um nó no GraphLoop.', ['origin']),
|
|
21
|
+
tool('forja_task_next', 'Obtém a próxima Task elegível de uma Sprint.', ['sprintId']),
|
|
22
|
+
tool('forja_handoff_create', 'Cria um handoff estruturado e auditável.', ['from', 'to', 'intent', 'objective', 'acceptance', 'evidenceIds', 'nextAgent']),
|
|
23
|
+
tool('forja_spec_check', 'Executa a verificação de uma spec pelo adapter configurado.', []),
|
|
24
|
+
tool('forja_test_run', 'Executa testes pelo adapter configurado.', []),
|
|
25
|
+
tool('forja_execution_validate', 'Valida uma execução pelo adapter configurado.', []),
|
|
26
|
+
];
|
|
27
|
+
export class McpServer {
|
|
28
|
+
dependencies;
|
|
29
|
+
tools = new Map();
|
|
30
|
+
resources = new Map();
|
|
31
|
+
constructor(dependencies) {
|
|
32
|
+
this.dependencies = dependencies;
|
|
33
|
+
for (const definition of MCP_TOOLS)
|
|
34
|
+
this.tools.set(definition.name, definition);
|
|
35
|
+
for (const uri of MCP_RESOURCE_URIS)
|
|
36
|
+
this.resources.set(uri, { uri, name: uri, description: `Forja resource ${uri}`, mimeType: 'application/json', read: () => dependencies.resourceData?.[uri] ?? { available: false, uri, reason: 'Resource provider is not configured' } });
|
|
37
|
+
for (const resource of dependencies.resources ?? [])
|
|
38
|
+
this.resources.set(resource.uri, resource);
|
|
39
|
+
}
|
|
40
|
+
listTools() { return [...this.tools.values()]; }
|
|
41
|
+
listResources() { return [...this.resources.values()]; }
|
|
42
|
+
async callTool(name, input = {}) {
|
|
43
|
+
const definition = this.tools.get(name);
|
|
44
|
+
if (definition === undefined)
|
|
45
|
+
return this.error('TOOL_NOT_FOUND', `MCP tool not found: ${name}`);
|
|
46
|
+
try {
|
|
47
|
+
const object = this.objectInput(input);
|
|
48
|
+
this.requireFields(definition, object);
|
|
49
|
+
const value = await this.dispatch(name, object);
|
|
50
|
+
return this.success(value);
|
|
51
|
+
}
|
|
52
|
+
catch (error) {
|
|
53
|
+
return this.error('TOOL_FAILED', error instanceof Error ? error.message : 'Unknown MCP tool error');
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
async readResource(uri) {
|
|
57
|
+
const resource = this.resources.get(uri);
|
|
58
|
+
if (resource === undefined)
|
|
59
|
+
return this.error('RESOURCE_NOT_FOUND', `MCP resource not found: ${uri}`);
|
|
60
|
+
try {
|
|
61
|
+
return this.success(await resource.read());
|
|
62
|
+
}
|
|
63
|
+
catch (error) {
|
|
64
|
+
return this.error('RESOURCE_FAILED', error instanceof Error ? error.message : 'Unknown MCP resource error');
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
async dispatch(name, input) {
|
|
68
|
+
switch (name) {
|
|
69
|
+
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) };
|
|
70
|
+
case 'forja_capabilities_list': return this.dependencies.registry.list({ agent: this.dependencies.agent, policy: this.dependencies.policy });
|
|
71
|
+
case 'forja_capability_execute': return this.executeCapability(input);
|
|
72
|
+
case 'forja_context_build': return this.requireContext().build(this.contextRequest(input));
|
|
73
|
+
case 'forja_memory_query': return this.requireMemory().query(this.string(input, 'objective'));
|
|
74
|
+
case 'forja_graph_query': return this.requireGraph().query(this.graphQuery(input));
|
|
75
|
+
case 'forja_code_impact': return this.requireGraph().impact(this.entity(input, 'origin'), this.number(input, 'depth', 2), this.direction(input));
|
|
76
|
+
case 'forja_task_next': return this.requireTasks().next(this.entity(input, 'sprintId'));
|
|
77
|
+
case 'forja_handoff_create': return this.createHandoff(input);
|
|
78
|
+
case 'forja_spec_check': return this.requireSpecChecker().check(input);
|
|
79
|
+
case 'forja_test_run': return this.requireTestRunner().run(input);
|
|
80
|
+
case 'forja_execution_validate': return this.requireExecutionValidator().validate(input);
|
|
81
|
+
default: throw new McpAdapterError(`MCP tool not implemented: ${name}`);
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
async createHandoff(input) {
|
|
85
|
+
this.authorize('forja_handoff_create', 'write', 'medium', []);
|
|
86
|
+
return this.requireHandoffs().create({
|
|
87
|
+
from: this.string(input, 'from'), to: this.string(input, 'to'), intent: this.string(input, 'intent'), objective: this.string(input, 'objective'),
|
|
88
|
+
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'),
|
|
89
|
+
});
|
|
90
|
+
}
|
|
91
|
+
executeCapability(input) {
|
|
92
|
+
const capabilityId = this.string(input, 'capabilityId');
|
|
93
|
+
return this.dependencies.registry.execute({
|
|
94
|
+
input: { capabilityId, payload: input.payload },
|
|
95
|
+
agent: this.dependencies.agent,
|
|
96
|
+
policy: this.dependencies.policy,
|
|
97
|
+
correlationId: this.optionalString(input, 'correlationId'),
|
|
98
|
+
projectId: this.optionalString(input, 'projectId'),
|
|
99
|
+
environment: this.optionalString(input, 'environment'),
|
|
100
|
+
categories: this.strings(input, 'categories'),
|
|
101
|
+
files: this.strings(input, 'files'),
|
|
102
|
+
budget: input.budget === undefined ? undefined : this.budget(input, 'budget'),
|
|
103
|
+
});
|
|
104
|
+
}
|
|
105
|
+
authorize(action, category, risk, files) {
|
|
106
|
+
const decision = this.dependencies.mcpPolicy?.authorize({ action, category, risk, files });
|
|
107
|
+
if (decision?.effect === 'DENY' || decision?.effect === 'REQUIRE_APPROVAL')
|
|
108
|
+
throw new McpAdapterError(`Policy blocked MCP action: ${decision.reason}`);
|
|
109
|
+
}
|
|
110
|
+
contextRequest(input) { return { objective: this.string(input, 'objective'), budget: this.budget(input, 'budget'), includeContent: input.includeContent !== false, maxItems: input.maxItems === undefined ? undefined : this.number(input, 'maxItems'), requireEvidence: input.requireEvidence !== false, correlationId: this.optionalString(input, 'correlationId') }; }
|
|
111
|
+
graphQuery(input) { return { type: this.optionalString(input, 'type'), status: this.optionalStatus(input, 'status'), labelIncludes: this.optionalString(input, 'labelIncludes') }; }
|
|
112
|
+
direction(input) { const value = input.direction ?? 'outgoing'; if (value !== 'outgoing' && value !== 'incoming' && value !== 'both')
|
|
113
|
+
throw new McpAdapterError('direction must be outgoing, incoming or both'); return value; }
|
|
114
|
+
budget(input, field) { const value = input[field]; if (!isRecord(value) || typeof value.inputTokens !== 'number' || typeof value.outputTokens !== 'number' || typeof value.totalTokens !== 'number' || typeof value.usedTokens !== 'number')
|
|
115
|
+
throw new McpAdapterError(`${field} must be a TokenBudget`); return value; }
|
|
116
|
+
objectInput(input) { if (!isRecord(input))
|
|
117
|
+
throw new McpAdapterError('MCP input must be an object'); return input; }
|
|
118
|
+
requireFields(definition, input) { for (const field of definition.inputSchema.required ?? [])
|
|
119
|
+
if (input[field] === undefined)
|
|
120
|
+
throw new McpAdapterError(`Missing required input: ${field}`); }
|
|
121
|
+
string(input, field) { const value = input[field]; if (typeof value !== 'string' || value.trim().length === 0)
|
|
122
|
+
throw new McpAdapterError(`${field} must be a non-empty string`); return value; }
|
|
123
|
+
optionalString(input, field) { const value = input[field]; return value === undefined ? undefined : this.string(input, field); }
|
|
124
|
+
strings(input, field) { const value = input[field] ?? []; if (!Array.isArray(value) || value.some((item) => typeof item !== 'string'))
|
|
125
|
+
throw new McpAdapterError(`${field} must be an array of strings`); return value; }
|
|
126
|
+
entity(input, field) { return this.string(input, field); }
|
|
127
|
+
entities(input, field) { return this.strings(input, field); }
|
|
128
|
+
number(input, field, fallback) { const value = input[field] ?? fallback; if (typeof value !== 'number' || !Number.isFinite(value))
|
|
129
|
+
throw new McpAdapterError(`${field} must be a finite number`); return value; }
|
|
130
|
+
optionalStatus(input, field) { const value = input[field]; if (value === undefined)
|
|
131
|
+
return undefined; if (value !== 'verified' && value !== 'inferred' && value !== 'hypothesis' && value !== 'contradicted' && value !== 'unknown')
|
|
132
|
+
throw new McpAdapterError(`${field} is an invalid knowledge status`); return value; }
|
|
133
|
+
requireContext() { if (this.dependencies.context === undefined)
|
|
134
|
+
throw new McpAdapterError('Context Engine is not configured'); return this.dependencies.context; }
|
|
135
|
+
requireGraph() { if (this.dependencies.graph === undefined)
|
|
136
|
+
throw new McpAdapterError('GraphLoop is not configured'); return this.dependencies.graph; }
|
|
137
|
+
requireMemory() { if (this.dependencies.memory === undefined)
|
|
138
|
+
throw new McpAdapterError('Memory adapter is not configured'); return this.dependencies.memory; }
|
|
139
|
+
requireTasks() { if (this.dependencies.taskEngine === undefined)
|
|
140
|
+
throw new McpAdapterError('Task Engine is not configured'); return this.dependencies.taskEngine; }
|
|
141
|
+
requireHandoffs() { if (this.dependencies.handoffEngine === undefined)
|
|
142
|
+
throw new McpAdapterError('Handoff Engine is not configured'); return this.dependencies.handoffEngine; }
|
|
143
|
+
requireSpecChecker() { if (this.dependencies.specChecker === undefined)
|
|
144
|
+
throw new McpAdapterError('Spec checker is not configured'); return this.dependencies.specChecker; }
|
|
145
|
+
requireTestRunner() { if (this.dependencies.testRunner === undefined)
|
|
146
|
+
throw new McpAdapterError('Test runner is not configured'); return this.dependencies.testRunner; }
|
|
147
|
+
requireExecutionValidator() { if (this.dependencies.executionValidator === undefined)
|
|
148
|
+
throw new McpAdapterError('Execution validator is not configured'); return this.dependencies.executionValidator; }
|
|
149
|
+
success(value) { return { isError: false, content: [{ type: 'text', text: JSON.stringify(value) }], structuredContent: value }; }
|
|
150
|
+
error(code, message) { const value = { code, message }; return { isError: true, content: [{ type: 'text', text: JSON.stringify(value) }], structuredContent: value }; }
|
|
151
|
+
}
|
|
152
|
+
function tool(name, description, required) { return { name, description, inputSchema: { type: 'object', properties: Object.fromEntries(required.map((field) => [field, { type: field === 'budget' ? 'object' : field.endsWith('Ids') ? 'array' : 'string' }])), required, additionalProperties: false } }; }
|
|
153
|
+
function isRecord(value) { return typeof value === 'object' && value !== null; }
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
import { type CapabilityId, type ControlPlaneMetrics, type EntityId, type Observation, type RunId } from '../../contracts/src/index.ts';
|
|
2
|
+
export interface ObservationInput {
|
|
3
|
+
readonly traceId: string;
|
|
4
|
+
readonly runId?: RunId;
|
|
5
|
+
readonly agentId?: EntityId;
|
|
6
|
+
readonly taskId?: EntityId;
|
|
7
|
+
readonly sprintId?: EntityId;
|
|
8
|
+
readonly capabilityId?: CapabilityId;
|
|
9
|
+
readonly model?: string;
|
|
10
|
+
readonly inputHash?: string;
|
|
11
|
+
readonly contextRefs?: readonly string[];
|
|
12
|
+
readonly inputTokens?: number;
|
|
13
|
+
readonly outputTokens?: number;
|
|
14
|
+
readonly durationMs?: number;
|
|
15
|
+
readonly cost?: number;
|
|
16
|
+
readonly tools?: readonly string[];
|
|
17
|
+
readonly files?: readonly string[];
|
|
18
|
+
readonly commands?: readonly string[];
|
|
19
|
+
readonly validationStatus?: Observation['validationStatus'];
|
|
20
|
+
readonly outcome: Observation['outcome'];
|
|
21
|
+
readonly errorCode?: string;
|
|
22
|
+
readonly evidenceIds?: readonly EntityId[];
|
|
23
|
+
readonly correlationId?: string;
|
|
24
|
+
}
|
|
25
|
+
export interface ObservationStore {
|
|
26
|
+
append(value: Observation): void | Promise<void>;
|
|
27
|
+
list(): readonly Observation[] | Promise<readonly Observation[]>;
|
|
28
|
+
}
|
|
29
|
+
export interface ControlPlanePort {
|
|
30
|
+
metrics(): ControlPlaneMetrics | Promise<ControlPlaneMetrics>;
|
|
31
|
+
observations(): readonly Observation[] | Promise<readonly Observation[]>;
|
|
32
|
+
runtimeStart?(input: unknown): unknown | Promise<unknown>;
|
|
33
|
+
runtimeGet?(id: string): unknown | Promise<unknown>;
|
|
34
|
+
runtimeExecute?(id: string): unknown | Promise<unknown>;
|
|
35
|
+
runtimePause?(id: string): unknown | Promise<unknown>;
|
|
36
|
+
runtimeResume?(id: string): unknown | Promise<unknown>;
|
|
37
|
+
runtimeCancel?(id: string): unknown | Promise<unknown>;
|
|
38
|
+
sprintCreate?(input: unknown): unknown | Promise<unknown>;
|
|
39
|
+
sprintStart?(id: string): unknown | Promise<unknown>;
|
|
40
|
+
sprintPause?(id: string): unknown | Promise<unknown>;
|
|
41
|
+
taskCreate?(input: unknown): unknown | Promise<unknown>;
|
|
42
|
+
taskStart?(id: string): unknown | Promise<unknown>;
|
|
43
|
+
taskBlock?(id: string): unknown | Promise<unknown>;
|
|
44
|
+
handoffCreate?(input: unknown): unknown | Promise<unknown>;
|
|
45
|
+
approvalGet?(id: string): unknown | Promise<unknown>;
|
|
46
|
+
approvalList?(): unknown | Promise<unknown>;
|
|
47
|
+
approvalDecide?(id: string, input: unknown): unknown | Promise<unknown>;
|
|
48
|
+
}
|
|
49
|
+
export interface ControlPlaneEvent {
|
|
50
|
+
readonly id: string;
|
|
51
|
+
readonly type: string;
|
|
52
|
+
readonly aggregateId: string;
|
|
53
|
+
readonly data: unknown;
|
|
54
|
+
readonly correlationId: string;
|
|
55
|
+
}
|
|
56
|
+
export interface ControlPlaneEventSink {
|
|
57
|
+
publish(event: ControlPlaneEvent): void;
|
|
58
|
+
}
|
|
59
|
+
export interface ControlPlaneServices {
|
|
60
|
+
readonly runtime?: {
|
|
61
|
+
readonly start: (input: unknown) => unknown | Promise<unknown>;
|
|
62
|
+
readonly get: (input: unknown) => unknown | Promise<unknown>;
|
|
63
|
+
readonly execute: (input: unknown) => unknown | Promise<unknown>;
|
|
64
|
+
readonly pause: (input: unknown) => unknown | Promise<unknown>;
|
|
65
|
+
readonly resume: (input: unknown) => unknown | Promise<unknown>;
|
|
66
|
+
readonly cancel: (input: unknown) => unknown | Promise<unknown>;
|
|
67
|
+
};
|
|
68
|
+
readonly sprint?: {
|
|
69
|
+
readonly create: (input: unknown) => unknown | Promise<unknown>;
|
|
70
|
+
readonly start: (input: unknown) => unknown | Promise<unknown>;
|
|
71
|
+
readonly pause: (input: unknown) => unknown | Promise<unknown>;
|
|
72
|
+
};
|
|
73
|
+
readonly task?: {
|
|
74
|
+
readonly create: (input: unknown) => unknown | Promise<unknown>;
|
|
75
|
+
readonly start: (input: unknown) => unknown | Promise<unknown>;
|
|
76
|
+
readonly block: (input: unknown) => unknown | Promise<unknown>;
|
|
77
|
+
};
|
|
78
|
+
readonly handoff?: {
|
|
79
|
+
readonly create: (input: unknown) => unknown | Promise<unknown>;
|
|
80
|
+
};
|
|
81
|
+
readonly approvals?: {
|
|
82
|
+
readonly get: (input: unknown) => unknown | Promise<unknown>;
|
|
83
|
+
readonly list?: (input: unknown) => unknown | Promise<unknown>;
|
|
84
|
+
readonly decide: (input: unknown) => unknown | Promise<unknown>;
|
|
85
|
+
};
|
|
86
|
+
readonly events?: ControlPlaneEventSink;
|
|
87
|
+
}
|
|
88
|
+
export declare class ObservabilityError extends Error {
|
|
89
|
+
constructor(message: string);
|
|
90
|
+
}
|
|
91
|
+
export declare class InMemoryObservationStore implements ObservationStore {
|
|
92
|
+
private readonly values;
|
|
93
|
+
append(value: Observation): void;
|
|
94
|
+
list(): readonly Observation[];
|
|
95
|
+
}
|
|
96
|
+
export declare class ObservabilityRecorder {
|
|
97
|
+
private readonly store;
|
|
98
|
+
constructor(store?: ObservationStore);
|
|
99
|
+
record(input: ObservationInput): Promise<Observation>;
|
|
100
|
+
metrics(): Promise<ControlPlaneMetrics>;
|
|
101
|
+
observations(): Promise<readonly Observation[]>;
|
|
102
|
+
private calculate;
|
|
103
|
+
private clean;
|
|
104
|
+
private nonNegative;
|
|
105
|
+
}
|
|
106
|
+
export declare class ControlPlane implements ControlPlanePort {
|
|
107
|
+
private readonly recorder;
|
|
108
|
+
private readonly services;
|
|
109
|
+
constructor(recorder?: ObservabilityRecorder, services?: ControlPlaneServices);
|
|
110
|
+
metrics(): Promise<ControlPlaneMetrics>;
|
|
111
|
+
observations(): Promise<readonly Observation[]>;
|
|
112
|
+
record(input: ObservationInput): Promise<Observation>;
|
|
113
|
+
runtimeStart(input: unknown): Promise<unknown>;
|
|
114
|
+
runtimeGet(id: string): Promise<unknown>;
|
|
115
|
+
runtimeExecute(id: string): Promise<unknown>;
|
|
116
|
+
runtimePause(id: string): Promise<unknown>;
|
|
117
|
+
runtimeResume(id: string): Promise<unknown>;
|
|
118
|
+
runtimeCancel(id: string): Promise<unknown>;
|
|
119
|
+
sprintCreate(input: unknown): Promise<unknown>;
|
|
120
|
+
sprintStart(id: string): Promise<unknown>;
|
|
121
|
+
sprintPause(id: string): Promise<unknown>;
|
|
122
|
+
taskCreate(input: unknown): Promise<unknown>;
|
|
123
|
+
taskStart(id: string): Promise<unknown>;
|
|
124
|
+
taskBlock(id: string): Promise<unknown>;
|
|
125
|
+
handoffCreate(input: unknown): Promise<unknown>;
|
|
126
|
+
approvalGet(id: string): Promise<unknown>;
|
|
127
|
+
approvalList(): Promise<unknown>;
|
|
128
|
+
approvalDecide(id: string, input: unknown): Promise<unknown>;
|
|
129
|
+
private delegate;
|
|
130
|
+
private runId;
|
|
131
|
+
private outcome;
|
|
132
|
+
}
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
import { randomUUID } from 'node:crypto';
|
|
2
|
+
import { CONTRACT_VERSION } from "../../contracts/src/index.js";
|
|
3
|
+
export class ObservabilityError extends Error {
|
|
4
|
+
constructor(message) { super(message); this.name = 'ObservabilityError'; }
|
|
5
|
+
}
|
|
6
|
+
export class InMemoryObservationStore {
|
|
7
|
+
values = [];
|
|
8
|
+
append(value) { this.values.push(value); }
|
|
9
|
+
list() { return [...this.values]; }
|
|
10
|
+
}
|
|
11
|
+
export class ObservabilityRecorder {
|
|
12
|
+
store;
|
|
13
|
+
constructor(store = new InMemoryObservationStore()) { this.store = store; }
|
|
14
|
+
async record(input) {
|
|
15
|
+
if (input.traceId.trim().length === 0)
|
|
16
|
+
throw new ObservabilityError('traceId is required');
|
|
17
|
+
const observation = {
|
|
18
|
+
schemaVersion: CONTRACT_VERSION, id: randomUUID(), createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), correlationId: input.correlationId ?? input.traceId,
|
|
19
|
+
traceId: input.traceId, runId: input.runId, agentId: input.agentId, taskId: input.taskId, sprintId: input.sprintId, capabilityId: input.capabilityId, model: input.model, inputHash: input.inputHash,
|
|
20
|
+
contextRefs: this.clean(input.contextRefs), inputTokens: this.nonNegative(input.inputTokens ?? 0, 'inputTokens'), outputTokens: this.nonNegative(input.outputTokens ?? 0, 'outputTokens'), durationMs: this.nonNegative(input.durationMs ?? 0, 'durationMs'), cost: this.nonNegative(input.cost ?? 0, 'cost'), tools: this.clean(input.tools), files: this.clean(input.files), commands: this.clean(input.commands), validationStatus: input.validationStatus, outcome: input.outcome, errorCode: input.errorCode,
|
|
21
|
+
};
|
|
22
|
+
await this.store.append(observation);
|
|
23
|
+
return observation;
|
|
24
|
+
}
|
|
25
|
+
async metrics() { return this.calculate(await this.store.list()); }
|
|
26
|
+
async observations() { return this.store.list(); }
|
|
27
|
+
calculate(values) {
|
|
28
|
+
const runOutcomes = new Map();
|
|
29
|
+
for (const value of values)
|
|
30
|
+
if (value.runId !== undefined)
|
|
31
|
+
runOutcomes.set(value.runId, value.outcome);
|
|
32
|
+
const runs = [...runOutcomes.values()];
|
|
33
|
+
const successfulRuns = runs.filter((outcome) => outcome === 'succeeded').length;
|
|
34
|
+
const failedRuns = runs.filter((outcome) => outcome === 'failed').length;
|
|
35
|
+
const blockedRuns = runs.filter((outcome) => outcome === 'blocked').length;
|
|
36
|
+
const evidenceCount = values.filter((value) => value.contextRefs.length > 0 || value.inputHash !== undefined).length;
|
|
37
|
+
return { observationCount: values.length, runCount: runs.length, successfulRuns, failedRuns, blockedRuns, successRate: runs.length === 0 ? 0 : successfulRuns / runs.length, totalInputTokens: values.reduce((sum, value) => sum + value.inputTokens, 0), totalOutputTokens: values.reduce((sum, value) => sum + value.outputTokens, 0), totalDurationMs: values.reduce((sum, value) => sum + value.durationMs, 0), totalCost: values.reduce((sum, value) => sum + (value.cost ?? 0), 0), evidenceCoverageRate: values.length === 0 ? 0 : evidenceCount / values.length };
|
|
38
|
+
}
|
|
39
|
+
clean(values) { return [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))]; }
|
|
40
|
+
nonNegative(value, field) { if (!Number.isFinite(value) || value < 0)
|
|
41
|
+
throw new ObservabilityError(`${field} must be non-negative`); return value; }
|
|
42
|
+
}
|
|
43
|
+
export class ControlPlane {
|
|
44
|
+
recorder;
|
|
45
|
+
services;
|
|
46
|
+
constructor(recorder = new ObservabilityRecorder(), services = {}) { this.recorder = recorder; this.services = services; }
|
|
47
|
+
metrics() { return this.recorder.metrics(); }
|
|
48
|
+
observations() { return this.recorder.observations(); }
|
|
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
|
+
runtimeStart(input) { return this.delegate(this.services.runtime?.start, input, 'runtimeStart'); }
|
|
51
|
+
runtimeGet(id) { return this.delegate(this.services.runtime?.get, id, 'runtimeGet'); }
|
|
52
|
+
runtimeExecute(id) { return this.delegate(this.services.runtime?.execute, id, 'runtimeExecute'); }
|
|
53
|
+
runtimePause(id) { return this.delegate(this.services.runtime?.pause, id, 'runtimePause'); }
|
|
54
|
+
runtimeResume(id) { return this.delegate(this.services.runtime?.resume, id, 'runtimeResume'); }
|
|
55
|
+
runtimeCancel(id) { return this.delegate(this.services.runtime?.cancel, id, 'runtimeCancel'); }
|
|
56
|
+
sprintCreate(input) { return this.delegate(this.services.sprint?.create, input, 'sprintCreate'); }
|
|
57
|
+
sprintStart(id) { return this.delegate(this.services.sprint?.start, id, 'sprintStart'); }
|
|
58
|
+
sprintPause(id) { return this.delegate(this.services.sprint?.pause, id, 'sprintPause'); }
|
|
59
|
+
taskCreate(input) { return this.delegate(this.services.task?.create, input, 'taskCreate'); }
|
|
60
|
+
taskStart(id) { return this.delegate(this.services.task?.start, id, 'taskStart'); }
|
|
61
|
+
taskBlock(id) { return this.delegate(this.services.task?.block, id, 'taskBlock'); }
|
|
62
|
+
handoffCreate(input) { return this.delegate(this.services.handoff?.create, input, 'handoffCreate'); }
|
|
63
|
+
approvalGet(id) { return this.delegate(this.services.approvals?.get, id, 'approvalGet'); }
|
|
64
|
+
approvalList() { return this.delegate(this.services.approvals?.list, 'all', 'approvalList'); }
|
|
65
|
+
approvalDecide(id, input) { return this.delegate(this.services.approvals?.decide, { id, input }, 'approvalDecide'); }
|
|
66
|
+
async delegate(handler, input, name) {
|
|
67
|
+
if (handler === undefined)
|
|
68
|
+
throw new ObservabilityError(`Control Plane service is not configured: ${name}`);
|
|
69
|
+
const traceId = `control-plane:${name}:${typeof input === 'string' ? input : name}`;
|
|
70
|
+
try {
|
|
71
|
+
const result = await handler(input);
|
|
72
|
+
await this.record({ traceId, runId: this.runId(result), outcome: this.outcome(result), inputTokens: 0, outputTokens: 0, durationMs: 0 });
|
|
73
|
+
return result;
|
|
74
|
+
}
|
|
75
|
+
catch (error) {
|
|
76
|
+
await this.record({ traceId, outcome: 'failed', errorCode: error instanceof Error ? error.name : 'UNKNOWN', inputTokens: 0, outputTokens: 0, durationMs: 0 });
|
|
77
|
+
throw error;
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
runId(value) { return isRecord(value) && typeof value.runId === 'string' ? value.runId : undefined; }
|
|
81
|
+
outcome(value) { if (!isRecord(value))
|
|
82
|
+
return 'succeeded'; if (value.state === 'blocked' || value.status === 'blocked')
|
|
83
|
+
return 'blocked'; if (value.state === 'failed' || value.status === 'failed')
|
|
84
|
+
return 'failed'; return 'succeeded'; }
|
|
85
|
+
}
|
|
86
|
+
function isRecord(value) { return typeof value === 'object' && value !== null; }
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
import { type EntityId, type EvaluationResult, type Handoff, type Sprint, type Task, type TokenBudget } from '../../contracts/src/index.ts';
|
|
2
|
+
export interface OrchestrationStore {
|
|
3
|
+
saveSprint(value: Sprint): void | Promise<void>;
|
|
4
|
+
getSprint(id: EntityId): Sprint | undefined | Promise<Sprint | undefined>;
|
|
5
|
+
listSprints(): readonly Sprint[] | Promise<readonly Sprint[]>;
|
|
6
|
+
saveTask(value: Task): void | Promise<void>;
|
|
7
|
+
getTask(id: EntityId): Task | undefined | Promise<Task | undefined>;
|
|
8
|
+
listTasks(sprintId?: EntityId): readonly Task[] | Promise<readonly Task[]>;
|
|
9
|
+
saveHandoff(value: Handoff): void | Promise<void>;
|
|
10
|
+
getHandoff(id: EntityId): Handoff | undefined | Promise<Handoff | undefined>;
|
|
11
|
+
listHandoffs(): readonly Handoff[] | Promise<readonly Handoff[]>;
|
|
12
|
+
}
|
|
13
|
+
export interface GraphRecorder {
|
|
14
|
+
record(input: {
|
|
15
|
+
readonly kind: 'sprint' | 'task' | 'handoff';
|
|
16
|
+
readonly id: EntityId;
|
|
17
|
+
readonly relatedIds: readonly EntityId[];
|
|
18
|
+
readonly evidenceIds: readonly EntityId[];
|
|
19
|
+
}): void | Promise<void>;
|
|
20
|
+
}
|
|
21
|
+
export interface CompletionValidator {
|
|
22
|
+
validateTask(task: Task): EvaluationResult | Promise<EvaluationResult>;
|
|
23
|
+
validateSprint(sprint: Sprint, tasks: readonly Task[]): EvaluationResult | Promise<EvaluationResult>;
|
|
24
|
+
}
|
|
25
|
+
export interface CreateSprintInput {
|
|
26
|
+
readonly objective: string;
|
|
27
|
+
readonly includedScope: readonly string[];
|
|
28
|
+
readonly excludedScope: readonly string[];
|
|
29
|
+
readonly budget: TokenBudget;
|
|
30
|
+
readonly completionCriteria: readonly string[];
|
|
31
|
+
readonly risks: readonly string[];
|
|
32
|
+
readonly evidenceIds: readonly EntityId[];
|
|
33
|
+
readonly correlationId?: string;
|
|
34
|
+
}
|
|
35
|
+
export interface CreateTaskInput {
|
|
36
|
+
readonly sprintId: EntityId;
|
|
37
|
+
readonly objective: string;
|
|
38
|
+
readonly acceptanceCriteria: readonly string[];
|
|
39
|
+
readonly allowedFiles: readonly string[];
|
|
40
|
+
readonly dependencyIds: readonly EntityId[];
|
|
41
|
+
readonly evidenceIds: readonly EntityId[];
|
|
42
|
+
readonly budget: TokenBudget;
|
|
43
|
+
readonly correlationId?: string;
|
|
44
|
+
}
|
|
45
|
+
export interface CreateHandoffInput {
|
|
46
|
+
readonly from: string;
|
|
47
|
+
readonly to: string;
|
|
48
|
+
readonly intent: string;
|
|
49
|
+
readonly objective: string;
|
|
50
|
+
readonly completedWork: readonly string[];
|
|
51
|
+
readonly decisions: readonly string[];
|
|
52
|
+
readonly constraints: readonly string[];
|
|
53
|
+
readonly pending: readonly string[];
|
|
54
|
+
readonly evidenceIds: readonly EntityId[];
|
|
55
|
+
readonly acceptance: readonly string[];
|
|
56
|
+
readonly blockers: readonly string[];
|
|
57
|
+
readonly nextAgent: string;
|
|
58
|
+
readonly correlationId?: string;
|
|
59
|
+
}
|
|
60
|
+
export declare class OrchestrationError extends Error {
|
|
61
|
+
constructor(message: string);
|
|
62
|
+
}
|
|
63
|
+
export declare class InMemoryOrchestrationStore implements OrchestrationStore {
|
|
64
|
+
private readonly sprints;
|
|
65
|
+
private readonly tasks;
|
|
66
|
+
private readonly handoffs;
|
|
67
|
+
saveSprint(value: Sprint): void;
|
|
68
|
+
getSprint(id: EntityId): Sprint | undefined;
|
|
69
|
+
listSprints(): readonly Sprint[];
|
|
70
|
+
saveTask(value: Task): void;
|
|
71
|
+
getTask(id: EntityId): Task | undefined;
|
|
72
|
+
listTasks(sprintId?: EntityId): readonly Task[];
|
|
73
|
+
saveHandoff(value: Handoff): void;
|
|
74
|
+
getHandoff(id: EntityId): Handoff | undefined;
|
|
75
|
+
listHandoffs(): readonly Handoff[];
|
|
76
|
+
}
|
|
77
|
+
export declare class SprintEngine {
|
|
78
|
+
private readonly store;
|
|
79
|
+
private readonly graph?;
|
|
80
|
+
constructor(store: OrchestrationStore, graph?: GraphRecorder);
|
|
81
|
+
create(input: CreateSprintInput): Promise<Sprint>;
|
|
82
|
+
start(id: EntityId): Promise<Sprint>;
|
|
83
|
+
pause(id: EntityId): Promise<Sprint>;
|
|
84
|
+
attachTask(sprintId: EntityId, taskId: EntityId): Promise<Sprint>;
|
|
85
|
+
complete(id: EntityId, validator: CompletionValidator): Promise<Sprint>;
|
|
86
|
+
private transition;
|
|
87
|
+
private requireSprint;
|
|
88
|
+
private record;
|
|
89
|
+
private updated;
|
|
90
|
+
private audit;
|
|
91
|
+
private auditFields;
|
|
92
|
+
private id;
|
|
93
|
+
private clean;
|
|
94
|
+
private unique;
|
|
95
|
+
private requireText;
|
|
96
|
+
private requireItems;
|
|
97
|
+
private evidenceFrom;
|
|
98
|
+
}
|
|
99
|
+
export declare class TaskEngine {
|
|
100
|
+
private readonly store;
|
|
101
|
+
private readonly sprintEngine;
|
|
102
|
+
private readonly graph?;
|
|
103
|
+
constructor(store: OrchestrationStore, sprintEngine: SprintEngine, graph?: GraphRecorder);
|
|
104
|
+
create(input: CreateTaskInput): Promise<Task>;
|
|
105
|
+
next(sprintId: EntityId): Promise<Task | undefined>;
|
|
106
|
+
start(id: EntityId): Promise<Task>;
|
|
107
|
+
block(id: EntityId): Promise<Task>;
|
|
108
|
+
complete(id: EntityId, validator: CompletionValidator): Promise<Task>;
|
|
109
|
+
private require;
|
|
110
|
+
private updated;
|
|
111
|
+
private clean;
|
|
112
|
+
private unique;
|
|
113
|
+
}
|
|
114
|
+
export declare class HandoffEngine {
|
|
115
|
+
private readonly store;
|
|
116
|
+
private readonly graph?;
|
|
117
|
+
private readonly maxItems;
|
|
118
|
+
private readonly maxItemLength;
|
|
119
|
+
constructor(store: OrchestrationStore, graph?: GraphRecorder, maxItems?: number, maxItemLength?: number);
|
|
120
|
+
create(input: CreateHandoffInput): Promise<Handoff>;
|
|
121
|
+
private compact;
|
|
122
|
+
}
|