@llm-dev-ops/agentics-cli 1.4.27 → 1.4.29

package/dist/bundled-agents/analytics-hub-agents/src/execution/execution-graph.ts

@@ -1,165 +0,0 @@
-/**
- * ExecutionGraph — per-request, append-only span accumulator
- *
- * Manages the lifecycle of repo-level and agent-level execution spans
- * within a single API request. Enforces the Agentics invariant that
- * every execution must contain at least one agent span.
- */
-
-import { v4 as uuidv4 } from 'uuid';
-import {
-  ExecutionContext,
-  ExecutionSpan,
-  SpanArtifact,
-  SpanHierarchy,
-  SpanStatus,
-} from './span-types';
-
-export class ExecutionGraph {
-  private repoSpan: ExecutionSpan;
-  private agentSpans: ExecutionSpan[] = [];
-
-  constructor(context: ExecutionContext, repoName: string) {
-    this.repoSpan = {
-      span_id: uuidv4(),
-      parent_span_id: context.parent_span_id,
-      trace_id: context.execution_id,
-      span_type: 'repo',
-      name: repoName,
-      status: 'ok',
-      start_time: new Date().toISOString(),
-      attributes: { repo_name: repoName },
-      artifacts: [],
-    };
-  }
-
-  /**
-   * Start an agent-level span. Returns the span_id for later
-   * use with endAgentSpan() and attachArtifact().
-   */
-  startAgentSpan(
-    agentName: string,
-    attributes?: Record<string, unknown>,
-  ): string {
-    const span: ExecutionSpan = {
-      span_id: uuidv4(),
-      parent_span_id: this.repoSpan.span_id,
-      trace_id: this.repoSpan.trace_id,
-      span_type: 'agent',
-      name: agentName,
-      status: 'ok',
-      start_time: new Date().toISOString(),
-      attributes: attributes || {},
-      artifacts: [],
-    };
-    this.agentSpans.push(span);
-    return span.span_id;
-  }
-
-  /**
-   * Complete an agent span, setting its end_time and final status.
-   */
-  endAgentSpan(spanId: string, status: SpanStatus): void {
-    const span = this.agentSpans.find((s) => s.span_id === spanId);
-    if (span) {
-      span.end_time = new Date().toISOString();
-      span.status = status;
-    }
-  }
-
-  /**
-   * Attach a machine-verifiable artifact to an agent span.
-   */
-  attachArtifact(
-    spanId: string,
-    artifact: Omit<SpanArtifact, 'timestamp'>,
-  ): void {
-    const span = this.agentSpans.find((s) => s.span_id === spanId);
-    if (span) {
-      span.artifacts.push({
-        ...artifact,
-        timestamp: new Date().toISOString(),
-      });
-    }
-  }
-
-  /**
-   * Finalize the repo-level span.
-   */
-  finalize(status: SpanStatus): void {
-    this.repoSpan.end_time = new Date().toISOString();
-    this.repoSpan.status = status;
-  }
-
-  /**
-   * Validate the execution graph invariants.
-   * Returns invalid if no agent spans were emitted.
-   */
-  validate(): { valid: boolean; error?: string } {
-    if (this.agentSpans.length === 0) {
-      return {
-        valid: false,
-        error: 'No agent-level spans were emitted during execution',
-      };
-    }
-    return { valid: true };
-  }
-
-  /**
-   * Build the JSON-serializable span hierarchy for the response.
-   */
-  toHierarchy(): SpanHierarchy {
-    return {
-      core_span_id: this.repoSpan.parent_span_id,
-      repo_span: { ...this.repoSpan },
-      agent_spans: this.agentSpans.map((s) => ({ ...s })),
-    };
-  }
-
-  getRepoSpanId(): string {
-    return this.repoSpan.span_id;
-  }
-
-  getTraceId(): string {
-    return this.repoSpan.trace_id;
-  }
-}
-
-// ─── Helper for data routes ────────────────────────────────────
-
-/**
- * Wrap a data-processing operation with an agent-level span.
- * Creates a `data-processing-agent` span, executes the handler,
- * and optionally attaches an artifact from the result.
- */
-export async function withDataProcessingSpan<T>(
-  graph: ExecutionGraph | null | undefined,
-  operationName: string,
-  handler: () => Promise<T>,
-  artifactBuilder?: (result: T) => { artifact_type: string; data: unknown },
-): Promise<T> {
-  if (!graph) return handler();
-
-  const spanId = graph.startAgentSpan('data-processing-agent', {
-    operation: operationName,
-  });
-
-  try {
-    const result = await handler();
-
-    if (artifactBuilder) {
-      const artifact = artifactBuilder(result);
-      graph.attachArtifact(spanId, {
-        artifact_type: artifact.artifact_type,
-        artifact_id: spanId,
-        data: artifact.data,
-      });
-    }
-
-    graph.endAgentSpan(spanId, 'ok');
-    return result;
-  } catch (error) {
-    graph.endAgentSpan(spanId, 'error');
-    throw error;
-  }
-}

package/dist/bundled-agents/analytics-hub-agents/src/execution/fastify-plugin.ts

@@ -1,168 +0,0 @@
-/**
- * Fastify Execution Context Plugin
- *
- * Hooks into the Fastify request lifecycle to:
- * 1. Extract execution context (execution_id, parent_span_id) from headers
- * 2. Create an ExecutionGraph per request
- * 3. Validate and wrap responses with the span hierarchy
- *
- * Enforces the Agentics contract: every non-operational request must
- * carry a parent_span_id and produce at least one agent span.
- */
-
-import fp from 'fastify-plugin';
-import { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
-import { v4 as uuidv4 } from 'uuid';
-import { ExecutionGraph } from './execution-graph';
-import type { ExecutionContext } from './span-types';
-
-const HEADER_EXECUTION_ID = 'x-execution-id';
-const HEADER_PARENT_SPAN_ID = 'x-parent-span-id';
-
-const UUID_REGEX =
-  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-/**
- * Operational paths that are excluded from execution context enforcement.
- * Also excludes public ingestion endpoints that receive events from
- * external producers (governance-core fanout, etc.) without an
- * Agentics execution context.
- */
-function isOperationalPath(url: string): boolean {
-  const path = url.split('?')[0];
-
-  // Top-level operational endpoints
-  if (
-    path === '/health' ||
-    path === '/ready' ||
-    path === '/metrics'
-  ) {
-    return true;
-  }
-
-  // Swagger documentation
-  if (path.startsWith('/documentation')) return true;
-
-  // Public ingestion endpoints — external producers won't carry span headers
-  if (path.startsWith('/api/v1/events') || path.startsWith('/api/v1/ingest')) {
-    return true;
-  }
-
-  // Agent health and metadata sub-routes (introspection, not execution)
-  if (path.endsWith('/health') || path.endsWith('/metadata')) return true;
-
-  return false;
-}
-
-async function executionContextPlugin(fastify: FastifyInstance) {
-  // Decorate request with executionGraph (null by default)
-  fastify.decorateRequest('executionGraph', null);
-
-  // ── onRequest: extract context, reject if missing ──────────
-
-  fastify.addHook(
-    'onRequest',
-    async (request: FastifyRequest, reply: FastifyReply) => {
-      if (isOperationalPath(request.url)) return;
-
-      const parentSpanId = request.headers[HEADER_PARENT_SPAN_ID] as
-        | string
-        | undefined;
-      const executionId = request.headers[HEADER_EXECUTION_ID] as
-        | string
-        | undefined;
-
-      if (!parentSpanId) {
-        reply.code(400).send({
-          success: false,
-          error: {
-            code: 'MISSING_EXECUTION_CONTEXT',
-            message:
-              'x-parent-span-id header is required for all non-operational requests',
-          },
-        });
-        return;
-      }
-
-      if (!UUID_REGEX.test(parentSpanId)) {
-        reply.code(400).send({
-          success: false,
-          error: {
-            code: 'INVALID_EXECUTION_CONTEXT',
-            message: 'x-parent-span-id must be a valid UUID',
-          },
-        });
-        return;
-      }
-
-      const context: ExecutionContext = {
-        execution_id: executionId && UUID_REGEX.test(executionId)
-          ? executionId
-          : uuidv4(),
-        parent_span_id: parentSpanId,
-      };
-
-      request.executionGraph = new ExecutionGraph(context, 'analytics-hub');
-    },
-  );
-
-  // ── onSend: validate graph and wrap response ───────────────
-
-  fastify.addHook(
-    'onSend',
-    async (
-      request: FastifyRequest,
-      reply: FastifyReply,
-      payload: unknown,
-    ) => {
-      if (!request.executionGraph) return payload;
-
-      const graph = request.executionGraph;
-      graph.finalize(reply.statusCode < 400 ? 'ok' : 'error');
-
-      const validation = graph.validate();
-      if (!validation.valid) {
-        // Invariant violation: no agent spans emitted.
-        // Mark repo span as failed and return 500.
-        graph.finalize('error');
-        reply.code(500);
-        return JSON.stringify({
-          success: false,
-          error: {
-            code: 'EXECUTION_INVARIANT_VIOLATION',
-            message: validation.error,
-          },
-          _execution: graph.toHierarchy(),
-        });
-      }
-
-      // Wrap JSON responses with _execution
-      let parsed: Record<string, unknown> | null = null;
-      try {
-        parsed =
-          typeof payload === 'string' ? JSON.parse(payload) : null;
-      } catch {
-        // Not JSON — attach trace via header
-      }
-
-      if (parsed && typeof parsed === 'object') {
-        return JSON.stringify({
-          ...parsed,
-          _execution: graph.toHierarchy(),
-        });
-      }
-
-      // Non-JSON payload: put trace in header
-      reply.header(
-        'x-execution-trace',
-        JSON.stringify(graph.toHierarchy()),
-      );
-      return payload;
-    },
-  );
-}
-
-export default fp(executionContextPlugin, {
-  name: 'execution-context',
-  fastify: '4.x',
-});

package/dist/bundled-agents/analytics-hub-agents/src/execution/index.ts

@@ -1,18 +0,0 @@
-/**
- * Agentics Execution Span Module
- *
- * Provides execution span instrumentation for the analytics-hub
- * as a Foundational Execution Unit within the Agentics system.
- */
-
-export type {
-  SpanType,
-  SpanStatus,
-  SpanArtifact,
-  ExecutionSpan,
-  ExecutionContext,
-  SpanHierarchy,
-} from './span-types';
-
-export { ExecutionContextSchema } from './span-types';
-export { ExecutionGraph, withDataProcessingSpan } from './execution-graph';

package/dist/bundled-agents/analytics-hub-agents/src/execution/span-types.ts

@@ -1,54 +0,0 @@
-/**
- * Agentics Execution Span Types
- *
- * Defines the span data model for the Agentics execution system.
- * All types are JSON-serializable, append-only, and causally ordered
- * via parent_span_id linkage.
- */
-
-import { z } from 'zod';
-
-// ─── Span Types ────────────────────────────────────────────────
-
-export type SpanType = 'core' | 'repo' | 'agent';
-export type SpanStatus = 'ok' | 'error';
-
-export interface SpanArtifact {
-  artifact_type: string;
-  artifact_id: string;
-  data: unknown;
-  timestamp: string;
-}
-
-export interface ExecutionSpan {
-  span_id: string;
-  parent_span_id: string;
-  trace_id: string;
-  span_type: SpanType;
-  name: string;
-  status: SpanStatus;
-  start_time: string;
-  end_time?: string;
-  attributes: Record<string, unknown>;
-  artifacts: SpanArtifact[];
-}
-
-// ─── Execution Context (from request headers) ──────────────────
-
-export interface ExecutionContext {
-  execution_id: string;
-  parent_span_id: string;
-}
-
-export const ExecutionContextSchema = z.object({
-  execution_id: z.string().uuid(),
-  parent_span_id: z.string().uuid(),
-});
-
-// ─── Output Contract ───────────────────────────────────────────
-
-export interface SpanHierarchy {
-  core_span_id: string;
-  repo_span: ExecutionSpan;
-  agent_spans: ExecutionSpan[];
-}

package/dist/bundled-agents/analytics-hub-agents/src/functions/handler.ts

@@ -1,264 +0,0 @@
-/**
- * Cloud Function Entry Point — analytics-hub-agents
- *
- * Maps the two Analytics Hub agents to Cloud Function routes:
- *   POST /v1/analytics-hub/consensus       → Consensus Agent
- *   POST /v1/analytics-hub/recommendation  → Strategic Recommendation Agent
- *   GET  /v1/analytics-hub/health          → Health check
- *
- * Every response includes execution_metadata and layers_executed.
- * Business logic is delegated entirely to existing agent modules.
- *
- * @module functions/handler
- */
-
-import crypto from 'crypto';
-import { handleConsensusRequest } from '../agents/consensus/handler';
-import { analyze as analyzeRecommendation } from '../agents/strategic-recommendation/agent';
-import type { StrategicRecommendationInput } from '../agents/strategic-recommendation/types';
-import { logger } from '../logger';
-
-// ── Types ──────────────────────────────────────────────────────
-
-interface ExecutionMetadata {
-  trace_id: string;
-  timestamp: string;
-  service: string;
-  execution_id: string;
-}
-
-interface LayerExecuted {
-  layer: string;
-  status: 'completed' | 'error';
-  duration_ms?: number;
-}
-
-/**
- * Cloud Function HTTP request (Express-compatible shape provided by the runtime)
- */
-interface CFRequest {
-  method: string;
-  path: string;
-  url: string;
-  body: any;
-  headers: Record<string, string | string[] | undefined>;
-}
-
-/**
- * Cloud Function HTTP response (Express-compatible shape provided by the runtime)
- */
-interface CFResponse {
-  status(code: number): CFResponse;
-  set(key: string, value: string): CFResponse;
-  json(data: unknown): void;
-  send(data: string): void;
-  end(): void;
-}
-
-// ── Helpers ────────────────────────────────────────────────────
-
-function buildExecutionMetadata(req: CFRequest): ExecutionMetadata {
-  const correlationHeader = req.headers['x-correlation-id'];
-  const traceId = (Array.isArray(correlationHeader) ? correlationHeader[0] : correlationHeader)
-    || crypto.randomUUID();
-
-  return {
-    trace_id: traceId,
-    timestamp: new Date().toISOString(),
-    service: 'analytics-hub-agents',
-    execution_id: crypto.randomUUID(),
-  };
-}
-
-function setCorsHeaders(res: CFResponse): void {
-  res.set('Access-Control-Allow-Origin', '*');
-  res.set('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-  res.set(
-    'Access-Control-Allow-Headers',
-    'Content-Type, Authorization, x-correlation-id, x-parent-span-id, x-execution-id, x-api-key',
-  );
-  res.set('Access-Control-Max-Age', '3600');
-}
-
-function sendJson(
-  res: CFResponse,
-  statusCode: number,
-  body: Record<string, unknown>,
-  meta: ExecutionMetadata,
-  layers: LayerExecuted[],
-): void {
-  res.status(statusCode).json({
-    ...body,
-    execution_metadata: meta,
-    layers_executed: layers,
-  });
-}
-
-// ── Route Handlers ─────────────────────────────────────────────
-
-async function handleHealth(
-  _req: CFRequest,
-  res: CFResponse,
-  meta: ExecutionMetadata,
-): Promise<void> {
-  sendJson(res, 200, {
-    status: 'healthy',
-    agents: ['consensus', 'recommendation'],
-    timestamp: new Date().toISOString(),
-  }, meta, [
-    { layer: 'AGENT_ROUTING', status: 'completed' },
-  ]);
-}
-
-async function handleConsensus(
-  req: CFRequest,
-  res: CFResponse,
-  meta: ExecutionMetadata,
-): Promise<void> {
-  const startTime = Date.now();
-  try {
-    const result = await handleConsensusRequest({
-      body: req.body,
-      headers: req.headers as Record<string, string>,
-    });
-    const responseBody = JSON.parse(result.body);
-    const durationMs = Date.now() - startTime;
-
-    sendJson(res, result.statusCode, responseBody, meta, [
-      { layer: 'AGENT_ROUTING', status: 'completed' },
-      { layer: 'ANALYTICS_HUB_CONSENSUS', status: 'completed', duration_ms: durationMs },
-    ]);
-  } catch (error) {
-    const durationMs = Date.now() - startTime;
-    logger.error({ err: error }, 'Consensus agent execution failed');
-
-    sendJson(res, 500, {
-      success: false,
-      error: { code: 'INTERNAL_ERROR', message: 'Consensus agent execution failed' },
-    }, meta, [
-      { layer: 'AGENT_ROUTING', status: 'completed' },
-      { layer: 'ANALYTICS_HUB_CONSENSUS', status: 'error', duration_ms: durationMs },
-    ]);
-  }
-}
-
-async function handleRecommendation(
-  req: CFRequest,
-  res: CFResponse,
-  meta: ExecutionMetadata,
-): Promise<void> {
-  const startTime = Date.now();
-  try {
-    const body = req.body || {};
-
-    // Build agent input, accepting both snake_case (API) and camelCase (internal) field names.
-    const agentInput = {
-      request_id: body.request_id || meta.execution_id,
-      timeWindow: {
-        startTime: body.start_time || body.timeWindow?.startTime,
-        endTime: body.end_time || body.timeWindow?.endTime,
-      },
-      time_range: {
-        start: body.start_time || body.time_range?.start || body.timeWindow?.startTime,
-        end: body.end_time || body.time_range?.end || body.timeWindow?.endTime,
-      },
-      sourceLayers: body.domains || body.sourceLayers || ['observatory', 'cost-ops', 'governance', 'consensus'],
-      minConfidence: body.min_confidence ?? body.minConfidence ?? 0.5,
-      maxRecommendations: body.max_recommendations ?? body.maxRecommendations ?? 10,
-      focusCategories: body.focus_areas || body.focusCategories,
-      executionRef: meta.execution_id,
-    } as StrategicRecommendationInput;
-
-    if (!agentInput.timeWindow.startTime || !agentInput.timeWindow.endTime) {
-      const durationMs = Date.now() - startTime;
-      sendJson(res, 400, {
-        success: false,
-        error: {
-          code: 'VALIDATION_ERROR',
-          message: 'start_time and end_time are required (or timeWindow.startTime / timeWindow.endTime)',
-        },
-      }, meta, [
-        { layer: 'AGENT_ROUTING', status: 'completed' },
-        { layer: 'ANALYTICS_HUB_RECOMMENDATION', status: 'error', duration_ms: durationMs },
-      ]);
-      return;
-    }
-
-    const { output, event } = await analyzeRecommendation(agentInput);
-    const durationMs = Date.now() - startTime;
-
-    sendJson(res, 200, {
-      ...output,
-      decision_event: event,
-    }, meta, [
-      { layer: 'AGENT_ROUTING', status: 'completed' },
-      { layer: 'ANALYTICS_HUB_RECOMMENDATION', status: 'completed', duration_ms: durationMs },
-    ]);
-  } catch (error) {
-    const durationMs = Date.now() - startTime;
-    logger.error({ err: error }, 'Recommendation agent execution failed');
-
-    sendJson(res, 500, {
-      success: false,
-      error: { code: 'INTERNAL_ERROR', message: 'Recommendation agent execution failed' },
-    }, meta, [
-      { layer: 'AGENT_ROUTING', status: 'completed' },
-      { layer: 'ANALYTICS_HUB_RECOMMENDATION', status: 'error', duration_ms: durationMs },
-    ]);
-  }
-}
-
-// ── Main Entry Point ───────────────────────────────────────────
-
-/**
- * Google Cloud Function HTTP handler.
- *
- * Deploy with:
- *   gcloud functions deploy analytics-hub-agents \
- *     --runtime nodejs20 --trigger-http --region us-central1 \
- *     --project agentics-dev --entry-point handler \
- *     --memory 512MB --timeout 120s --no-allow-unauthenticated
- */
-export async function handler(req: CFRequest, res: CFResponse): Promise<void> {
-  setCorsHeaders(res);
-
-  // CORS preflight
-  if (req.method === 'OPTIONS') {
-    res.status(204).send('');
-    return;
-  }
-
-  const meta = buildExecutionMetadata(req);
-  const path = req.path || req.url;
-
-  // ── Health ──────────────────────────────────────────────────
-  if (path === '/v1/analytics-hub/health' && req.method === 'GET') {
-    return handleHealth(req, res, meta);
-  }
-
-  // ── Consensus Agent ─────────────────────────────────────────
-  if (path === '/v1/analytics-hub/consensus' && req.method === 'POST') {
-    return handleConsensus(req, res, meta);
-  }
-
-  // ── Strategic Recommendation Agent ──────────────────────────
-  if (path === '/v1/analytics-hub/recommendation' && req.method === 'POST') {
-    return handleRecommendation(req, res, meta);
-  }
-
-  // ── 404 ─────────────────────────────────────────────────────
-  sendJson(res, 404, {
-    success: false,
-    error: {
-      code: 'NOT_FOUND',
-      message: `Route not found: ${req.method} ${path}`,
-      available_routes: [
-        'GET  /v1/analytics-hub/health',
-        'POST /v1/analytics-hub/consensus',
-        'POST /v1/analytics-hub/recommendation',
-      ],
-    },
-  }, meta, [
-    { layer: 'AGENT_ROUTING', status: 'error' },
-  ]);
-}