@a5c-ai/kradle 5.0.1-staging.3abdf9534c25

package/src/agent-provider-config-controller.js

@@ -0,0 +1,151 @@
+// Agent Provider Config Controller — Slice 1.2c
+// Manages AgentProviderConfig resources: model provider config validation,
+// endpoint resolution, credential ref validation, and feature flag management.
+
+export const AGENT_PROVIDER_CONFIG_CONTROLLER_BOUNDARY = {
+  role: 'agent-provider-config-controller',
+  scope: 'AgentProviderConfig lifecycle: validation, endpoint resolution, credential ref validation, feature flags',
+  owns: ['provider config validation', 'endpoint resolution', 'credential ref validation', 'feature flag defaults', 'rate limit defaults'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['secret values', 'dispatch execution', 'Agent Mux sessions', 'adapter implementation']
+};
+
+const VALID_PROVIDER_TYPES = ['anthropic', 'openai', 'azure-openai', 'google-vertex', 'foundry', 'custom', 'kserve'];
+
+const DEFAULT_ENDPOINTS = Object.freeze({
+  anthropic: 'https://api.anthropic.com/v1',
+  openai: 'https://api.openai.com/v1',
+  'azure-openai': null,   // requires explicit endpoint (tenant-specific)
+  'google-vertex': 'https://us-central1-aiplatform.googleapis.com/v1',
+  foundry: null,          // requires explicit endpoint
+  custom: null,           // requires explicit endpoint
+  kserve: null            // requires explicit endpoint from InferenceService discovery
+});
+
+const DEFAULT_FEATURE_FLAGS = Object.freeze({
+  streaming: true,
+  tool_use: true,
+  vision: false
+});
+
+const DEFAULT_RATE_LIMITS = Object.freeze({
+  requestsPerMinute: 60,
+  tokensPerMinute: 100000
+});
+
+/**
+ * Validate an AgentProviderConfig resource. Returns { valid, errors }.
+ * @param {object} resource
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateAgentProviderConfig(resource) {
+  const errors = [];
+
+  // Guard against null/undefined resource
+  if (resource == null) {
+    errors.push('resource must not be null or undefined');
+    return { valid: false, errors };
+  }
+
+  // Validate metadata.name
+  if (!resource?.metadata?.name) {
+    errors.push('metadata.name is required');
+  }
+
+  const spec = resource?.spec || {};
+
+  // Validate providerType
+  const providerType = spec.providerType;
+  if (!providerType) {
+    errors.push(`spec.providerType is required; valid types are: ${VALID_PROVIDER_TYPES.join(', ')}`);
+  } else if (!VALID_PROVIDER_TYPES.includes(providerType)) {
+    errors.push(`spec.providerType "${providerType}" is not supported; valid types are: ${VALID_PROVIDER_TYPES.join(', ')}`);
+  }
+
+  // Validate credentialRef — always required for security
+  if (!spec.credentialRef) {
+    errors.push('spec.credentialRef is required; provide a Kubernetes Secret name for the API key');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Factory that returns an AgentProviderConfig controller instance.
+ */
+export function createAgentProviderConfigController() {
+  return {
+    role: 'agent-provider-config-controller',
+
+    /**
+     * Validate an AgentProviderConfig resource.
+     * @param {object} resource
+     * @returns {{ valid: boolean, errors: string[] }}
+     */
+    validate(resource) {
+      return validateAgentProviderConfig(resource);
+    },
+
+    /**
+     * Resolve the effective API endpoint for a provider config.
+     * Returns the explicit spec.endpoint if set, otherwise falls back to
+     * the well-known default for the provider type.
+     * @param {object} resource
+     * @returns {string|null}
+     */
+    resolveEndpoint(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const spec = resource?.spec || {};
+
+      // If an explicit endpoint is set in spec, prefer it
+      if (spec.endpoint) {
+        return spec.endpoint;
+      }
+
+      // Fall back to the known default for the provider type
+      const providerType = spec.providerType;
+      return DEFAULT_ENDPOINTS[providerType] ?? null;
+    },
+
+    /**
+     * Return the effective feature flags for a provider config.
+     * Merges spec.featureFlags with defaults; spec values take precedence.
+     * @param {object} resource
+     * @returns {{ streaming: boolean, tool_use: boolean, vision: boolean, [key: string]: boolean }}
+     */
+    getFeatureFlags(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const specFlags = resource?.spec?.featureFlags ?? {};
+      return { ...DEFAULT_FEATURE_FLAGS, ...specFlags };
+    },
+
+    /**
+     * Return the effective rate limit configuration for a provider config.
+     * Merges spec.rateLimits with defaults; spec values take precedence.
+     * @param {object} resource
+     * @returns {{ requestsPerMinute: number, tokensPerMinute: number }}
+     */
+    getRateLimits(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const specLimits = resource?.spec?.rateLimits ?? {};
+      return {
+        requestsPerMinute: specLimits.requestsPerMinute ?? DEFAULT_RATE_LIMITS.requestsPerMinute,
+        tokensPerMinute: specLimits.tokensPerMinute ?? DEFAULT_RATE_LIMITS.tokensPerMinute
+      };
+    },
+
+    /**
+     * Return the list of supported provider types.
+     * @returns {string[]}
+     */
+    getSupportedProviderTypes() {
+      return [...VALID_PROVIDER_TYPES];
+    }
+  };
+}

package/src/agent-secret-config-grant-controller.js

@@ -0,0 +1,282 @@
+// Agent Secret/Config Grant Controller — Secret & ConfigMap grant lifecycle
+//
+// Provides:
+//   - createAgentSecretGrantController() — validates AgentSecretGrant resources
+//   - createAgentConfigGrantController() — validates AgentConfigGrant resources
+//   - listGrantsForAgent(agentRef) — filter grants by target agent
+//   - revokeGrant(grantName) — mark a grant as revoked
+
+import { createResource, clone } from './resource-model.js';
+
+export const AGENT_SECRET_GRANT_CONTROLLER_BOUNDARY = {
+  role: 'agent-secret-grant-controller',
+  scope: 'AgentSecretGrant lifecycle — creation, listing, revocation for agent-to-secret access grants',
+  owns: ['grant creation', 'grant listing', 'grant revocation', 'input validation'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['Kubernetes Secret storage', 'agent execution', 'secret value decryption', 'UI rendering']
+};
+
+export const AGENT_CONFIG_GRANT_CONTROLLER_BOUNDARY = {
+  role: 'agent-config-grant-controller',
+  scope: 'AgentConfigGrant lifecycle — creation, listing, revocation for agent-to-configmap access grants',
+  owns: ['grant creation', 'grant listing', 'grant revocation', 'input validation'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['Kubernetes ConfigMap storage', 'agent execution', 'UI rendering']
+};
+
+const VALID_PERMISSIONS = new Set(['read', 'use', 'mount']);
+
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate an AgentSecretGrant input.
+ *
+ * @param {object} input
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateAgentSecretGrant(input) {
+  const errors = [];
+  if (!input) return { valid: false, errors: ['input must not be null or undefined'] };
+  if (!input.name || typeof input.name !== 'string') errors.push('name is required and must be a non-empty string');
+  if (!input.orgRef || typeof input.orgRef !== 'string') errors.push('orgRef is required and must be a non-empty string');
+  if (!input.secretName || typeof input.secretName !== 'string') errors.push('secretName is required and must be a non-empty string');
+  if (!input.grantedTo || typeof input.grantedTo !== 'string') errors.push('grantedTo is required and must be a non-empty string');
+  if (!Array.isArray(input.permissions) || input.permissions.length === 0) {
+    errors.push('permissions is required and must be a non-empty array');
+  } else {
+    const invalid = input.permissions.filter((p) => !VALID_PERMISSIONS.has(p));
+    if (invalid.length > 0) errors.push(`invalid permissions: ${invalid.join(', ')}. Valid values: ${[...VALID_PERMISSIONS].join(', ')}`);
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate an AgentConfigGrant input.
+ *
+ * @param {object} input
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateAgentConfigGrant(input) {
+  const errors = [];
+  if (!input) return { valid: false, errors: ['input must not be null or undefined'] };
+  if (!input.name || typeof input.name !== 'string') errors.push('name is required and must be a non-empty string');
+  if (!input.orgRef || typeof input.orgRef !== 'string') errors.push('orgRef is required and must be a non-empty string');
+  if (!input.configMapName || typeof input.configMapName !== 'string') errors.push('configMapName is required and must be a non-empty string');
+  if (!input.grantedTo || typeof input.grantedTo !== 'string') errors.push('grantedTo is required and must be a non-empty string');
+  return { valid: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// listGrantsForAgent — shared utility
+// ---------------------------------------------------------------------------
+
+/**
+ * Filter grants by the grantedTo (agent ref) field from a collection of grant resources.
+ *
+ * @param {object[]} grants  Array of AgentSecretGrant or AgentConfigGrant resources
+ * @param {string}   agentRef  The agent identifier to filter by
+ * @returns {object[]}
+ */
+export function listGrantsForAgent(grants, agentRef) {
+  if (!agentRef) return [];
+  return grants.filter((g) => g.spec?.grantedTo === agentRef || g.spec?.subject === agentRef);
+}
+
+// ---------------------------------------------------------------------------
+// revokeGrant — shared utility
+// ---------------------------------------------------------------------------
+
+/**
+ * Mark a grant as revoked by returning an updated copy of the resource.
+ *
+ * @param {object[]} grants  Array of grant resources
+ * @param {string}   grantName  Name of the grant to revoke
+ * @returns {{ grant: object } | { error: true, reason: string, message: string }}
+ */
+export function revokeGrant(grants, grantName) {
+  if (!grantName) return { error: true, reason: 'missing-name', message: 'grantName is required' };
+
+  const found = grants.find((g) => g.metadata?.name === grantName);
+  if (!found) return { error: true, reason: 'not-found', message: `Grant not found: ${grantName}` };
+
+  if (found.status?.phase === 'Revoked') {
+    return { error: true, reason: 'already-revoked', message: `Grant "${grantName}" is already revoked` };
+  }
+
+  const updated = clone(found);
+  updated.status = {
+    ...updated.status,
+    phase: 'Revoked',
+    revokedAt: new Date().toISOString()
+  };
+
+  return { grant: updated };
+}
+
+// ---------------------------------------------------------------------------
+// createAgentSecretGrantController
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a controller for AgentSecretGrant resources.
+ *
+ * @param {{ persistFn?: (resource: object) => Promise<any> }} [opts]
+ * @returns {object}
+ */
+export function createAgentSecretGrantController({ persistFn } = {}) {
+  function persist(resource) {
+    if (typeof persistFn === 'function') {
+      Promise.resolve(persistFn(resource)).catch(() => {});
+    }
+  }
+
+  return {
+    role: 'agent-secret-grant-controller',
+
+    /**
+     * Create an AgentSecretGrant resource.
+     *
+     * @param {{ name, orgRef, secretName, grantedTo, permissions, namespace?, keys? }} input
+     * @returns {{ grant: object } | { error: true, message: string }}
+     */
+    createSecretGrant({
+      name,
+      orgRef,
+      secretName,
+      grantedTo,
+      permissions = ['read'],
+      namespace = 'default',
+      keys = []
+    }) {
+      const validation = validateAgentSecretGrant({ name, orgRef, secretName, grantedTo, permissions });
+      if (!validation.valid) {
+        return { error: true, message: validation.errors.join('; ') };
+      }
+
+      const now = new Date().toISOString();
+      const grant = createResource('AgentSecretGrant', { name, namespace }, {
+        organizationRef: orgRef,
+        orgRef,
+        secretName,
+        secretRef: secretName,
+        grantedTo,
+        subject: grantedTo,
+        permissions,
+        keys,
+        purpose: permissions.join(',')
+      });
+      grant.status = { phase: 'Active', createdAt: now };
+
+      persist(grant);
+      return { grant };
+    },
+
+    /**
+     * List all grants for a specific agent.
+     *
+     * @param {string}   agentRef
+     * @param {object[]} grants
+     * @returns {object[]}
+     */
+    listGrantsForAgent(agentRef, grants = []) {
+      return listGrantsForAgent(grants, agentRef);
+    },
+
+    /**
+     * Revoke a grant by name.
+     *
+     * @param {string}   grantName
+     * @param {object[]} grants
+     * @returns {{ grant: object } | { error: true, reason: string, message: string }}
+     */
+    revokeGrant(grantName, grants = []) {
+      const result = revokeGrant(grants, grantName);
+      if (!result.error && result.grant) persist(result.grant);
+      return result;
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// createAgentConfigGrantController
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a controller for AgentConfigGrant resources.
+ *
+ * @param {{ persistFn?: (resource: object) => Promise<any> }} [opts]
+ * @returns {object}
+ */
+export function createAgentConfigGrantController({ persistFn } = {}) {
+  function persist(resource) {
+    if (typeof persistFn === 'function') {
+      Promise.resolve(persistFn(resource)).catch(() => {});
+    }
+  }
+
+  return {
+    role: 'agent-config-grant-controller',
+
+    /**
+     * Create an AgentConfigGrant resource.
+     *
+     * @param {{ name, orgRef, configMapName, grantedTo, namespace?, keys? }} input
+     * @returns {{ grant: object } | { error: true, message: string }}
+     */
+    createConfigGrant({
+      name,
+      orgRef,
+      configMapName,
+      grantedTo,
+      namespace = 'default',
+      keys = []
+    }) {
+      const validation = validateAgentConfigGrant({ name, orgRef, configMapName, grantedTo });
+      if (!validation.valid) {
+        return { error: true, message: validation.errors.join('; ') };
+      }
+
+      const now = new Date().toISOString();
+      const grant = createResource('AgentConfigGrant', { name, namespace }, {
+        organizationRef: orgRef,
+        orgRef,
+        configMapName,
+        configMapRef: configMapName,
+        grantedTo,
+        subject: grantedTo,
+        keys,
+        purpose: 'read'
+      });
+      grant.status = { phase: 'Active', createdAt: now };
+
+      persist(grant);
+      return { grant };
+    },
+
+    /**
+     * List all grants for a specific agent.
+     *
+     * @param {string}   agentRef
+     * @param {object[]} grants
+     * @returns {object[]}
+     */
+    listGrantsForAgent(agentRef, grants = []) {
+      return listGrantsForAgent(grants, agentRef);
+    },
+
+    /**
+     * Revoke a grant by name.
+     *
+     * @param {string}   grantName
+     * @param {object[]} grants
+     * @returns {{ grant: object } | { error: true, reason: string, message: string }}
+     */
+    revokeGrant(grantName, grants = []) {
+      const result = revokeGrant(grants, grantName);
+      if (!result.error && result.grant) persist(result.grant);
+      return result;
+    }
+  };
+}

package/src/agent-session-transcript-controller.js

@@ -0,0 +1,189 @@
+// Agent Session Transcript Controller — Slice 1.2e
+// Manages AgentSessionTranscript resources: durable transcript storage,
+// message indexing, and pagination support.
+
+export const AGENT_SESSION_TRANSCRIPT_CONTROLLER_BOUNDARY = {
+  role: 'agent-session-transcript-controller',
+  scope: 'AgentSessionTranscript lifecycle: validation, message indexing, pagination, role/tool filtering',
+  owns: ['transcript validation', 'message indexing', 'pagination', 'role filter', 'tool name filter'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['session lifecycle', 'dispatch execution', 'Agent Mux sessions', 'secret values']
+};
+
+const VALID_ROLES = ['user', 'assistant', 'tool', 'system'];
+
+/**
+ * Validate an AgentSessionTranscript resource. Returns { valid, errors }.
+ * @param {object} resource
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateAgentSessionTranscript(resource) {
+  const errors = [];
+
+  // Guard against null/undefined resource
+  if (resource == null) {
+    errors.push('resource must not be null or undefined');
+    return { valid: false, errors };
+  }
+
+  // Validate metadata.name
+  if (!resource?.metadata?.name) {
+    errors.push('metadata.name is required');
+  }
+
+  const spec = resource?.spec || {};
+
+  // Validate organizationRef
+  if (!spec.organizationRef) {
+    errors.push('spec.organizationRef is required');
+  }
+
+  // Validate sessionRef
+  if (!spec.sessionRef) {
+    errors.push('spec.sessionRef is required; provide the AgentSession ID this transcript is linked to');
+  }
+
+  // Validate messages — must be an array (can be empty for a new transcript)
+  const messages = spec.messages;
+  if (!Array.isArray(messages)) {
+    errors.push('spec.messages must be an array');
+  } else {
+    // Validate each message shape
+    for (let i = 0; i < messages.length; i++) {
+      const msg = messages[i];
+      if (msg == null || typeof msg !== 'object') {
+        errors.push(`spec.messages[${i}] must be an object`);
+        continue;
+      }
+      if (!msg.role) {
+        errors.push(`spec.messages[${i}].role is required`);
+      } else if (!VALID_ROLES.includes(msg.role)) {
+        errors.push(`spec.messages[${i}].role "${msg.role}" is not valid; valid roles are: ${VALID_ROLES.join(', ')}`);
+      }
+      if (msg.content == null) {
+        errors.push(`spec.messages[${i}].content is required`);
+      }
+    }
+  }
+
+  // Validate pageSize if explicitly set
+  const pageSize = spec.pageSize;
+  if (pageSize != null && (!Number.isInteger(pageSize) || pageSize < 1)) {
+    errors.push('spec.pageSize must be a positive integer when specified');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Factory that returns an AgentSessionTranscript controller instance.
+ */
+export function createAgentSessionTranscriptController() {
+  return {
+    role: 'agent-session-transcript-controller',
+
+    /**
+     * Validate an AgentSessionTranscript resource.
+     * @param {object} resource
+     * @returns {{ valid: boolean, errors: string[] }}
+     */
+    validate(resource) {
+      return validateAgentSessionTranscript(resource);
+    },
+
+    /**
+     * Return all messages in the transcript, in order.
+     * @param {object} resource
+     * @returns {Array<{ role: string, content: string, timestamp?: string, toolCalls?: object[] }>}
+     */
+    getMessages(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const messages = resource?.spec?.messages;
+      if (!Array.isArray(messages)) {
+        return [];
+      }
+      return [...messages];
+    },
+
+    /**
+     * Return the total number of messages in the transcript.
+     * @param {object} resource
+     * @returns {number}
+     */
+    getTotalMessages(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const messages = resource?.spec?.messages;
+      return Array.isArray(messages) ? messages.length : 0;
+    },
+
+    /**
+     * Return a page of messages from the transcript.
+     * @param {object} resource
+     * @param {number} pageIndex - zero-based page index
+     * @param {number} [pageSizeOverride] - override spec.pageSize (defaults to spec.pageSize or 20)
+     * @returns {{ messages: object[], pageIndex: number, pageSize: number, totalMessages: number, totalPages: number }}
+     */
+    getPage(resource, pageIndex, pageSizeOverride) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const messages = Array.isArray(resource?.spec?.messages) ? resource.spec.messages : [];
+      const pageSize = pageSizeOverride ?? resource?.spec?.pageSize ?? 20;
+      const totalMessages = messages.length;
+      const totalPages = Math.max(1, Math.ceil(totalMessages / pageSize));
+      const safePageIndex = Math.max(0, Math.min(pageIndex, totalPages - 1));
+      const start = safePageIndex * pageSize;
+      const end = start + pageSize;
+      return {
+        messages: messages.slice(start, end),
+        pageIndex: safePageIndex,
+        pageSize,
+        totalMessages,
+        totalPages
+      };
+    },
+
+    /**
+     * Return all messages filtered by role.
+     * @param {object} resource
+     * @param {string} role - one of: user, assistant, tool, system
+     * @returns {Array<object>}
+     */
+    getMessagesByRole(resource, role) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const messages = Array.isArray(resource?.spec?.messages) ? resource.spec.messages : [];
+      return messages.filter((m) => m.role === role);
+    },
+
+    /**
+     * Return all messages that contain a tool call with the given tool name.
+     * @param {object} resource
+     * @param {string} toolName
+     * @returns {Array<object>}
+     */
+    getMessagesByToolName(resource, toolName) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const messages = Array.isArray(resource?.spec?.messages) ? resource.spec.messages : [];
+      return messages.filter((m) => {
+        if (!Array.isArray(m.toolCalls)) return false;
+        return m.toolCalls.some((tc) => tc.name === toolName);
+      });
+    },
+
+    /**
+     * Return the list of valid message roles.
+     * @returns {string[]}
+     */
+    getValidRoles() {
+      return [...VALID_ROLES];
+    }
+  };
+}