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

package/dist/bundled-agents/shield-agents/functions/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@llm-shield/functions",
+  "version": "1.0.0",
+  "description": "Cloud Function entry point for shield-agents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "node -e \"const{execSync}=require('child_process');execSync('npx esbuild index.ts --outdir=dist --format=esm --platform=node --target=node20',{stdio:'inherit'})\"",
+    "start": "npx functions-framework --target=api --signature-type=http",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@google-cloud/functions-framework": "^3.3.0",
+    "express": "^4.18.2",
+    "@llm-shield/lib": "file:../lib",
+    "@llm-shield/agentics-contracts": "file:../contracts",
+    "@llm-shield/prompt-injection-detection": "file:../prompt-injection-detection",
+    "@llm-shield/pii-detection": "file:../pii-detection",
+    "@llm-shield/data-redaction": "file:../data-redaction",
+    "@llm-shield/secrets-leakage-detection": "file:../secrets-leakage-detection",
+    "@llm-shield/toxicity-detection": "file:../toxicity-detection",
+    "@llm-shield/safety-boundary": "file:../safety-boundary",
+    "@llm-shield/content-moderation": "file:../content-moderation",
+    "@llm-shield/model-abuse-detection": "file:../model-abuse-detection",
+    "@llm-shield/credential-exposure-detection": "file:../credential-exposure-detection"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/dist/bundled-agents/shield-agents/functions/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/dist/bundled-agents/shield-agents/lib/decision-event.ts

@@ -0,0 +1,331 @@
+/**
+ * @module decision-event
+ * @description Standardized DecisionEvent factory for LLM-Shield agents
+ *
+ * Phase 1 / Layer 1 - Foundational Tooling
+ *
+ * CRITICAL RULES:
+ * - Agents MUST emit signals, NOT conclusions
+ * - Every event MUST include: source_agent, domain, phase, layer
+ * - Every event MUST include: event_type, confidence, evidence_refs (if applicable)
+ * - Agents MUST NOT emit summaries, recommendations, or perform synthesis
+ */
+
+import { getAgentIdentity, structuredLog, type AgentIdentityContext } from './startup-validator.js';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * Evidence reference for supporting a detection signal
+ */
+export interface EvidenceRef {
+  /** Type of evidence (pattern_match, heuristic, model_output) */
+  evidence_type: 'pattern_match' | 'heuristic' | 'model_output' | 'rule_based';
+  /** Identifier for the evidence source */
+  source_id: string;
+  /** Position in content (if applicable) */
+  position?: { start: number; end: number };
+  /** Evidence confidence (0-1) */
+  confidence: number;
+}
+
+/**
+ * Standardized DecisionEvent structure
+ *
+ * CRITICAL: This is a SIGNAL, not a conclusion or recommendation
+ */
+export interface DecisionEvent {
+  // === AGENT IDENTITY (MANDATORY) ===
+  /** Source agent identifier */
+  source_agent: string;
+  /** Agent domain */
+  domain: string;
+  /** Deployment phase */
+  phase: string;
+  /** Deployment layer */
+  layer: string;
+
+  // === EVENT METADATA (MANDATORY) ===
+  /** Agent version */
+  agent_version: string;
+  /** Type of event/decision */
+  event_type: string;
+  /** Execution reference (UUID) */
+  execution_ref: string;
+  /** ISO 8601 timestamp */
+  timestamp: string;
+  /** Execution duration in milliseconds */
+  duration_ms: number;
+
+  // === SIGNAL DATA (MANDATORY) ===
+  /** Overall confidence score (0-1) */
+  confidence: number;
+  /** SHA-256 hash of inputs (NEVER raw content) */
+  inputs_hash: string;
+  /** Detection signals (NOT conclusions) */
+  signals: DetectionSignal[];
+  /** Evidence references supporting the signals */
+  evidence_refs: EvidenceRef[];
+
+  // === POLICY CONTEXT ===
+  /** Applied policy references */
+  constraints_applied: PolicyReference[];
+
+  // === TELEMETRY (OPTIONAL) ===
+  /** Non-sensitive telemetry metadata */
+  telemetry?: TelemetryMetadata;
+}
+
+/**
+ * Detection signal - raw observation without synthesis
+ */
+export interface DetectionSignal {
+  /** Signal type identifier */
+  signal_type: string;
+  /** Signal category */
+  category: string;
+  /** Severity level */
+  severity: 'none' | 'low' | 'medium' | 'high' | 'critical';
+  /** Confidence for this specific signal (0-1) */
+  confidence: number;
+  /** Count of occurrences */
+  count: number;
+  /** Evidence IDs supporting this signal */
+  evidence_ids: string[];
+}
+
+/**
+ * Policy reference
+ */
+export interface PolicyReference {
+  policy_id: string;
+  rule_ids?: string[];
+}
+
+/**
+ * Non-sensitive telemetry metadata
+ */
+export interface TelemetryMetadata {
+  content_length?: number;
+  content_source?: string;
+  session_id?: string;
+  caller_id?: string;
+  [key: string]: unknown;
+}
+
+// =============================================================================
+// DECISION EVENT FACTORY
+// =============================================================================
+
+export interface CreateDecisionEventParams {
+  /** Agent version */
+  agentVersion: string;
+  /** Event type (e.g., pii_detection, prompt_injection_detection) */
+  eventType: string;
+  /** Execution reference (UUID) */
+  executionRef: string;
+  /** Timestamp (ISO 8601) */
+  timestamp: string;
+  /** Duration in milliseconds */
+  durationMs: number;
+  /** Overall confidence (0-1) */
+  confidence: number;
+  /** SHA-256 hash of inputs */
+  inputsHash: string;
+  /** Detection signals */
+  signals: DetectionSignal[];
+  /** Evidence references */
+  evidenceRefs: EvidenceRef[];
+  /** Applied constraints/policies */
+  constraintsApplied: PolicyReference[];
+  /** Optional telemetry metadata */
+  telemetry?: TelemetryMetadata;
+}
+
+/**
+ * Create a standardized DecisionEvent
+ *
+ * Automatically injects agent identity from environment
+ */
+export function createDecisionEvent(params: CreateDecisionEventParams): DecisionEvent {
+  let identity: AgentIdentityContext;
+
+  try {
+    identity = getAgentIdentity();
+  } catch {
+    // Fallback for testing or cases where identity isn't initialized
+    identity = {
+      agent_name: process.env.AGENT_NAME || 'unknown',
+      domain: process.env.AGENT_DOMAIN || 'unknown',
+      phase: process.env.AGENT_PHASE || 'unknown',
+      layer: process.env.AGENT_LAYER || 'unknown',
+    };
+  }
+
+  const event: DecisionEvent = {
+    // Agent identity (MANDATORY)
+    source_agent: identity.agent_name,
+    domain: identity.domain,
+    phase: identity.phase,
+    layer: identity.layer,
+
+    // Event metadata
+    agent_version: params.agentVersion,
+    event_type: params.eventType,
+    execution_ref: params.executionRef,
+    timestamp: params.timestamp,
+    duration_ms: params.durationMs,
+
+    // Signal data
+    confidence: params.confidence,
+    inputs_hash: params.inputsHash,
+    signals: params.signals,
+    evidence_refs: params.evidenceRefs,
+
+    // Policy context
+    constraints_applied: params.constraintsApplied,
+
+    // Telemetry
+    ...(params.telemetry && { telemetry: params.telemetry }),
+  };
+
+  return event;
+}
+
+// =============================================================================
+// VALIDATION
+// =============================================================================
+
+/**
+ * Validate a DecisionEvent meets all requirements
+ */
+export function validateDecisionEvent(event: DecisionEvent): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  // Check agent identity fields
+  if (!event.source_agent || event.source_agent === 'unknown') {
+    errors.push('Missing or invalid source_agent');
+  }
+  if (!event.domain || event.domain === 'unknown') {
+    errors.push('Missing or invalid domain');
+  }
+  if (!event.phase || event.phase === 'unknown') {
+    errors.push('Missing or invalid phase');
+  }
+  if (!event.layer || event.layer === 'unknown') {
+    errors.push('Missing or invalid layer');
+  }
+
+  // Check mandatory fields
+  if (!event.event_type) {
+    errors.push('Missing event_type');
+  }
+  if (!event.execution_ref) {
+    errors.push('Missing execution_ref');
+  }
+  if (!event.inputs_hash || !/^[a-f0-9]{64}$/.test(event.inputs_hash)) {
+    errors.push('Invalid or missing inputs_hash (must be SHA-256)');
+  }
+
+  // Check confidence is valid
+  if (typeof event.confidence !== 'number' || event.confidence < 0 || event.confidence > 1) {
+    errors.push('Invalid confidence (must be 0-1)');
+  }
+
+  // Check signals array
+  if (!Array.isArray(event.signals)) {
+    errors.push('Missing signals array');
+  }
+
+  // Check evidence_refs array
+  if (!Array.isArray(event.evidence_refs)) {
+    errors.push('Missing evidence_refs array');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// =============================================================================
+// EVENT EMISSION HELPER
+// =============================================================================
+
+/**
+ * Emit a DecisionEvent and log the emission
+ */
+export function emitDecisionEvent(event: DecisionEvent): void {
+  // Validate event
+  const validation = validateDecisionEvent(event);
+  if (!validation.valid) {
+    throw new Error(`Invalid DecisionEvent: ${validation.errors.join(', ')}`);
+  }
+
+  // Log emission
+  try {
+    const identity = getAgentIdentity();
+    structuredLog('decision_event_emitted', `Emitted ${event.event_type} event`, identity, {
+      execution_ref: event.execution_ref,
+      event_type: event.event_type,
+      confidence: event.confidence,
+      signal_count: event.signals.length,
+      evidence_count: event.evidence_refs.length,
+    });
+  } catch {
+    // Log without identity if not initialized
+    console.log(JSON.stringify({
+      level: 'decision_event_emitted',
+      timestamp: new Date().toISOString(),
+      message: `Emitted ${event.event_type} event`,
+      execution_ref: event.execution_ref,
+      event_type: event.event_type,
+      confidence: event.confidence,
+    }));
+  }
+}
+
+// =============================================================================
+// CONTRACT ASSERTIONS
+// =============================================================================
+
+let _decisionEventCount = 0;
+
+/**
+ * Reset decision event counter (call at start of each run)
+ */
+export function resetDecisionEventCounter(): void {
+  _decisionEventCount = 0;
+}
+
+/**
+ * Increment decision event counter (call when event is emitted)
+ */
+export function incrementDecisionEventCounter(): void {
+  _decisionEventCount++;
+}
+
+/**
+ * Assert at least one DecisionEvent was emitted
+ * Call this at the end of each agent run
+ */
+export function assertDecisionEventEmitted(executionRef: string): void {
+  if (_decisionEventCount === 0) {
+    const error = new Error(`Contract violation: No DecisionEvent emitted for execution ${executionRef}`);
+
+    try {
+      const identity = getAgentIdentity();
+      structuredLog('agent_abort', 'Contract violation: No DecisionEvent emitted', identity, {
+        execution_ref: executionRef,
+      });
+    } catch {
+      console.error(JSON.stringify({
+        level: 'agent_abort',
+        timestamp: new Date().toISOString(),
+        message: 'Contract violation: No DecisionEvent emitted',
+        execution_ref: executionRef,
+      }));
+    }
+
+    throw error;
+  }
+}

package/dist/bundled-agents/shield-agents/lib/execution-span.ts

@@ -0,0 +1,290 @@
+/**
+ * @module execution-span
+ * @description Execution span management for the Agentics Foundational Execution Unit
+ *
+ * This module implements the span lifecycle for LLM-Shield's participation
+ * in the Agentics hierarchical ExecutionGraph.
+ *
+ * Invariant: Core -> Repo (llm-shield) -> Agent (one or more)
+ *
+ * RULES:
+ * - Every external invocation MUST provide execution_id and parent_span_id
+ * - A repo-level span MUST be created on entry
+ * - An agent-level span MUST be created for every agent that executes
+ * - Artifacts MUST be attached to agent-level spans, never directly to Core
+ * - Execution is INVALID if no agent-level spans exist
+ * - All spans are append-only and causally ordered via parent_span_id
+ */
+
+import { randomUUID } from 'crypto';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/** Span type discriminator within the Agentics hierarchy */
+export type SpanType = 'core' | 'repo' | 'agent';
+
+/** Status of span execution */
+export type SpanStatus = 'running' | 'completed' | 'error';
+
+/** An artifact or evidence attached to a span */
+export interface SpanArtifact {
+  /** Stable reference identifier */
+  artifact_id: string;
+  /** Classification of the artifact */
+  artifact_type: 'detection_signal' | 'evidence_ref' | 'decision_event' | 'metric';
+  /** Machine-verifiable data payload */
+  data: Record<string, unknown>;
+  /** ISO 8601 timestamp of when the artifact was produced */
+  timestamp: string;
+}
+
+/** Execution context passed inward from the Agentics Core */
+export interface ExecutionContext {
+  /** UUID identifying the full execution tree */
+  execution_id: string;
+  /** Span ID of the parent (from the Core) - REQUIRED for all external calls */
+  parent_span_id: string;
+}
+
+/** A single execution span in the hierarchy */
+export interface ExecutionSpan {
+  /** Unique identifier for this span */
+  span_id: string;
+  /** Position in the hierarchy */
+  span_type: SpanType;
+  /** ID of the parent span (establishes causal ordering) */
+  parent_span_id: string;
+  /** ID of the execution tree this span belongs to */
+  execution_id: string;
+  /** Human-readable name */
+  name: string;
+  /** Type-specific attributes (repo_name, agent_name, agent_key, etc.) */
+  attributes: Record<string, string>;
+  /** ISO 8601 start timestamp */
+  start_time: string;
+  /** ISO 8601 end timestamp (null if still running) */
+  end_time: string | null;
+  /** Current status */
+  status: SpanStatus;
+  /** Duration in milliseconds (null if still running) */
+  duration_ms: number | null;
+  /** Artifacts and evidence attached to this span */
+  artifacts: SpanArtifact[];
+  /** Child spans (agent spans nested under repo span) */
+  children: ExecutionSpan[];
+}
+
+/** The complete execution output envelope */
+export interface ExecutionOutput {
+  /** Execution tree identifier */
+  execution_id: string;
+  /** Root repo-level span with nested agent spans */
+  repo_span: ExecutionSpan;
+}
+
+// =============================================================================
+// VALIDATION
+// =============================================================================
+
+/**
+ * Validate that an incoming execution context has the required fields.
+ * Throws if execution_id or parent_span_id is missing or empty.
+ */
+export function validateExecutionContext(ctx: unknown): ExecutionContext {
+  if (!ctx || typeof ctx !== 'object') {
+    throw new Error('Execution context is required: parent_span_id is missing');
+  }
+
+  const obj = ctx as Record<string, unknown>;
+
+  const execution_id = typeof obj.execution_id === 'string' ? obj.execution_id.trim() : '';
+  const parent_span_id = typeof obj.parent_span_id === 'string' ? obj.parent_span_id.trim() : '';
+
+  if (!execution_id) {
+    throw new Error('Execution context is required: execution_id is missing or empty');
+  }
+
+  if (!parent_span_id) {
+    throw new Error('Execution context is required: parent_span_id is missing or empty');
+  }
+
+  return { execution_id, parent_span_id };
+}
+
+// =============================================================================
+// SPAN LIFECYCLE
+// =============================================================================
+
+/**
+ * Create the repo-level execution span.
+ * This is the first span created on entry to this repository.
+ */
+export function createRepoSpan(ctx: ExecutionContext): ExecutionSpan {
+  return {
+    span_id: randomUUID(),
+    span_type: 'repo',
+    parent_span_id: ctx.parent_span_id,
+    execution_id: ctx.execution_id,
+    name: 'llm-shield',
+    attributes: { repo_name: 'llm-shield' },
+    start_time: new Date().toISOString(),
+    end_time: null,
+    status: 'running',
+    duration_ms: null,
+    artifacts: [],
+    children: [],
+  };
+}
+
+/**
+ * Create an agent-level execution span as a child of the repo span.
+ * Each agent that executes logic MUST have its own span.
+ */
+export function createAgentSpan(
+  repoSpan: ExecutionSpan,
+  agentName: string,
+  agentKey: string,
+): ExecutionSpan {
+  const span: ExecutionSpan = {
+    span_id: randomUUID(),
+    span_type: 'agent',
+    parent_span_id: repoSpan.span_id,
+    execution_id: repoSpan.execution_id,
+    name: agentName,
+    attributes: {
+      agent_name: agentName,
+      agent_key: agentKey,
+      repo_name: 'llm-shield',
+    },
+    start_time: new Date().toISOString(),
+    end_time: null,
+    status: 'running',
+    duration_ms: null,
+    artifacts: [],
+    children: [],
+  };
+
+  repoSpan.children.push(span);
+  return span;
+}
+
+/**
+ * Attach a machine-verifiable artifact to a span.
+ * Artifacts MUST be attached to agent-level spans, not the Core span.
+ */
+export function attachArtifact(
+  span: ExecutionSpan,
+  artifactType: SpanArtifact['artifact_type'],
+  data: Record<string, unknown>,
+): void {
+  span.artifacts.push({
+    artifact_id: randomUUID(),
+    artifact_type: artifactType,
+    data,
+    timestamp: new Date().toISOString(),
+  });
+}
+
+/**
+ * Mark a span as successfully completed.
+ */
+export function completeSpan(span: ExecutionSpan): void {
+  const endTime = new Date();
+  span.end_time = endTime.toISOString();
+  span.status = 'completed';
+  span.duration_ms = endTime.getTime() - new Date(span.start_time).getTime();
+}
+
+/**
+ * Mark a span as failed with an explicit reason.
+ * Failed spans still appear in the output -- execution is never silent.
+ */
+export function failSpan(span: ExecutionSpan, error: string): void {
+  const endTime = new Date();
+  span.end_time = endTime.toISOString();
+  span.status = 'error';
+  span.duration_ms = endTime.getTime() - new Date(span.start_time).getTime();
+  span.artifacts.push({
+    artifact_id: randomUUID(),
+    artifact_type: 'metric',
+    data: { error_reason: error },
+    timestamp: endTime.toISOString(),
+  });
+}
+
+/**
+ * Finalize the repo span and produce the execution output.
+ *
+ * INVARIANT: Throws if no agent-level spans exist.
+ * If no agent span exists, execution is INVALID.
+ */
+export function finalizeRepoSpan(repoSpan: ExecutionSpan): ExecutionOutput {
+  if (repoSpan.children.length === 0) {
+    throw new Error(
+      'Execution invariant violated: no agent-level spans were emitted. '
+      + 'This repository MUST NOT return a successful result without agent spans.',
+    );
+  }
+
+  if (repoSpan.status === 'running') {
+    completeSpan(repoSpan);
+  }
+
+  return {
+    execution_id: repoSpan.execution_id,
+    repo_span: repoSpan,
+  };
+}
+
+/**
+ * Validate that a finalized execution output meets all invariants.
+ *
+ * Checks:
+ * - repo_span exists and has type 'repo'
+ * - At least one child span exists
+ * - All children have type 'agent'
+ * - All spans are JSON-serializable
+ */
+export function validateExecutionOutput(output: ExecutionOutput): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  if (!output.execution_id) {
+    errors.push('Missing execution_id');
+  }
+
+  if (!output.repo_span) {
+    errors.push('Missing repo_span');
+    return { valid: false, errors };
+  }
+
+  if (output.repo_span.span_type !== 'repo') {
+    errors.push(`repo_span has wrong type: ${output.repo_span.span_type} (expected: repo)`);
+  }
+
+  if (output.repo_span.children.length === 0) {
+    errors.push('repo_span has no agent children -- execution is INVALID');
+  }
+
+  for (const child of output.repo_span.children) {
+    if (child.span_type !== 'agent') {
+      errors.push(`Child span "${child.name}" has wrong type: ${child.span_type} (expected: agent)`);
+    }
+    if (child.parent_span_id !== output.repo_span.span_id) {
+      errors.push(`Child span "${child.name}" has wrong parent_span_id`);
+    }
+    if (child.execution_id !== output.execution_id) {
+      errors.push(`Child span "${child.name}" has wrong execution_id`);
+    }
+  }
+
+  // Verify JSON-serializability
+  try {
+    JSON.stringify(output);
+  } catch {
+    errors.push('Output is not JSON-serializable');
+  }
+
+  return { valid: errors.length === 0, errors };
+}