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

package/src/agent-stack-controller.js

@@ -0,0 +1,421 @@
+import { createPermissionReviewer } from './agent-permission-review.js';
+import { clone } from './resource-model.js';
+
+export const AGENT_STACK_CONTROLLER_BOUNDARY = {
+  role: 'agent-stack-controller',
+  scope: 'Stack readiness reconciliation with capability resolution and condition management',
+  owns: ['capability resolution', 'stack conditions', 'readiness computation', 'mcp health checks'],
+  delegatesTo: ['agent-permission-review', 'resource-model'],
+  mustNotOwn: ['secret values', 'dispatch execution', 'Agent Mux sessions']
+};
+
+const MCP_HEALTH_TIMEOUT_MS = 3000;
+const JITSI_ROLES = new Set(['observer', 'participant', 'moderator']);
+const JITSI_TOOLS = new Set([
+  'kradle_send_chat_message',
+  'kradle_get_meeting_transcript',
+  'kradle_get_participant_list',
+  'kradle_raise_hand',
+  'kradle_share_screen',
+  'kradle_invite_to_meeting',
+  'kradle_start_recording',
+  'kradle_react',
+]);
+
+/**
+ * Perform an HTTP health check for an MCP server endpoint.
+ * @param {string} url
+ * @param {Function|null} fetchFn
+ * @returns {Promise<{ status: string, latencyMs: number, error?: string }>}
+ */
+async function performMcpHealthCheck(url, fetchFn) {
+  const fn = fetchFn || globalThis.fetch;
+  const start = Date.now();
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), MCP_HEALTH_TIMEOUT_MS);
+    let response;
+    try {
+      response = await fn(url, { signal: controller.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+    const latencyMs = Date.now() - start;
+    if (response.ok) {
+      return { status: 'healthy', latencyMs };
+    }
+    return { status: 'unhealthy', latencyMs, error: `HTTP ${response.status}` };
+  } catch (err) {
+    const latencyMs = Date.now() - start;
+    return { status: 'unhealthy', latencyMs, error: err.message || String(err) };
+  }
+}
+
+export function createAgentStackController(options = {}) {
+  const permissionReviewer = options.permissionReviewer || createPermissionReviewer();
+  const fetchFn = options.fetch || null;
+
+  return {
+    role: 'agent-stack-controller',
+
+    reconcileStack(stack, resources = {}) {
+      const spec = stack?.spec || {};
+      const conditions = [];
+      const missing = [];
+
+      // --- Resolve capability refs from stack spec ---
+      const resolvedTools = [];
+      const resolvedMcpServers = [];
+      const resolvedSkills = [];
+      const resolvedSubagents = [];
+      const resolvedContextLabels = [];
+
+      // toolPolicyRef
+      const toolPolicyRef = spec.toolPolicy || spec.toolPolicyRef || null;
+      let toolPolicyFound = true;
+      if (toolPolicyRef) {
+        const profiles = resources.AgentToolProfile || [];
+        const profile = profiles.find((p) => p.metadata?.name === toolPolicyRef);
+        if (profile) {
+          resolvedTools.push(profile.metadata.name);
+        } else {
+          toolPolicyFound = false;
+          missing.push(`AgentToolProfile/${toolPolicyRef}`);
+        }
+      }
+
+      // mcpServerRefs — support both flat spec.mcpServerRefs and structured spec.externalTools.mcpServerRefs
+      const mcpServerRefs = [
+        ...(spec.mcpServerRefs || []),
+        ...(spec.externalTools?.mcpServerRefs || [])
+      ].filter((v, i, a) => a.indexOf(v) === i); // dedupe
+      let allMcpFound = true;
+      for (const ref of mcpServerRefs) {
+        const servers = resources.AgentMcpServer || [];
+        const server = servers.find((s) => s.metadata?.name === ref);
+        if (server) {
+          resolvedMcpServers.push(server.metadata.name);
+        } else {
+          allMcpFound = false;
+          missing.push(`AgentMcpServer/${ref}`);
+        }
+      }
+
+      // memoryRepositoryRefs — resolve memory repository associations
+      const memoryRepositoryRefs = spec.memoryRepositoryRefs || [];
+      const resolvedMemoryRepos = [];
+      let allMemoryReposFound = true;
+      for (const ref of memoryRepositoryRefs) {
+        const repos = resources.AgentMemoryRepository || [];
+        const repo = repos.find((r) => r.metadata?.name === ref);
+        if (repo) {
+          resolvedMemoryRepos.push(repo.metadata.name);
+        } else {
+          allMemoryReposFound = false;
+          missing.push(`AgentMemoryRepository/${ref}`);
+        }
+      }
+
+      // skillRefs
+      const skillRefs = spec.skillRefs || [];
+      let allSkillsFound = true;
+      let allSkillsValid = true;
+      for (const ref of skillRefs) {
+        const skills = resources.AgentSkill || [];
+        const skill = skills.find((s) => s.metadata?.name === ref);
+        if (skill) {
+          resolvedSkills.push(skill.metadata.name);
+          if (!skill.spec?.format || !skill.spec?.sourceRef) {
+            allSkillsValid = false;
+          }
+        } else {
+          allSkillsFound = false;
+          allSkillsValid = false;
+          missing.push(`AgentSkill/${ref}`);
+        }
+      }
+
+      // subagentRefs
+      const subagentRefs = spec.subagentRefs || [];
+      let allSubagentsFound = true;
+      let allSubagentsValid = true;
+      for (const ref of subagentRefs) {
+        const subagents = resources.AgentSubagent || [];
+        const subagent = subagents.find((s) => s.metadata?.name === ref);
+        if (subagent) {
+          resolvedSubagents.push(subagent.metadata.name);
+          if (!subagent.spec?.taskKinds || subagent.spec.taskKinds.length === 0) {
+            allSubagentsValid = false;
+          }
+        } else {
+          allSubagentsFound = false;
+          allSubagentsValid = false;
+          missing.push(`AgentSubagent/${ref}`);
+        }
+      }
+
+      // contextLabelRefs
+      const contextLabelRefs = spec.contextLabelRefs || [];
+      let allContextLabelsFound = true;
+      for (const ref of contextLabelRefs) {
+        const labels = resources.AgentContextLabel || [];
+        const label = labels.find((l) => l.metadata?.name === ref);
+        if (label) {
+          resolvedContextLabels.push(label.metadata.name);
+        } else {
+          allContextLabelsFound = false;
+          missing.push(`AgentContextLabel/${ref}`);
+        }
+      }
+
+      // --- Build conditions ---
+      const allRefsFound = missing.length === 0;
+      conditions.push({
+        type: 'CapabilitiesResolved',
+        status: allRefsFound ? 'True' : 'False',
+        reason: allRefsFound ? 'AllRefsResolved' : 'MissingRefs',
+        message: allRefsFound ? 'All capability references resolved' : `Missing: ${missing.join(', ')}`
+      });
+
+      conditions.push({
+        type: 'ToolsAdmitted',
+        status: (toolPolicyFound || !toolPolicyRef) ? 'True' : 'False',
+        reason: !toolPolicyRef ? 'NoToolPolicyRef' : toolPolicyFound ? 'ToolPolicyResolved' : 'ToolPolicyMissing',
+        message: !toolPolicyRef ? 'No tool policy reference set' : toolPolicyFound ? 'Tool policy resolved' : `AgentToolProfile/${toolPolicyRef} not found`
+      });
+
+      conditions.push({
+        type: 'McpHealthy',
+        status: allMcpFound ? 'True' : 'False',
+        reason: allMcpFound ? 'AllMcpServersExist' : 'MissingMcpServers',
+        message: allMcpFound ? 'All MCP servers exist (health check deferred)' : `Missing MCP servers: ${mcpServerRefs.filter((ref) => !resolvedMcpServers.includes(ref)).join(', ')}`
+      });
+
+      conditions.push({
+        type: 'SkillsValidated',
+        status: (allSkillsFound && allSkillsValid) ? 'True' : 'False',
+        reason: !allSkillsFound ? 'MissingSkills' : !allSkillsValid ? 'InvalidSkillFormat' : 'AllSkillsValid',
+        message: !allSkillsFound ? `Missing skills: ${skillRefs.filter((ref) => !resolvedSkills.includes(ref)).join(', ')}` : !allSkillsValid ? 'Some skills have invalid format or missing sourceRef' : 'All skills validated'
+      });
+
+      conditions.push({
+        type: 'SubagentsValid',
+        status: (allSubagentsFound && allSubagentsValid) ? 'True' : 'False',
+        reason: !allSubagentsFound ? 'MissingSubagents' : !allSubagentsValid ? 'InvalidSubagentTaskKinds' : 'AllSubagentsValid',
+        message: !allSubagentsFound ? `Missing subagents: ${subagentRefs.filter((ref) => !resolvedSubagents.includes(ref)).join(', ')}` : !allSubagentsValid ? 'Some subagents have invalid or empty taskKinds' : 'All subagents validated'
+      });
+
+      conditions.push({
+        type: 'ContextLabelsValid',
+        status: allContextLabelsFound ? 'True' : 'False',
+        reason: allContextLabelsFound ? 'AllContextLabelsExist' : 'MissingContextLabels',
+        message: allContextLabelsFound ? 'All context labels exist' : `Missing context labels: ${contextLabelRefs.filter((ref) => !resolvedContextLabels.includes(ref)).join(', ')}`
+      });
+
+      const memoryBound = memoryRepositoryRefs.length === 0 || allMemoryReposFound;
+      conditions.push({
+        type: 'MemoryBound',
+        status: memoryBound ? 'True' : 'False',
+        reason: memoryRepositoryRefs.length === 0 ? 'NoMemoryRefsConfigured' : allMemoryReposFound ? 'AllMemoryReposResolved' : 'MissingMemoryRepos',
+        message: memoryRepositoryRefs.length === 0 ? 'No memory repository references configured' : allMemoryReposFound ? 'All memory repositories resolved' : `Missing memory repositories: ${memoryRepositoryRefs.filter((ref) => !resolvedMemoryRepos.includes(ref)).join(', ')}`
+      });
+
+      if (spec.jitsiCapability === true) {
+        const jitsiConfig = spec.jitsiConfig || {};
+        const role = jitsiConfig.role || 'observer';
+        const tools = jitsiConfig.tools || [];
+        const invalidTools = tools.filter((tool) => !JITSI_TOOLS.has(tool));
+        const providerRef = spec.jitsiMeetingProviderRef;
+        let providerFound = true;
+        if (providerRef) {
+          providerFound = (resources.JitsiMeetProvider || []).some((provider) => provider.metadata?.name === providerRef);
+          if (!providerFound) missing.push(`JitsiMeetProvider/${providerRef}`);
+        }
+        const observerCanSpeak = role === 'observer' && ['speak', 'both'].includes(jitsiConfig.capabilities?.audio);
+        const valid = Boolean(providerRef) && providerFound && JITSI_ROLES.has(role) && invalidTools.length === 0 && !observerCanSpeak;
+        conditions.push({
+          type: 'JitsiCapabilityReady',
+          status: valid ? 'True' : 'False',
+          reason: valid ? 'JitsiCapabilityValid' : 'InvalidJitsiCapability',
+          message: valid
+            ? 'Jitsi meeting capability is valid'
+            : [
+                !providerRef ? 'jitsiMeetingProviderRef is required' : null,
+                providerRef && !providerFound ? `JitsiMeetProvider/${providerRef} not found` : null,
+                !JITSI_ROLES.has(role) ? `Invalid role: ${role}` : null,
+                observerCanSpeak ? 'observer role cannot use speak or both audio modes' : null,
+                invalidTools.length ? `Invalid Jitsi tools: ${invalidTools.join(', ')}` : null,
+              ].filter(Boolean).join('; ')
+        });
+      } else {
+        conditions.push({
+          type: 'JitsiCapabilityReady',
+          status: 'True',
+          reason: 'JitsiCapabilityDisabled',
+          message: 'No Jitsi meeting capability configured'
+        });
+      }
+
+      // --- Permission review conditions via permissionReviewer ---
+      const serviceAccountRef = spec.runtimeIdentity?.serviceAccountRef || spec.runtimeIdentity;
+      const serviceAccounts = resources.AgentServiceAccount || [];
+      const serviceAccount = serviceAccounts.find((sa) => sa.metadata?.name === serviceAccountRef);
+      const runtimeIdentityReady = Boolean(serviceAccount);
+
+      conditions.push({
+        type: 'RuntimeIdentityReady',
+        status: runtimeIdentityReady ? 'True' : 'False',
+        reason: runtimeIdentityReady ? 'ServiceAccountBound' : 'MissingServiceAccount',
+        message: runtimeIdentityReady ? `AgentServiceAccount ${serviceAccountRef} bound` : `AgentServiceAccount ${serviceAccountRef || 'undefined'} not found`
+      });
+
+      // Run permission review for roles, secrets, config
+      const permissionReview = permissionReviewer.reviewPermissions({
+        repository: stack?.metadata?.labels?.repository || 'unknown',
+        ref: stack?.metadata?.labels?.ref || 'main',
+        actor: stack?.metadata?.labels?.actor || 'system',
+        agentStack: stack?.metadata?.name,
+        triggerSource: 'reconciliation',
+        taskKind: spec.taskKind || 'general',
+        resources
+      });
+
+      const rolesAdmitted = !permissionReview.reasons.some((r) => r.severity === 'error' && r.message.includes('AgentRoleBinding'));
+      const secretsAdmitted = !permissionReview.reasons.some((r) => r.severity === 'error' && r.message.includes('AgentSecretGrant'));
+      const configAdmitted = !permissionReview.reasons.some((r) => r.severity === 'error' && r.message.includes('AgentConfigGrant'));
+
+      conditions.push({
+        type: 'RolesAdmitted',
+        status: rolesAdmitted ? 'True' : 'False',
+        reason: rolesAdmitted ? 'RoleBindingsResolved' : 'MissingRoleBindings',
+        message: rolesAdmitted ? 'Role bindings satisfied' : 'Missing required AgentRoleBinding resources'
+      });
+
+      conditions.push({
+        type: 'SecretsAdmitted',
+        status: secretsAdmitted ? 'True' : 'False',
+        reason: secretsAdmitted ? 'SecretGrantsResolved' : 'MissingSecretGrants',
+        message: secretsAdmitted ? 'Secret grants satisfied' : 'Missing required AgentSecretGrant resources'
+      });
+
+      conditions.push({
+        type: 'ConfigAdmitted',
+        status: configAdmitted ? 'True' : 'False',
+        reason: configAdmitted ? 'ConfigGrantsResolved' : 'MissingConfigGrants',
+        message: configAdmitted ? 'Config grants satisfied' : 'Missing required AgentConfigGrant resources'
+      });
+
+      // --- Ready condition: true only if ALL other conditions are true ---
+      const allTrue = conditions.every((c) => c.status === 'True');
+      const hasErrors = conditions.some((c) => c.status === 'False');
+
+      conditions.push({
+        type: 'Ready',
+        status: allTrue ? 'True' : 'False',
+        reason: allTrue ? 'StackReady' : 'StackNotReady',
+        message: allTrue ? 'All conditions met' : `Failing conditions: ${conditions.filter((c) => c.status === 'False').map((c) => c.type).join(', ')}`
+      });
+
+      return {
+        conditions: clone(conditions),
+        capabilities: {
+          tools: clone(resolvedTools),
+          mcpServers: clone(resolvedMcpServers),
+          skills: clone(resolvedSkills),
+          subagents: clone(resolvedSubagents),
+          contextLabels: clone(resolvedContextLabels),
+          memoryRepos: clone(resolvedMemoryRepos)
+        },
+        validation: allTrue ? 'valid' : hasErrors ? 'invalid' : 'warning',
+        permissionDecision: permissionReview.decision
+      };
+    },
+
+    listStackCapabilities(stack, resources = {}) {
+      const spec = stack?.spec || {};
+      const capabilities = [];
+
+      // Tools
+      const toolPolicyRef = spec.toolPolicy || spec.toolPolicyRef || null;
+      if (toolPolicyRef) {
+        const profiles = resources.AgentToolProfile || [];
+        const profile = profiles.find((p) => p.metadata?.name === toolPolicyRef);
+        capabilities.push({
+          kind: 'tool',
+          name: toolPolicyRef,
+          status: profile ? 'resolved' : 'missing',
+          ref: toolPolicyRef
+        });
+      }
+
+      // MCP Servers
+      for (const ref of spec.mcpServerRefs || []) {
+        const servers = resources.AgentMcpServer || [];
+        const server = servers.find((s) => s.metadata?.name === ref);
+        capabilities.push({
+          kind: 'mcp',
+          name: ref,
+          status: server ? 'resolved' : 'missing',
+          ref
+        });
+      }
+
+      // Skills
+      for (const ref of spec.skillRefs || []) {
+        const skills = resources.AgentSkill || [];
+        const skill = skills.find((s) => s.metadata?.name === ref);
+        capabilities.push({
+          kind: 'skill',
+          name: ref,
+          status: skill ? 'resolved' : 'missing',
+          ref
+        });
+      }
+
+      // Subagents
+      for (const ref of spec.subagentRefs || []) {
+        const subagents = resources.AgentSubagent || [];
+        const subagent = subagents.find((s) => s.metadata?.name === ref);
+        capabilities.push({
+          kind: 'subagent',
+          name: ref,
+          status: subagent ? 'resolved' : 'missing',
+          ref
+        });
+      }
+
+      // Context Labels
+      for (const ref of spec.contextLabelRefs || []) {
+        const labels = resources.AgentContextLabel || [];
+        const label = labels.find((l) => l.metadata?.name === ref);
+        capabilities.push({
+          kind: 'contextLabel',
+          name: ref,
+          status: label ? 'resolved' : 'missing',
+          ref
+        });
+      }
+
+      return capabilities;
+    },
+
+    /**
+     * Perform a health check for an AgentMcpServer resource.
+     * If no endpoint is configured in spec, returns { status: 'unknown', reason: 'no-endpoint' }.
+     * Otherwise performs a real HTTP GET with a 3s timeout.
+     * @param {object} mcpServer
+     * @returns {Promise<{ serverName: string, status: string, latencyMs?: number, reason?: string, error?: string }>}
+     */
+    async checkMcpHealth(mcpServer) {
+      const serverName = mcpServer?.metadata?.name;
+      const endpoint = mcpServer?.spec?.endpoint;
+
+      if (!endpoint) {
+        return { serverName, status: 'unknown', reason: 'no-endpoint' };
+      }
+
+      const checkResult = await performMcpHealthCheck(endpoint, fetchFn);
+      return { serverName, ...checkResult };
+    }
+  };
+}

package/src/agent-subagent-controller.js

@@ -0,0 +1,160 @@
+import { createResource, clone } from './resource-model.js';
+
+export const AGENT_SUBAGENT_CONTROLLER_BOUNDARY = {
+  role: 'agent-subagent-controller',
+  scope: 'Subagent dispatch orchestration with tool scoping, role-based routing, and supervision protocol',
+  owns: ['subagent validation', 'dispatch record creation', 'tool scope resolution', 'task routing', 'supervision config'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['secret values', 'Agent Mux sessions', 'parent session lifecycle']
+};
+
+const DEFAULT_SUPERVISION = {
+  monitorInterval: 60,
+  maxDuration: 7200,
+  autoTerminate: false
+};
+
+export function createAgentSubagentController() {
+  return {
+    role: 'agent-subagent-controller',
+
+    /**
+     * Validate an AgentSubagent resource.
+     * Checks for required fields beyond what the CRD spec.requiredSpec covers:
+     * - metadata.name
+     * - spec.parentStackRef
+     * - spec.role
+     */
+    validate(subagent) {
+      const errors = [];
+
+      if (!subagent?.metadata?.name) {
+        errors.push('metadata.name is required');
+      }
+
+      const spec = subagent?.spec || {};
+
+      if (!spec.parentStackRef) {
+        errors.push('spec.parentStackRef is required');
+      }
+
+      if (!spec.role) {
+        errors.push('spec.role is required');
+      }
+
+      return {
+        valid: errors.length === 0,
+        errors
+      };
+    },
+
+    /**
+     * Get the tool scope for a subagent.
+     * Returns { unrestricted: true, allowed: [], denied: [] } when no toolScope is set.
+     * Returns { unrestricted: false, allowed: [...], denied: [...] } when toolScope is configured.
+     */
+    getToolScope(subagent) {
+      const toolScope = subagent?.spec?.toolScope;
+      if (!toolScope) {
+        return {
+          unrestricted: true,
+          allowed: [],
+          denied: []
+        };
+      }
+      return {
+        unrestricted: false,
+        allowed: clone(toolScope.allowed || []),
+        denied: clone(toolScope.denied || [])
+      };
+    },
+
+    /**
+     * Get the list of explicitly denied tools for a subagent.
+     */
+    getDeniedTools(subagent) {
+      const toolScope = subagent?.spec?.toolScope;
+      return clone(toolScope?.denied || []);
+    },
+
+    /**
+     * Dispatch a subagent — creates a dispatch record linking the subagent to
+     * a parent session. Requires parentSessionRef to be provided.
+     */
+    dispatchSubagent({ subagent, parentSessionRef, taskKind, namespace = 'default', organizationRef = 'default', resources = {} }) {
+      if (!parentSessionRef) {
+        return {
+          error: true,
+          reason: 'parentSessionRef-required',
+          message: 'parentSessionRef is required to dispatch a subagent'
+        };
+      }
+
+      const subagentName = subagent?.metadata?.name;
+      const parentStackRef = subagent?.spec?.parentStackRef;
+      const role = subagent?.spec?.role;
+      const recordName = `subagent-dispatch-${subagentName}-${Date.now()}`;
+
+      const dispatchRecord = createResource(
+        'AgentDispatchRun',
+        { name: recordName, namespace },
+        {
+          organizationRef,
+          repository: resources.AgentStack?.[0]?.spec?.repositoryRef || 'unknown',
+          sourceRefs: [],
+          agentStack: parentStackRef || 'unknown',
+          taskKind: taskKind || 'general',
+          parentSessionRef,
+          subagentRef: subagentName,
+          subagentRole: role
+        }
+      );
+
+      dispatchRecord.status = { phase: 'Queued', queuedAt: new Date().toISOString() };
+
+      return {
+        dispatchRecord: clone(dispatchRecord)
+      };
+    },
+
+    /**
+     * Get supervision configuration for the subagent.
+     * Returns configured values or defaults when supervision is not set.
+     */
+    getSupervisionConfig(subagent) {
+      const supervision = subagent?.spec?.supervision;
+      if (!supervision) {
+        return { ...DEFAULT_SUPERVISION };
+      }
+      return {
+        monitorInterval: supervision.monitorInterval !== undefined ? supervision.monitorInterval : DEFAULT_SUPERVISION.monitorInterval,
+        maxDuration: supervision.maxDuration !== undefined ? supervision.maxDuration : DEFAULT_SUPERVISION.maxDuration,
+        autoTerminate: supervision.autoTerminate !== undefined ? supervision.autoTerminate : DEFAULT_SUPERVISION.autoTerminate
+      };
+    },
+
+    /**
+     * Validate task routing: checks that the requested role maps to an available subagent.
+     */
+    validateTaskRouting({ role, taskKind, subagents = [] }) {
+      const match = subagents.find(s => s?.spec?.role === role);
+      if (!match) {
+        return {
+          valid: false,
+          error: `No subagent found for role '${role}'`
+        };
+      }
+      return {
+        valid: true,
+        matchedSubagent: clone(match)
+      };
+    },
+
+    /**
+     * Get current status of a subagent from its status field.
+     */
+    getSubagentStatus(subagent) {
+      return clone(subagent?.status || { phase: 'idle' });
+    }
+  };
+}