@a5c-ai/krate 5.0.1-staging.04a3db697

package/src/agent-stack-controller.js

@@ -0,0 +1,347 @@
+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;
+
+/**
+ * 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
+      const mcpServerRefs = spec.mcpServerRefs || [];
+      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}`);
+        }
+      }
+
+      // 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(', ')}`
+      });
+
+      // --- 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)
+        },
+        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' });
+    }
+  };
+}

package/src/agent-transport-binding-controller.js

@@ -0,0 +1,121 @@
+// Agent Transport Binding Controller — Slice 1.2b
+// Manages AgentTransportBinding resources: connection config validation,
+// health status tracking, and reconnect policy enforcement.
+
+export const AGENT_TRANSPORT_BINDING_CONTROLLER_BOUNDARY = {
+  role: 'agent-transport-binding-controller',
+  scope: 'AgentTransportBinding lifecycle: validation, connection status tracking, reconnect policy enforcement',
+  owns: ['binding validation', 'connection status tracking', 'reconnect policy enforcement'],
+  delegatesTo: ['resource-model', 'agent-adapter-controller'],
+  mustNotOwn: ['secret values', 'dispatch execution', 'Agent Mux sessions', 'adapter implementation']
+};
+
+const VALID_PROTOCOLS = ['stdio', 'http', 'websocket', 'unix'];
+
+const DEFAULT_RECONNECT_POLICY = Object.freeze({
+  maxRetries: 3,
+  backoffMs: 1000,
+  maxBackoffMs: 30000
+});
+
+/**
+ * Validate an AgentTransportBinding resource. Returns { valid, errors }.
+ * @param {object} resource
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateAgentTransportBinding(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 adapterRef
+  if (!spec.adapterRef) {
+    errors.push('spec.adapterRef is required');
+  }
+
+  // Validate endpoint
+  if (!spec.endpoint) {
+    errors.push('spec.endpoint is required');
+  }
+
+  // Validate protocol
+  const protocol = spec.protocol;
+  if (!protocol) {
+    errors.push(`spec.protocol is required; valid protocols are: ${VALID_PROTOCOLS.join(', ')}`);
+  } else if (!VALID_PROTOCOLS.includes(protocol)) {
+    errors.push(`spec.protocol "${protocol}" is not supported; valid protocols are: ${VALID_PROTOCOLS.join(', ')}`);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Factory that returns an AgentTransportBinding controller instance.
+ */
+export function createAgentTransportBindingController() {
+  return {
+    role: 'agent-transport-binding-controller',
+
+    /**
+     * Validate an AgentTransportBinding resource.
+     * @param {object} resource
+     * @returns {{ valid: boolean, errors: string[] }}
+     */
+    validate(resource) {
+      return validateAgentTransportBinding(resource);
+    },
+
+    /**
+     * Return the current connection status for a transport binding.
+     * Reads from resource.status.connectionStatus when available,
+     * otherwise returns 'unknown'.
+     * @param {object} resource
+     * @returns {{ bindingName: string, connectionStatus: string }}
+     */
+    getConnectionStatus(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const bindingName = resource?.metadata?.name;
+      const connectionStatus = resource?.status?.connectionStatus ?? 'unknown';
+      return { bindingName, connectionStatus };
+    },
+
+    /**
+     * Return the reconnect policy for a transport binding.
+     * Merges spec.reconnectPolicy values with defaults.
+     * @param {object} resource
+     * @returns {{ maxRetries: number, backoffMs: number, maxBackoffMs: number }}
+     */
+    getReconnectPolicy(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const specPolicy = resource?.spec?.reconnectPolicy ?? {};
+      return {
+        maxRetries: specPolicy.maxRetries ?? DEFAULT_RECONNECT_POLICY.maxRetries,
+        backoffMs: specPolicy.backoffMs ?? DEFAULT_RECONNECT_POLICY.backoffMs,
+        maxBackoffMs: specPolicy.maxBackoffMs ?? DEFAULT_RECONNECT_POLICY.maxBackoffMs
+      };
+    },
+
+    /**
+     * Return the list of supported protocol types.
+     * @returns {string[]}
+     */
+    getSupportedProtocols() {
+      return [...VALID_PROTOCOLS];
+    }
+  };
+}