@beeuni/sdk 0.1.0

package/dist/core/turns/tools/tool-outcome.js

@@ -0,0 +1,147 @@
+import { jsonTail, stripErrorPrefixes } from '../text-scan.js';
+function isJsonObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function looksLikeError(text) {
+    const t = text.trim();
+    if (t.length > 500)
+        return false;
+    if (/^Error:\s/i.test(t))
+        return true;
+    if (/^([\w._-]+Error|[\w._-]+Exception):\s/i.test(t))
+        return true;
+    if (/Traceback \(most recent call last\)/i.test(t))
+        return true;
+    if (/^\s*\[\s*\{[\s\S]*"message"\s*:/.test(t))
+        return true;
+    return false;
+}
+export function isErrorOutput(output) {
+    return !!output && (looksLikeError(output) || parseJsonFailure(output) !== null);
+}
+export function partOutcome(part) {
+    const cached = OUTCOME_CACHE.get(part);
+    if (cached && cached.state === part.state)
+        return cached.outcome;
+    const outcome = computeOutcome(part);
+    OUTCOME_CACHE.set(part, { state: part.state, outcome });
+    return outcome;
+}
+const OUTCOME_CACHE = new WeakMap();
+function computeOutcome(part) {
+    const state = part.state;
+    if (state.status === 'error')
+        return 'failed';
+    if (state.status !== 'completed')
+        return 'ok';
+    const output = typeof state.output === 'string' ? state.output.trim() : '';
+    if (!output)
+        return 'ok';
+    if (looksLikeError(output))
+        return 'failed';
+    const parsed = tryParseJson(output);
+    if (parsed === undefined)
+        return 'ok';
+    if (isJsonFailure(parsed))
+        return 'failed';
+    return batchOutcomeOf(parsed);
+}
+function tryParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isJsonFailure(parsed) {
+    return isJsonObject(parsed) && parsed.success === false && typeof parsed.error === 'string';
+}
+function batchOutcomeOf(parsed) {
+    const results = isJsonObject(parsed) ? parsed.results : undefined;
+    if (!Array.isArray(results) || results.length === 0)
+        return 'ok';
+    const failed = results.filter((item) => item !== null &&
+        typeof item === 'object' &&
+        item.success === false).length;
+    if (failed === 0)
+        return 'ok';
+    return failed === results.length ? 'failed' : 'partial';
+}
+export function parseJsonFailure(output) {
+    const trimmed = output.trim();
+    if (!trimmed)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (!isJsonObject(parsed))
+        return null;
+    if (parsed.success !== false || typeof parsed.error !== 'string')
+        return null;
+    const result = {
+        errorSummary: parsed.error.trim(),
+        hint: typeof parsed.hint === 'string' ? parsed.hint.trim() : undefined,
+    };
+    const nestedJson = jsonTail(result.errorSummary);
+    if (nestedJson === null)
+        return result;
+    try {
+        const nested = JSON.parse(nestedJson);
+        if (typeof nested.message === 'string' && nested.message.trim()) {
+            result.nestedMessage = nested.message.trim();
+        }
+        if (typeof nested.status === 'number') {
+            result.status = nested.status;
+        }
+        if (typeof nested.error === 'boolean') {
+            result.nestedError = nested.error;
+        }
+    }
+    catch { }
+    return result;
+}
+export function cleanErrorMessage(raw) {
+    const cleaned = stripErrorPrefixes(raw).replace(/\s+/g, ' ').trim();
+    return cleaned || raw.trim();
+}
+export function formatJsonFailureOutput(output) {
+    const trimmed = output.trim();
+    if (!trimmed)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (!isJsonObject(parsed))
+        return null;
+    const success = parsed.success;
+    const error = parsed.error;
+    const hint = parsed.hint;
+    if (success !== false || typeof error !== 'string')
+        return null;
+    const lines = [];
+    lines.push(error.trim());
+    const nestedJson = jsonTail(error);
+    if (nestedJson !== null) {
+        try {
+            const nested = JSON.parse(nestedJson);
+            const nestedMessage = nested.message;
+            if (typeof nestedMessage === 'string' && nestedMessage.trim()) {
+                lines.push(`Details: ${nestedMessage.trim()}`);
+            }
+        }
+        catch { }
+    }
+    if (typeof hint === 'string' && hint.trim()) {
+        lines.push(`Hint: ${hint.trim()}`);
+    }
+    return lines.join('\n\n');
+}

package/dist/core/turns/tools/tool-output-format.d.ts

@@ -0,0 +1,17 @@
+export declare function looksLikeJsonPayload(text: string | undefined): boolean;
+export declare function formatRawOutput(output: string | undefined, maxChars?: number): {
+    text: string;
+    truncatedChars: number;
+};
+export declare function cleanResultSnippet(content: string | undefined, maxChars?: number): string;
+export interface EmbeddedFailure {
+    message: string;
+    status?: number;
+}
+export declare function parseEmbeddedFailure(output: string | undefined): EmbeddedFailure | null;
+export interface RecoveredResult {
+    title: string;
+    url: string;
+    snippet?: string;
+}
+export declare function recoverLinkResults(raw: string | undefined, max?: number): RecoveredResult[];

package/dist/core/turns/tools/tool-output-format.js

@@ -0,0 +1,124 @@
+import { jsonTail, stripMarkdownImages, unwrapMarkdownLinks } from '../text-scan.js';
+export function looksLikeJsonPayload(text) {
+    const s = (text ?? '').trimStart();
+    return s.startsWith('{') || s.startsWith('[');
+}
+export function formatRawOutput(output, maxChars = 2000) {
+    let s = (output ?? '').trim();
+    try {
+        let value = JSON.parse(s);
+        if (typeof value === 'string') {
+            try {
+                value = JSON.parse(value);
+            }
+            catch {
+            }
+        }
+        if (value && typeof value === 'object') {
+            s = JSON.stringify(value, null, 2);
+        }
+    }
+    catch {
+    }
+    if (s.length > maxChars) {
+        return { text: s.slice(0, maxChars).trimEnd(), truncatedChars: s.length - maxChars };
+    }
+    return { text: s, truncatedChars: 0 };
+}
+export function cleanResultSnippet(content, maxChars = 200) {
+    let s = content ?? '';
+    s = s.replace(/\\n/g, ' ');
+    s = stripMarkdownImages(s);
+    s = unwrapMarkdownLinks(s);
+    s = s.replace(/[#*_`>]+/g, ' ');
+    s = s.replace(/\s+/g, ' ').trim();
+    s = s.replace(/\b(\w{2,})(?:\s+\1\b)+/gi, '$1');
+    return s.length > maxChars ? s.slice(0, maxChars).trimEnd() + '…' : s;
+}
+export function parseEmbeddedFailure(output) {
+    const trimmed = (output ?? '').trim();
+    if (!trimmed)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+        if (typeof parsed === 'string') {
+            try {
+                parsed = JSON.parse(parsed);
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const obj = parsed;
+    if (obj.success !== false || typeof obj.error !== 'string' || !obj.error.trim())
+        return null;
+    let message = obj.error.trim();
+    let status;
+    for (let i = 0; i < 3; i++) {
+        const nestedJson = jsonTail(message);
+        if (nestedJson === null)
+            break;
+        let nested;
+        try {
+            nested = JSON.parse(nestedJson);
+        }
+        catch {
+            break;
+        }
+        if (typeof nested.status === 'number')
+            status = nested.status;
+        if (typeof nested.message === 'string' && nested.message.trim()) {
+            message = nested.message.trim();
+        }
+        else if (typeof nested.error === 'string' && nested.error.trim()) {
+            message = nested.error.trim();
+        }
+        else {
+            break;
+        }
+    }
+    return { message, status };
+}
+function decodeJsonStringLiteral(escaped) {
+    try {
+        return JSON.parse(`"${escaped}"`);
+    }
+    catch {
+        return escaped;
+    }
+}
+export function recoverLinkResults(raw, max = 30) {
+    if (!raw)
+        return [];
+    const out = [];
+    const seen = new Set();
+    const push = (title, url, snippet) => {
+        if (!/^https?:\/\//i.test(url) || seen.has(url) || out.length >= max)
+            return;
+        seen.add(url);
+        out.push({ title: title.trim() || url, url, snippet: snippet?.trim() || undefined });
+    };
+    const titleFirst = /"title"\s*:\s*"((?:\\.|[^"\\])*)"\s*,\s*"url"\s*:\s*"((?:\\.|[^"\\])*)"(?:\s*,\s*"(?:snippet|content|text)"\s*:\s*"((?:\\.|[^"\\])*)")?/g;
+    let m;
+    while ((m = titleFirst.exec(raw)) !== null) {
+        push(decodeJsonStringLiteral(m[1]), decodeJsonStringLiteral(m[2]), m[3] ? decodeJsonStringLiteral(m[3]) : undefined);
+        if (out.length >= max)
+            return out;
+    }
+    if (out.length === 0) {
+        const urlFirst = /"url"\s*:\s*"((?:\\.|[^"\\])*)"[^{}]{0,400}?"title"\s*:\s*"((?:\\.|[^"\\])*)"/g;
+        while ((m = urlFirst.exec(raw)) !== null) {
+            push(decodeJsonStringLiteral(m[2]), decodeJsonStringLiteral(m[1]));
+            if (out.length >= max)
+                return out;
+        }
+    }
+    return out;
+}

package/dist/core/turns/tools/web-helpers.d.ts

@@ -0,0 +1,34 @@
+export interface WebSearchSource {
+    title: string;
+    url: string;
+    snippet?: string;
+    author?: string;
+    publishedDate?: string;
+}
+export interface WebSearchQueryResult {
+    query: string;
+    answer?: string;
+    sources: WebSearchSource[];
+}
+export declare function parseWebSearchOutput(output: string | any): WebSearchQueryResult[];
+export declare function wsDomain(url: string): string;
+export declare function wsRootDomain(url: string): string;
+export declare function wsFavicon(url: string): string | null;
+export interface ScrapeResult {
+    url: string;
+    success: boolean;
+    title?: string;
+    content?: string;
+    error?: string;
+}
+export interface ParsedScrapeOutput {
+    total: number;
+    successful: number;
+    failed: number;
+    results: ScrapeResult[];
+}
+export declare function looksLikeHtml(s: string): boolean;
+export declare function parseScrapeInputUrls(input: Record<string, unknown>): string[];
+export declare function buildScrapeFailureResults(output: string, urls: string[]): ScrapeResult[];
+export declare function resolveScrapeResults(output: string | unknown, input: Record<string, unknown>): ScrapeResult[];
+export declare function parseScrapeOutput(output: string | any): ParsedScrapeOutput | null;

package/dist/core/turns/tools/web-helpers.js

@@ -0,0 +1,229 @@
+import { urlError } from '../text-scan.js';
+import { recoverLinkResults } from './tool-output-format.js';
+function parseJsonOutput(output, trimBom = false) {
+    if (typeof output === 'object' && output !== null)
+        return output;
+    if (typeof output !== 'string')
+        return null;
+    try {
+        let result = JSON.parse(output);
+        if (typeof result === 'string') {
+            try {
+                result = JSON.parse(result);
+            }
+            catch { }
+        }
+        return typeof result === 'object' ? result : null;
+    }
+    catch {
+        const trimmed = trimBom && output.trim().replace(/^\uFEFF/, '');
+        if (trimmed && trimmed !== output) {
+            try {
+                return JSON.parse(trimmed);
+            }
+            catch { }
+        }
+        return null;
+    }
+}
+function collectSources(list) {
+    return list.filter((s) => s.title && s.url).map((s) => ({
+        title: s.title,
+        url: s.url,
+        snippet: s.snippet || s.content || s.text || undefined,
+        author: s.author || undefined,
+        publishedDate: s.publishedDate || s.published_date || undefined,
+    }));
+}
+export function parseWebSearchOutput(output) {
+    if (!output)
+        return [];
+    const parsed = parseJsonOutput(output, true);
+    if (parsed?.success === false)
+        return [];
+    if (Array.isArray(parsed?.results) && parsed.results.length > 0) {
+        const firstItem = parsed.results[0];
+        if (firstItem && typeof firstItem.query === 'string') {
+            const queries = [];
+            for (const r of parsed.results) {
+                if (typeof r.query !== 'string')
+                    continue;
+                queries.push({
+                    query: r.query,
+                    answer: r.answer || undefined,
+                    sources: Array.isArray(r.results) ? collectSources(r.results) : [],
+                });
+            }
+            if (queries.length > 0)
+                return queries;
+        }
+        else if (firstItem && (firstItem.title || firstItem.url)) {
+            const sources = collectSources(parsed.results);
+            if (sources.length > 0)
+                return [{ query: parsed.query || '', answer: parsed.answer || undefined, sources }];
+        }
+    }
+    if (parsed?.query && typeof parsed.query === 'string') {
+        return [
+            {
+                query: parsed.query,
+                answer: parsed.answer || undefined,
+                sources: Array.isArray(parsed.results)
+                    ? collectSources(parsed.results)
+                    : [],
+            },
+        ];
+    }
+    if (Array.isArray(parsed) &&
+        parsed.length > 0 &&
+        parsed[0] &&
+        (parsed[0].title || parsed[0].url)) {
+        const sources = collectSources(parsed);
+        if (sources.length > 0)
+            return [{ query: '', sources }];
+    }
+    if (typeof output === 'string') {
+        const blocks = output.split(/(?=^Title: )/m).filter(Boolean);
+        const sources = [];
+        for (const block of blocks) {
+            const titleMatch = block.match(/^Title:\s*(.+)/m);
+            const urlMatch = block.match(/^URL:\s*(.+)/m);
+            const authorMatch = block.match(/^Author:\s*(.+)/m);
+            const dateMatch = block.match(/^Published Date:\s*(.+)/m);
+            const textMatch = block.match(/^Text:\s*([\s\S]*?)$/m);
+            if (titleMatch && urlMatch) {
+                sources.push({
+                    title: titleMatch[1].trim(),
+                    url: urlMatch[1].trim(),
+                    snippet: textMatch?.[1]?.trim() || undefined,
+                    author: authorMatch?.[1]?.trim() || undefined,
+                    publishedDate: dateMatch?.[1]?.trim() || undefined,
+                });
+            }
+        }
+        if (sources.length > 0)
+            return [{ query: '', sources }];
+    }
+    if (typeof output === 'string') {
+        const recovered = recoverLinkResults(output);
+        if (recovered.length > 0)
+            return [{ query: '', sources: recovered.map((r) => ({ title: r.title, url: r.url, snippet: r.snippet })) }];
+    }
+    return [];
+}
+export function wsDomain(url) {
+    try {
+        return new URL(url).hostname.replace('www.', '');
+    }
+    catch {
+        return url;
+    }
+}
+export function wsRootDomain(url) {
+    try {
+        const hostname = new URL(url).hostname.replace(/^www\./, '');
+        const parts = hostname.split('.');
+        if (parts.length <= 2)
+            return hostname;
+        return parts.slice(-2).join('.');
+    }
+    catch {
+        return wsDomain(url);
+    }
+}
+export function wsFavicon(url) {
+    try {
+        const hostname = new URL(url).hostname.replace(/^www\./, '');
+        return `https://www.google.com/s2/favicons?domain=${hostname}&sz=128`;
+    }
+    catch {
+        return null;
+    }
+}
+export function looksLikeHtml(s) {
+    if (!s)
+        return false;
+    const head = s.slice(0, 600).toLowerCase();
+    if (head.includes('<!doctype html') || head.includes('<html'))
+        return true;
+    return /<\/(body|head|div|p|span|table)>/i.test(s.slice(0, 3000));
+}
+export function parseScrapeInputUrls(input) {
+    const raw = input.urls ?? input.url;
+    if (typeof raw === 'string') {
+        return raw
+            .split(/[\s,]+/)
+            .map((s) => s.trim())
+            .filter((u) => /^https?:\/\//i.test(u));
+    }
+    if (Array.isArray(raw)) {
+        const urls = [];
+        for (const u of raw) {
+            if (typeof u !== 'string')
+                continue;
+            const trimmed = u.trim();
+            if (/^https?:\/\//i.test(trimmed))
+                urls.push(trimmed);
+        }
+        return urls;
+    }
+    return [];
+}
+export function buildScrapeFailureResults(output, urls) {
+    if (urls.length === 0)
+        return [];
+    const cleaned = output.replace(/^Error:\s*/i, '').trim();
+    return urls.map((url) => {
+        const error = urlError(cleaned, url)?.trim() || cleaned;
+        return { url, success: false, error };
+    });
+}
+export function resolveScrapeResults(output, input) {
+    const parsed = parseScrapeOutput(output);
+    if (parsed?.results?.length)
+        return parsed.results;
+    const outputStr = typeof output === 'string' ? output : '';
+    if (!outputStr.trim())
+        return [];
+    return buildScrapeFailureResults(outputStr, parseScrapeInputUrls(input));
+}
+export function parseScrapeOutput(output) {
+    if (!output)
+        return null;
+    const parsed = parseJsonOutput(output);
+    if (!parsed)
+        return null;
+    if (parsed.results && Array.isArray(parsed.results)) {
+        return {
+            total: parsed.total || parsed.results.length,
+            successful: parsed.successful ??
+                parsed.results.filter((r) => r.success !== false).length,
+            failed: parsed.failed ??
+                parsed.results.filter((r) => r.success === false).length,
+            results: parsed.results.map((r) => ({
+                url: r.url || '',
+                success: r.success !== false,
+                title: r.title || undefined,
+                content: r.content || r.text || r.snippet || undefined,
+                error: r.error || undefined,
+            })),
+        };
+    }
+    if (typeof output === 'string') {
+        const recovered = recoverLinkResults(output);
+        if (recovered.length > 0) {
+            return {
+                total: recovered.length,
+                successful: recovered.length,
+                failed: 0,
+                results: recovered.map((r) => ({
+                    url: r.url,
+                    success: true,
+                    title: r.title || undefined,
+                    content: r.snippet || undefined,
+                })),
+            };
+        }
+    }
+    return null;
+}

package/dist/core/turns/types.d.ts

@@ -0,0 +1,110 @@
+import type { GatewayErrorDetails } from './errors.js';
+export interface PartLike {
+    type: string;
+}
+export interface MessageInfoLike {
+    id: string;
+    role: string;
+    parentID?: string;
+    error?: unknown;
+    tokens?: {
+        input?: number;
+        output?: number;
+        reasoning?: number;
+    };
+    time?: {
+        created?: number;
+    };
+}
+export interface MessageWithPartsLike {
+    info: MessageInfoLike;
+    parts: PartLike[];
+}
+export interface TurnLike<M extends MessageWithPartsLike = MessageWithPartsLike> {
+    userMessage: M;
+    assistantMessages: M[];
+    partial?: true;
+}
+export interface PartWithMessage<M extends MessageWithPartsLike = MessageWithPartsLike> {
+    part: M['parts'][number];
+    message: M;
+}
+export interface ToolStateLike {
+    status: 'pending' | 'running' | 'completed' | 'error';
+    input?: Record<string, unknown>;
+    output?: string;
+    title?: string;
+    metadata?: Record<string, unknown>;
+    error?: string;
+}
+export interface ToolPartLike {
+    type: 'tool';
+    tool: string;
+    callID: string;
+    state: ToolStateLike;
+}
+export interface SessionStatusLike {
+    type: string;
+}
+export interface RequestWithToolLike {
+    tool?: {
+        messageID: string;
+        callID: string;
+    };
+}
+export interface TokenUsageLike {
+    input?: number;
+    output?: number;
+    reasoning?: number;
+    cache?: {
+        read?: number;
+        write?: number;
+    };
+}
+export interface ModelCostRates {
+    inputPer1M: number;
+    outputPer1M: number;
+    cacheReadPer1M?: number;
+    cacheWritePer1M?: number;
+    tiers?: ModelCostTierRates[];
+    contextOver200k?: ModelCostTierRates;
+}
+export interface ModelCostTierRates extends ModelCostRates {
+    contextThreshold: number;
+}
+export type ModelPricingLookup = (providerID: string, modelID: string) => ModelCostRates | null;
+export interface ToolInfo {
+    icon: string;
+    title: string;
+    subtitle?: string;
+}
+export interface TurnCostInfo {
+    cost: number;
+    tokens: {
+        input: number;
+        output: number;
+        reasoning: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+}
+export interface RetryInfo {
+    attempt: number;
+    message: string;
+    next: number;
+    details?: GatewayErrorDetails;
+}
+export interface Diagnostic {
+    range: {
+        start: {
+            line: number;
+            character: number;
+        };
+        end: {
+            line: number;
+            character: number;
+        };
+    };
+    message: string;
+    severity?: number;
+}

package/dist/core/turns/types.js

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