@od-oneapp/ai-platform 0.1.0

package/dist/tool-JSf8JXZ8.mjs

@@ -0,0 +1,1150 @@
+import { Ft as tool, et as generateText, h as anthropic, vt as openai } from "./ai-runtime-CDzQztTt.mjs";
+import { z } from "zod";
+import { createHash, randomUUID } from "node:crypto";
+import { logError, logWarn } from "@od-oneapp/shared/logs";
+import { promises } from "node:fs";
+import { join, resolve } from "node:path";
+
+//#region src/grounding/rag/circuit-breaker.ts
+var CircuitBreaker = class {
+	config;
+	state;
+	constructor(config) {
+		this.config = config;
+		this.state = {
+			state: "closed",
+			failures: 0,
+			successes: 0,
+			halfOpenAttempts: 0
+		};
+	}
+	getMetrics() {
+		return {
+			name: this.config.name,
+			state: this.state.state,
+			failures: this.state.failures,
+			successes: this.state.successes,
+			lastFailureAt: this.state.lastFailureAt,
+			lastSuccessAt: this.state.lastSuccessAt,
+			openUntil: this.state.openUntil
+		};
+	}
+	reset() {
+		this.state = {
+			state: "closed",
+			failures: 0,
+			successes: 0,
+			halfOpenAttempts: 0
+		};
+	}
+	async execute(fn) {
+		const now = Date.now();
+		if (this.state.state === "open") {
+			if (now >= (this.state.openUntil ?? 0)) this.transitionTo("half-open");
+			else if (this.config.fallbackBehavior !== "allow") throw new Error(`[CircuitBreaker] ${this.config.name} is open`);
+		}
+		if (this.state.state === "half-open") if (this.state.halfOpenAttempts >= this.config.halfOpenRequests) {
+			if (this.config.fallbackBehavior !== "allow") throw new Error(`[CircuitBreaker] ${this.config.name} half-open limit reached`);
+		} else this.state.halfOpenAttempts += 1;
+		try {
+			const result = await fn();
+			this.recordSuccess();
+			return result;
+		} catch (error) {
+			this.recordFailure();
+			throw error;
+		}
+	}
+	recordSuccess() {
+		const now = Date.now();
+		this.state.lastSuccessAt = now;
+		this.state.failures = 0;
+		if (this.state.state === "half-open") {
+			this.state.successes += 1;
+			if (this.state.successes >= this.config.halfOpenRequests) this.transitionTo("closed");
+		} else this.state.successes += 1;
+	}
+	recordFailure() {
+		const now = Date.now();
+		this.state.lastFailureAt = now;
+		this.state.failures += 1;
+		this.state.successes = 0;
+		if (this.state.state === "half-open" || this.state.failures >= this.config.failureThreshold) this.transitionTo("open");
+	}
+	transitionTo(next) {
+		if (this.state.state === next) return;
+		const prev = this.state.state;
+		this.state.state = next;
+		if (next === "open") {
+			this.state.openUntil = Date.now() + this.config.resetTimeout;
+			this.state.halfOpenAttempts = 0;
+		}
+		if (next === "half-open") {
+			this.state.halfOpenAttempts = 0;
+			this.state.successes = 0;
+			this.state.openUntil = void 0;
+		}
+		if (next === "closed") {
+			this.state.failures = 0;
+			this.state.halfOpenAttempts = 0;
+			this.state.openUntil = void 0;
+		}
+		this.config.onStateChange?.(prev, next);
+	}
+};
+
+//#endregion
+//#region src/grounding/rag/pipeline.ts
+/**
+* @fileoverview Multi-model research pipeline
+*
+* Three-stage research pipeline for high-quality, verified research:
+* 1. Perplexity: Context expansion (grounded notes + citations)
+* 2. Sonnet 4.5: Structured reasoning (claims, assumptions, gaps)
+* 3. GPT-5: Verification (fact-check, tighten citations)
+*
+* Benefits:
+* - Cuts hallucinations via grounded notes
+* - Readable traces (notes → reasoning → verification)
+* - Tunable research depth (fast/balanced/deep)
+* - Circuit breaker protection for fault tolerance
+*
+* @module @od-oneapp/ai-platform/research/pipeline
+*/
+/**
+* Circuit breaker instances for each pipeline stage.
+* @internal
+*/
+const pipelineCircuits = {
+	perplexity: new CircuitBreaker({
+		name: "research-perplexity",
+		failureThreshold: 3,
+		resetTimeout: 6e4,
+		halfOpenRequests: 1,
+		fallbackBehavior: "error",
+		onStateChange: (from, to) => {
+			if (to === "open") logError("[Pipeline] Perplexity circuit opened - requests will fail until reset");
+		}
+	}),
+	sonnet: new CircuitBreaker({
+		name: "research-sonnet",
+		failureThreshold: 3,
+		resetTimeout: 45e3,
+		halfOpenRequests: 1,
+		fallbackBehavior: "error"
+	}),
+	verification: new CircuitBreaker({
+		name: "research-verification",
+		failureThreshold: 3,
+		resetTimeout: 45e3,
+		halfOpenRequests: 1,
+		fallbackBehavior: "error"
+	})
+};
+/**
+* Tier configurations for research depth.
+* Defines token limits and modes for each tier.
+* @internal
+*/
+const TIER_CONFIGS = {
+	fast: {
+		maxTokens: 400,
+		mode: "concise-notes"
+	},
+	balanced: {
+		maxTokens: 800,
+		mode: "concise-notes"
+	},
+	deep: {
+		maxTokens: 1600,
+		mode: "deep-notes"
+	}
+};
+/**
+* Gets verification model from environment variable.
+* Supports: gpt-4-turbo, o1-preview, o1-pro, gpt-5
+* @returns Model identifier (defaults to 'gpt-4-turbo').
+* @internal
+*/
+function getVerificationModel() {
+	return process.env.NEXT_AI_VERIFICATION_MODEL ?? "gpt-4-turbo";
+}
+/**
+* Step 1: Perplexity - Context expansion.
+* Returns crisp notes + URLs only (no long prose).
+* Bounded context keeps costs predictable.
+* Protected by circuit breaker for fault tolerance.
+*
+* @param query - Research question or query.
+* @param tier - Research depth tier (defaults to 'balanced').
+* @returns Perplexity response with notes, citations, and usage stats.
+* @throws {Error} If Perplexity API fails and GPT-4 Turbo fallback also fails.
+* @throws {CircuitOpenError} If circuit breaker is open after repeated failures.
+* @remarks Falls back to GPT-4 Turbo if Perplexity API is unavailable or times out (30s timeout).
+* Extracts citations from both API response and inline [Source: URL] markers.
+* Limits citations to maximum of 7 URLs.
+* Circuit breaker opens after 3 failures and resets after 60 seconds.
+* @example
+* ```ts
+* const result = await researchWithPerplexity('What is quantum computing?', 'balanced');
+* console.log(result.notes, result.cites);
+* ```
+*/
+async function researchWithPerplexity(query, tier = "balanced") {
+	return pipelineCircuits.perplexity.execute(async () => {
+		return researchWithPerplexityInternal(query, tier);
+	});
+}
+/**
+* Internal implementation of Perplexity research.
+* @internal
+*/
+async function researchWithPerplexityInternal(query, tier) {
+	const config = TIER_CONFIGS[tier];
+	if (process.env.PPLX_API_KEY) {
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), 3e4);
+		try {
+			const response = await fetch("https://api.perplexity.ai/chat/completions", {
+				method: "POST",
+				signal: controller.signal,
+				headers: {
+					Authorization: `Bearer ${process.env.PPLX_API_KEY}`,
+					"Content-Type": "application/json"
+				},
+				body: JSON.stringify({
+					model: "llama-3.1-sonar-large-128k-online",
+					messages: [{
+						role: "system",
+						content: `You are a research assistant. Provide concise, citation-dense notes.
+Format:
+- Use bullet points
+- Include specific facts and figures
+- Cite sources as [Source: URL]
+- Keep to ${config.maxTokens} tokens max
+- ${config.mode === "deep-notes" ? "Provide comprehensive coverage" : "Be concise"}`
+					}, {
+						role: "user",
+						content: query
+					}],
+					max_tokens: config.maxTokens,
+					return_citations: true,
+					temperature: .3
+				})
+			});
+			clearTimeout(timeoutId);
+			if (!response.ok) {
+				const errorBody = await response.text().catch(() => "Unable to read error body");
+				throw new Error(`Perplexity API error: ${response.status} ${response.statusText} - ${errorBody}`);
+			}
+			const data = await response.json();
+			const cites = data.citations ?? [];
+			const content = data.choices?.[0]?.message?.content ?? "";
+			const citationRegex = /\[Source: (https?:\/\/[^\]]+)\]/g;
+			let match;
+			while ((match = citationRegex.exec(content)) !== null) {
+				const url = match[1];
+				if (url && !cites.includes(url)) cites.push(url);
+			}
+			return {
+				notes: content,
+				cites: cites.slice(0, 7),
+				usage: {
+					inputTokens: data.usage?.prompt_tokens ?? 0,
+					outputTokens: data.usage?.completion_tokens ?? 0
+				}
+			};
+		} catch (error) {
+			clearTimeout(timeoutId);
+			if (error instanceof Error) if (error.name === "AbortError") logWarn("[Perplexity] Request timed out after 30s, falling back to GPT-4 Turbo");
+			else logWarn("[Perplexity] API call failed, falling back to GPT-4 Turbo", { error: error.message });
+			else logWarn("[Perplexity] Unknown error, falling back to GPT-4 Turbo", { error: String(error) });
+		}
+	}
+	const result = await generateText({
+		model: openai("gpt-4-turbo"),
+		prompt: `You are a research assistant. Provide concise, citation-dense notes for: "${query}"
+
+Format:
+- Use bullet points
+- Include specific facts and figures
+- Cite sources as [Source: URL]
+- Keep to ${config.maxTokens} tokens max
+- ${config.mode === "deep-notes" ? "Provide comprehensive coverage" : "Be concise"}
+
+Return only the notes with citations.`,
+		maxRetries: 2
+	});
+	const citationRegex = /\[Source: (https?:\/\/[^\]]+)\]/g;
+	const cites = [];
+	let match;
+	while ((match = citationRegex.exec(result.text)) !== null) {
+		const url = match[1];
+		if (url && !cites.includes(url)) cites.push(url);
+	}
+	return {
+		notes: result.text,
+		cites: cites.slice(0, 7),
+		usage: {
+			inputTokens: result.usage.inputTokens ?? 0,
+			outputTokens: result.usage.outputTokens ?? 0
+		}
+	};
+}
+/**
+* Schema for Sonnet reasoning output.
+* @internal
+*/
+const reasoningSchema = z.object({
+	claims: z.array(z.object({
+		statement: z.string(),
+		supportedBy: z.array(z.string()).describe("Citation URLs"),
+		confidence: z.enum([
+			"high",
+			"medium",
+			"low"
+		])
+	})),
+	assumptions: z.array(z.string()).describe("Underlying assumptions made"),
+	gaps: z.array(z.object({
+		description: z.string(),
+		sources: z.array(z.string()).describe("Conflicting sources if any")
+	})).describe("Knowledge gaps or conflicts"),
+	answerDraft: z.string().describe("Draft answer based on notes")
+});
+/**
+* Step 2: Sonnet 4.5 - Structured reasoning.
+* Reasons over ONLY the provided notes.
+* Outputs: claims[], assumptions[], gaps[], answerDraft.
+* Protected by circuit breaker for fault tolerance.
+*
+* @param input - Reasoning input containing question, notes, and citations.
+* @param input.question - Research question.
+* @param input.notes - Research notes from Perplexity.
+* @param input.cites - Citation URLs.
+* @returns Reasoning output with claims, assumptions, gaps, and draft answer.
+* @throws {Error} If JSON extraction or parsing fails, or if model call fails.
+* @throws {CircuitOpenError} If circuit breaker is open after repeated failures.
+* @remarks Uses Claude 3.5 Sonnet with temperature 0.3 for consistent reasoning.
+* Strictly enforces using only provided notes (no external knowledge).
+* Returns structured JSON matching the reasoning schema.
+* Circuit breaker opens after 3 failures and resets after 45 seconds.
+* @example
+* ```ts
+* const reasoning = await reasonWithSonnet({
+*   question: 'What is quantum computing?',
+*   notes: perplexityResult.notes,
+*   cites: perplexityResult.cites
+* });
+* ```
+*/
+async function reasonWithSonnet(input) {
+	return pipelineCircuits.sonnet.execute(async () => {
+		return reasonWithSonnetInternal(input);
+	});
+}
+/**
+* Internal implementation of Sonnet reasoning.
+* @internal
+*/
+async function reasonWithSonnetInternal(input) {
+	const systemPrompt = `You are a rigorous analyst.
+
+CRITICAL RULES:
+1. Use ONLY the provided notes and citations
+2. Do not add external knowledge
+3. Explicitly mark any assumptions
+4. Flag gaps where citations conflict or are insufficient
+5. Output structured JSON matching the schema
+
+Your goal is to produce verifiable, citation-backed reasoning.`;
+	const scratchpad = `## QUESTION
+${input.question}
+
+## NOTES
+${input.notes}
+
+## CITATIONS
+${input.cites.map((c, i) => `[${i + 1}] ${c}`).join("\n")}
+
+## TASK
+Analyze the notes and produce structured reasoning. Return JSON only.`;
+	const result = await generateText({
+		model: anthropic("claude-3-5-sonnet-20241022"),
+		system: systemPrompt,
+		prompt: scratchpad,
+		temperature: .3,
+		maxRetries: 2
+	});
+	const jsonMatch = result.text.match(/\{[\s\S]*\}/);
+	if (!jsonMatch) throw new Error("Failed to extract JSON from Sonnet response");
+	let parsed;
+	try {
+		parsed = JSON.parse(jsonMatch[0]);
+	} catch (parseError) {
+		throw new Error(`Failed to parse JSON from Sonnet: ${parseError instanceof Error ? parseError.message : "Unknown error"}`);
+	}
+	return {
+		...reasoningSchema.parse(parsed),
+		usage: {
+			inputTokens: result.usage.inputTokens ?? 0,
+			outputTokens: result.usage.outputTokens ?? 0
+		}
+	};
+}
+/**
+* Schema for GPT-5 verification output.
+* @internal
+*/
+const verificationSchema = z.object({
+	finalAnswer: z.string().describe("Verified, tightened answer"),
+	flags: z.array(z.object({
+		claim: z.string(),
+		issue: z.enum([
+			"unverifiable",
+			"weak-citation",
+			"conflicting-sources"
+		]),
+		details: z.string()
+	})).describe("Issues found during verification"),
+	trace: z.array(z.object({
+		claim: z.string(),
+		citationCheck: z.enum([
+			"verified",
+			"partial",
+			"failed"
+		]),
+		notes: z.string().optional()
+	})).describe("Per-claim verification trace"),
+	confidence: z.enum([
+		"high",
+		"medium",
+		"low"
+	]).describe("Overall confidence in answer")
+});
+/**
+* Step 3: GPT-5 - Verification.
+* Fact-checks each claim against citations.
+* Flags unverifiable items.
+* Returns final answer with trace.
+* Protected by circuit breaker for fault tolerance.
+*
+* @param draft - Reasoning output from Sonnet stage.
+* @param cites - Citation URLs to verify against.
+* @returns Verification output with final answer, flags, trace, and confidence.
+* @throws {Error} If JSON extraction or parsing fails, or if model call fails.
+* @throws {CircuitOpenError} If circuit breaker is open after repeated failures.
+* @remarks Uses verification model from NEXT_AI_VERIFICATION_MODEL env var (defaults to 'gpt-4-turbo').
+* Supports: gpt-4-turbo, o1-preview, o1-pro, gpt-5.
+* Uses temperature 0.2 for strict verification.
+* Returns verification trace for each claim with citation check results.
+* Circuit breaker opens after 3 failures and resets after 45 seconds.
+* @example
+* ```ts
+* const verification = await verifyWithGPT5(reasoning, cites);
+* console.log(verification.finalAnswer, verification.confidence);
+* ```
+*/
+async function verifyWithGPT5(draft, cites) {
+	return pipelineCircuits.verification.execute(async () => {
+		return verifyWithGPT5Internal(draft, cites);
+	});
+}
+/**
+* Internal implementation of GPT-5 verification.
+* @internal
+*/
+async function verifyWithGPT5Internal(draft, cites) {
+	const verificationModel = getVerificationModel();
+	const systemPrompt = `You are ${verificationModel}, a verification model.
+
+TASKS:
+1. Check each claim against the provided citations
+2. Flag claims that lack strong citation support
+3. Identify conflicting sources
+4. Produce a tightened final answer
+5. Return structured JSON with verification trace
+
+VERIFICATION RULES:
+- "verified": Claim directly supported by citation
+- "partial": Citation provides weak or indirect support
+- "failed": No citation support found
+
+Be strict but fair. Better to flag uncertainty than claim certainty.`;
+	const verificationInput = {
+		draft: {
+			claims: draft.claims,
+			assumptions: draft.assumptions,
+			gaps: draft.gaps,
+			answerDraft: draft.answerDraft
+		},
+		citations: cites.map((c, i) => ({
+			id: i + 1,
+			url: c
+		}))
+	};
+	const result = await generateText({
+		model: openai(verificationModel),
+		system: systemPrompt,
+		prompt: `Verify this reasoning:\n\n${JSON.stringify(verificationInput, null, 2)}\n\nReturn JSON only.`,
+		temperature: .2,
+		maxRetries: 2
+	});
+	const jsonMatch = result.text.match(/\{[\s\S]*\}/);
+	if (!jsonMatch) throw new Error("Failed to extract JSON from verification response");
+	let parsed;
+	try {
+		parsed = JSON.parse(jsonMatch[0]);
+	} catch (parseError) {
+		throw new Error(`Failed to parse JSON from verification: ${parseError instanceof Error ? parseError.message : "Unknown error"}`);
+	}
+	return {
+		...verificationSchema.parse(parsed),
+		usage: {
+			inputTokens: result.usage.inputTokens ?? 0,
+			outputTokens: result.usage.outputTokens ?? 0
+		}
+	};
+}
+/**
+* Orchestrator: Full research pipeline.
+* Executes all three steps in sequence (Perplexity → Sonnet → GPT-5).
+* Returns final answer with full trace.
+*
+* @param question - Research question to answer.
+* @param config - Research configuration (defaults to { tier: 'balanced' }).
+* @returns Complete research pipeline result with answer, confidence, flags, and trace.
+* @throws {Error} If any pipeline stage fails (propagates errors from individual stages).
+* @remarks Executes stages sequentially. Each stage's output feeds into the next.
+* Full trace includes token usage and results from all three stages.
+* Confidence level reflects overall verification quality.
+* @example
+* ```ts
+* const result = await executeResearchPipeline(
+*   'What are the latest developments in quantum computing?',
+*   { tier: 'deep' }
+* );
+* console.log(result.answer, result.confidence);
+* ```
+*/
+async function executeResearchPipeline(question, config = { tier: "balanced" }) {
+	const { notes, cites, usage: perplexityUsage } = await researchWithPerplexity(question, config.tier);
+	const reasoning = await reasonWithSonnet({
+		question,
+		notes,
+		cites
+	});
+	const verification = await verifyWithGPT5(reasoning, cites);
+	return {
+		answer: verification.finalAnswer,
+		confidence: verification.confidence,
+		flags: verification.flags,
+		trace: {
+			contextExpansion: {
+				notes,
+				cites,
+				usage: perplexityUsage
+			},
+			reasoning: {
+				claims: reasoning.claims,
+				assumptions: reasoning.assumptions,
+				gaps: reasoning.gaps,
+				usage: reasoning.usage
+			},
+			verification: {
+				trace: verification.trace,
+				flags: verification.flags,
+				usage: verification.usage
+			}
+		}
+	};
+}
+
+//#endregion
+//#region src/grounding/rag/trace.ts
+/**
+* @fileoverview Research trace storage with cost & latency tracking
+*
+* Extends the artifact pattern for multi-model research runs:
+* - Per-step artifact storage (context expansion → reasoning → verification)
+* - Cost tracking per model (configurable via PipelineModelConfig.costRates)
+* - Latency profiling
+* - Fast indexing for dashboard queries
+*
+* Storage pattern:
+* - File-based for prototype (like artifacts.ts)
+* - Production: Neon Postgres + Upstash Redis + R2
+*
+* @module @od-oneapp/ai-platform/research/trace
+*/
+/** Directory for storing research traces. */
+const TRACES_DIR = process.env.NEXT_AI_TRACES_PATH ?? "/tmp/next-ai-traces";
+/**
+* Validates run ID to prevent path traversal attacks.
+* Format: {timestamp}-{12-char-hex}
+* Example: 1733875200000-a1b2c3d4e5f6
+*
+* @param runId - Run ID to validate.
+* @returns `true` if run ID is valid, `false` otherwise.
+* @internal
+*/
+function validateRunId(runId) {
+	return /^[0-9]+-[0-9a-f]{12}$/i.test(runId);
+}
+/**
+* Safely constructs run path with validation.
+* Prevents path traversal attacks by ensuring paths stay within TRACES_DIR.
+*
+* @param runId - Run ID (validated).
+* @param filename - Optional filename to append.
+* @returns Resolved path or `null` if validation fails.
+* @internal
+*/
+function getRunPath(runId, filename) {
+	if (!validateRunId(runId)) {
+		logError("Invalid run ID format", { runId });
+		return null;
+	}
+	const runPath = filename ? resolve(join(TRACES_DIR, runId, filename)) : resolve(join(TRACES_DIR, runId));
+	const baseDir = resolve(TRACES_DIR);
+	if (!runPath.startsWith(baseDir)) {
+		logError("Path traversal attempt detected", { runId });
+		return null;
+	}
+	return runPath;
+}
+/**
+* Default token-based cost rates ($/1k tokens).
+* Override via `PipelineModelConfig.costRates` or the `customRates` param on `estimateCost`.
+*/
+const DEFAULT_COST_RATES = {
+	"perplexity-latest": { flat: .002 },
+	"llama-3.1-sonar-large-128k-online": { flat: .002 },
+	"gpt-4-turbo": {
+		input: .01,
+		output: .03
+	},
+	"gpt-5": {
+		input: .01,
+		output: .03
+	},
+	"claude-3-5-sonnet-20241022": {
+		input: .003,
+		output: .015
+	}
+};
+/**
+* Estimates cost for a model call based on token usage.
+*
+* @param model - Model identifier.
+* @param inputTokens - Input tokens consumed (defaults to 0).
+* @param outputTokens - Output tokens generated (defaults to 0).
+* @returns Estimated cost in USD.
+* @remarks Cost rates ($/1k tokens):
+* - Perplexity: $0.002 flat per call
+* - Claude 3.5 Sonnet: $0.003 input, $0.015 output
+* - GPT-4 Turbo: $0.01 input, $0.03 output
+* Returns 0 if model is not in cost rates table.
+* @example
+* ```ts
+* const cost = estimateCost('claude-3-5-sonnet-20241022', 1000, 500);
+* // Returns: (1000/1000 * 0.003) + (500/1000 * 0.015) = 0.0105
+* ```
+*/
+function estimateCost(model, inputTokens = 0, outputTokens = 0, customRates) {
+	const rate = (customRates ? {
+		...DEFAULT_COST_RATES,
+		...customRates
+	} : DEFAULT_COST_RATES)[model];
+	if (!rate) return 0;
+	if (rate.flat) return rate.flat;
+	return inputTokens / 1e3 * (rate.input ?? 0) + outputTokens / 1e3 * (rate.output ?? 0);
+}
+/**
+* Ensures traces directory exists.
+* Creates directory recursively if it doesn't exist.
+* @internal
+*/
+async function ensureTracesDir() {
+	try {
+		await promises.mkdir(TRACES_DIR, { recursive: true });
+	} catch (error) {
+		logError("Failed to create traces directory", { error });
+	}
+}
+/**
+* Starts a new research run trace.
+* Creates a new TraceRun with generated runId and initial timestamp.
+*
+* @param question - Research question.
+* @param tier - Research tier.
+* @param app - Application/client identifier (defaults to 'research-agent').
+* @returns New TraceRun object.
+* @example
+* ```ts
+* const run = startRun('What is quantum computing?', 'balanced', 'my-app');
+* ```
+*/
+function startRun(question, tier, app = "research-agent") {
+	const timestamp = Date.now();
+	return {
+		runId: `${timestamp}-${createHash("sha256").update(`${timestamp}-${question}`).digest("hex").slice(0, 12)}`,
+		app,
+		question,
+		tier,
+		startedAt: timestamp,
+		steps: []
+	};
+}
+/**
+* Starts a new research step trace.
+* Creates a new TraceStep with generated ID and start timestamp.
+*
+* @param kind - Pipeline stage kind ('context-expansion', 'reasoning', or 'verification').
+* @param model - Optional model identifier.
+* @returns New TraceStep object.
+* @example
+* ```ts
+* const step = startStep('context-expansion', 'llama-3.1-sonar-large-128k-online');
+* ```
+*/
+function startStep(kind, model) {
+	return {
+		id: randomUUID(),
+		kind,
+		startAt: Date.now(),
+		endAt: 0,
+		latencyMs: 0,
+		model,
+		artifacts: {},
+		artifactKeys: []
+	};
+}
+/**
+* Ends a research step with usage metrics.
+* Calculates latency and cost, updates step with token usage.
+*
+* @param step - Step to end.
+* @param usage - Optional usage metrics (inputTokens, outputTokens, costUSD).
+* @returns Updated step with end timestamp, latency, and cost.
+* @example
+* ```ts
+* const completedStep = endStep(step, {
+*   inputTokens: 1000,
+*   outputTokens: 500
+* });
+* ```
+*/
+function endStep(step, usage) {
+	step.endAt = Date.now();
+	step.latencyMs = step.endAt - step.startAt;
+	if (usage?.inputTokens) step.inputTokens = usage.inputTokens;
+	if (usage?.outputTokens) step.outputTokens = usage.outputTokens;
+	if (usage?.costUSD !== void 0) step.costUSD = usage.costUSD;
+	else if (step.model) step.costUSD = estimateCost(step.model, step.inputTokens ?? 0, step.outputTokens ?? 0);
+	return step;
+}
+/**
+* Ends a research run and calculates totals.
+* Computes total latency and cost from all steps.
+*
+* @param run - Run to end.
+* @returns Updated run with end timestamp, total latency, and total cost.
+* @example
+* ```ts
+* const completedRun = endRun(run);
+* console.log(`Total cost: $${completedRun.totalCostUSD}`);
+* ```
+*/
+function endRun(run) {
+	run.endedAt = Date.now();
+	run.totalLatencyMs = run.endedAt - run.startedAt;
+	run.totalCostUSD = run.steps.reduce((acc, s) => acc + (s.costUSD ?? 0), 0);
+	return run;
+}
+/**
+* Persists step artifacts to storage.
+* Writes step artifacts as JSON files in the run directory.
+*
+* @param run - Research run.
+* @param step - Research step.
+* @param payloads - Artifact payloads keyed by name.
+* @throws {Error} If run ID is invalid or file write fails.
+* @remarks Production: Replace with R2 writes.
+* Artifact keys are added to step.artifactKeys array for reference.
+* Files are named as: `{step.kind}-{step.id}.{name}.json`
+* @example
+* ```ts
+* await persistStep(run, step, {
+*   p_notes: { notes: '...', cites: [...] },
+*   p_index: { sources: [...], fetchedAt: '...' }
+* });
+* ```
+*/
+async function persistStep(run, step, payloads) {
+	await ensureTracesDir();
+	const runDir = getRunPath(run.runId);
+	if (!runDir) throw new Error(`Invalid run ID: ${run.runId}`);
+	await promises.mkdir(runDir, { recursive: true });
+	for (const [name, body] of Object.entries(payloads)) {
+		const filename = `${step.kind}-${step.id}.${name}.json`;
+		const filepath = join(runDir, filename);
+		await promises.writeFile(filepath, JSON.stringify(body, null, 2), "utf-8");
+		step.artifactKeys.push(filename);
+	}
+}
+/**
+* Persists run index for fast listing.
+* Creates an index file with run metadata for quick queries.
+*
+* @param run - Research run to index.
+* @remarks Production: Write to Upstash Redis ZSET.
+* @example
+* ```ts
+* await persistRunIndex(run);
+* ```
+*/
+async function persistRunIndex(run) {
+	await ensureTracesDir();
+	const indexPath = join(TRACES_DIR, `${run.runId}.index.json`);
+	const index = {
+		runId: run.runId,
+		app: run.app,
+		question: run.question,
+		tier: run.tier,
+		startedAt: run.startedAt,
+		endedAt: run.endedAt ?? 0,
+		totalLatencyMs: run.totalLatencyMs ?? 0,
+		totalCostUSD: run.totalCostUSD ?? 0,
+		flags: run.flags ?? []
+	};
+	await promises.writeFile(indexPath, JSON.stringify(index, null, 2), "utf-8");
+}
+/**
+* Persists full run metadata.
+* Writes complete run object as JSON file.
+*
+* @param run - Research run to persist.
+* @throws {Error} If run ID is invalid or file write fails.
+* @remarks Writes to `{runId}/run.meta.json` in traces directory.
+* Contains complete run state including all steps and metadata.
+* @example
+* ```ts
+* await persistRunMeta(run);
+* ```
+*/
+async function persistRunMeta(run) {
+	await ensureTracesDir();
+	const runDir = getRunPath(run.runId);
+	if (!runDir) throw new Error(`Invalid run ID: ${run.runId}`);
+	await promises.mkdir(runDir, { recursive: true });
+	const metaPath = join(runDir, "run.meta.json");
+	await promises.writeFile(metaPath, JSON.stringify(run, null, 2), "utf-8");
+}
+/**
+* Lists recent research runs.
+* Returns runs sorted by start time (most recent first).
+*
+* @param limit - Maximum number of runs to return (defaults to 100).
+* @returns Array of TraceRun objects sorted by startedAt descending.
+* @remarks Production: Query from Redis ZSET.
+* Reads index files from traces directory and parses JSON.
+* Returns empty array on error (logs error to console).
+* @example
+* ```ts
+* const runs = await listRuns(50);
+* ```
+*/
+async function listRuns(limit = 100) {
+	await ensureTracesDir();
+	try {
+		const indexFiles = (await promises.readdir(TRACES_DIR)).filter((f) => f.endsWith(".index.json"));
+		return (await Promise.all(indexFiles.map(async (file) => {
+			const content = await promises.readFile(join(TRACES_DIR, file), "utf-8");
+			return JSON.parse(content);
+		}))).sort((a, b) => b.startedAt - a.startedAt).slice(0, limit);
+	} catch (error) {
+		logError("Failed to list runs", { error });
+		return [];
+	}
+}
+/**
+* Loads full run metadata from storage.
+*
+* @param runId - Run identifier.
+* @returns TraceRun object or `null` if not found or invalid.
+* @remarks Reads from `{runId}/run.meta.json` file.
+* Returns `null` if file doesn't exist, runId is invalid, or parse fails.
+* Logs errors to console.
+* @example
+* ```ts
+* const run = await loadRun('1733875200000-a1b2c3d4e5f6');
+* ```
+*/
+async function loadRun(runId) {
+	try {
+		const metaPath = getRunPath(runId, "run.meta.json");
+		if (!metaPath) return null;
+		const content = await promises.readFile(metaPath, "utf-8");
+		return JSON.parse(content);
+	} catch (error) {
+		logError("Failed to load run", {
+			error,
+			runId
+		});
+		return null;
+	}
+}
+/**
+* Loads a step artifact from storage.
+* Validates artifact key to prevent path traversal attacks.
+*
+* @param runId - Run identifier.
+* @param artifactKey - Artifact key (filename).
+* @returns Artifact data or `null` if not found or validation fails.
+* @remarks Rejects artifact keys containing '..' or '/' to prevent path traversal.
+* Returns `null` on any error (file not found, invalid key, parse error).
+* @example
+* ```ts
+* const artifact = await loadStepArtifact(runId, 'perplexity-123.p_notes.json');
+* ```
+*/
+async function loadStepArtifact(runId, artifactKey) {
+	try {
+		if (artifactKey.includes("..") || artifactKey.includes("/")) {
+			logError("Invalid artifact key", { artifactKey });
+			return null;
+		}
+		const artifactPath = getRunPath(runId, artifactKey);
+		if (!artifactPath) return null;
+		const content = await promises.readFile(artifactPath, "utf-8");
+		return JSON.parse(content);
+	} catch (error) {
+		logError("Failed to load artifact", {
+			error,
+			artifactKey,
+			runId
+		});
+		return null;
+	}
+}
+
+//#endregion
+//#region src/grounding/rag/tool.ts
+/**
+* @fileoverview Research tool for agent integration
+*
+* Wraps the three-stage research pipeline as an AI SDK tool
+* that can be used by any agent (canvas, chat, etc.)
+*
+* Features:
+* - Configurable models per stage via PipelineModelConfig
+* - Tier-based research (fast/balanced/deep)
+* - Full trace with cost/latency
+* - Compliance signal integration
+* - Artifact storage for research results
+*
+* @module @od-oneapp/ai-platform/research/tool
+*/
+/**
+* Schema for research tool input.
+*/
+const researchInputSchema = z.object({
+	question: z.string().min(1).describe("Research question or query"),
+	tier: z.enum([
+		"fast",
+		"balanced",
+		"deep"
+	]).optional().default("balanced").describe("Research depth: fast (400 tokens), balanced (800 tokens), deep (1600 tokens)")
+});
+/**
+* Creates a research tool for AI SDK agents.
+* Wraps the multi-model research pipeline with trace storage and compliance signals.
+*
+* @param options - Optional tool configuration:
+* - `onSignal` - Callback for compliance signal emission
+* - `onTrace` - Callback for trace step completion (receives runId, step kind, latency, cost)
+* @returns AI SDK tool ready for agent integration.
+* @remarks Tool executes full three-stage research pipeline (context expansion → reasoning → verification).
+* Persists step artifacts and run metadata for traceability.
+* Emits compliance signals at start and completion.
+* Returns structured result with answer, confidence, citations, flags, and trace.
+* On error, returns failure result with error message and emits guardrail.blocked signal.
+* @example
+* ```ts
+* const researchTool = createResearchTool({
+*   onSignal: (signal) => persistSignal(signal),
+*   onTrace: (runId, step) => console.log(`Step ${step.kind} completed`)
+* });
+*
+* const agent = createAgent({
+*   tools: { research: researchTool }
+* });
+* ```
+*/
+function createResearchTool(options) {
+	return tool({
+		description: `Perform multi-model research using a three-stage pipeline: context expansion → structured reasoning → verification.
+
+This tool provides grounded, verified research with:
+- Context expansion (notes + citations)
+- Structured reasoning (claims, assumptions, gaps)
+- Verification (fact-checking, confidence scoring)
+
+Use this tool when you need factual, citation-backed answers to complex questions.
+
+Tiers:
+- fast: Quick research (400 tokens, ~2-3 citations)
+- balanced: Standard research (800 tokens, ~5 citations)
+- deep: Comprehensive research (1600 tokens, ~7 citations)`,
+		inputSchema: researchInputSchema,
+		execute: async (input) => {
+			const { question, tier } = input;
+			try {
+				const run = startRun(question, tier, "next-ai");
+				options?.onSignal?.({
+					id: crypto.randomUUID(),
+					type: "tool.executed",
+					message: `Starting multi-model research (tier: ${tier})`,
+					runId: run.runId,
+					timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+					metadata: {
+						question,
+						tier
+					}
+				});
+				const mc = options?.modelConfig;
+				const expansionStep = startStep("context-expansion", mc?.contextExpansion?.model ?? "llama-3.1-sonar-large-128k-online");
+				const { notes, cites, usage: expansionUsage } = await researchWithPerplexity(question, tier);
+				endStep(expansionStep, {
+					inputTokens: expansionUsage.inputTokens,
+					outputTokens: expansionUsage.outputTokens
+				});
+				await persistStep(run, expansionStep, {
+					expansion_notes: {
+						notes,
+						cites
+					},
+					expansion_index: {
+						sources: cites,
+						fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
+						tier
+					}
+				});
+				run.steps.push(expansionStep);
+				options?.onTrace?.(run.runId, {
+					kind: "context-expansion",
+					latencyMs: expansionStep.latencyMs,
+					costUSD: expansionStep.costUSD ?? 0
+				});
+				const reasoningStep = startStep("reasoning", mc?.reasoning?.model ?? "claude-3-5-sonnet-20241022");
+				const reasoning = await reasonWithSonnet({
+					question,
+					notes,
+					cites
+				});
+				endStep(reasoningStep, {
+					inputTokens: reasoning.usage.inputTokens,
+					outputTokens: reasoning.usage.outputTokens
+				});
+				await persistStep(run, reasoningStep, { reasoning_output: {
+					claims: reasoning.claims,
+					assumptions: reasoning.assumptions,
+					gaps: reasoning.gaps,
+					answerDraft: reasoning.answerDraft,
+					meta: {
+						model: reasoningStep.model,
+						timestamp: (/* @__PURE__ */ new Date()).toISOString()
+					}
+				} });
+				run.steps.push(reasoningStep);
+				options?.onTrace?.(run.runId, {
+					kind: "reasoning",
+					latencyMs: reasoningStep.latencyMs,
+					costUSD: reasoningStep.costUSD ?? 0
+				});
+				const verificationStep = startStep("verification", mc?.verification?.model ?? process.env.NEXT_AI_VERIFICATION_MODEL ?? "gpt-4-turbo");
+				const verification = await verifyWithGPT5(reasoning, cites);
+				endStep(verificationStep, {
+					inputTokens: verification.usage.inputTokens,
+					outputTokens: verification.usage.outputTokens
+				});
+				await persistStep(run, verificationStep, { verification_output: {
+					finalAnswer: verification.finalAnswer,
+					flags: verification.flags,
+					trace: verification.trace,
+					confidence: verification.confidence,
+					meta: {
+						model: verificationStep.model,
+						timestamp: (/* @__PURE__ */ new Date()).toISOString()
+					}
+				} });
+				run.steps.push(verificationStep);
+				options?.onTrace?.(run.runId, {
+					kind: "verification",
+					latencyMs: verificationStep.latencyMs,
+					costUSD: verificationStep.costUSD ?? 0
+				});
+				run.flags = verification.flags.map((f) => f.issue);
+				endRun(run);
+				await persistRunMeta(run);
+				await persistRunIndex(run);
+				options?.onSignal?.({
+					id: crypto.randomUUID(),
+					type: "tool.executed",
+					message: `Research completed (confidence: ${verification.confidence}, ${verification.flags.length} flags)`,
+					runId: run.runId,
+					timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+					metadata: {
+						runId: run.runId,
+						latencyMs: run.totalLatencyMs,
+						costUSD: run.totalCostUSD,
+						confidence: verification.confidence,
+						flagCount: verification.flags.length
+					}
+				});
+				return {
+					success: true,
+					answer: verification.finalAnswer,
+					confidence: verification.confidence,
+					citations: cites.map((url, i) => `[${i + 1}] ${url}`).join("\n"),
+					flags: verification.flags.length > 0 ? verification.flags.map((f) => `⚠️ ${f.claim}: ${f.issue} (${f.details})`).join("\n") : "No verification issues",
+					reasoning: {
+						claims: reasoning.claims.length,
+						assumptions: reasoning.assumptions.length,
+						gaps: reasoning.gaps.length
+					},
+					trace: {
+						runId: run.runId,
+						latencyMs: run.totalLatencyMs,
+						costUSD: `$${run.totalCostUSD?.toFixed(4)}`,
+						steps: run.steps.map((s) => ({
+							kind: s.kind,
+							latencyMs: s.latencyMs,
+							costUSD: `$${s.costUSD?.toFixed(4)}`
+						}))
+					}
+				};
+			} catch (error) {
+				const errorMessage = error instanceof Error ? error.message : "Unknown error";
+				options?.onSignal?.({
+					id: crypto.randomUUID(),
+					type: "guardrail.blocked",
+					message: `Research failed: ${errorMessage}`,
+					runId: crypto.randomUUID(),
+					timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+					metadata: { error: errorMessage }
+				});
+				return {
+					success: false,
+					error: errorMessage,
+					answer: "Research pipeline failed. Please try again or rephrase your question."
+				};
+			}
+		}
+	});
+}
+
+//#endregion
+export { verifyWithGPT5 as _, estimateCost as a, loadStepArtifact as c, persistStep as d, startRun as f, researchWithPerplexity as g, reasonWithSonnet as h, endStep as i, persistRunIndex as l, executeResearchPipeline as m, DEFAULT_COST_RATES as n, listRuns as o, startStep as p, endRun as r, loadRun as s, createResearchTool as t, persistRunMeta as u };
+//# sourceMappingURL=tool-JSf8JXZ8.mjs.map