limen-ai 1.0.0

package/dist/substrate/transport/adapters/gemini_adapter.js

@@ -0,0 +1,456 @@
+/**
+ * Google Gemini REST API adapter.
+ * S ref: §25.4 (LLM Gateway), I-01 (no SDK deps), I-04 (provider independence)
+ *
+ * Phase: 5B (Sprint 5B — OpenAI + Google Adapters)
+ * Implements: ProviderAdapter for Google's Gemini REST API.
+ *
+ * Auth: API key in query parameter ?key={key}
+ * URL:
+ *   Non-streaming: {baseUrl}/v1beta/models/{model}:generateContent?key={key}
+ *   Streaming: {baseUrl}/v1beta/models/{model}:streamGenerateContent?key={key}&alt=sse
+ *
+ * C-SEC-P5-03 (CRITICAL): URL credential scrubbing.
+ *   The API key is in the query string. scrubUrl() replaces the key value with [REDACTED].
+ *   This function MUST be called:
+ *     - Before any URL is included in an error message
+ *     - Before any URL is logged
+ *   TransportHttpRequest.url sent to fetch() contains the real key.
+ *   Any error thrown by the adapter must use scrubUrl().
+ *
+ * Request translation: Gemini uses contents[].parts[] format (not messages).
+ *   role: 'user'/'model' (not 'assistant'). System instruction in systemInstruction field.
+ *
+ * Response parsing: candidates[0].content.parts, usageMetadata.promptTokenCount/candidatesTokenCount
+ *
+ * Thinking/Deliberation: usageMetadata.thoughtsTokenCount → provider_authoritative
+ *
+ * Tool calls: Gemini uses functionCall in parts. Map to LlmToolCall.
+ *
+ * Streaming: SSE format. Events contain partial candidates.
+ *
+ * Retryable: 429, 500, 502, 503
+ *
+ * Security:
+ *   - C-SEC-P5-01/02: API key NEVER in error messages (use scrubUrl)
+ *   - C-SEC-P5-03: URL credential scrubbing
+ *   - C-SEC-P5-04 / CR-1: API key resolved ONCE at creation
+ *   - C-SEC-P5-22: Provider output is untrusted input
+ *   - C-SEC-P5-23: Tool call structural validation (functionCall)
+ */
+import { parseSSEStream } from '../stream_parser.js';
+// ─── Constants ───
+/** Retryable HTTP status codes for Gemini */
+const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503]);
+/** C-SEC-P5-23: Valid function name pattern */
+const TOOL_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+// ─── URL Credential Scrubbing (C-SEC-P5-03) ───
+/**
+ * C-SEC-P5-03: Remove API key from a Gemini URL.
+ * Replaces the `key=` query parameter value with [REDACTED].
+ * MUST be called before including any URL in error messages, logs, or metadata.
+ */
+export function scrubUrl(url) {
+    // Replace key=value in query string, handling both ?key=xxx and &key=xxx
+    return url.replace(/([?&])key=[^&]*/g, '$1key=[REDACTED]');
+}
+// ─── Gemini Request Translation ───
+/**
+ * Map Limen LlmContentBlock to Gemini part format.
+ */
+function mapToGeminiPart(block) {
+    switch (block.type) {
+        case 'text':
+            return { text: block.text };
+        case 'image':
+            return {
+                inlineData: {
+                    mimeType: block.mediaType,
+                    data: block.data,
+                },
+            };
+        case 'tool_use':
+            return {
+                functionCall: {
+                    name: block.name,
+                    args: block.input,
+                },
+            };
+        case 'tool_result':
+            return {
+                functionResponse: {
+                    name: block.toolUseId, // Gemini expects the function name, but we use toolUseId as fallback
+                    response: { content: block.content },
+                },
+            };
+        default:
+            return { text: '' };
+    }
+}
+/**
+ * Map Limen role to Gemini role.
+ * Gemini uses 'user' and 'model' (not 'assistant').
+ */
+function mapRole(role) {
+    switch (role) {
+        case 'assistant': return 'model';
+        case 'tool': return 'function';
+        default: return role;
+    }
+}
+// ─── Gemini Tool Call Validation ───
+/**
+ * Validate a Gemini functionCall part into an LlmToolCall.
+ * C-SEC-P5-23: Name must match pattern, args must be an object.
+ * Gemini does not provide a tool call ID — we generate one from the function name.
+ */
+function validateGeminiFunctionCall(fc, index) {
+    const name = fc.name;
+    if (typeof name !== 'string' || !TOOL_NAME_PATTERN.test(name))
+        return null;
+    const args = fc.args;
+    if (typeof args !== 'object' || args === null || Array.isArray(args))
+        return null;
+    // Gemini does not provide IDs — generate a deterministic one
+    const id = `gemini-call-${index}`;
+    return {
+        id,
+        name,
+        input: args,
+    };
+}
+// ─── Gemini Adapter Factory ───
+/**
+ * Create a Google Gemini REST API adapter.
+ *
+ * @param providerId - Provider identifier for health tracking
+ * @param baseUrl - Base URL for the Gemini API (e.g., 'https://generativelanguage.googleapis.com')
+ * @param apiKey - API key (resolved ONCE at creation — CR-1 / C-SEC-P5-04)
+ * @param time - Optional TimeProvider for clock injection
+ */
+export function createGeminiAdapter(providerId, baseUrl, apiKey, time) {
+    // CR-1 / C-SEC-P5-04: Key resolved once at creation
+    const resolvedKey = apiKey;
+    function buildRequest(request, streaming) {
+        // Build contents array (Gemini format: contents[].parts[])
+        const contents = [];
+        for (const msg of request.messages) {
+            if (msg.role === 'system') {
+                // System messages handled via systemInstruction
+                continue;
+            }
+            const parts = [];
+            if (typeof msg.content === 'string') {
+                parts.push({ text: msg.content });
+            }
+            else {
+                const blocks = msg.content;
+                for (const block of blocks) {
+                    parts.push(mapToGeminiPart(block));
+                }
+            }
+            contents.push({
+                role: mapRole(msg.role),
+                parts,
+            });
+        }
+        // Build request body
+        const body = {
+            contents,
+        };
+        // System instruction
+        if (request.systemPrompt) {
+            body.systemInstruction = {
+                parts: [{ text: request.systemPrompt }],
+            };
+        }
+        else {
+            // Check for system messages in the messages array
+            const systemMsgs = request.messages.filter(m => m.role === 'system');
+            if (systemMsgs.length > 0) {
+                const systemText = systemMsgs
+                    .map(m => typeof m.content === 'string' ? m.content : '')
+                    .join('\n');
+                if (systemText) {
+                    body.systemInstruction = {
+                        parts: [{ text: systemText }],
+                    };
+                }
+            }
+        }
+        // Generation config
+        const generationConfig = {
+            maxOutputTokens: request.maxTokens,
+        };
+        if (request.temperature !== undefined) {
+            generationConfig.temperature = request.temperature;
+        }
+        body.generationConfig = generationConfig;
+        // Tools (Gemini format: tools[].functionDeclarations[])
+        if (request.tools && request.tools.length > 0) {
+            body.tools = [{
+                    functionDeclarations: request.tools.map((tool) => ({
+                        name: tool.name,
+                        description: tool.description,
+                        parameters: tool.inputSchema,
+                    })),
+                }];
+        }
+        // URL construction — key in query parameter
+        const action = streaming ? 'streamGenerateContent' : 'generateContent';
+        const streamParam = streaming ? '&alt=sse' : '';
+        const url = `${baseUrl}/v1beta/models/${request.model}:${action}?key=${resolvedKey}${streamParam}`;
+        return {
+            url,
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+            },
+            body,
+            stream: streaming,
+        };
+    }
+    function parseResponse(httpResponse) {
+        // C-SEC-P5-07: JSON parse safety
+        let parsed;
+        try {
+            parsed = JSON.parse(httpResponse.body);
+        }
+        catch {
+            throw new Error(`JSON parse error: invalid response body from ${providerId}`);
+        }
+        // C-SEC-P5-22: Validate structure
+        const candidates = parsed.candidates;
+        if (!Array.isArray(candidates) || candidates.length === 0) {
+            throw new Error(`${providerId} response missing candidates array`);
+        }
+        const firstCandidate = candidates[0];
+        const content = firstCandidate.content;
+        const parts = content?.parts;
+        // Extract content blocks and tool calls
+        const responseBlocks = [];
+        const toolCalls = [];
+        let toolCallIndex = 0;
+        if (Array.isArray(parts)) {
+            for (const part of parts) {
+                if (typeof part !== 'object' || part === null)
+                    continue;
+                if (typeof part.text === 'string') {
+                    responseBlocks.push({ type: 'text', text: part.text });
+                }
+                else if (part.functionCall) {
+                    // C-SEC-P5-23: Validate function call
+                    const fc = part.functionCall;
+                    const validated = validateGeminiFunctionCall(fc, toolCallIndex++);
+                    if (validated) {
+                        toolCalls.push(validated);
+                        responseBlocks.push({
+                            type: 'tool_use',
+                            id: validated.id,
+                            name: validated.name,
+                            input: validated.input,
+                        });
+                    }
+                }
+            }
+        }
+        // Extract usage metadata
+        const usageMetadata = parsed.usageMetadata;
+        const promptTokens = typeof usageMetadata?.promptTokenCount === 'number'
+            ? usageMetadata.promptTokenCount : 0;
+        const candidateTokens = typeof usageMetadata?.candidatesTokenCount === 'number'
+            ? usageMetadata.candidatesTokenCount : 0;
+        // Thinking/Deliberation: thoughtsTokenCount
+        const thoughtsTokenCount = typeof usageMetadata?.thoughtsTokenCount === 'number'
+            ? usageMetadata.thoughtsTokenCount : 0;
+        let deliberation;
+        if (thoughtsTokenCount > 0) {
+            deliberation = {
+                deliberationTokens: thoughtsTokenCount,
+                accountingMode: 'provider_authoritative',
+                providerReportedThinkingTokens: thoughtsTokenCount,
+            };
+        }
+        else {
+            deliberation = {
+                deliberationTokens: 0,
+                accountingMode: 'estimated',
+                providerReportedThinkingTokens: null,
+            };
+        }
+        // Finish reason
+        const rawFinishReason = firstCandidate.finishReason;
+        const finishReason = mapGeminiFinishReason(rawFinishReason, toolCalls.length > 0);
+        const response = {
+            content: responseBlocks.length === 1 && responseBlocks[0]?.type === 'text'
+                ? responseBlocks[0].text
+                : responseBlocks.length > 0 ? responseBlocks : '',
+            toolCalls,
+            finishReason,
+            usage: {
+                inputTokens: promptTokens,
+                outputTokens: candidateTokens,
+                providerInputTokens: promptTokens,
+                providerOutputTokens: candidateTokens,
+            },
+            model: String(parsed.modelVersion ?? ''),
+            providerId,
+            latencyMs: 0, // Filled by transport engine
+        };
+        return {
+            response,
+            deliberation,
+            retryCount: 0, // Filled by transport engine
+            totalMs: 0, // Filled by transport engine
+        };
+    }
+    function parseStream(body, signal) {
+        let deliberation = {
+            deliberationTokens: 0,
+            accountingMode: 'estimated',
+            providerReportedThinkingTokens: null,
+        };
+        let totalMs = 0;
+        const clock = time ?? { nowMs: () => Date.now() }; // clock-exempt: fallback only
+        const streamStart = clock.nowMs();
+        let toolCallIndex = 0;
+        async function* processStream() {
+            for await (const event of parseSSEStream(body, signal, time)) {
+                // Skip empty data
+                if (!event.data || event.data === '[DONE]')
+                    continue;
+                let parsed;
+                try {
+                    parsed = JSON.parse(event.data);
+                }
+                catch {
+                    continue; // Skip unparseable events
+                }
+                // Gemini streaming: each event contains a partial candidate
+                const candidates = parsed.candidates;
+                if (Array.isArray(candidates) && candidates.length > 0) {
+                    const firstCandidate = candidates[0];
+                    const content = firstCandidate.content;
+                    const parts = content?.parts;
+                    if (Array.isArray(parts)) {
+                        for (const part of parts) {
+                            if (typeof part !== 'object' || part === null)
+                                continue;
+                            if (typeof part.text === 'string') {
+                                yield {
+                                    type: 'content_delta',
+                                    delta: part.text,
+                                };
+                            }
+                            else if (part.functionCall) {
+                                const fc = part.functionCall;
+                                const validated = validateGeminiFunctionCall(fc, toolCallIndex++);
+                                if (validated) {
+                                    // Emit as tool_call_delta (Gemini sends complete tool calls, not deltas)
+                                    yield {
+                                        type: 'tool_call_delta',
+                                        toolCallId: validated.id,
+                                        name: validated.name,
+                                        inputDelta: JSON.stringify(validated.input),
+                                    };
+                                }
+                            }
+                        }
+                    }
+                    // Check finish reason
+                    const finishReason = firstCandidate.finishReason;
+                    if (finishReason && finishReason !== 'FINISH_REASON_UNSPECIFIED') {
+                        yield {
+                            type: 'done',
+                            finishReason: mapGeminiFinishReason(finishReason, false),
+                        };
+                    }
+                }
+                // Usage metadata (Gemini sends this with the final chunk)
+                const usageMetadata = parsed.usageMetadata;
+                if (usageMetadata) {
+                    const promptTokens = typeof usageMetadata.promptTokenCount === 'number'
+                        ? usageMetadata.promptTokenCount : 0;
+                    const candidateTokens = typeof usageMetadata.candidatesTokenCount === 'number'
+                        ? usageMetadata.candidatesTokenCount : 0;
+                    yield {
+                        type: 'usage',
+                        inputTokens: promptTokens,
+                        outputTokens: candidateTokens,
+                    };
+                    // Update deliberation from usage metadata
+                    const thoughtsTokenCount = typeof usageMetadata.thoughtsTokenCount === 'number'
+                        ? usageMetadata.thoughtsTokenCount : 0;
+                    if (thoughtsTokenCount > 0) {
+                        deliberation = {
+                            deliberationTokens: thoughtsTokenCount,
+                            accountingMode: 'provider_authoritative',
+                            providerReportedThinkingTokens: thoughtsTokenCount,
+                        };
+                    }
+                }
+            }
+            // Set timing after stream completes
+            totalMs = clock.nowMs() - streamStart;
+        }
+        return {
+            stream: processStream(),
+            getDeliberation: () => deliberation,
+            getTotalMs: () => totalMs || (clock.nowMs() - streamStart),
+        };
+    }
+    function supportsStreaming() {
+        return true;
+    }
+    function isRetryableStatus(status) {
+        return RETRYABLE_STATUS_CODES.has(status);
+    }
+    const adapter = {
+        providerId,
+        buildRequest,
+        parseResponse,
+        parseStream,
+        supportsStreaming,
+        isRetryableStatus,
+    };
+    return Object.freeze(adapter);
+}
+/**
+ * Create a Gemini adapter with API key from environment variable.
+ * C-SEC-P5-01/02: Key is read from env and NEVER logged.
+ * CR-1: Key resolved once at creation.
+ *
+ * @param providerId - Provider identifier
+ * @param baseUrl - Base URL (e.g., 'https://generativelanguage.googleapis.com')
+ * @param apiKeyEnvVar - Environment variable name containing the API key
+ * @param time - Optional TimeProvider
+ * @throws Error if API key env var is not set (message does NOT include key value)
+ */
+export function createGeminiAdapterFromEnv(providerId, baseUrl, apiKeyEnvVar, time) {
+    const apiKey = process.env[apiKeyEnvVar];
+    // C-SEC-P5-01: NEVER include the key value in error messages
+    if (!apiKey) {
+        throw new Error(`TRANSPORT_MISSING_API_KEY: API key environment variable is not set. Provider: ${providerId}`);
+    }
+    return createGeminiAdapter(providerId, baseUrl, apiKey, time);
+}
+// ─── Helpers ───
+/**
+ * Map Gemini finishReason to Limen finish reason.
+ */
+function mapGeminiFinishReason(reason, hasToolCalls) {
+    switch (reason) {
+        case 'STOP':
+            return hasToolCalls ? 'tool_use' : 'stop';
+        case 'MAX_TOKENS':
+            return 'length';
+        case 'SAFETY':
+        case 'RECITATION':
+            return 'content_filter';
+        default:
+            return hasToolCalls ? 'tool_use' : 'stop';
+    }
+}
+// ─── Exported for testing ───
+export { RETRYABLE_STATUS_CODES, TOOL_NAME_PATTERN, validateGeminiFunctionCall, mapGeminiFinishReason };
+//# sourceMappingURL=gemini_adapter.js.map

package/dist/substrate/transport/adapters/gemini_adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini_adapter.js","sourceRoot":"","sources":["../../../../src/substrate/transport/adapters/gemini_adapter.ts"],"names":[],"mappings":"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"}

package/dist/substrate/transport/adapters/groq_adapter.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Groq API adapter (OpenAI-compatible Chat Completions format).
+ * S ref: §25.4 (LLM Gateway), I-01 (no SDK deps), I-04 (provider independence)
+ *
+ * Phase: 5C (Sprint 5C — Ollama + Groq + Mistral Adapters)
+ * Implements: ProviderAdapter for Groq's OpenAI-compatible Chat Completions API.
+ *
+ * Groq speaks the OpenAI Chat Completions wire format — this is a thin wrapper
+ * around openai_compat.ts shared functions. Minimal adapter.
+ *
+ * Auth: Authorization: Bearer {key} — same as OpenAI
+ * URL: {baseUrl}/openai/v1/chat/completions (default baseUrl: https://api.groq.com)
+ * Request: Delegates to buildOpenAICompatRequest() from openai_compat.ts
+ * Response: Delegates to parseOpenAICompatResponse() from openai_compat.ts
+ * Streaming: SSE via parseSSEStream() — same pattern as OpenAI Chat Completions
+ * Deliberation: Always estimated with 0 tokens (Groq does not report reasoning tokens)
+ *
+ * Security:
+ *   - C-SEC-P5-01/02: API key NEVER in logs or error messages
+ *   - C-SEC-P5-04 / CR-1: API key resolved ONCE at creation
+ *   - C-SEC-P5-22: Provider output is untrusted input
+ *   - C-SEC-P5-23: Tool call structural validation (via openai_compat)
+ *
+ * Retryable: 429, 500, 502, 503
+ */
+import type { ProviderAdapter } from '../transport_types.js';
+import type { TimeProvider } from '../../../kernel/interfaces/time.js';
+/** Retryable HTTP status codes for Groq */
+declare const RETRYABLE_STATUS_CODES: Set<number>;
+/**
+ * Create a Groq API adapter.
+ *
+ * @param providerId - Provider identifier for health tracking
+ * @param baseUrl - Base URL for the Groq API (e.g., 'https://api.groq.com')
+ * @param apiKey - API key (resolved ONCE at creation — CR-1 / C-SEC-P5-04)
+ * @param time - Optional TimeProvider for clock injection (Hard Stop #7)
+ */
+export declare function createGroqAdapter(providerId: string, baseUrl: string, apiKey: string, time?: TimeProvider): ProviderAdapter;
+/**
+ * Create a Groq adapter with API key from environment variable.
+ * C-SEC-P5-01/02: Key is read from env and NEVER logged.
+ * CR-1: Key resolved once at creation.
+ *
+ * @param providerId - Provider identifier (defaults to 'groq')
+ * @param time - Optional TimeProvider
+ * @throws Error if GROQ_API_KEY env var is not set (message does NOT include key value)
+ */
+export declare function createGroqAdapterFromEnv(providerId?: string, time?: TimeProvider): ProviderAdapter;
+export { RETRYABLE_STATUS_CODES };
+//# sourceMappingURL=groq_adapter.d.ts.map

package/dist/substrate/transport/adapters/groq_adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groq_adapter.d.ts","sourceRoot":"","sources":["../../../../src/substrate/transport/adapters/groq_adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EACV,eAAe,EAMhB,MAAM,uBAAuB,CAAC;AAU/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAIvE,2CAA2C;AAC3C,QAAA,MAAM,sBAAsB,aAAgC,CAAC;AAI7D;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,YAAY,GAClB,eAAe,CA4IjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,GAAE,MAAe,EAC3B,IAAI,CAAC,EAAE,YAAY,GAClB,eAAe,CAWjB;AAGD,OAAO,EAAE,sBAAsB,EAAE,CAAC"}