agentic-orchestrator 0.1.2 → 0.1.4

package/agentic/orchestrator/tools/catalog.json

@@ -394,6 +394,74 @@
       "handler_id": "report.feature_summary",
       "mutating": false,
       "requires_operation_id": false
+    },
+    {
+      "name": "feature.send_message",
+      "description": "Send a message to the active orchestrator session for a feature.",
+      "input_schema_ref": "schemas/input/feature.send_message.input.schema.json",
+      "output_schema_ref": "schemas/output/feature.send_message.output.schema.json",
+      "supported_roles": [
+        "orchestrator",
+        "system"
+      ],
+      "handler_id": "feature.send_message",
+      "mutating": true,
+      "requires_operation_id": true
+    },
+    {
+      "name": "cost.record",
+      "description": "Record token usage and estimated cost for a feature.",
+      "input_schema_ref": "schemas/input/cost.record.input.schema.json",
+      "output_schema_ref": "schemas/output/cost.record.output.schema.json",
+      "supported_roles": [
+        "orchestrator",
+        "system"
+      ],
+      "handler_id": "cost.record",
+      "mutating": true,
+      "requires_operation_id": true
+    },
+    {
+      "name": "cost.get",
+      "description": "Get current cost tracking data for a feature.",
+      "input_schema_ref": "schemas/input/cost.get.input.schema.json",
+      "output_schema_ref": "schemas/output/cost.get.output.schema.json",
+      "supported_roles": [
+        "orchestrator",
+        "system"
+      ],
+      "handler_id": "cost.get",
+      "mutating": false,
+      "requires_operation_id": false
+    },
+    {
+      "name": "performance.record_outcome",
+      "description": "Record per-feature outcome metrics for agent performance analytics.",
+      "input_schema_ref": "schemas/input/performance.record_outcome.input.schema.json",
+      "output_schema_ref": "schemas/output/performance.record_outcome.output.schema.json",
+      "supported_roles": [
+        "orchestrator",
+        "system"
+      ],
+      "handler_id": "performance.record_outcome",
+      "mutating": true,
+      "requires_operation_id": true
+    },
+    {
+      "name": "performance.get_analytics",
+      "description": "Get agent performance analytics with optional provider/model filters.",
+      "input_schema_ref": "schemas/input/performance.get_analytics.input.schema.json",
+      "output_schema_ref": "schemas/output/performance.get_analytics.output.schema.json",
+      "supported_roles": [
+        "orchestrator",
+        "planner",
+        "builder",
+        "qa",
+        "system"
+      ],
+      "handler_id": "performance.get_analytics",
+      "mutating": false,
+      "requires_operation_id": false
     }
   ]
 }

package/agentic/orchestrator/tools/schemas/input/cost.get.input.schema.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/tools/schemas/input/cost.get.input.schema.json",
+  "type": "object",
+  "required": ["feature_id"],
+  "properties": {
+    "feature_id": { "type": "string", "minLength": 1 }
+  },
+  "additionalProperties": false
+}

package/agentic/orchestrator/tools/schemas/input/cost.record.input.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/tools/schemas/input/cost.record.input.schema.json",
+  "type": "object",
+  "required": ["feature_id", "tokens_used", "estimated_cost_usd"],
+  "properties": {
+    "feature_id": { "type": "string", "minLength": 1 },
+    "tokens_used": { "type": "integer", "minimum": 0 },
+    "estimated_cost_usd": { "type": "number", "minimum": 0 },
+    "operation_id": { "type": "string" }
+  },
+  "additionalProperties": false
+}

package/agentic/orchestrator/tools/schemas/input/feature.send_message.input.schema.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["feature_id", "message", "operation_id"],
+  "properties": {
+    "feature_id": { "type": "string" },
+    "message": { "type": "string", "minLength": 1 },
+    "operation_id": { "type": "string" }
+  },
+  "additionalProperties": false
+}

package/agentic/orchestrator/tools/schemas/input/performance.get_analytics.input.schema.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/tools/schemas/input/performance.get_analytics.input.schema.json",
+  "type": "object",
+  "properties": {
+    "provider": { "type": "string" },
+    "model": { "type": "string" }
+  },
+  "additionalProperties": false
+}

package/agentic/orchestrator/tools/schemas/input/performance.record_outcome.input.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/tools/schemas/input/performance.record_outcome.input.schema.json",
+  "type": "object",
+  "required": ["feature_id", "provider", "model", "status", "gate_pass", "retry_count", "duration_ms", "cost_usd"],
+  "properties": {
+    "feature_id": { "type": "string", "minLength": 1 },
+    "provider": { "type": "string", "minLength": 1 },
+    "model": { "type": "string", "minLength": 1 },
+    "status": { "type": "string", "minLength": 1 },
+    "gate_pass": { "type": "boolean" },
+    "retry_count": { "type": "integer", "minimum": 0 },
+    "duration_ms": { "type": "number", "minimum": 0 },
+    "cost_usd": { "type": "number", "minimum": 0 },
+    "operation_id": { "type": "string" }
+  },
+  "additionalProperties": false
+}

package/agentic/orchestrator/tools/schemas/output/cost.get.output.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/tools/schemas/output/cost.get.output.schema.json",
+  "type": "object",
+  "required": ["feature_id", "tokens_used", "estimated_cost_usd"],
+  "properties": {
+    "feature_id": { "type": "string", "minLength": 1 },
+    "tokens_used": { "type": "integer", "minimum": 0 },
+    "estimated_cost_usd": { "type": "number", "minimum": 0 },
+    "recorded_at": { "type": ["string", "null"] }
+  },
+  "additionalProperties": false
+}

package/agentic/orchestrator/tools/schemas/output/cost.record.output.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/tools/schemas/output/cost.record.output.schema.json",
+  "type": "object",
+  "required": ["feature_id", "tokens_used", "estimated_cost_usd"],
+  "properties": {
+    "feature_id": { "type": "string", "minLength": 1 },
+    "tokens_used": { "type": "integer", "minimum": 0 },
+    "estimated_cost_usd": { "type": "number", "minimum": 0 },
+    "recorded_at": { "type": "string" }
+  },
+  "additionalProperties": false
+}

package/agentic/orchestrator/tools/schemas/output/feature.ready_to_merge.output.schema.json

@@ -24,6 +24,13 @@
     "status": {
       "type": "string",
       "minLength": 1
+    },
+    "retained_for_cleanup": {
+      "type": "boolean"
+    },
+    "cleanup_grace_period_seconds": {
+      "type": "number",
+      "minimum": 0
     }
   },
   "additionalProperties": false

package/agentic/orchestrator/tools/schemas/output/feature.send_message.output.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["ok"],
+  "properties": {
+    "ok": { "type": "boolean" },
+    "data": {
+      "type": "object",
+      "properties": {
+        "feature_id": { "type": "string" },
+        "session_id": { "type": "string" },
+        "delivered": { "type": "boolean" }
+      }
+    },
+    "error": {
+      "type": "object",
+      "properties": {
+        "code": { "type": "string" },
+        "message": { "type": "string" }
+      }
+    }
+  }
+}

package/agentic/orchestrator/tools/schemas/output/performance.get_analytics.output.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/tools/schemas/output/performance.get_analytics.output.schema.json",
+  "type": "object",
+  "required": ["outcomes", "aggregates", "generated_at"],
+  "properties": {
+    "outcomes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["feature_id", "provider", "model", "status", "gate_pass", "retry_count", "duration_ms", "cost_usd", "recorded_at"],
+        "properties": {
+          "feature_id": { "type": "string" },
+          "provider": { "type": "string" },
+          "model": { "type": "string" },
+          "status": { "type": "string" },
+          "gate_pass": { "type": "boolean" },
+          "retry_count": { "type": "integer" },
+          "duration_ms": { "type": "number" },
+          "cost_usd": { "type": "number" },
+          "recorded_at": { "type": "string" }
+        }
+      }
+    },
+    "aggregates": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["provider", "model", "total_features", "success_count", "success_rate", "avg_retry_count", "avg_duration_ms", "avg_cost_usd", "last_updated"],
+        "properties": {
+          "provider": { "type": "string" },
+          "model": { "type": "string" },
+          "total_features": { "type": "integer" },
+          "success_count": { "type": "integer" },
+          "success_rate": { "type": "number" },
+          "avg_retry_count": { "type": "number" },
+          "avg_duration_ms": { "type": "number" },
+          "avg_cost_usd": { "type": "number" },
+          "last_updated": { "type": "string" }
+        }
+      }
+    },
+    "generated_at": { "type": "string" }
+  },
+  "additionalProperties": false
+}

package/agentic/orchestrator/tools/schemas/output/performance.record_outcome.output.schema.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/agentic/tools/schemas/output/performance.record_outcome.output.schema.json",
+  "type": "object",
+  "required": ["total_outcomes"],
+  "properties": {
+    "total_outcomes": { "type": "integer", "minimum": 0 }
+  },
+  "additionalProperties": false
+}

package/agentic/orchestrator/tools.md

@@ -3,6 +3,8 @@
 Generated from `agentic/orchestrator/tools/catalog.json`.
 
 - collisions.scan
+- cost.get
+- cost.record
 - evidence.latest
 - feature.delete
 - feature.discover_specs
@@ -10,12 +12,15 @@ Generated from `agentic/orchestrator/tools/catalog.json`.
 - feature.init
 - feature.log_append
 - feature.ready_to_merge
+- feature.send_message
 - feature.state_get
 - feature.state_patch
 - gates.list
 - gates.run
 - locks.acquire
 - locks.release
+- performance.get_analytics
+- performance.record_outcome
 - plan.get
 - plan.submit
 - plan.update

package/apps/control-plane/scripts/validate-architecture-rules.mjs

@@ -4,6 +4,7 @@ import path from 'node:path';
 const ARCHITECTURE_RULES = {
   'application-services': ['cli', 'interfaces', 'mcp', 'providers', 'supervisor'],
   'application-tools': ['cli', 'interfaces', 'mcp', 'providers', 'supervisor'],
+  application: ['cli', 'interfaces', 'supervisor'],
   cli: [],
   core: ['cli', 'interfaces', 'supervisor'],
   interfaces: [],
@@ -12,6 +13,8 @@ const ARCHITECTURE_RULES = {
   supervisor: ['cli', 'interfaces']
 };
 
+const EXEMPT_FILES = new Set(['index.ts']);
+
 const IMPORT_PATTERN = /(?:import|export)\s+[^'"]*?from\s+['"]([^'"]+)['"]/g;
 const SRC_ROOT = path.resolve(process.cwd(), 'apps/control-plane/src');
 
@@ -39,6 +42,9 @@ function classifyLayer(filePath) {
   if (relativePath.startsWith('application/tools/')) {
     return 'application-tools';
   }
+  if (relativePath.startsWith('application/')) {
+    return 'application';
+  }
   if (relativePath.startsWith('cli/')) {
     return 'cli';
   }
@@ -106,10 +112,16 @@ function extractImports(content) {
 async function collectViolations() {
   const files = await collectFiles(SRC_ROOT);
   const violations = [];
+  const errors = [];
 
   for (const file of files) {
+    const relativePath = path.relative(SRC_ROOT, file).replaceAll('\\', '/');
+    if (EXEMPT_FILES.has(path.basename(file))) {
+      continue;
+    }
     const sourceLayer = classifyLayer(file);
     if (sourceLayer === 'unknown') {
+      errors.push(`Unclassified source file "${relativePath}" — add it to the layer map in validate-architecture-rules.mjs`);
       continue;
     }
     const forbiddenTargets = ARCHITECTURE_RULES[sourceLayer];
@@ -142,7 +154,7 @@ async function collectViolations() {
     }
   }
 
-  return { filesChecked: files.length, violations };
+  return { filesChecked: files.length, violations, errors };
 }
 
 function printViolation(violation) {
@@ -153,7 +165,17 @@ function printViolation(violation) {
 }
 
 async function main() {
-  const { filesChecked, violations } = await collectViolations();
+  const { filesChecked, violations, errors } = await collectViolations();
+  let failed = false;
+
+  if (errors.length > 0) {
+    process.stderr.write('architecture_unclassified_files_detected\n');
+    for (const error of errors) {
+      process.stderr.write(`- ${error}\n`);
+    }
+    failed = true;
+  }
+
   if (violations.length > 0) {
     process.stderr.write('architecture_rule_violations_detected\n');
     for (const violation of violations) {
@@ -161,6 +183,10 @@ async function main() {
     }
     process.stderr.write(`files_checked=${filesChecked}\n`);
     process.stderr.write(`violation_count=${violations.length}\n`);
+    failed = true;
+  }
+
+  if (failed) {
     process.exit(1);
   }
 

package/apps/control-plane/scripts/validate-docker-mcp-contract.mjs

@@ -33,6 +33,17 @@ const compose = readText(composePath);
 const entrypoint = readText(entrypointPath);
 
 assertContains(dockerfile, /^FROM\s+node:/m, 'docker image must be Node-based');
+
+const MIN_NODE_MAJOR = 22;
+const fromMatch = dockerfile.match(/^FROM\s+node:(\d+)/m);
+if (!fromMatch) {
+  fail('Dockerfile must use a pinned Node version (e.g. node:22-bookworm-slim)');
+}
+const nodeMajor = parseInt(fromMatch[1], 10);
+if (nodeMajor < MIN_NODE_MAJOR) {
+  fail(`Dockerfile Node version ${nodeMajor} is below minimum required ${MIN_NODE_MAJOR}`);
+}
+
 assertContains(dockerfile, /apt-get install[^]*\bgit\b/m, 'docker image must include git toolchain');
 assertContains(dockerfile, /ENV\s+AOP_REPO_ROOT=\/repo/m, 'docker image must declare /repo root');
 assertContains(
@@ -47,6 +58,7 @@ assertContains(compose, /working_dir:\s*\/repo/m, 'compose service must execute
 
 assertContains(entrypoint, /if \[ ! -d "\/repo" ]/m, 'entrypoint must enforce /repo mount check');
 assertContains(entrypoint, /for tool in node npm npx git;/m, 'entrypoint must verify required toolchains');
+assertContains(entrypoint, /\bexec\s+"\$@"/, 'entrypoint must contain exec "$@" passthrough');
 
 if (!runSmoke) {
   console.log('validate:docker-mcp: contract checks passed');

package/apps/control-plane/scripts/validate-mcp-contracts.ts

@@ -1,8 +1,20 @@
 import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
 import path from 'node:path';
+import Ajv from 'ajv';
+import Ajv2020 from 'ajv/dist/2020.js';
 import { MCP_PROTOCOL_PIN, REQUIRED_MCP_TRANSPORTS } from '../src/mcp/protocol-contract.js';
 import { ToolsMarkdownGenerator } from '../src/mcp/tools-markdown-generator.js';
 import { ToolRegistryLoader } from '../src/mcp/tool-registry-loader.js';
+import { TOOL_BEHAVIOR_METADATA } from '../src/index.js';
+
+const KNOWN_ROLES = new Set(['orchestrator', 'planner', 'builder', 'qa', 'system']);
+
+const KNOWN_SHARED_SCHEMAS = new Set([
+  'schemas/input/mutating.schema.json',
+  'schemas/input/read.schema.json',
+  'schemas/output/standard_success.schema.json'
+]);
 
 function fail(message: string): never {
   throw new Error(message);
@@ -12,6 +24,14 @@ function normalizeMarkdown(content: string): string {
   return `${content.replace(/\r\n/g, '\n').trimEnd()}\n`;
 }
 
+function globSchemaFiles(dir: string, prefix: string): string[] {
+  try {
+    return fsSync.readdirSync(dir).map((f) => `${prefix}/${f}`);
+  } catch {
+    return [];
+  }
+}
+
 async function main(): Promise<void> {
   const repoRoot = process.cwd();
   const loader = new ToolRegistryLoader(repoRoot);
@@ -49,6 +69,78 @@ async function main(): Promise<void> {
     fail('tools_markdown_drift_detected');
   }
 
+  const toolsDir = path.join(repoRoot, 'agentic', 'orchestrator', 'tools');
+  const ajv7 = new Ajv({ strict: false });
+  const ajv2020 = new Ajv2020({ strict: false });
+  function compileSchema(schema: Record<string, unknown>): void {
+    const schemaVersion = schema['$schema'] as string | undefined;
+    if (schemaVersion?.includes('2020-12') === true) {
+      ajv2020.compile(schema);
+    } else {
+      ajv7.compile(schema);
+    }
+  }
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const referencedSchemas = new Set<string>();
+
+  for (const tool of registry.catalog.tools) {
+    // V1.1: mutating cross-check
+    const mutatingInCatalog = tool.mutating === true;
+    const mutatingInCode = TOOL_BEHAVIOR_METADATA[tool.handler_id]?.mutating === true;
+    if (mutatingInCatalog !== mutatingInCode) {
+      errors.push(
+        `Tool "${tool.handler_id}" mutating flag mismatch: catalog=${String(mutatingInCatalog)}, code=${String(mutatingInCode)}`
+      );
+    }
+
+    // V1.4: supported_roles validation
+    for (const role of tool.supported_roles ?? []) {
+      if (!KNOWN_ROLES.has(role)) {
+        errors.push(`Tool "${tool.name}" has unknown role "${role}" in supported_roles`);
+      }
+    }
+
+    // V1.2: AJV schema compilation + V1.3: orphan tracking
+    for (const schemaRef of [tool.input_schema_ref, tool.output_schema_ref]) {
+      if (!schemaRef) { continue; }
+      referencedSchemas.add(schemaRef);
+      const schemaPath = path.resolve(toolsDir, schemaRef);
+      try {
+        const schema = JSON.parse(await fs.readFile(schemaPath, 'utf8'));
+        try {
+          compileSchema(schema as Record<string, unknown>);
+        } catch (e) {
+          errors.push(`Schema "${schemaRef}" failed AJV compilation: ${(e as Error).message}`);
+        }
+      } catch {
+        errors.push(`Schema file not found: ${schemaRef}`);
+      }
+    }
+  }
+
+  // V1.3: orphan schema detection
+  const allSchemaFiles = [
+    ...globSchemaFiles(path.join(toolsDir, 'schemas', 'input'), 'schemas/input'),
+    ...globSchemaFiles(path.join(toolsDir, 'schemas', 'output'), 'schemas/output')
+  ];
+  for (const file of allSchemaFiles) {
+    if (!referencedSchemas.has(file) && !KNOWN_SHARED_SCHEMAS.has(file)) {
+      warnings.push(`Orphan schema file not referenced by any catalog tool: ${file}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    for (const error of errors) {
+      process.stderr.write(`[validate:mcp-contracts] error: ${error}\n`);
+    }
+    fail(`${errors.length} contract error(s) detected`);
+  }
+
+  for (const warning of warnings) {
+    process.stdout.write(`[validate:mcp-contracts] warning: ${warning}\n`);
+  }
+
   process.stdout.write(
     `[validate:mcp-contracts] ok: tools=${registry.catalog.tools.length} protocol=${protocol.mcp_protocol_version} sdk=${protocol.sdk.package}@${protocol.sdk.version}\n`
   );