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

package/src/assistant-runtime.js

@@ -0,0 +1,284 @@
+import { randomUUID } from 'node:crypto';
+import http from 'node:http';
+import https from 'node:https';
+import { URL } from 'node:url';
+
+export const ASSISTANT_RUNTIME_BOUNDARY = {
+  role: 'assistant-runtime',
+  scope: 'In-process agent runtime for chat sessions and structured agentic calls via AgentStack CRDs',
+  owns: ['chat sessions', 'message history', 'model API calls', 'structured agentic calls', 'session lifecycle'],
+  delegatesTo: ['resource-model', 'agent-stack-controller', 'agent-mux-client'],
+  mustNotOwn: ['secret values', 'K8s Job dispatch', 'resource persistence'],
+};
+
+/**
+ * Default assistant stack configuration used when no CRD is found.
+ * @returns {object}
+ */
+export function defaultAssistantConfig() {
+  return {
+    baseAgent: 'kradle-assistant',
+    provider: process.env.KRADLE_ASSISTANT_PROVIDER || 'anthropic',
+    model: process.env.KRADLE_ASSISTANT_MODEL || 'claude-sonnet-4-6',
+    systemPrompt: `You are the Kradle Assistant — an AI agent embedded in the Kradle Kubernetes-native forge. You help users manage repositories, agent stacks, workspaces, deployments, and policies. You have access to kradle MCP tools for resource management and Atlas graph for knowledge queries.`,
+    approvalMode: 'prompt',
+  };
+}
+
+/**
+ * Default system prompt for the assistant.
+ * @returns {string}
+ */
+export function defaultSystemPrompt() {
+  return `You are the Kradle Assistant — an AI agent embedded in the Kradle Kubernetes-native forge platform.
+
+You help users with:
+- Managing repositories, branches, and pull requests
+- Configuring agent stacks and dispatching agent runs
+- Managing workspaces and codespaces
+- Querying the Atlas knowledge graph
+- Configuring external provider integrations
+- Managing secrets, policies, and permissions
+
+You have access to MCP tools for direct resource management. Be concise and helpful.`;
+}
+
+/**
+ * Call a model via the Anthropic Messages API.
+ * Uses node:http/node:https — zero external deps.
+ *
+ * @param {{ provider: string, model: string, messages: object[], tools?: object[], maxTokens?: number, responseFormat?: string, apiKey?: string, fetchImpl?: Function }} params
+ * @returns {Promise<{ content: string, usage: object, stopReason?: string, toolCalls?: object[] }>}
+ */
+export async function callModel({ provider, model, messages, tools, maxTokens, responseFormat, apiKey, baseUrl, fetchImpl } = {}) {
+  const resolvedProvider = provider || process.env.KRADLE_ASSISTANT_PROVIDER || 'anthropic';
+
+  if (resolvedProvider === 'anthropic') {
+    return callAnthropicModel({ model, messages, tools, maxTokens, apiKey, fetchImpl });
+  }
+
+  return callOpenAICompatibleModel({ provider: resolvedProvider, model, messages, tools, maxTokens, apiKey, baseUrl, fetchImpl });
+}
+
+async function callAnthropicModel({ model, messages, tools, maxTokens, apiKey, fetchImpl }) {
+  const resolvedKey = apiKey || process.env.ANTHROPIC_API_KEY || process.env.KRADLE_ASSISTANT_API_KEY;
+  if (!resolvedKey) {
+    return { content: 'Anthropic API key not configured. Set ANTHROPIC_API_KEY or KRADLE_ASSISTANT_API_KEY.', usage: {} };
+  }
+
+  const systemMessage = messages.find(m => m.role === 'system');
+  const nonSystemMessages = messages.filter(m => m.role !== 'system');
+
+  const body = {
+    model: model || 'claude-sonnet-4-6',
+    max_tokens: maxTokens || 4096,
+    messages: nonSystemMessages,
+    ...(systemMessage ? { system: systemMessage.content } : {}),
+    ...(tools?.length ? { tools } : {}),
+  };
+
+  const doFetch = fetchImpl || globalThis.fetch;
+
+  try {
+    const res = await doFetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': resolvedKey,
+        'anthropic-version': '2023-06-01',
+      },
+      body: JSON.stringify(body),
+    });
+    const data = await res.json();
+    if (!res.ok) return { content: data.error?.message || 'Model API error', usage: {} };
+    return {
+      content: data.content?.map(b => b.text || '').join('') || '',
+      usage: data.usage || {},
+      stopReason: data.stop_reason,
+      toolCalls: data.content?.filter(b => b.type === 'tool_use') || [],
+    };
+  } catch (err) {
+    return { content: `Error calling model: ${err.message}`, usage: {} };
+  }
+}
+
+async function callOpenAICompatibleModel({ provider, model, messages, tools, maxTokens, apiKey, baseUrl, fetchImpl }) {
+  const resolvedKey = apiKey || process.env.AZURE_API_KEY || process.env.OPENAI_API_KEY || process.env.KRADLE_ASSISTANT_API_KEY;
+  const resolvedBase = baseUrl || process.env.KRADLE_ASSISTANT_BASE_URL || process.env.AGENT_MUX_API_BASE;
+
+  if (!resolvedKey) {
+    return { content: `API key not configured for ${provider}. Set AZURE_API_KEY, OPENAI_API_KEY, or KRADLE_ASSISTANT_API_KEY.`, usage: {} };
+  }
+  if (!resolvedBase) {
+    return { content: `Base URL not configured for ${provider}. Set KRADLE_ASSISTANT_BASE_URL or AGENT_MUX_API_BASE.`, usage: {} };
+  }
+
+  const endpoint = resolvedBase.replace(/\/$/, '') + '/openai/deployments/' + (model || 'gpt-5.5') + '/chat/completions?api-version=2024-12-01-preview';
+
+  const body = {
+    messages,
+    max_tokens: maxTokens || 4096,
+    ...(tools?.length ? { tools: tools.map(t => ({ type: 'function', function: t })) } : {}),
+  };
+
+  const doFetch = fetchImpl || globalThis.fetch;
+
+  try {
+    const res = await doFetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'api-key': resolvedKey,
+      },
+      body: JSON.stringify(body),
+    });
+    const data = await res.json();
+    if (!res.ok) return { content: data.error?.message || `${provider} API error: ${res.status}`, usage: {} };
+    const choice = data.choices?.[0]?.message;
+    return {
+      content: choice?.content || '',
+      usage: data.usage ? { input_tokens: data.usage.prompt_tokens, output_tokens: data.usage.completion_tokens } : {},
+      stopReason: data.choices?.[0]?.finish_reason,
+      toolCalls: choice?.tool_calls || [],
+    };
+  } catch (err) {
+    return { content: `Error calling ${provider} model: ${err.message}`, usage: {} };
+  }
+}
+
+/**
+ * Create an in-process assistant runtime that reads config from AgentStack CRDs,
+ * manages chat sessions with message history, and supports structured agentic calls.
+ *
+ * @param {{ stackName?: string, apiKey?: string, fetchImpl?: Function }} options
+ * @returns {object} Assistant runtime object
+ */
+export function createAssistantRuntime(options = {}) {
+  const stackName = options.stackName || 'assistant';
+  const sessions = new Map();
+
+  return {
+    role: 'assistant-runtime',
+
+    /**
+     * Resolve stack config from a controller's AgentStack CRD, falling back to defaults.
+     * @param {object} controller - Object with getResource(kind, name) method
+     * @param {string} [stackNameOverride]
+     * @returns {Promise<object>}
+     */
+    async resolveConfig(controller, stackNameOverride) {
+      const name = stackNameOverride || stackName;
+      if (!controller) return defaultAssistantConfig();
+      try {
+        const result = await controller.getResource('AgentStack', name);
+        return result.resource?.spec || defaultAssistantConfig();
+      } catch {
+        return defaultAssistantConfig();
+      }
+    },
+
+    /**
+     * Create a new chat session.
+     * @param {string} [sessionId] - Optional session ID; auto-generated if omitted.
+     * @param {string} [stackRef] - Stack name reference; defaults to the runtime's stackName.
+     * @returns {object} Session object with id, messages, createdAt, stackRef, status.
+     */
+    createSession(sessionId, stackRef) {
+      const session = {
+        id: sessionId || randomUUID(),
+        messages: [],
+        createdAt: new Date().toISOString(),
+        stackRef: stackRef || stackName,
+        status: 'active',
+      };
+      sessions.set(session.id, session);
+      return session;
+    },
+
+    /**
+     * Send a message in a session and receive the assistant's response.
+     * @param {string} sessionId
+     * @param {string} message
+     * @param {{ controller?: object, tools?: object[], maxTokens?: number }} opts
+     * @returns {Promise<object>} Model response with content, usage, stopReason, toolCalls.
+     */
+    async chat(sessionId, message, opts = {}) {
+      const session = sessions.get(sessionId);
+      if (!session) throw new Error(`Session ${sessionId} not found`);
+
+      session.messages.push({ role: 'user', content: message, timestamp: new Date().toISOString() });
+
+      const config = await this.resolveConfig(opts.controller, session.stackRef);
+      const systemPromptText = config.systemPrompt || defaultSystemPrompt();
+
+      const response = await callModel({
+        provider: config.provider || 'anthropic',
+        model: config.model || 'claude-sonnet-4-20250514',
+        messages: [
+          { role: 'system', content: systemPromptText },
+          ...session.messages.map(m => ({ role: m.role, content: m.content })),
+        ],
+        tools: opts.tools || [],
+        maxTokens: opts.maxTokens || 4096,
+        apiKey: options.apiKey,
+        fetchImpl: options.fetchImpl,
+      });
+
+      session.messages.push({ role: 'assistant', content: response.content, timestamp: new Date().toISOString() });
+      return response;
+    },
+
+    /**
+     * Get a session by ID.
+     * @param {string} sessionId
+     * @returns {object|null}
+     */
+    getSession(sessionId) {
+      return sessions.get(sessionId) || null;
+    },
+
+    /**
+     * List all active sessions.
+     * @returns {object[]}
+     */
+    listSessions() {
+      return [...sessions.values()];
+    },
+
+    /**
+     * Delete a session by ID.
+     * @param {string} sessionId
+     * @returns {boolean}
+     */
+    deleteSession(sessionId) {
+      return sessions.delete(sessionId);
+    },
+
+    /**
+     * Structured agentic call (non-chat, single-shot).
+     * @param {string|object} task - Task description or structured task object.
+     * @param {{ controller?: object, stackRef?: string, systemPrompt?: string, tools?: object[], maxTokens?: number, responseFormat?: string }} opts
+     * @returns {Promise<object>} Model response.
+     */
+    async structuredCall(task, opts = {}) {
+      const config = await this.resolveConfig(opts.controller, opts.stackRef);
+      const systemPromptText = opts.systemPrompt || config.systemPrompt || defaultSystemPrompt();
+
+      const response = await callModel({
+        provider: config.provider || 'anthropic',
+        model: config.model || 'claude-sonnet-4-20250514',
+        messages: [
+          { role: 'system', content: systemPromptText },
+          { role: 'user', content: typeof task === 'string' ? task : JSON.stringify(task) },
+        ],
+        tools: opts.tools || [],
+        maxTokens: opts.maxTokens || 8192,
+        responseFormat: opts.responseFormat,
+        apiKey: options.apiKey,
+        fetchImpl: options.fetchImpl,
+      });
+
+      return response;
+    },
+  };
+}

package/src/async-controller.js

@@ -0,0 +1,207 @@
+/**
+ * Async controller utilities for event batching, retry policies, delivery queues,
+ * and checkpoint persistence.
+ */
+
+// ---------------------------------------------------------------------------
+// Event batcher
+// ---------------------------------------------------------------------------
+
+/**
+ * Accumulates events and flushes them in batches either when the batch is full
+ * or when the flush interval expires.
+ *
+ * @param {(events: any[]) => void | Promise<void>} handler - Called with each flushed batch.
+ * @param {{ maxBatchSize?: number, flushIntervalMs?: number }} [options]
+ * @returns {{ push(event: any): void, flush(): Promise<void>, stop(): void }}
+ */
+export function createEventBatcher(handler, { maxBatchSize = 50, flushIntervalMs = 1000 } = {}) {
+  let batch = [];
+  let timer = null;
+
+  function scheduleFlush() {
+    if (timer !== null) return;
+    timer = setTimeout(async () => {
+      timer = null;
+      await flushNow();
+    }, flushIntervalMs);
+  }
+
+  async function flushNow() {
+    if (batch.length === 0) return;
+    const toFlush = batch;
+    batch = [];
+    await handler(toFlush);
+  }
+
+  return {
+    push(event) {
+      batch.push(event);
+      if (batch.length >= maxBatchSize) {
+        if (timer !== null) {
+          clearTimeout(timer);
+          timer = null;
+        }
+        // Fire-and-forget the synchronous portion; handler may return a Promise
+        const toFlush = batch;
+        batch = [];
+        Promise.resolve(handler(toFlush)).catch(() => {});
+      } else {
+        scheduleFlush();
+      }
+    },
+    async flush() {
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      await flushNow();
+    },
+    stop() {
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      batch = [];
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Retry policy
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a retry policy with exponential backoff and optional jitter.
+ *
+ * @param {{ maxRetries?: number, baseDelayMs?: number, maxDelayMs?: number, jitter?: boolean }} [options]
+ * @returns {{ shouldRetry(attempt: number, error: any): boolean, getDelay(attempt: number): number }}
+ */
+export function createRetryPolicy({ maxRetries = 3, baseDelayMs = 1000, maxDelayMs = 30000, jitter = true } = {}) {
+  return {
+    /**
+     * Returns true if another attempt should be made.
+     * @param {number} attempt - 0-based number of the attempt that just failed.
+     */
+    shouldRetry(attempt, _error) {
+      return attempt < maxRetries;
+    },
+    /**
+     * Returns the delay in ms to wait before the next attempt.
+     * @param {number} attempt - 0-based number of the attempt that just failed.
+     */
+    getDelay(attempt) {
+      const exponential = baseDelayMs * Math.pow(2, attempt);
+      const capped = Math.min(exponential, maxDelayMs);
+      if (!jitter) return capped;
+      // Full-jitter: random value in [0, capped]
+      return Math.floor(Math.random() * (capped + 1));
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Delivery queue
+// ---------------------------------------------------------------------------
+
+/**
+ * In-memory ordered queue with configurable concurrency and optional retry support.
+ *
+ * @param {(item: any) => Promise<void>} processor - Called for each dequeued item.
+ * @param {{ concurrency?: number, retryPolicy?: ReturnType<typeof createRetryPolicy> }} [options]
+ * @returns {{ enqueue(item: any): void, drain(): Promise<void>, size(): number, stop(): void }}
+ */
+export function createDeliveryQueue(processor, { concurrency = 5, retryPolicy } = {}) {
+  const queue = [];
+  let active = 0;
+  let stopped = false;
+  /** @type {Array<() => void>} */
+  let drainResolvers = [];
+
+  function checkDrain() {
+    if (active === 0 && queue.length === 0) {
+      for (const resolve of drainResolvers) resolve();
+      drainResolvers = [];
+    }
+  }
+
+  async function processItem(item) {
+    let attempt = 0;
+    while (true) {
+      try {
+        await processor(item);
+        return;
+      } catch (err) {
+        if (retryPolicy && retryPolicy.shouldRetry(attempt, err)) {
+          const delay = retryPolicy.getDelay(attempt);
+          attempt++;
+          if (delay > 0) await new Promise((r) => setTimeout(r, delay));
+        } else {
+          // Swallow the error; callers can handle via processor rejections externally
+          return;
+        }
+      }
+    }
+  }
+
+  function tick() {
+    while (!stopped && queue.length > 0 && active < concurrency) {
+      const item = queue.shift();
+      active++;
+      processItem(item).finally(() => {
+        active--;
+        tick();
+        checkDrain();
+      });
+    }
+    if (!stopped) checkDrain();
+  }
+
+  return {
+    enqueue(item) {
+      if (stopped) return;
+      queue.push(item);
+      tick();
+    },
+    drain() {
+      if (active === 0 && queue.length === 0) return Promise.resolve();
+      return new Promise((resolve) => drainResolvers.push(resolve));
+    },
+    size() {
+      return queue.length + active;
+    },
+    stop() {
+      stopped = true;
+      queue.length = 0;
+      for (const resolve of drainResolvers) resolve();
+      drainResolvers = [];
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Checkpointer
+// ---------------------------------------------------------------------------
+
+/**
+ * Simple key-value checkpoint persistence backed by any Map-like storage.
+ *
+ * @param {Map<string, any>} [storage]
+ * @returns {{ save(key: string, value: any): void, load(key: string): any, clear(key: string): void, listKeys(): string[] }}
+ */
+export function createCheckpointer(storage = new Map()) {
+  return {
+    save(key, value) {
+      storage.set(key, value);
+    },
+    load(key) {
+      return storage.has(key) ? storage.get(key) : undefined;
+    },
+    clear(key) {
+      storage.delete(key);
+    },
+    listKeys() {
+      return Array.from(storage.keys());
+    },
+  };
+}

package/src/audit-controller.js

@@ -0,0 +1,191 @@
+/**
+ * Audit Controller — Org-scoped audit log, event streaming, smart polling with
+ * exponential backoff, replay on reconnect, and metrics aggregation.
+ *
+ * @module audit-controller
+ */
+
+export const AUDIT_CONTROLLER_BOUNDARY = {
+  role: 'audit-controller',
+  scope: 'Org-scoped audit log — event recording, streaming, replay, metrics',
+  owns: ['audit events', 'event streaming', 'event polling', 'audit metrics'],
+  delegatesTo: [],
+  mustNotOwn: ['identity management', 'resource storage', 'git operations'],
+};
+
+// ─── AuditController ─────────────────────────────────────────────────────────
+
+/**
+ * Create an in-memory audit controller.
+ *
+ * @returns {{
+ *   log: Function,
+ *   query: Function,
+ *   getStream: Function,
+ *   getMetrics: Function,
+ * }}
+ */
+export function createAuditController() {
+  /** @type {Array<AuditEvent>} */
+  const store = [];
+  let seq = 0;
+
+  return {
+    role: 'audit-controller',
+
+    /**
+     * Record an audit event.
+     *
+     * @param {{ org: string, actor?: string, action: string, resource?: object, timestamp?: string }} params
+     * @returns {AuditEvent}
+     */
+    log({ org, actor = 'system', action, resource = {}, timestamp } = {}) {
+      if (!org || typeof org !== 'string') {
+        throw new Error('audit.log: org is required');
+      }
+      if (!action || typeof action !== 'string') {
+        throw new Error('audit.log: action is required');
+      }
+
+      const event = {
+        id: ++seq,
+        org,
+        actor,
+        action,
+        resource: Object.assign({}, resource),
+        timestamp: timestamp || new Date().toISOString(),
+      };
+
+      store.push(event);
+      return Object.assign({}, event);
+    },
+
+    /**
+     * Query audit events with filtering and pagination.
+     *
+     * @param {{ org?: string, action?: string, since?: string, until?: string, limit?: number, offset?: number }} params
+     * @returns {{ events: AuditEvent[], total: number }}
+     */
+    query({ org, action, since, until, limit, offset = 0 } = {}) {
+      let filtered = store.slice();
+
+      if (org) filtered = filtered.filter(e => e.org === org);
+      if (action) filtered = filtered.filter(e => e.action === action);
+
+      if (since) {
+        const sinceMs = new Date(since).getTime();
+        filtered = filtered.filter(e => new Date(e.timestamp).getTime() >= sinceMs);
+      }
+      if (until) {
+        const untilMs = new Date(until).getTime();
+        filtered = filtered.filter(e => new Date(e.timestamp).getTime() <= untilMs);
+      }
+
+      // reverse chronological
+      filtered = filtered.slice().sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+
+      const total = filtered.length;
+      filtered = filtered.slice(offset);
+      if (limit != null) filtered = filtered.slice(0, limit);
+
+      return { events: filtered.map(e => Object.assign({}, e)), total };
+    },
+
+    /**
+     * Return all events after the given sequence number for a given org (event replay).
+     *
+     * @param {{ org?: string, afterSeq: number }} params
+     * @returns {{ events: AuditEvent[], lastSeq: number }}
+     */
+    getStream({ org, afterSeq = 0 } = {}) {
+      let filtered = store.filter(e => e.id > afterSeq);
+      if (org) filtered = filtered.filter(e => e.org === org);
+      // chronological order for stream replay
+      filtered = filtered.slice().sort((a, b) => a.id - b.id);
+      return {
+        events: filtered.map(e => Object.assign({}, e)),
+        lastSeq: filtered.length > 0 ? filtered[filtered.length - 1].id : afterSeq,
+      };
+    },
+
+    /**
+     * Aggregate audit metrics for an org.
+     *
+     * @param {{ org?: string }} params
+     * @returns {{ byAction: object, byOrg: object, byHour: object, total: number }}
+     */
+    getMetrics({ org } = {}) {
+      let events = store.slice();
+      if (org) events = events.filter(e => e.org === org);
+
+      const byAction = {};
+      const byOrg = {};
+      const byHour = {};
+
+      for (const event of events) {
+        byAction[event.action] = (byAction[event.action] || 0) + 1;
+        byOrg[event.org] = (byOrg[event.org] || 0) + 1;
+        // hour key: "2026-05-13T10" (drop minutes/seconds)
+        const hourKey = event.timestamp.slice(0, 13);
+        byHour[hourKey] = (byHour[hourKey] || 0) + 1;
+      }
+
+      return { byAction, byOrg, byHour, total: events.length };
+    },
+  };
+}
+
+// ─── EventPoller ─────────────────────────────────────────────────────────────
+
+/**
+ * Create a smart event poller with exponential backoff.
+ *
+ * When polls return no new events the backoff interval doubles (up to maxBackoff).
+ * When new events arrive the backoff resets to initialBackoff.
+ *
+ * @param {{ controller: object, org?: string, initialBackoff?: number, maxBackoff?: number }} options
+ * @returns {{ poll: Function, getBackoff: Function, reset: Function }}
+ */
+export function createEventPoller({ controller, org, initialBackoff = 1000, maxBackoff = 30000 } = {}) {
+  let lastSeq = 0;
+  let currentBackoff = initialBackoff;
+
+  return {
+    /**
+     * Poll for new events.  Updates backoff state.
+     * @returns {{ events: AuditEvent[], lastSeq: number }}
+     */
+    poll() {
+      const result = controller.getStream({ org, afterSeq: lastSeq });
+      if (result.events.length > 0) {
+        // New events — reset backoff and advance cursor
+        lastSeq = result.lastSeq;
+        currentBackoff = initialBackoff;
+      } else {
+        // No new events — double the backoff, capped at maxBackoff
+        currentBackoff = Math.min(currentBackoff * 2, maxBackoff);
+      }
+      return result;
+    },
+
+    /**
+     * Get the current backoff interval in milliseconds.
+     * @returns {number}
+     */
+    getBackoff() {
+      return currentBackoff;
+    },
+
+    /**
+     * Reset the poller cursor and backoff to their initial states.
+     */
+    reset() {
+      lastSeq = 0;
+      currentBackoff = initialBackoff;
+    },
+  };
+}
+
+/**
+ * @typedef {{ id: number, org: string, actor: string, action: string, resource: object, timestamp: string }} AuditEvent
+ */