@aexol/spectral 0.7.0 → 0.7.3

package/dist/pi/ai/providers/openai-prompt-cache.js

@@ -0,0 +1,9 @@
+export const OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH = 64;
+export function clampOpenAIPromptCacheKey(key) {
+    if (key === undefined)
+        return undefined;
+    const chars = Array.from(key);
+    if (chars.length <= OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH)
+        return key;
+    return chars.slice(0, OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH).join("");
+}

package/dist/pi/ai/providers/register-builtins.js

@@ -0,0 +1,97 @@
+import { clearApiProviders, registerApiProvider } from "../api-registry.js";
+import { AssistantMessageEventStream } from "../utils/event-stream.js";
+function createLazyErrorMessage(model, error) {
+    return {
+        role: "assistant",
+        content: [],
+        api: model.api,
+        provider: model.provider,
+        model: model.id,
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+        stopReason: "error",
+        errorMessage: error instanceof Error ? error.message : String(error),
+        timestamp: Date.now(),
+    };
+}
+function forwardStream(target, source) {
+    (async () => {
+        for await (const event of source)
+            target.push(event);
+        target.end();
+    })();
+}
+function createLazyStream(loadModule) {
+    return (model, context, options) => {
+        const outer = new AssistantMessageEventStream();
+        loadModule()
+            .then((mod) => {
+            const inner = mod.stream(model, context, options);
+            forwardStream(outer, inner);
+        })
+            .catch((error) => {
+            const message = createLazyErrorMessage(model, error);
+            outer.push({ type: "error", reason: "error", error: message });
+            outer.end(message);
+        });
+        return outer;
+    };
+}
+function createLazySimpleStream(loadModule) {
+    return (model, context, options) => {
+        const outer = new AssistantMessageEventStream();
+        loadModule()
+            .then((mod) => {
+            const inner = mod.streamSimple(model, context, options);
+            forwardStream(outer, inner);
+        })
+            .catch((error) => {
+            const message = createLazyErrorMessage(model, error);
+            outer.push({ type: "error", reason: "error", error: message });
+            outer.end(message);
+        });
+        return outer;
+    };
+}
+let anthropicProviderPromise;
+function loadAnthropic() {
+    anthropicProviderPromise ||= import("./anthropic.js").then((mod) => {
+        const m = mod;
+        return { stream: m.streamAnthropic, streamSimple: m.streamSimpleAnthropic };
+    });
+    return anthropicProviderPromise;
+}
+let openaiCompletionsPromise;
+function loadOpenAICompletions() {
+    openaiCompletionsPromise ||= import("./openai-completions.js").then((mod) => {
+        const m = mod;
+        return { stream: m.streamOpenAICompletions, streamSimple: m.streamSimpleOpenAICompletions };
+    });
+    return openaiCompletionsPromise;
+}
+// ─── Exports ──────────────────────────────────────────────────────────
+export const streamAnthropic = createLazyStream(loadAnthropic);
+export const streamSimpleAnthropic = createLazySimpleStream(loadAnthropic);
+export const streamOpenAICompletions = createLazyStream(loadOpenAICompletions);
+export const streamSimpleOpenAICompletions = createLazySimpleStream(loadOpenAICompletions);
+/**
+ * Register only the API providers needed by Aexol AI proxy:
+ * - anthropic-messages (Claude models routed through backend)
+ * - openai-completions (OpenAI-compatible models routed through backend)
+ */
+export function registerBuiltInApiProviders() {
+    registerApiProvider({
+        api: "anthropic-messages",
+        stream: streamAnthropic,
+        streamSimple: streamSimpleAnthropic,
+    });
+    registerApiProvider({
+        api: "openai-completions",
+        stream: streamOpenAICompletions,
+        streamSimple: streamSimpleOpenAICompletions,
+    });
+}
+export function resetApiProviders() {
+    clearApiProviders();
+    registerBuiltInApiProviders();
+}
+registerBuiltInApiProviders();

package/dist/pi/ai/providers/simple-options.js

@@ -0,0 +1,40 @@
+export function buildBaseOptions(_model, options, apiKey) {
+    return {
+        temperature: options?.temperature,
+        maxTokens: options?.maxTokens,
+        signal: options?.signal,
+        apiKey: apiKey || options?.apiKey,
+        transport: options?.transport,
+        cacheRetention: options?.cacheRetention,
+        sessionId: options?.sessionId,
+        headers: options?.headers,
+        onPayload: options?.onPayload,
+        onResponse: options?.onResponse,
+        timeoutMs: options?.timeoutMs,
+        maxRetries: options?.maxRetries,
+        maxRetryDelayMs: options?.maxRetryDelayMs,
+        metadata: options?.metadata,
+    };
+}
+export function clampReasoning(effort) {
+    return effort === "xhigh" ? "high" : effort;
+}
+export function adjustMaxTokensForThinking(
+// Undefined means no explicit caller cap. Use the model cap and fit thinking inside it.
+baseMaxTokens, modelMaxTokens, reasoningLevel, customBudgets) {
+    const defaultBudgets = {
+        minimal: 1024,
+        low: 2048,
+        medium: 8192,
+        high: 16384,
+    };
+    const budgets = { ...defaultBudgets, ...customBudgets };
+    const minOutputTokens = 1024;
+    const level = clampReasoning(reasoningLevel);
+    let thinkingBudget = budgets[level];
+    const maxTokens = baseMaxTokens === undefined ? modelMaxTokens : Math.min(baseMaxTokens + thinkingBudget, modelMaxTokens);
+    if (maxTokens <= thinkingBudget) {
+        thinkingBudget = Math.max(0, maxTokens - minOutputTokens);
+    }
+    return { maxTokens, thinkingBudget };
+}

package/dist/pi/ai/providers/transform-messages.js

@@ -0,0 +1,183 @@
+const NON_VISION_USER_IMAGE_PLACEHOLDER = "(image omitted: model does not support images)";
+const NON_VISION_TOOL_IMAGE_PLACEHOLDER = "(tool image omitted: model does not support images)";
+function replaceImagesWithPlaceholder(content, placeholder) {
+    const result = [];
+    let previousWasPlaceholder = false;
+    for (const block of content) {
+        if (block.type === "image") {
+            if (!previousWasPlaceholder) {
+                result.push({ type: "text", text: placeholder });
+            }
+            previousWasPlaceholder = true;
+            continue;
+        }
+        result.push(block);
+        previousWasPlaceholder = block.text === placeholder;
+    }
+    return result;
+}
+function downgradeUnsupportedImages(messages, model) {
+    if (model.input.includes("image")) {
+        return messages;
+    }
+    return messages.map((msg) => {
+        if (msg.role === "user" && Array.isArray(msg.content)) {
+            return {
+                ...msg,
+                content: replaceImagesWithPlaceholder(msg.content, NON_VISION_USER_IMAGE_PLACEHOLDER),
+            };
+        }
+        if (msg.role === "toolResult") {
+            return {
+                ...msg,
+                content: replaceImagesWithPlaceholder(msg.content, NON_VISION_TOOL_IMAGE_PLACEHOLDER),
+            };
+        }
+        return msg;
+    });
+}
+/**
+ * Normalize tool call ID for cross-provider compatibility.
+ * OpenAI Responses API generates IDs that are 450+ chars with special characters like `|`.
+ * Anthropic APIs require IDs matching ^[a-zA-Z0-9_-]+$ (max 64 chars).
+ */
+export function transformMessages(messages, model, normalizeToolCallId) {
+    // Build a map of original tool call IDs to normalized IDs
+    const toolCallIdMap = new Map();
+    const imageAwareMessages = downgradeUnsupportedImages(messages, model);
+    // First pass: transform messages (unsupported image downgrade, thinking blocks, tool call ID normalization)
+    const transformed = imageAwareMessages.map((msg) => {
+        // User messages pass through unchanged
+        if (msg.role === "user") {
+            return msg;
+        }
+        // Handle toolResult messages - normalize toolCallId if we have a mapping
+        if (msg.role === "toolResult") {
+            const normalizedId = toolCallIdMap.get(msg.toolCallId);
+            if (normalizedId && normalizedId !== msg.toolCallId) {
+                return { ...msg, toolCallId: normalizedId };
+            }
+            return msg;
+        }
+        // Assistant messages need transformation check
+        if (msg.role === "assistant") {
+            const assistantMsg = msg;
+            const isSameModel = assistantMsg.provider === model.provider &&
+                assistantMsg.api === model.api &&
+                assistantMsg.model === model.id;
+            const transformedContent = assistantMsg.content.flatMap((block) => {
+                if (block.type === "thinking") {
+                    // Redacted thinking is opaque encrypted content, only valid for the same model.
+                    // Drop it for cross-model to avoid API errors.
+                    if (block.redacted) {
+                        return isSameModel ? block : [];
+                    }
+                    // For same model: keep thinking blocks with signatures (needed for replay)
+                    // even if the thinking text is empty (OpenAI encrypted reasoning)
+                    if (isSameModel && block.thinkingSignature)
+                        return block;
+                    // Skip empty thinking blocks, convert others to plain text
+                    if (!block.thinking || block.thinking.trim() === "")
+                        return [];
+                    if (isSameModel)
+                        return block;
+                    return {
+                        type: "text",
+                        text: block.thinking,
+                    };
+                }
+                if (block.type === "text") {
+                    if (isSameModel)
+                        return block;
+                    return {
+                        type: "text",
+                        text: block.text,
+                    };
+                }
+                if (block.type === "toolCall") {
+                    const toolCall = block;
+                    let normalizedToolCall = toolCall;
+                    if (!isSameModel && toolCall.thoughtSignature) {
+                        normalizedToolCall = { ...toolCall };
+                        delete normalizedToolCall.thoughtSignature;
+                    }
+                    if (!isSameModel && normalizeToolCallId) {
+                        const normalizedId = normalizeToolCallId(toolCall.id, model, assistantMsg);
+                        if (normalizedId !== toolCall.id) {
+                            toolCallIdMap.set(toolCall.id, normalizedId);
+                            normalizedToolCall = { ...normalizedToolCall, id: normalizedId };
+                        }
+                    }
+                    return normalizedToolCall;
+                }
+                return block;
+            });
+            return {
+                ...assistantMsg,
+                content: transformedContent,
+            };
+        }
+        return msg;
+    });
+    // Second pass: insert synthetic empty tool results for orphaned tool calls
+    // This preserves thinking signatures and satisfies API requirements
+    const result = [];
+    let pendingToolCalls = [];
+    let existingToolResultIds = new Set();
+    const insertSyntheticToolResults = () => {
+        if (pendingToolCalls.length > 0) {
+            for (const tc of pendingToolCalls) {
+                if (!existingToolResultIds.has(tc.id)) {
+                    result.push({
+                        role: "toolResult",
+                        toolCallId: tc.id,
+                        toolName: tc.name,
+                        content: [{ type: "text", text: "No result provided" }],
+                        isError: true,
+                        timestamp: Date.now(),
+                    });
+                }
+            }
+            pendingToolCalls = [];
+            existingToolResultIds = new Set();
+        }
+    };
+    for (let i = 0; i < transformed.length; i++) {
+        const msg = transformed[i];
+        if (msg.role === "assistant") {
+            // If we have pending orphaned tool calls from a previous assistant, insert synthetic results now
+            insertSyntheticToolResults();
+            // Skip errored/aborted assistant messages entirely.
+            // These are incomplete turns that shouldn't be replayed:
+            // - May have partial content (reasoning without message, incomplete tool calls)
+            // - Replaying them can cause API errors (e.g., OpenAI "reasoning without following item")
+            // - The model should retry from the last valid state
+            const assistantMsg = msg;
+            if (assistantMsg.stopReason === "error" || assistantMsg.stopReason === "aborted") {
+                continue;
+            }
+            // Track tool calls from this assistant message
+            const toolCalls = assistantMsg.content.filter((b) => b.type === "toolCall");
+            if (toolCalls.length > 0) {
+                pendingToolCalls = toolCalls;
+                existingToolResultIds = new Set();
+            }
+            result.push(msg);
+        }
+        else if (msg.role === "toolResult") {
+            existingToolResultIds.add(msg.toolCallId);
+            result.push(msg);
+        }
+        else if (msg.role === "user") {
+            // User message interrupts tool flow - insert synthetic results for orphaned calls
+            insertSyntheticToolResults();
+            result.push(msg);
+        }
+        else {
+            result.push(msg);
+        }
+    }
+    // If the conversation ends with unresolved tool calls, synthesize results now.
+    insertSyntheticToolResults();
+    return result;
+}

package/dist/pi/ai/session-resources.js

@@ -0,0 +1,21 @@
+const sessionResourceCleanups = new Set();
+export function registerSessionResourceCleanup(cleanup) {
+    sessionResourceCleanups.add(cleanup);
+    return () => {
+        sessionResourceCleanups.delete(cleanup);
+    };
+}
+export function cleanupSessionResources(sessionId) {
+    const errors = [];
+    for (const cleanup of sessionResourceCleanups) {
+        try {
+            cleanup(sessionId);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    if (errors.length > 0) {
+        throw new AggregateError(errors, "Failed to cleanup session resources");
+    }
+}

package/dist/pi/ai/stream.js

@@ -0,0 +1,26 @@
+import "./providers/register-builtins.js";
+import { getApiProvider } from "./api-registry.js";
+export { getEnvApiKey } from "./env-api-keys.js";
+function resolveApiProvider(api) {
+    const provider = getApiProvider(api);
+    if (!provider) {
+        throw new Error(`No API provider registered for api: ${api}`);
+    }
+    return provider;
+}
+export function stream(model, context, options) {
+    const provider = resolveApiProvider(model.api);
+    return provider.stream(model, context, options);
+}
+export async function complete(model, context, options) {
+    const s = stream(model, context, options);
+    return s.result();
+}
+export function streamSimple(model, context, options) {
+    const provider = resolveApiProvider(model.api);
+    return provider.streamSimple(model, context, options);
+}
+export async function completeSimple(model, context, options) {
+    const s = streamSimple(model, context, options);
+    return s.result();
+}

package/dist/pi/ai/types.js

@@ -0,0 +1 @@
+export {};

package/dist/pi/ai/utils/diagnostics.js

@@ -0,0 +1,24 @@
+export function formatThrownValue(value) {
+    if (value instanceof Error)
+        return value.message || value.name;
+    if (typeof value === "string")
+        return value;
+    return String(value);
+}
+export function extractDiagnosticError(error) {
+    if (!(error instanceof Error))
+        return { name: "ThrownValue", message: formatThrownValue(error) };
+    const code = error.code;
+    return {
+        name: error.name || undefined,
+        message: error.message || error.name,
+        stack: error.stack,
+        code: typeof code === "string" || typeof code === "number" ? code : undefined,
+    };
+}
+export function createAssistantMessageDiagnostic(type, error, details) {
+    return { type, timestamp: Date.now(), error: extractDiagnosticError(error), details };
+}
+export function appendAssistantMessageDiagnostic(message, diagnostic) {
+    message.diagnostics = [...(message.diagnostics ?? []), diagnostic];
+}

package/dist/pi/ai/utils/event-stream.js

@@ -0,0 +1,80 @@
+// Generic event stream class for async iteration
+export class EventStream {
+    queue = [];
+    waiting = [];
+    done = false;
+    finalResultPromise;
+    resolveFinalResult;
+    isComplete;
+    extractResult;
+    constructor(isComplete, extractResult) {
+        this.isComplete = isComplete;
+        this.extractResult = extractResult;
+        this.finalResultPromise = new Promise((resolve) => {
+            this.resolveFinalResult = resolve;
+        });
+    }
+    push(event) {
+        if (this.done)
+            return;
+        if (this.isComplete(event)) {
+            this.done = true;
+            this.resolveFinalResult(this.extractResult(event));
+        }
+        // Deliver to waiting consumer or queue it
+        const waiter = this.waiting.shift();
+        if (waiter) {
+            waiter({ value: event, done: false });
+        }
+        else {
+            this.queue.push(event);
+        }
+    }
+    end(result) {
+        this.done = true;
+        if (result !== undefined) {
+            this.resolveFinalResult(result);
+        }
+        // Notify all waiting consumers that we're done
+        while (this.waiting.length > 0) {
+            const waiter = this.waiting.shift();
+            waiter({ value: undefined, done: true });
+        }
+    }
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            if (this.queue.length > 0) {
+                yield this.queue.shift();
+            }
+            else if (this.done) {
+                return;
+            }
+            else {
+                const result = await new Promise((resolve) => this.waiting.push(resolve));
+                if (result.done)
+                    return;
+                yield result.value;
+            }
+        }
+    }
+    result() {
+        return this.finalResultPromise;
+    }
+}
+export class AssistantMessageEventStream extends EventStream {
+    constructor() {
+        super((event) => event.type === "done" || event.type === "error", (event) => {
+            if (event.type === "done") {
+                return event.message;
+            }
+            else if (event.type === "error") {
+                return event.error;
+            }
+            throw new Error("Unexpected event type for final result");
+        });
+    }
+}
+/** Factory function for AssistantMessageEventStream (for use in extensions) */
+export function createAssistantMessageEventStream() {
+    return new AssistantMessageEventStream();
+}

package/dist/pi/ai/utils/hash.js

@@ -0,0 +1,13 @@
+/** Fast deterministic hash to shorten long strings */
+export function shortHash(str) {
+    let h1 = 0xdeadbeef;
+    let h2 = 0x41c6ce57;
+    for (let i = 0; i < str.length; i++) {
+        const ch = str.charCodeAt(i);
+        h1 = Math.imul(h1 ^ ch, 2654435761);
+        h2 = Math.imul(h2 ^ ch, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return (h2 >>> 0).toString(36) + (h1 >>> 0).toString(36);
+}

package/dist/pi/ai/utils/headers.js

@@ -0,0 +1,7 @@
+export function headersToRecord(headers) {
+    const result = {};
+    for (const [key, value] of headers.entries()) {
+        result[key] = value;
+    }
+    return result;
+}

package/dist/pi/ai/utils/json-parse.js

@@ -0,0 +1,112 @@
+import { parse as partialParse } from "partial-json";
+const VALID_JSON_ESCAPES = new Set(['"', "\\", "/", "b", "f", "n", "r", "t", "u"]);
+function isControlCharacter(char) {
+    const codePoint = char.codePointAt(0);
+    return codePoint !== undefined && codePoint >= 0x00 && codePoint <= 0x1f;
+}
+function escapeControlCharacter(char) {
+    switch (char) {
+        case "\b":
+            return "\\b";
+        case "\f":
+            return "\\f";
+        case "\n":
+            return "\\n";
+        case "\r":
+            return "\\r";
+        case "\t":
+            return "\\t";
+        default:
+            return `\\u${char.codePointAt(0)?.toString(16).padStart(4, "0") ?? "0000"}`;
+    }
+}
+/**
+ * Repairs malformed JSON string literals by:
+ * - escaping raw control characters inside strings
+ * - doubling backslashes before invalid escape characters
+ */
+export function repairJson(json) {
+    let repaired = "";
+    let inString = false;
+    for (let index = 0; index < json.length; index++) {
+        const char = json[index];
+        if (!inString) {
+            repaired += char;
+            if (char === '"') {
+                inString = true;
+            }
+            continue;
+        }
+        if (char === '"') {
+            repaired += char;
+            inString = false;
+            continue;
+        }
+        if (char === "\\") {
+            const nextChar = json[index + 1];
+            if (nextChar === undefined) {
+                repaired += "\\\\";
+                continue;
+            }
+            if (nextChar === "u") {
+                const unicodeDigits = json.slice(index + 2, index + 6);
+                if (/^[0-9a-fA-F]{4}$/.test(unicodeDigits)) {
+                    repaired += `\\u${unicodeDigits}`;
+                    index += 5;
+                    continue;
+                }
+            }
+            if (VALID_JSON_ESCAPES.has(nextChar)) {
+                repaired += `\\${nextChar}`;
+                index += 1;
+                continue;
+            }
+            repaired += "\\\\";
+            continue;
+        }
+        repaired += isControlCharacter(char) ? escapeControlCharacter(char) : char;
+    }
+    return repaired;
+}
+export function parseJsonWithRepair(json) {
+    try {
+        return JSON.parse(json);
+    }
+    catch (error) {
+        const repairedJson = repairJson(json);
+        if (repairedJson !== json) {
+            return JSON.parse(repairedJson);
+        }
+        throw error;
+    }
+}
+/**
+ * Attempts to parse potentially incomplete JSON during streaming.
+ * Always returns a valid object, even if the JSON is incomplete.
+ *
+ * @param partialJson The partial JSON string from streaming
+ * @returns Parsed object or empty object if parsing fails
+ */
+export function parseStreamingJson(partialJson) {
+    if (!partialJson || partialJson.trim() === "") {
+        return {};
+    }
+    try {
+        return parseJsonWithRepair(partialJson);
+    }
+    catch {
+        try {
+            const result = partialParse(partialJson);
+            return (result ?? {});
+        }
+        catch {
+            try {
+                const result = partialParse(repairJson(partialJson));
+                return (result ?? {});
+            }
+            catch {
+                return {};
+            }
+        }
+    }
+}