@a5c-ai/krate 5.0.1-staging.660d2b90f → 5.0.1-staging.69cb593ea

package/src/agent-adapter-controller.js

@@ -0,0 +1,169 @@
+// Agent Adapter Controller — Slice 1.2a / C4
+// Manages AgentAdapter resources: validation, capabilities, transports, and health checks.
+
+export const AGENT_ADAPTER_CONTROLLER_BOUNDARY = {
+  role: 'agent-adapter-controller',
+  scope: 'AgentAdapter lifecycle: validation, capabilities matrix, transport enumeration, real health checks',
+  owns: ['adapter validation', 'capabilities matrix', 'transport enumeration', 'health checks'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['secret values', 'dispatch execution', 'Agent Mux sessions']
+};
+
+const HEALTH_CHECK_TIMEOUT_MS = 3000;
+
+const VALID_TRANSPORTS = ['stdio', 'http', 'websocket', 'unix'];
+const VALID_ADAPTER_TYPES = ['subprocess', 'remote', 'programmatic'];
+
+/**
+ * Validate an AgentAdapter resource. Returns { valid, errors }.
+ * @param {object} resource
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateAgentAdapter(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 adapterType
+  const adapterType = spec.adapterType;
+  if (!adapterType) {
+    errors.push(`spec.adapterType is required; valid types are: ${VALID_ADAPTER_TYPES.join(', ')}`);
+  } else if (!VALID_ADAPTER_TYPES.includes(adapterType)) {
+    errors.push(`spec.adapterType "${adapterType}" is not supported; valid types are: ${VALID_ADAPTER_TYPES.join(', ')}`);
+  }
+
+  // Validate transport
+  const transport = spec.transport;
+  if (!transport) {
+    errors.push(`spec.transport is required; valid transports are: ${VALID_TRANSPORTS.join(', ')}`);
+  } else if (!VALID_TRANSPORTS.includes(transport)) {
+    errors.push(`spec.transport "${transport}" is not supported; valid transports are: ${VALID_TRANSPORTS.join(', ')}`);
+  }
+
+  // Validate capabilities — must be a non-empty array
+  const capabilities = spec.capabilities;
+  if (!Array.isArray(capabilities) || capabilities.length === 0) {
+    errors.push('spec.capabilities must be a non-empty array');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Perform an HTTP health check against the given URL.
+ * Returns { status: 'healthy'|'unhealthy', latencyMs, error? }.
+ * @param {string} url
+ * @param {Function} fetchFn - injectable fetch (defaults to globalThis.fetch)
+ * @returns {Promise<{ status: string, latencyMs: number, error?: string }>}
+ */
+async function performHttpHealthCheck(url, fetchFn) {
+  const fn = fetchFn || globalThis.fetch;
+  const start = Date.now();
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), HEALTH_CHECK_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) };
+  }
+}
+
+/**
+ * Factory that returns an AgentAdapter controller instance.
+ * @param {object} [options]
+ * @param {Function} [options.fetch] - injectable fetch function (for testing)
+ */
+export function createAgentAdapterController(options = {}) {
+  const fetchFn = options.fetch || null;
+  return {
+    role: 'agent-adapter-controller',
+
+    /**
+     * Validate an AgentAdapter resource.
+     * @param {object} resource
+     * @returns {{ valid: boolean, errors: string[] }}
+     */
+    validate(resource) {
+      return validateAgentAdapter(resource);
+    },
+
+    /**
+     * Return the capabilities matrix for an adapter.
+     * @param {object} resource
+     * @returns {{ adapterName: string, supported: string[] }}
+     */
+    getCapabilities(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const supported = Array.isArray(resource?.spec?.capabilities)
+        ? [...resource.spec.capabilities]
+        : [];
+      return {
+        adapterName: resource?.metadata?.name,
+        supported
+      };
+    },
+
+    /**
+     * Return the list of supported transport types.
+     * @returns {string[]}
+     */
+    getSupportedTransports() {
+      return [...VALID_TRANSPORTS];
+    },
+
+    /**
+     * Return the list of supported adapter types.
+     * @returns {string[]}
+     */
+    getSupportedAdapterTypes() {
+      return [...VALID_ADAPTER_TYPES];
+    },
+
+    /**
+     * Perform a health check for an AgentAdapter.
+     * If no healthEndpoint is configured in spec, returns { status: 'unknown', reason: 'no-endpoint' }.
+     * If a healthEndpoint is configured, performs a real HTTP GET with a 3s timeout.
+     * Returns { status: 'healthy'|'unhealthy', latencyMs, error? } or { status: 'unknown', reason }.
+     * @param {object} resource
+     * @returns {Promise<{ adapterName: string, status: string, latencyMs?: number, reason?: string, error?: string }>}
+     */
+    async healthCheck(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const adapterName = resource?.metadata?.name;
+      const endpoint = resource?.spec?.healthEndpoint;
+
+      if (!endpoint) {
+        return { adapterName, status: 'unknown', reason: 'no-endpoint' };
+      }
+
+      const checkResult = await performHttpHealthCheck(endpoint, fetchFn);
+      return { adapterName, ...checkResult };
+    }
+  };
+}

package/src/agent-approval-controller.js

@@ -118,6 +118,53 @@ export function createAgentApprovalController() {
     listApprovalsForRun({ dispatchRun, resources = {} }) {
       const approvals = resources.AgentApproval || [];
       return approvals.filter((a) => a.spec?.dispatchRun === dispatchRun).map(clone);
+    },
+
+    // -----------------------------------------------------------------------
+    // B1: Persistence
+    // -----------------------------------------------------------------------
+
+    async persistApproval({ approval, applyResource }) {
+      if (!approval) {
+        return { error: true, reason: 'missing-approval', message: 'approval is required' };
+      }
+      if (typeof applyResource !== 'function') {
+        return { error: true, reason: 'missing-apply-resource', message: 'applyResource function is required' };
+      }
+      try {
+        const applyResult = await applyResource(approval);
+        return { error: false, approval, applyResult };
+      } catch (err) {
+        return { error: true, reason: 'persist-failed', message: err?.message || 'applyResource failed' };
+      }
+    },
+
+    // -----------------------------------------------------------------------
+    // B1: Enforcement gate
+    // -----------------------------------------------------------------------
+
+    enforceApproval({ dispatchRun, action, resources = {} }) {
+      const approvals = resources.AgentApproval || [];
+      const match = approvals.find(
+        (a) => a.spec?.dispatchRun === dispatchRun && a.spec?.action === action
+      );
+
+      if (!match) {
+        return { allowed: false, reason: 'no-approval-found', message: `No approval found for dispatchRun=${dispatchRun} action=${action}`, approval: null };
+      }
+
+      const phase = match.status?.phase;
+
+      if (phase === 'Approved') {
+        return { allowed: true, approval: clone(match), reason: 'approved' };
+      }
+
+      if (phase === 'Denied') {
+        return { allowed: false, reason: 'approval-denied', message: `Approval for dispatchRun=${dispatchRun} action=${action} was denied`, approval: clone(match) };
+      }
+
+      // Pending or unknown
+      return { allowed: false, reason: 'approval-pending', message: `Approval for dispatchRun=${dispatchRun} action=${action} is still pending`, approval: clone(match) };
     }
   };
 }

package/src/agent-dispatch-controller.js

@@ -3,12 +3,15 @@ import { createAgentStackController } from './agent-stack-controller.js';
 import { assembleContextBundle } from './agent-context-bundles.js';
 import { createResource, clone } from './resource-model.js';
 import { createAgentMuxClient } from './agent-mux-client.js';
+import { createAgentMemoryController } from './agent-memory-controller.js';
+import { createAgentApprovalController } from './agent-approval-controller.js';
+import { createAgentWorkspaceController } from './agent-workspace-controller.js';
 
 export const AGENT_DISPATCH_CONTROLLER_BOUNDARY = {
   role: 'agent-dispatch-controller',
-  scope: 'Manual dispatch orchestration with permission gating and context assembly',
-  owns: ['dispatch creation', 'attempt lifecycle', 'Agent Mux session binding'],
-  delegatesTo: ['agent-permission-review', 'agent-stack-controller', 'agent-context-bundles', 'agent-mux-client'],
+  scope: 'Manual dispatch orchestration with permission gating, context assembly, and workspace provisioning',
+  owns: ['dispatch creation', 'attempt lifecycle', 'Agent Mux session binding', 'workspace provisioning'],
+  delegatesTo: ['agent-permission-review', 'agent-stack-controller', 'agent-context-bundles', 'agent-mux-client', 'agent-memory-controller', 'agent-approval-controller', 'agent-workspace-controller'],
   mustNotOwn: ['secret values', 'UI rendering']
 };
 
@@ -16,6 +19,9 @@ export function createAgentDispatchController(options = {}) {
   const permissionReviewer = options.permissionReviewer || createPermissionReviewer();
   const stackController = options.stackController || createAgentStackController();
   const agentMuxClient = options.agentMuxClient || createAgentMuxClient();
+  const memoryController = options.memoryController || createAgentMemoryController();
+  const approvalController = options.approvalController || createAgentApprovalController();
+  const workspaceController = options.workspaceController || createAgentWorkspaceController();
 
   return {
     role: 'agent-dispatch-controller',
@@ -32,10 +38,102 @@ export function createAgentDispatchController(options = {}) {
       }
       const permissionSnapshot = permissionReviewer.createPermissionSnapshot(review);
 
-      // 3. Assemble context bundle
+      // 3. Memory snapshot — create if any AgentMemoryRepository exists in resources
+      let memorySnapshot = null;
+      const memoryRepos = resources.AgentMemoryRepository || [];
+      if (memoryRepos.length > 0) {
+        const memRepo = memoryRepos[0];
+        const timeTravel = memoryController.resolveTimeTravel({ mode: 'current', commits: [] });
+        memorySnapshot = memoryController.createMemorySnapshot({
+          memoryRepository: memRepo.metadata.name,
+          requestedRef: ref,
+          resolvedCommit: timeTravel.resolvedCommit || ref,
+          queryManifest: {},
+          selectedRecords: [],
+          selectedDocuments: [],
+          ontologyDigest: '',
+          namespace,
+          organizationRef,
+        });
+      }
+
+      // 4. Approval gate — if review requires approval, create approval and return early
+      if (review.decision === 'requires-approval') {
+        const now = new Date().toISOString();
+        const runName = `dispatch-${Date.now()}`;
+
+        const run = createResource('AgentDispatchRun', { name: runName, namespace }, {
+          organizationRef,
+          repository,
+          sourceRefs: clone(sourceRefs),
+          agentStack,
+          taskKind: taskKind || 'diagnostic',
+          contextBundleRef: null,
+        });
+        run.status = { phase: 'AwaitingApproval', queuedAt: now };
+        if (memorySnapshot) {
+          run.spec.memorySnapshotRef = memorySnapshot.metadata.name;
+        }
+
+        const approvalResult = approvalController.createApprovalRequest({
+          dispatchRun: runName,
+          action: 'secret-access',
+          requestedBy: actor,
+          context: `Dispatch requires approval for agent stack: ${agentStack}`,
+          namespace,
+          organizationRef,
+          resources,
+        });
+
+        return {
+          error: false,
+          run,
+          approval: approvalResult.error ? null : approvalResult.approval,
+          awaitingApproval: true,
+          memorySnapshot,
+          permissionSnapshot,
+          review,
+        };
+      }
+
+      // 5. Workspace provisioning — reuse or create
+      let workspaceResult = null;
+      let mountSpec = null;
+      const branch = ref || 'main';
+
+      const reusable = workspaceController.findReusableWorkspace({
+        organizationRef, repository, branch, resources,
+      });
+
+      if (reusable) {
+        const claimResult = workspaceController.claimWorkspace({
+          name: reusable.metadata.name,
+          runRef: `dispatch-pending`,
+          resources,
+        });
+        if (!claimResult.error) {
+          workspaceResult = { workspace: claimResult.workspace, reused: true };
+          const mount = workspaceController.getMountSpec({ workspace: claimResult.workspace });
+          if (!mount.error) mountSpec = { volume: mount.volume, volumeMount: mount.volumeMount };
+        }
+      }
+
+      if (!workspaceResult) {
+        const createResult = workspaceController.createWorkspace({
+          organizationRef, repository, branch, namespace,
+          volumeSpec: {},
+        });
+        if (!createResult.error) {
+          workspaceResult = { workspace: createResult.workspace, pvcManifest: createResult.pvcManifest, reused: false };
+          const mount = workspaceController.getMountSpec({ workspace: createResult.workspace });
+          if (!mount.error) mountSpec = { volume: mount.volume, volumeMount: mount.volumeMount };
+        }
+      }
+
+      // 6. Assemble context bundle
       const contextBundle = assembleContextBundle({ stack, repository, ref, sourceRefs, contextLabels: [], resources });
 
-      // 4. Create resources
+      // 7. Create resources
       const now = new Date().toISOString();
       const runName = `dispatch-${Date.now()}`;
 
@@ -48,6 +146,20 @@ export function createAgentDispatchController(options = {}) {
         contextBundleRef: contextBundle.metadata.name,
       });
       run.status = { phase: 'Pending', queuedAt: now };
+      if (memorySnapshot) {
+        run.spec.memorySnapshotRef = memorySnapshot.metadata.name;
+      }
+      if (workspaceResult) {
+        run.spec.workspaceRef = workspaceResult.workspace.metadata.name;
+      }
+      if (mountSpec) {
+        run.spec.mountSpec = mountSpec;
+      }
+
+      // Update workspace runRef to actual dispatch name
+      if (workspaceResult) {
+        workspaceResult.workspace.status.runRef = runName;
+      }
 
       const attempt = createResource('AgentDispatchAttempt', { name: `${runName}-attempt-1`, namespace }, {
         organizationRef,
@@ -58,7 +170,8 @@ export function createAgentDispatchController(options = {}) {
       });
       attempt.status = { permissionSnapshot, queueEnteredAt: now };
 
-      // 5. Try Agent Mux launch
+      // 7. Try Agent Mux launch
+      let transcript = null;
       if (agentMuxClient.isAvailable()) {
         try {
           const session = await agentMuxClient.launchSession({ stack, contextBundle, permissionSnapshot });
@@ -67,6 +180,16 @@ export function createAgentDispatchController(options = {}) {
             attempt.status.agentMuxSessionId = session.sessionId;
             run.status.phase = 'Running';
             attempt.status.startedAt = now;
+
+            // 8. After successful launch — start SSE subscription + create initial transcript
+            const collectedEvents = [];
+            const subscription = agentMuxClient.subscribeToEvents(session.runId, (event) => {
+              collectedEvents.push(event);
+            });
+            run.status.sseSubscription = { runId: session.runId, active: true };
+
+            transcript = agentMuxClient.reconcileTranscript(session.sessionId, collectedEvents, { namespace, organizationRef });
+            run.status.transcriptRef = transcript.metadata.name;
           } else {
             run.status.phase = 'Queued';
             run.status.conditions = [{ type: 'AgentMuxBound', status: 'False', reason: 'LaunchFailed', message: 'Agent Mux launch returned no session' }];
@@ -80,7 +203,7 @@ export function createAgentDispatchController(options = {}) {
         run.status.conditions = [{ type: 'AgentMuxBound', status: 'False', reason: 'Unavailable', message: 'Agent Mux gateway not configured' }];
       }
 
-      return { error: false, run, attempt, contextBundle, permissionSnapshot };
+      return { error: false, run, attempt, contextBundle, permissionSnapshot, memorySnapshot, transcript, workspace: workspaceResult, mountSpec };
     }
   };
 }

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

@@ -0,0 +1,147 @@
+// Agent Gateway Config Controller — Slice 1.2e
+// Manages AgentGatewayConfig resources: gateway name, endpoint URL, feature flags,
+// connection pool settings, and TLS configuration reference.
+
+export const AGENT_GATEWAY_CONFIG_CONTROLLER_BOUNDARY = {
+  role: 'agent-gateway-config-controller',
+  scope: 'AgentGatewayConfig lifecycle: validation, endpoint resolution, feature flags, connection pool, TLS config ref',
+  owns: ['gateway config validation', 'endpoint URL', 'feature flags', 'connection pool defaults', 'TLS config ref'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['secret values', 'dispatch execution', 'Agent Mux sessions', 'adapter implementation']
+};
+
+const DEFAULT_FEATURE_FLAGS = Object.freeze({
+  streaming: true,
+  reconnect: true,
+  healthCheck: true
+});
+
+const DEFAULT_POOL_SETTINGS = Object.freeze({
+  maxConnections: 10,
+  timeoutMs: 30000
+});
+
+/**
+ * Validate an AgentGatewayConfig resource. Returns { valid, errors }.
+ * @param {object} resource
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateAgentGatewayConfig(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 endpoint URL
+  if (!spec.endpointUrl) {
+    errors.push('spec.endpointUrl is required; provide the Agent Mux gateway endpoint URL');
+  } else {
+    // Basic URL validation: must start with http:// or https:// or ws:// or wss://
+    const validProtocols = ['http://', 'https://', 'ws://', 'wss://'];
+    const hasValidProtocol = validProtocols.some((p) => spec.endpointUrl.startsWith(p));
+    if (!hasValidProtocol) {
+      errors.push(`spec.endpointUrl must start with one of: ${validProtocols.join(', ')}`);
+    }
+  }
+
+  // Validate connectionPool if provided
+  const pool = spec.connectionPool;
+  if (pool != null) {
+    if (pool.maxConnections != null && (!Number.isInteger(pool.maxConnections) || pool.maxConnections < 1)) {
+      errors.push('spec.connectionPool.maxConnections must be a positive integer');
+    }
+    if (pool.timeoutMs != null && (!Number.isFinite(pool.timeoutMs) || pool.timeoutMs < 0)) {
+      errors.push('spec.connectionPool.timeoutMs must be a non-negative number');
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Factory that returns an AgentGatewayConfig controller instance.
+ */
+export function createAgentGatewayConfigController() {
+  return {
+    role: 'agent-gateway-config-controller',
+
+    /**
+     * Validate an AgentGatewayConfig resource.
+     * @param {object} resource
+     * @returns {{ valid: boolean, errors: string[] }}
+     */
+    validate(resource) {
+      return validateAgentGatewayConfig(resource);
+    },
+
+    /**
+     * Return the effective endpoint URL for the gateway config.
+     * @param {object} resource
+     * @returns {string}
+     */
+    getEndpointUrl(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      return resource?.spec?.endpointUrl ?? null;
+    },
+
+    /**
+     * Return the effective feature flags for a gateway config.
+     * Merges spec.featureFlags with defaults; spec values take precedence.
+     * @param {object} resource
+     * @returns {{ streaming: boolean, reconnect: boolean, healthCheck: 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 connection pool settings for a gateway config.
+     * Merges spec.connectionPool with defaults; spec values take precedence.
+     * @param {object} resource
+     * @returns {{ maxConnections: number, timeoutMs: number }}
+     */
+    getConnectionPool(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const specPool = resource?.spec?.connectionPool ?? {};
+      return {
+        maxConnections: specPool.maxConnections ?? DEFAULT_POOL_SETTINGS.maxConnections,
+        timeoutMs: specPool.timeoutMs ?? DEFAULT_POOL_SETTINGS.timeoutMs
+      };
+    },
+
+    /**
+     * Return the TLS configuration reference from the spec, or null if not set.
+     * @param {object} resource
+     * @returns {string|null}
+     */
+    getTlsConfigRef(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      return resource?.spec?.tlsConfigRef ?? null;
+    }
+  };
+}