@farming-labs/svelte 0.1.70 → 0.1.72

package/dist/server.js

@@ -30,7 +30,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { applySidebarFolderIndexBehavior, buildDocsAgentDiscoverySpec, emitDocsAnalyticsEvent, findDocsMarkdownPage, isDocsAgentDiscoveryRequest, isDocsSkillRequest, normalizeDocsRelated, performDocsSearch, renderDocsMarkdownDocument, renderDocsSkillDocument, stripGeneratedAgentProvenance, resolveDocsAgentMdxContent, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, resolveDocsI18n, resolveDocsLlmsTxtFormat, resolveDocsLocale, resolveDocsMarkdownRequest, resolveDocsPath, resolvePageReadingTime, resolveReadingTimeOptions, resolveDocsSkillFormat, } from "@farming-labs/docs";
+import { applySidebarFolderIndexBehavior, buildDocsAgentDiscoverySpec, createDocsAgentTraceContext, createDocsAgentTraceId, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, findDocsMarkdownPage, isDocsAgentDiscoveryRequest, isDocsSkillRequest, normalizeDocsRelated, performDocsSearch, renderDocsMarkdownDocument, renderDocsSkillDocument, stripGeneratedAgentProvenance, resolveDocsAgentMdxContent, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, resolveDocsI18n, resolveDocsLlmsTxtFormat, resolveDocsLocale, resolveDocsMarkdownRequest, resolveDocsPath, resolvePageReadingTime, resolveReadingTimeOptions, resolveDocsSkillFormat, } from "@farming-labs/docs";
 import { createDocsMcpHttpHandler, resolveDocsMcpConfig, serializeDocsIconRegistry, serializeOpenDocsProviders, } from "@farming-labs/docs/server";
 import { loadDocsNavTree, loadDocsContent, flattenNavTree } from "./content.js";
 import { renderMarkdown } from "./markdown.js";
@@ -59,6 +59,14 @@ function resolveAIModelAndProvider(aiConfig, requestedModelId) {
         (typeof process !== "undefined" ? process.env?.OPENAI_API_KEY : undefined);
     return { model: modelId, baseUrl, apiKey };
 }
+function safeUrlOrigin(value) {
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        return value;
+    }
+}
 function stripMarkdownText(content) {
     return content
         .replace(/^(import|export)\s.*$/gm, "")
@@ -342,6 +350,7 @@ function findPageInMap(contentMap, dirPrefix, slug) {
 export function createDocsServer(config = {}) {
     const entry = config.entry ?? "docs";
     const analytics = config.analytics;
+    const observability = config.observability;
     const contentDirBase = config.contentDir ?? entry;
     const rootDir = path.resolve(config.rootDir ?? process.cwd());
     const i18n = resolveDocsI18n(config.i18n);
@@ -755,6 +764,51 @@ export function createDocsServer(config = {}) {
     async function POST(event) {
         const requestUrl = new URL(event.request.url);
         const requestStartedAt = Date.now();
+        const trace = createDocsAgentTraceContext("ask-ai");
+        const runSpanId = createDocsAgentTraceId("span");
+        const traceBase = {
+            source: "server",
+            traceId: trace.traceId,
+            url: event.request.url,
+            path: requestUrl.pathname,
+        };
+        async function emitTrace(traceEvent) {
+            await emitDocsAgentTraceEvent(observability, {
+                ...traceBase,
+                ...traceEvent,
+            });
+        }
+        async function emitRunError(reason, outputPreview = {}) {
+            const endedAt = new Date().toISOString();
+            const elapsed = Math.max(0, Date.now() - requestStartedAt);
+            const common = {
+                name: "ask-ai",
+                startedAt: trace.startedAt,
+                endedAt,
+                durationMs: elapsed,
+                status: "error",
+                outputPreview: {
+                    reason,
+                    ...outputPreview,
+                },
+                metadata: { reason },
+            };
+            await emitTrace({ ...common, type: "error", parentSpanId: runSpanId });
+            await emitTrace({ ...common, type: "run.error", spanId: runSpanId });
+            await emitTrace({ ...common, type: "run.end", spanId: runSpanId });
+        }
+        await emitTrace({
+            type: "run.start",
+            name: "ask-ai",
+            spanId: runSpanId,
+            startedAt: trace.startedAt,
+            durationMs: 0,
+            status: "started",
+            inputPreview: {
+                method: event.request.method,
+                path: requestUrl.pathname,
+            },
+        });
         if (!aiConfig.enabled) {
             await emitDocsAnalyticsEvent(analytics, {
                 type: "api_ai_error",
@@ -763,6 +817,7 @@ export function createDocsServer(config = {}) {
                 path: requestUrl.pathname,
                 properties: { reason: "disabled" },
             });
+            await emitRunError("disabled", { status: 404 });
             return new Response(JSON.stringify({
                 error: "AI is not enabled. Set `ai: { enabled: true }` in your docs config to enable it.",
             }), { status: 404, headers: { "Content-Type": "application/json" } });
@@ -781,6 +836,7 @@ export function createDocsServer(config = {}) {
                     durationMs: Math.max(0, Date.now() - requestStartedAt),
                 },
             });
+            await emitRunError("missing_api_key", { status: 500 });
             return new Response(JSON.stringify({
                 error: "AI is enabled but no API key was found. Set `apiKey` in your docs config `ai` section or add OPENAI_API_KEY to your environment.",
             }), { status: 500, headers: { "Content-Type": "application/json" } });
@@ -802,6 +858,7 @@ export function createDocsServer(config = {}) {
                     durationMs: Math.max(0, Date.now() - requestStartedAt),
                 },
             });
+            await emitRunError("invalid_json", { status: 400, locale: ctx.locale });
             return new Response(JSON.stringify({ error: "Invalid JSON body. Expected { messages: [...] }" }), { status: 400, headers: { "Content-Type": "application/json" } });
         }
         const messages = body.messages;
@@ -817,6 +874,7 @@ export function createDocsServer(config = {}) {
                     durationMs: Math.max(0, Date.now() - requestStartedAt),
                 },
             });
+            await emitRunError("missing_messages", { status: 400, locale: ctx.locale });
             return new Response(JSON.stringify({ error: "messages array is required and must not be empty." }), { status: 400, headers: { "Content-Type": "application/json" } });
         }
         const lastUserMessage = [...messages].reverse().find((m) => m.role === "user");
@@ -833,13 +891,69 @@ export function createDocsServer(config = {}) {
                     durationMs: Math.max(0, Date.now() - requestStartedAt),
                 },
             });
+            await emitRunError("missing_user_message", {
+                status: 400,
+                locale: ctx.locale,
+                messageCount: messages.length,
+            });
             return new Response(JSON.stringify({ error: "At least one user message is required." }), {
                 status: 400,
                 headers: { "Content-Type": "application/json" },
             });
         }
         const maxResults = aiConfig.maxResults ?? 5;
+        await emitTrace({
+            type: "user.input",
+            name: "ask-ai",
+            parentSpanId: runSpanId,
+            startedAt: new Date().toISOString(),
+            endedAt: new Date().toISOString(),
+            durationMs: 0,
+            status: "success",
+            locale: ctx.locale,
+            inputPreview: {
+                messageCount: messages.length,
+                questionLength: lastUserMessage.content.length,
+                requestedModel: typeof body.model === "string" && body.model.trim().length > 0
+                    ? body.model.trim()
+                    : undefined,
+            },
+        });
+        const retrievalStartedAt = Date.now();
+        const retrievalStartedAtIso = new Date().toISOString();
+        const retrievalSpanId = createDocsAgentTraceId("span");
+        await emitTrace({
+            type: "retrieval.query",
+            name: "docs-index",
+            spanId: retrievalSpanId,
+            parentSpanId: runSpanId,
+            startedAt: retrievalStartedAtIso,
+            status: "started",
+            locale: ctx.locale,
+            inputPreview: {
+                queryLength: lastUserMessage.content.length,
+                maxResults,
+            },
+        });
         const scored = searchByQuery(lastUserMessage.content.toLowerCase(), ctx).slice(0, maxResults);
+        await emitTrace({
+            type: "retrieval.result",
+            name: "docs-index",
+            parentSpanId: retrievalSpanId,
+            startedAt: retrievalStartedAtIso,
+            endedAt: new Date().toISOString(),
+            durationMs: Math.max(0, Date.now() - retrievalStartedAt),
+            status: "success",
+            locale: ctx.locale,
+            outputPreview: {
+                resultCount: scored.length,
+                urls: scored.slice(0, 5).map((doc) => doc.url),
+            },
+            metadata: { maxResults },
+        });
+        const promptStartedAt = Date.now();
+        const promptStartedAtIso = new Date().toISOString();
+        const promptSpanId = createDocsAgentTraceId("span");
         const contextParts = scored.map((doc) => `## ${doc.title}\nURL: ${doc.url}\n${doc.description ? `Description: ${doc.description}\n` : ""}\n${doc.content}`);
         const context = contextParts.join("\n\n---\n\n");
         const systemPrompt = aiConfig.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
@@ -853,6 +967,26 @@ export function createDocsServer(config = {}) {
             systemMessage,
             ...messages.filter((m) => m.role !== "system"),
         ];
+        await emitTrace({
+            type: "prompt.build",
+            name: "ask-ai.prompt",
+            spanId: promptSpanId,
+            parentSpanId: runSpanId,
+            startedAt: promptStartedAtIso,
+            endedAt: new Date().toISOString(),
+            durationMs: Math.max(0, Date.now() - promptStartedAt),
+            status: "success",
+            locale: ctx.locale,
+            inputPreview: {
+                messageCount: messages.length,
+                retrievedCount: scored.length,
+            },
+            outputPreview: {
+                llmMessageCount: llmMessages.length,
+                contextChars: context.length,
+                systemMessageChars: systemMessage.content.length,
+            },
+        });
         const requestedModel = typeof body.model === "string" && body.model.trim().length > 0
             ? body.model.trim()
             : undefined;
@@ -872,16 +1006,96 @@ export function createDocsServer(config = {}) {
                 model: resolved.model,
             },
         });
-        const llmResponse = await fetch(`${resolved.baseUrl}/chat/completions`, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Bearer ${finalKey}`,
+        const modelStartedAt = Date.now();
+        const modelStartedAtIso = new Date().toISOString();
+        const modelSpanId = createDocsAgentTraceId("span");
+        const providerOrigin = safeUrlOrigin(resolved.baseUrl);
+        await emitTrace({
+            type: "model.call",
+            name: resolved.model,
+            spanId: modelSpanId,
+            parentSpanId: runSpanId,
+            startedAt: modelStartedAtIso,
+            status: "started",
+            locale: ctx.locale,
+            inputPreview: {
+                messageCount: llmMessages.length,
+                stream: true,
+                providerOrigin,
             },
-            body: JSON.stringify({ model: resolved.model, stream: true, messages: llmMessages }),
+            metadata: { model: resolved.model },
         });
+        let llmResponse;
+        try {
+            llmResponse = await fetch(`${resolved.baseUrl}/chat/completions`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${finalKey}`,
+                },
+                body: JSON.stringify({ model: resolved.model, stream: true, messages: llmMessages }),
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            await emitTrace({
+                type: "model.error",
+                name: resolved.model,
+                parentSpanId: modelSpanId,
+                startedAt: modelStartedAtIso,
+                endedAt: new Date().toISOString(),
+                durationMs: Math.max(0, Date.now() - modelStartedAt),
+                status: "error",
+                locale: ctx.locale,
+                outputPreview: { message },
+                metadata: { model: resolved.model, providerOrigin },
+            });
+            await emitDocsAnalyticsEvent(analytics, {
+                type: "api_ai_error",
+                source: "server",
+                url: event.request.url,
+                path: requestUrl.pathname,
+                locale: ctx.locale,
+                input: { question: lastUserMessage.content },
+                properties: {
+                    reason: "llm_fetch_error",
+                    messageCount: messages.length,
+                    questionLength: lastUserMessage.content.length,
+                    retrievedCount: scored.length,
+                    model: resolved.model,
+                    durationMs: Math.max(0, Date.now() - requestStartedAt),
+                },
+            });
+            await emitRunError("llm_fetch_error", {
+                status: 502,
+                locale: ctx.locale,
+                messageCount: messages.length,
+                questionLength: lastUserMessage.content.length,
+                retrievedCount: scored.length,
+                model: resolved.model,
+            });
+            return new Response(JSON.stringify({ error: "LLM API request failed." }), {
+                status: 502,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
         if (!llmResponse.ok) {
             const errText = await llmResponse.text().catch(() => "Unknown error");
+            await emitTrace({
+                type: "model.error",
+                name: resolved.model,
+                parentSpanId: modelSpanId,
+                startedAt: modelStartedAtIso,
+                endedAt: new Date().toISOString(),
+                durationMs: Math.max(0, Date.now() - modelStartedAt),
+                status: "error",
+                locale: ctx.locale,
+                outputPreview: {
+                    status: llmResponse.status,
+                    errorChars: errText.length,
+                },
+                metadata: { model: resolved.model, providerOrigin },
+            });
             await emitDocsAnalyticsEvent(analytics, {
                 type: "api_ai_error",
                 source: "server",
@@ -899,6 +1113,15 @@ export function createDocsServer(config = {}) {
                     durationMs: Math.max(0, Date.now() - requestStartedAt),
                 },
             });
+            await emitRunError("llm_error", {
+                status: 502,
+                modelStatus: llmResponse.status,
+                locale: ctx.locale,
+                messageCount: messages.length,
+                questionLength: lastUserMessage.content.length,
+                retrievedCount: scored.length,
+                model: resolved.model,
+            });
             return new Response(JSON.stringify({ error: `LLM API error (${llmResponse.status}): ${errText}` }), { status: 502, headers: { "Content-Type": "application/json" } });
         }
         await emitDocsAnalyticsEvent(analytics, {
@@ -916,6 +1139,67 @@ export function createDocsServer(config = {}) {
                 durationMs: Math.max(0, Date.now() - requestStartedAt),
             },
         });
+        const responseEndedAt = new Date().toISOString();
+        const modelDurationMs = Math.max(0, Date.now() - modelStartedAt);
+        await emitTrace({
+            type: "model.response",
+            name: resolved.model,
+            parentSpanId: modelSpanId,
+            startedAt: modelStartedAtIso,
+            endedAt: responseEndedAt,
+            durationMs: modelDurationMs,
+            status: "success",
+            locale: ctx.locale,
+            outputPreview: {
+                status: llmResponse.status,
+                stream: true,
+                contentType: llmResponse.headers.get("content-type") ?? undefined,
+            },
+            metadata: { model: resolved.model, providerOrigin },
+        });
+        await emitTrace({
+            type: "model.stream",
+            name: resolved.model,
+            parentSpanId: modelSpanId,
+            startedAt: modelStartedAtIso,
+            endedAt: responseEndedAt,
+            durationMs: modelDurationMs,
+            status: "success",
+            locale: ctx.locale,
+            outputPreview: { stream: true },
+            metadata: { model: resolved.model },
+        });
+        const runDurationMs = Math.max(0, Date.now() - requestStartedAt);
+        await emitTrace({
+            type: "agent.final",
+            name: "ask-ai",
+            parentSpanId: runSpanId,
+            startedAt: trace.startedAt,
+            endedAt: new Date().toISOString(),
+            durationMs: runDurationMs,
+            status: "success",
+            locale: ctx.locale,
+            outputPreview: {
+                stream: true,
+                retrievedCount: scored.length,
+            },
+            metadata: { model: resolved.model },
+        });
+        await emitTrace({
+            type: "run.end",
+            name: "ask-ai",
+            spanId: runSpanId,
+            startedAt: trace.startedAt,
+            endedAt: new Date().toISOString(),
+            durationMs: runDurationMs,
+            status: "success",
+            locale: ctx.locale,
+            outputPreview: {
+                stream: true,
+                retrievedCount: scored.length,
+            },
+            metadata: { model: resolved.model },
+        });
         return new Response(llmResponse.body, {
             headers: {
                 "Content-Type": "text/event-stream",
@@ -947,6 +1231,7 @@ export function createDocsServer(config = {}) {
         },
         mcp: config.mcp,
         analytics,
+        observability,
         defaultName: mcpSiteTitle,
     });
     return { load, GET, POST, MCP };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/svelte",
-  "version": "0.1.70",
+  "version": "0.1.72",
   "description": "SvelteKit adapter for @farming-labs/docs — content loading and navigation utilities",
   "keywords": [
     "docs",
@@ -56,7 +56,7 @@
   "devDependencies": {
     "@types/node": "^22.10.0",
     "typescript": "^5.9.3",
-    "@farming-labs/docs": "0.1.70"
+    "@farming-labs/docs": "0.1.72"
   },
   "peerDependencies": {
     "@farming-labs/docs": "*"