@aexol/spectral 0.7.0 → 0.7.3

package/dist/pi/agent-core/harness/utils/truncate.js

@@ -0,0 +1,289 @@
+/**
+ * Shared truncation utilities for tool outputs.
+ *
+ * Truncation is based on two independent limits - whichever is hit first wins:
+ * - Line limit (default: 2000 lines)
+ * - Byte limit (default: 50KB)
+ *
+ * Never returns partial lines (except bash tail truncation edge case).
+ */
+export const DEFAULT_MAX_LINES = 2000;
+export const DEFAULT_MAX_BYTES = 50 * 1024; // 50KB
+export const GREP_MAX_LINE_LENGTH = 500; // Max chars per grep match line
+const runtimeBuffer = globalThis.Buffer;
+const nonAsciiPattern = /[^\x00-\x7f]/;
+function utf8ByteLength(content) {
+    if (runtimeBuffer)
+        return runtimeBuffer.byteLength(content, "utf8");
+    const firstNonAscii = content.search(nonAsciiPattern);
+    if (firstNonAscii === -1)
+        return content.length;
+    let bytes = firstNonAscii;
+    for (let i = firstNonAscii; i < content.length; i++) {
+        const code = content.charCodeAt(i);
+        if (code <= 0x7f) {
+            bytes += 1;
+        }
+        else if (code <= 0x7ff) {
+            bytes += 2;
+        }
+        else if (code >= 0xd800 && code <= 0xdbff && i + 1 < content.length) {
+            const next = content.charCodeAt(i + 1);
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                bytes += 4;
+                i++;
+            }
+            else {
+                bytes += 3;
+            }
+        }
+        else {
+            bytes += 3;
+        }
+    }
+    return bytes;
+}
+function replaceUnpairedSurrogates(content) {
+    let output = "";
+    for (let i = 0; i < content.length; i++) {
+        const code = content.charCodeAt(i);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            if (i + 1 < content.length) {
+                const next = content.charCodeAt(i + 1);
+                if (next >= 0xdc00 && next <= 0xdfff) {
+                    output += content[i] + content[i + 1];
+                    i++;
+                    continue;
+                }
+            }
+            output += "�";
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            output += "�";
+        }
+        else {
+            output += content[i];
+        }
+    }
+    return output;
+}
+/**
+ * Format bytes as human-readable size.
+ */
+export function formatSize(bytes) {
+    if (bytes < 1024) {
+        return `${bytes}B`;
+    }
+    else if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    }
+    else {
+        return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+    }
+}
+/**
+ * Truncate content from the head (keep first N lines/bytes).
+ * Suitable for file reads where you want to see the beginning.
+ *
+ * Never returns partial lines. If first line exceeds byte limit,
+ * returns empty content with firstLineExceedsLimit=true.
+ */
+export function truncateHead(content, options = {}) {
+    const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const totalBytes = utf8ByteLength(content);
+    const lines = content.split("\n");
+    const totalLines = lines.length;
+    // Check if no truncation needed
+    if (totalLines <= maxLines && totalBytes <= maxBytes) {
+        return {
+            content,
+            truncated: false,
+            truncatedBy: null,
+            totalLines,
+            totalBytes,
+            outputLines: totalLines,
+            outputBytes: totalBytes,
+            lastLinePartial: false,
+            firstLineExceedsLimit: false,
+            maxLines,
+            maxBytes,
+        };
+    }
+    // Check if first line alone exceeds byte limit
+    const firstLineBytes = utf8ByteLength(lines[0]);
+    if (firstLineBytes > maxBytes) {
+        return {
+            content: "",
+            truncated: true,
+            truncatedBy: "bytes",
+            totalLines,
+            totalBytes,
+            outputLines: 0,
+            outputBytes: 0,
+            lastLinePartial: false,
+            firstLineExceedsLimit: true,
+            maxLines,
+            maxBytes,
+        };
+    }
+    // Collect complete lines that fit
+    const outputLinesArr = [];
+    let outputBytesCount = 0;
+    let truncatedBy = "lines";
+    for (let i = 0; i < lines.length && i < maxLines; i++) {
+        const line = lines[i];
+        const lineBytes = utf8ByteLength(line) + (i > 0 ? 1 : 0); // +1 for newline
+        if (outputBytesCount + lineBytes > maxBytes) {
+            truncatedBy = "bytes";
+            break;
+        }
+        outputLinesArr.push(line);
+        outputBytesCount += lineBytes;
+    }
+    // If we exited due to line limit
+    if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
+        truncatedBy = "lines";
+    }
+    const outputContent = outputLinesArr.join("\n");
+    const finalOutputBytes = utf8ByteLength(outputContent);
+    return {
+        content: outputContent,
+        truncated: true,
+        truncatedBy,
+        totalLines,
+        totalBytes,
+        outputLines: outputLinesArr.length,
+        outputBytes: finalOutputBytes,
+        lastLinePartial: false,
+        firstLineExceedsLimit: false,
+        maxLines,
+        maxBytes,
+    };
+}
+/**
+ * Truncate content from the tail (keep last N lines/bytes).
+ * Suitable for bash output where you want to see the end (errors, final results).
+ *
+ * May return partial first line if the last line of original content exceeds byte limit.
+ */
+export function truncateTail(content, options = {}) {
+    const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const totalBytes = utf8ByteLength(content);
+    const lines = content.split("\n");
+    if (lines.length > 1 && lines[lines.length - 1] === "")
+        lines.pop();
+    const totalLines = lines.length;
+    // Check if no truncation needed
+    if (totalLines <= maxLines && totalBytes <= maxBytes) {
+        return {
+            content,
+            truncated: false,
+            truncatedBy: null,
+            totalLines,
+            totalBytes,
+            outputLines: totalLines,
+            outputBytes: totalBytes,
+            lastLinePartial: false,
+            firstLineExceedsLimit: false,
+            maxLines,
+            maxBytes,
+        };
+    }
+    // Work backwards from the end
+    const outputLinesArr = [];
+    let outputBytesCount = 0;
+    let truncatedBy = "lines";
+    let lastLinePartial = false;
+    for (let i = lines.length - 1; i >= 0 && outputLinesArr.length < maxLines; i--) {
+        const line = lines[i];
+        const lineBytes = utf8ByteLength(line) + (outputLinesArr.length > 0 ? 1 : 0); // +1 for newline
+        if (outputBytesCount + lineBytes > maxBytes) {
+            truncatedBy = "bytes";
+            // Edge case: if we haven't added ANY lines yet and this line exceeds maxBytes,
+            // take the end of the line (partial)
+            if (outputLinesArr.length === 0) {
+                const truncatedLine = truncateStringToBytesFromEnd(line, maxBytes);
+                outputLinesArr.unshift(truncatedLine);
+                outputBytesCount = utf8ByteLength(truncatedLine);
+                lastLinePartial = true;
+            }
+            break;
+        }
+        outputLinesArr.unshift(line);
+        outputBytesCount += lineBytes;
+    }
+    // If we exited due to line limit
+    if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
+        truncatedBy = "lines";
+    }
+    const outputContent = outputLinesArr.join("\n");
+    const finalOutputBytes = utf8ByteLength(outputContent);
+    return {
+        content: outputContent,
+        truncated: true,
+        truncatedBy,
+        totalLines,
+        totalBytes,
+        outputLines: outputLinesArr.length,
+        outputBytes: finalOutputBytes,
+        lastLinePartial,
+        firstLineExceedsLimit: false,
+        maxLines,
+        maxBytes,
+    };
+}
+/**
+ * Truncate a string to fit within a byte limit (from the end).
+ * Handles multi-byte UTF-8 characters correctly.
+ */
+function truncateStringToBytesFromEnd(str, maxBytes) {
+    if (maxBytes <= 0)
+        return "";
+    let outputBytes = 0;
+    let start = str.length;
+    let needsReplacement = false;
+    for (let i = str.length; i > 0;) {
+        let characterStart = i - 1;
+        const code = str.charCodeAt(characterStart);
+        let characterBytes;
+        let unpairedSurrogate = false;
+        if (code >= 0xdc00 && code <= 0xdfff && characterStart > 0) {
+            const previous = str.charCodeAt(characterStart - 1);
+            if (previous >= 0xd800 && previous <= 0xdbff) {
+                characterStart--;
+                characterBytes = 4;
+            }
+            else {
+                characterBytes = 3;
+                unpairedSurrogate = true;
+            }
+        }
+        else if (code >= 0xd800 && code <= 0xdfff) {
+            characterBytes = 3;
+            unpairedSurrogate = true;
+        }
+        else {
+            characterBytes = code <= 0x7f ? 1 : code <= 0x7ff ? 2 : 3;
+        }
+        if (outputBytes + characterBytes > maxBytes)
+            break;
+        outputBytes += characterBytes;
+        start = characterStart;
+        needsReplacement ||= unpairedSurrogate;
+        i = characterStart;
+    }
+    const output = str.slice(start);
+    return needsReplacement ? replaceUnpairedSurrogates(output) : output;
+}
+/**
+ * Truncate a single line to max characters, adding [truncated] suffix.
+ * Used for grep match lines.
+ */
+export function truncateLine(line, maxChars = GREP_MAX_LINE_LENGTH) {
+    if (line.length <= maxChars) {
+        return { text: line, wasTruncated: false };
+    }
+    return { text: `${line.slice(0, maxChars)}... [truncated]`, wasTruncated: true };
+}

package/dist/pi/agent-core/index.js

@@ -0,0 +1,24 @@
+// Core Agent
+export * from "./agent.js";
+// Loop functions
+export * from "./agent-loop.js";
+export * from "./harness/agent-harness.js";
+export { collectEntriesForBranchSummary, generateBranchSummary, prepareBranchEntries, } from "./harness/compaction/branch-summarization.js";
+export { calculateContextTokens, compact, DEFAULT_COMPACTION_SETTINGS, estimateContextTokens, estimateTokens, findCutPoint, findTurnStartIndex, generateSummary, getLastAssistantUsage, prepareCompaction, serializeConversation, shouldCompact, } from "./harness/compaction/compaction.js";
+export * from "./harness/messages.js";
+export * from "./harness/prompt-templates.js";
+export * from "./harness/session/jsonl-repo.js";
+export * from "./harness/session/memory-repo.js";
+export * from "./harness/session/repo-utils.js";
+export * from "./harness/session/session.js";
+export { uuidv7 } from "./harness/session/uuid.js";
+export * from "./harness/skills.js";
+export * from "./harness/system-prompt.js";
+// Harness
+export * from "./harness/types.js";
+export * from "./harness/utils/shell-output.js";
+export * from "./harness/utils/truncate.js";
+// Proxy utilities
+export * from "./proxy.js";
+// Types
+export * from "./types.js";

package/dist/pi/agent-core/node.js

@@ -0,0 +1,2 @@
+export { NodeExecutionEnv } from "./harness/env/nodejs.js";
+export * from "./index.js";

package/dist/pi/agent-core/proxy.js

@@ -0,0 +1,277 @@
+/**
+ * Proxy stream function for apps that route LLM calls through a server.
+ * The server manages auth and proxies requests to LLM providers.
+ */
+// Internal import for JSON parsing utility
+import { EventStream, parseStreamingJson, } from "../ai/index.js";
+// Create stream class matching ProxyMessageEventStream
+class ProxyMessageEventStream extends EventStream {
+    constructor() {
+        super((event) => event.type === "done" || event.type === "error", (event) => {
+            if (event.type === "done")
+                return event.message;
+            if (event.type === "error")
+                return event.error;
+            throw new Error("Unexpected event type");
+        });
+    }
+}
+/**
+ * Stream function that proxies through a server instead of calling LLM providers directly.
+ * The server strips the partial field from delta events to reduce bandwidth.
+ * We reconstruct the partial message client-side.
+ *
+ * Use this as the `streamFn` option when creating an Agent that needs to go through a proxy.
+ *
+ * @example
+ * ```typescript
+ * const agent = new Agent({
+ *   streamFn: (model, context, options) =>
+ *     streamProxy(model, context, {
+ *       ...options,
+ *       authToken: await getAuthToken(),
+ *       proxyUrl: "https://genai.example.com",
+ *     }),
+ * });
+ * ```
+ */
+function buildProxyRequestOptions(options) {
+    return {
+        temperature: options.temperature,
+        maxTokens: options.maxTokens,
+        reasoning: options.reasoning,
+        cacheRetention: options.cacheRetention,
+        sessionId: options.sessionId,
+        headers: options.headers,
+        metadata: options.metadata,
+        transport: options.transport,
+        thinkingBudgets: options.thinkingBudgets,
+        maxRetryDelayMs: options.maxRetryDelayMs,
+    };
+}
+export function streamProxy(model, context, options) {
+    const stream = new ProxyMessageEventStream();
+    (async () => {
+        // Initialize the partial message that we'll build up from events
+        const partial = {
+            role: "assistant",
+            stopReason: "stop",
+            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 },
+            },
+            timestamp: Date.now(),
+        };
+        let reader;
+        const abortHandler = () => {
+            if (reader) {
+                reader.cancel("Request aborted by user").catch(() => { });
+            }
+        };
+        if (options.signal) {
+            options.signal.addEventListener("abort", abortHandler);
+        }
+        try {
+            const response = await fetch(`${options.proxyUrl}/api/stream`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${options.authToken}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    model,
+                    context,
+                    options: buildProxyRequestOptions(options),
+                }),
+                signal: options.signal,
+            });
+            if (!response.ok) {
+                let errorMessage = `Proxy error: ${response.status} ${response.statusText}`;
+                try {
+                    const errorData = (await response.json());
+                    if (errorData.error) {
+                        errorMessage = `Proxy error: ${errorData.error}`;
+                    }
+                }
+                catch {
+                    // Couldn't parse error response
+                }
+                throw new Error(errorMessage);
+            }
+            reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = "";
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (options.signal?.aborted) {
+                    throw new Error("Request aborted by user");
+                }
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split("\n");
+                buffer = lines.pop() || "";
+                for (const line of lines) {
+                    if (line.startsWith("data: ")) {
+                        const data = line.slice(6).trim();
+                        if (data) {
+                            const proxyEvent = JSON.parse(data);
+                            const event = processProxyEvent(proxyEvent, partial);
+                            if (event) {
+                                stream.push(event);
+                            }
+                        }
+                    }
+                }
+            }
+            if (options.signal?.aborted) {
+                throw new Error("Request aborted by user");
+            }
+            stream.end();
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const reason = options.signal?.aborted ? "aborted" : "error";
+            partial.stopReason = reason;
+            partial.errorMessage = errorMessage;
+            stream.push({
+                type: "error",
+                reason,
+                error: partial,
+            });
+            stream.end();
+        }
+        finally {
+            if (options.signal) {
+                options.signal.removeEventListener("abort", abortHandler);
+            }
+        }
+    })();
+    return stream;
+}
+/**
+ * Process a proxy event and update the partial message.
+ */
+function processProxyEvent(proxyEvent, partial) {
+    switch (proxyEvent.type) {
+        case "start":
+            return { type: "start", partial };
+        case "text_start":
+            partial.content[proxyEvent.contentIndex] = { type: "text", text: "" };
+            return { type: "text_start", contentIndex: proxyEvent.contentIndex, partial };
+        case "text_delta": {
+            const content = partial.content[proxyEvent.contentIndex];
+            if (content?.type === "text") {
+                content.text += proxyEvent.delta;
+                return {
+                    type: "text_delta",
+                    contentIndex: proxyEvent.contentIndex,
+                    delta: proxyEvent.delta,
+                    partial,
+                };
+            }
+            throw new Error("Received text_delta for non-text content");
+        }
+        case "text_end": {
+            const content = partial.content[proxyEvent.contentIndex];
+            if (content?.type === "text") {
+                content.textSignature = proxyEvent.contentSignature;
+                return {
+                    type: "text_end",
+                    contentIndex: proxyEvent.contentIndex,
+                    content: content.text,
+                    partial,
+                };
+            }
+            throw new Error("Received text_end for non-text content");
+        }
+        case "thinking_start":
+            partial.content[proxyEvent.contentIndex] = { type: "thinking", thinking: "" };
+            return { type: "thinking_start", contentIndex: proxyEvent.contentIndex, partial };
+        case "thinking_delta": {
+            const content = partial.content[proxyEvent.contentIndex];
+            if (content?.type === "thinking") {
+                content.thinking += proxyEvent.delta;
+                return {
+                    type: "thinking_delta",
+                    contentIndex: proxyEvent.contentIndex,
+                    delta: proxyEvent.delta,
+                    partial,
+                };
+            }
+            throw new Error("Received thinking_delta for non-thinking content");
+        }
+        case "thinking_end": {
+            const content = partial.content[proxyEvent.contentIndex];
+            if (content?.type === "thinking") {
+                content.thinkingSignature = proxyEvent.contentSignature;
+                return {
+                    type: "thinking_end",
+                    contentIndex: proxyEvent.contentIndex,
+                    content: content.thinking,
+                    partial,
+                };
+            }
+            throw new Error("Received thinking_end for non-thinking content");
+        }
+        case "toolcall_start":
+            partial.content[proxyEvent.contentIndex] = {
+                type: "toolCall",
+                id: proxyEvent.id,
+                name: proxyEvent.toolName,
+                arguments: {},
+                partialJson: "",
+            };
+            return { type: "toolcall_start", contentIndex: proxyEvent.contentIndex, partial };
+        case "toolcall_delta": {
+            const content = partial.content[proxyEvent.contentIndex];
+            if (content?.type === "toolCall") {
+                content.partialJson += proxyEvent.delta;
+                content.arguments = parseStreamingJson(content.partialJson) || {};
+                partial.content[proxyEvent.contentIndex] = { ...content }; // Trigger reactivity
+                return {
+                    type: "toolcall_delta",
+                    contentIndex: proxyEvent.contentIndex,
+                    delta: proxyEvent.delta,
+                    partial,
+                };
+            }
+            throw new Error("Received toolcall_delta for non-toolCall content");
+        }
+        case "toolcall_end": {
+            const content = partial.content[proxyEvent.contentIndex];
+            if (content?.type === "toolCall") {
+                delete content.partialJson;
+                return {
+                    type: "toolcall_end",
+                    contentIndex: proxyEvent.contentIndex,
+                    toolCall: content,
+                    partial,
+                };
+            }
+            return undefined;
+        }
+        case "done":
+            partial.stopReason = proxyEvent.reason;
+            partial.usage = proxyEvent.usage;
+            return { type: "done", reason: proxyEvent.reason, message: partial };
+        case "error":
+            partial.stopReason = proxyEvent.reason;
+            partial.errorMessage = proxyEvent.errorMessage;
+            partial.usage = proxyEvent.usage;
+            return { type: "error", reason: proxyEvent.reason, error: partial };
+        default: {
+            const _exhaustiveCheck = proxyEvent;
+            console.warn(`Unhandled proxy event type: ${proxyEvent.type}`);
+            return undefined;
+        }
+    }
+}

package/dist/pi/agent-core/types.js

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

package/dist/pi/ai/api-registry.js

@@ -0,0 +1,43 @@
+const apiProviderRegistry = new Map();
+function wrapStream(api, stream) {
+    return (model, context, options) => {
+        if (model.api !== api) {
+            throw new Error(`Mismatched api: ${model.api} expected ${api}`);
+        }
+        return stream(model, context, options);
+    };
+}
+function wrapStreamSimple(api, streamSimple) {
+    return (model, context, options) => {
+        if (model.api !== api) {
+            throw new Error(`Mismatched api: ${model.api} expected ${api}`);
+        }
+        return streamSimple(model, context, options);
+    };
+}
+export function registerApiProvider(provider, sourceId) {
+    apiProviderRegistry.set(provider.api, {
+        provider: {
+            api: provider.api,
+            stream: wrapStream(provider.api, provider.stream),
+            streamSimple: wrapStreamSimple(provider.api, provider.streamSimple),
+        },
+        sourceId,
+    });
+}
+export function getApiProvider(api) {
+    return apiProviderRegistry.get(api)?.provider;
+}
+export function getApiProviders() {
+    return Array.from(apiProviderRegistry.values(), (entry) => entry.provider);
+}
+export function unregisterApiProviders(sourceId) {
+    for (const [api, entry] of apiProviderRegistry.entries()) {
+        if (entry.sourceId === sourceId) {
+            apiProviderRegistry.delete(api);
+        }
+    }
+}
+export function clearApiProviders() {
+    apiProviderRegistry.clear();
+}