@a5c-ai/krate 5.0.1-staging.00fa5317c

package/src/agent-memory-repository-source-controller.js

@@ -0,0 +1,255 @@
+// Agent Memory Repository & Source Controller — Slice 2.3a
+//
+// AgentMemoryRepository: org-level memory storage pointer, git repo ref validation.
+// AgentMemorySource: read policies for memory paths, access control.
+
+// ---------------------------------------------------------------------------
+// Boundaries
+// ---------------------------------------------------------------------------
+
+export const AGENT_MEMORY_REPOSITORY_CONTROLLER_BOUNDARY = {
+  role: 'agent-memory-repository-controller',
+  scope: 'AgentMemoryRepository lifecycle: validation, repo URL resolution, retention policy defaults',
+  owns: ['memory repository validation', 'repo URL', 'retention policy defaults'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['git operations', 'secret values', 'Agent Mux sessions', 'memory search']
+};
+
+export const AGENT_MEMORY_SOURCE_CONTROLLER_BOUNDARY = {
+  role: 'agent-memory-source-controller',
+  scope: 'AgentMemorySource lifecycle: validation, read policy, included/excluded paths, access control',
+  owns: ['memory source validation', 'read policy defaults', 'included paths', 'excluded paths'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['git operations', 'secret values', 'Agent Mux sessions', 'memory search']
+};
+
+// ---------------------------------------------------------------------------
+// Constants — defaults
+// ---------------------------------------------------------------------------
+
+const DEFAULT_RETENTION_POLICY = Object.freeze({
+  maxAgeDays: 90,
+  maxSizeMb: 500,
+});
+
+const DEFAULT_READ_POLICY = Object.freeze({
+  mode: 'allow-all',
+  maxDepth: 5,
+});
+
+// Valid git/http/ssh URL schemes
+// Accepted forms:
+//   https://...   http://...   ssh://...   git://...   git@host:path (SCP-style)
+const VALID_REPO_URL_PATTERNS = [
+  /^https?:\/\//,
+  /^ssh:\/\//,
+  /^git:\/\//,
+  /^git@[^:]+:.+/,
+];
+
+// ---------------------------------------------------------------------------
+// Standalone validateMemoryRepository
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate an AgentMemoryRepository resource. Returns { valid, errors }.
+ * @param {object} resource
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateMemoryRepository(resource) {
+  const errors = [];
+
+  // Guard against null/undefined
+  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 repoUrl — presence
+  if (!spec.repoUrl) {
+    errors.push('spec.repoUrl is required; provide a git/http/ssh repository URL');
+  } else {
+    // Validate repoUrl — format (git/http/ssh/scp-style)
+    const isValid = VALID_REPO_URL_PATTERNS.some((re) => re.test(spec.repoUrl));
+    if (!isValid) {
+      errors.push(
+        'spec.repoUrl must be a valid git repository URL (https://, http://, ssh://, git://, or git@host:path format)'
+      );
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// AgentMemoryRepository controller factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Factory that returns an AgentMemoryRepository controller instance.
+ */
+export function createAgentMemoryRepositoryController() {
+  return {
+    role: 'agent-memory-repository-controller',
+
+    /**
+     * Validate an AgentMemoryRepository resource.
+     * @param {object} resource
+     * @returns {{ valid: boolean, errors: string[] }}
+     */
+    validateMemoryRepository(resource) {
+      return validateMemoryRepository(resource);
+    },
+
+    /**
+     * Return the repository URL configured in spec.repoUrl.
+     * @param {object} resource
+     * @returns {string}
+     */
+    getRepositoryUrl(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      return resource.spec?.repoUrl ?? null;
+    },
+
+    /**
+     * Return the effective retention policy for the memory repository.
+     * Merges spec.retentionPolicy with defaults; spec values take precedence.
+     * Defaults: maxAgeDays = 90, maxSizeMb = 500.
+     * @param {object} resource
+     * @returns {{ maxAgeDays: number, maxSizeMb: number }}
+     */
+    getRetentionPolicy(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const specPolicy = resource.spec?.retentionPolicy ?? {};
+      return {
+        maxAgeDays: specPolicy.maxAgeDays ?? DEFAULT_RETENTION_POLICY.maxAgeDays,
+        maxSizeMb: specPolicy.maxSizeMb ?? DEFAULT_RETENTION_POLICY.maxSizeMb,
+      };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Standalone validateMemorySource
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate an AgentMemorySource resource. Returns { valid, errors }.
+ * @param {object} resource
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateMemorySource(resource) {
+  const errors = [];
+
+  // Guard against null/undefined
+  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 repositoryRef
+  if (!spec.repositoryRef) {
+    errors.push('spec.repositoryRef is required; provide a reference to the AgentMemoryRepository');
+  }
+
+  // Validate paths — must be present and non-empty
+  const paths = spec.paths;
+  if (!Array.isArray(paths) || paths.length === 0) {
+    errors.push('spec.paths must be a non-empty array of memory path patterns');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// AgentMemorySource controller factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Factory that returns an AgentMemorySource controller instance.
+ */
+export function createAgentMemorySourceController() {
+  return {
+    role: 'agent-memory-source-controller',
+
+    /**
+     * Validate an AgentMemorySource resource.
+     * @param {object} resource
+     * @returns {{ valid: boolean, errors: string[] }}
+     */
+    validateMemorySource(resource) {
+      return validateMemorySource(resource);
+    },
+
+    /**
+     * Return the effective read policy for the memory source.
+     * Merges spec.readPolicy with defaults; spec values take precedence.
+     * Defaults: mode = 'allow-all', maxDepth = 5.
+     * @param {object} resource
+     * @returns {{ mode: string, maxDepth: number }}
+     */
+    getReadPolicy(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const specPolicy = resource.spec?.readPolicy ?? {};
+      return {
+        mode: specPolicy.mode ?? DEFAULT_READ_POLICY.mode,
+        maxDepth: specPolicy.maxDepth ?? DEFAULT_READ_POLICY.maxDepth,
+      };
+    },
+
+    /**
+     * Return the included memory path patterns from spec.paths.
+     * @param {object} resource
+     * @returns {string[]}
+     */
+    getIncludedPaths(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      return Array.isArray(resource.spec?.paths) ? [...resource.spec.paths] : [];
+    },
+
+    /**
+     * Return the excluded memory path patterns from spec.excludedPaths.
+     * Returns an empty array when not set.
+     * @param {object} resource
+     * @returns {string[]}
+     */
+    getExcludedPaths(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      return Array.isArray(resource.spec?.excludedPaths) ? [...resource.spec.excludedPaths] : [];
+    },
+  };
+}

package/src/agent-mux-client.js

@@ -0,0 +1,280 @@
+import http from 'node:http';
+import https from 'node:https';
+import { URL } from 'node:url';
+import { createResource } from './resource-model.js';
+
+export const AGENT_MUX_CLIENT_BOUNDARY = {
+  role: 'agent-mux-client',
+  scope: 'HTTP/SSE adapter for Agent Mux gateway — capabilities, sessions, events, transcripts',
+  owns: ['gateway HTTP calls', 'SSE event streaming', 'transcript reconciliation'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['secret values', 'permission review', 'resource persistence']
+};
+
+/**
+ * Internal HTTP request helper. Zero external deps — uses node:http / node:https.
+ * @param {string} url
+ * @param {{ method?: string, body?: object, headers?: Record<string,string>, timeout?: number }} options
+ * @returns {Promise<{ status: number, body: any }>}
+ */
+function httpRequest(url, { method = 'GET', body, headers = {}, timeout = 30000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const transport = parsed.protocol === 'https:' ? https : http;
+    const opts = {
+      hostname: parsed.hostname,
+      port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+      path: parsed.pathname + parsed.search,
+      method,
+      headers: { 'Accept': 'application/json', ...headers },
+      timeout,
+    };
+    if (body) {
+      const payload = JSON.stringify(body);
+      opts.headers['Content-Type'] = 'application/json';
+      opts.headers['Content-Length'] = Buffer.byteLength(payload);
+    }
+    const req = transport.request(opts, (res) => {
+      const chunks = [];
+      res.on('data', chunk => chunks.push(chunk));
+      res.on('end', () => {
+        const raw = Buffer.concat(chunks).toString();
+        try {
+          resolve({ status: res.statusCode, body: JSON.parse(raw) });
+        } catch {
+          resolve({ status: res.statusCode, body: raw });
+        }
+      });
+    });
+    req.on('timeout', () => { req.destroy(); reject(new Error('Request timeout')); });
+    req.on('error', reject);
+    if (body) req.write(JSON.stringify(body));
+    req.end();
+  });
+}
+
+/**
+ * Parse SSE text into an array of parsed JSON data payloads.
+ * Each `data: {...}` line is extracted; malformed JSON is silently skipped.
+ * @param {string} text
+ * @returns {object[]}
+ */
+export function parseSseLines(text) {
+  const events = [];
+  for (const block of text.split('\n\n')) {
+    for (const line of block.split('\n')) {
+      if (line.startsWith('data: ')) {
+        try { events.push(JSON.parse(line.slice(6))); } catch { /* skip malformed */ }
+      }
+    }
+  }
+  return events;
+}
+
+/**
+ * @param {{ gateway?: string, enabled?: boolean }} options
+ */
+export function createAgentMuxClient(options = {}) {
+  const { gateway = '', enabled = false } = options;
+
+  return {
+    role: 'agent-mux-client',
+
+    isAvailable() {
+      return enabled && !!gateway;
+    },
+
+    /**
+     * Query adapter capabilities from the gateway.
+     * GET {gateway}/api/v1/agents/{adapter}/capabilities
+     * @param {string} adapter
+     * @returns {Promise<object|null>}
+     */
+    async queryCapabilities(adapter) {
+      if (!this.isAvailable()) return null;
+      try {
+        const { status, body } = await httpRequest(`${gateway}/api/v1/agents/${encodeURIComponent(adapter)}/capabilities`);
+        if (status >= 200 && status < 300) return body;
+        return null;
+      } catch {
+        return null;
+      }
+    },
+
+    /**
+     * Launch a new agent session through the gateway.
+     * POST {gateway}/api/v1/sessions
+     * @param {{ stack: object, contextBundle?: object, permissionSnapshot?: object, workspace?: object }} params
+     * @returns {Promise<{ runId: string, sessionId: string }|null>}
+     */
+    async launchSession({ stack, contextBundle, permissionSnapshot, workspace }) {
+      if (!this.isAvailable()) return null;
+      try {
+        const payload = {
+          agent: stack?.baseAgent,
+          model: stack?.model,
+          prompt: contextBundle?.prompt,
+          systemPrompt: contextBundle?.systemPrompt,
+          attachments: contextBundle?.attachments,
+          workspace: workspace?.mountPath || '/workspace',
+        };
+        const { status, body } = await httpRequest(`${gateway}/api/v1/sessions`, { method: 'POST', body: payload });
+        if (status >= 200 && status < 300 && body?.runId && body?.sessionId) {
+          return { runId: body.runId, sessionId: body.sessionId };
+        }
+        return null;
+      } catch {
+        return null;
+      }
+    },
+
+    /**
+     * Get session status from the gateway.
+     * GET {gateway}/api/v1/sessions/{sessionId}
+     * @param {string} sessionId
+     * @returns {Promise<object|null>}
+     */
+    async getSessionStatus(sessionId) {
+      if (!this.isAvailable()) return null;
+      try {
+        const { status, body } = await httpRequest(`${gateway}/api/v1/sessions/${encodeURIComponent(sessionId)}`);
+        if (status >= 200 && status < 300) return body;
+        return null;
+      } catch {
+        return null;
+      }
+    },
+
+    /**
+     * Subscribe to SSE events for a run. Reconnects with exponential backoff (1s, 2s, 4s... max 30s).
+     * GET {gateway}/api/v1/runs/{runId}/events (Accept: text/event-stream)
+     * @param {string} runId
+     * @param {(event: object) => void} callback
+     * @returns {{ abort: () => void }}
+     */
+    subscribeToEvents(runId, callback) {
+      let aborted = false;
+      let currentReq = null;
+      let backoff = 1000;
+
+      const connect = () => {
+        if (aborted) return;
+        try {
+          const parsed = new URL(`${gateway}/api/v1/runs/${encodeURIComponent(runId)}/events`);
+          const transport = parsed.protocol === 'https:' ? https : http;
+          const opts = {
+            hostname: parsed.hostname,
+            port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+            path: parsed.pathname + parsed.search,
+            method: 'GET',
+            headers: { 'Accept': 'text/event-stream' },
+          };
+          currentReq = transport.request(opts, (res) => {
+            if (aborted) return;
+            // Reset backoff on successful connection
+            backoff = 1000;
+            let buffer = '';
+            res.on('data', (chunk) => {
+              if (aborted) return;
+              buffer += chunk.toString();
+              // Process complete SSE blocks (separated by double newlines)
+              const parts = buffer.split('\n\n');
+              // Keep the last part as it may be incomplete
+              buffer = parts.pop() || '';
+              for (const block of parts) {
+                for (const line of block.split('\n')) {
+                  if (line.startsWith('data: ')) {
+                    try {
+                      callback(JSON.parse(line.slice(6)));
+                    } catch { /* skip malformed */ }
+                  }
+                }
+              }
+            });
+            res.on('end', () => {
+              if (!aborted) reconnect();
+            });
+            res.on('error', () => {
+              if (!aborted) reconnect();
+            });
+          });
+          currentReq.on('error', () => {
+            if (!aborted) reconnect();
+          });
+          currentReq.end();
+        } catch {
+          if (!aborted) reconnect();
+        }
+      };
+
+      const reconnect = () => {
+        if (aborted) return;
+        const delay = backoff;
+        backoff = Math.min(backoff * 2, 30000);
+        setTimeout(connect, delay);
+      };
+
+      connect();
+
+      return {
+        abort() {
+          aborted = true;
+          if (currentReq) {
+            currentReq.destroy();
+            currentReq = null;
+          }
+        }
+      };
+    },
+
+    /**
+     * Reconcile SSE events into an AgentSessionTranscript resource.
+     * Parses events by role, computes cost, creates the resource via createResource().
+     * @param {string} sessionId
+     * @param {object[]} events
+     * @param {{ namespace?: string, organizationRef?: string }} options
+     * @returns {object} AgentSessionTranscript resource
+     */
+    reconcileTranscript(sessionId, events, { namespace = 'default', organizationRef = 'default' } = {}) {
+      const messages = [];
+      let totalInputTokens = 0;
+      let totalOutputTokens = 0;
+
+      for (const event of events) {
+        if (!event || typeof event !== 'object') continue;
+        const role = event.role || 'unknown';
+        const content = event.content || event.text || event.message || '';
+        const node = {
+          role,
+          content: typeof content === 'string' ? content : JSON.stringify(content),
+          timestamp: event.timestamp || new Date().toISOString(),
+        };
+        if (event.toolUse) node.toolUse = event.toolUse;
+        if (event.toolResult) node.toolResult = event.toolResult;
+        messages.push(node);
+
+        // Accumulate token usage if present
+        if (event.usage) {
+          totalInputTokens += event.usage.inputTokens || 0;
+          totalOutputTokens += event.usage.outputTokens || 0;
+        }
+      }
+
+      return createResource(
+        'AgentSessionTranscript',
+        { name: `transcript-${sessionId}`, namespace },
+        {
+          organizationRef,
+          sessionRef: sessionId,
+          messages,
+          cost: {
+            inputTokens: totalInputTokens,
+            outputTokens: totalOutputTokens,
+            totalTokens: totalInputTokens + totalOutputTokens,
+          },
+        },
+        { phase: 'Reconciled', reconciledAt: new Date().toISOString() }
+      );
+    },
+  };
+}