An AI-powered search engine with a generative UI
TypeScript generative-aigenerative-uinextjsollamareactsearxngshadcn-uitailwindcsstavilytypescriptupstashvercel-ai-sdk
import type { PublicErrorPayload } from './public-error'
export type ToolName = 'fetch' | 'search'
/**
* Raised by the fetch tool when its argument is not an address at all, so the
* classifier can tell that case apart from a page that really did fail. The
* platform's own text embeds the rejected value, which would otherwise put a
* model-authored string into the trace and into the copy shown to the user.
*/
export const INVALID_URL_SENTINEL = 'Invalid fetch URL.'
/**
* Raised when a URL resolves into private address space. Kept apart from the
* invalid-URL case because the address was well formed: the refusal is about
* where it points, and the copy below must not repeat that back to the caller,
* which would turn a refusal into a probe of the internal network.
*/
export const BLOCKED_URL_SENTINEL = 'Blocked fetch URL.'
// What the failure happened to. The whole point of this module is that it is
// never the user and never the AI service.
const SUBJECT: Record<ToolName, string> = {
fetch: 'The page',
search: 'The search service'
}
function getErrorMessage(error: unknown): string {
return error instanceof Error ? error.message : String(error)
}
function getErrorStatus(error: unknown): number | undefined {
if (typeof error !== 'object' || error === null) return undefined
const record = error as Record<string, unknown>
const status = record.statusCode ?? record.status
return typeof status === 'number' && Number.isFinite(status)
? status
: undefined
}
export class ToolFailureError extends Error {
readonly isToolFailureError = true
readonly originalMessage: string
readonly status?: number
constructor(
readonly toolName: ToolName,
error: unknown
) {
const originalMessage = getErrorMessage(error)
super(originalMessage, { cause: error })
this.name = 'ToolFailureError'
this.originalMessage = originalMessage
this.status = getErrorStatus(error)
}
}
/**
* Structural rather than `instanceof`, so a failure that crossed a bundle
* boundary is still recognized as one.
*/
export function isToolFailureError(error: unknown): error is ToolFailureError {
if (typeof error !== 'object' || error === null) return false
const value = error as Record<string, unknown>
return (
value.isToolFailureError === true &&
(value.toolName === 'fetch' || value.toolName === 'search') &&
typeof value.originalMessage === 'string'
)
}
const REFUSED = (subject: string) => `${subject} refused the request.`
const NOT_FOUND = (subject: string) => `${subject} could not be found.`
const RATE_LIMITED = (subject: string) =>
`${subject} is rate limiting requests. Please try again shortly.`
const UNAVAILABLE = (subject: string) =>
`${subject} is temporarily unavailable. Please try again shortly.`
const TOO_SLOW = (subject: string) => `${subject} took too long to respond.`
const INVALID_URL = 'The link is not a valid web address.'
const BLOCKED_URL = 'The link points to an address that cannot be read.'
const UNREADABLE_TYPE = 'The page is not in a readable text format.'
const NO_CONTENT = 'The page did not return any readable content.'
const FETCH_FALLBACK = 'The page could not be read.'
const SEARCH_FALLBACK = 'The search could not be completed.'
/**
* Every sentence this module can produce.
*
* `public-error` preserves a `tool_failed` message instead of reclassifying it,
* and an error whose own text happens to be JSON is parsed by that same code
* path. Checking membership here means an upstream payload claiming the code
* can still only carry copy we wrote ourselves.
*/
export const TOOL_FAILURE_MESSAGES: ReadonlySet<string> = new Set([
...Object.values(SUBJECT).flatMap(subject => [
REFUSED(subject),
NOT_FOUND(subject),
RATE_LIMITED(subject),
UNAVAILABLE(subject),
TOO_SLOW(subject)
]),
INVALID_URL,
BLOCKED_URL,
UNREADABLE_TYPE,
NO_CONTENT,
FETCH_FALLBACK,
SEARCH_FALLBACK
])
export function isToolFailureMessage(message: string): boolean {
return TOOL_FAILURE_MESSAGES.has(message)
}
function classifyToolFailure(error: ToolFailureError): {
message: string
retryable: boolean
} {
const message = error.originalMessage
const status = error.status
const subject = SUBJECT[error.toolName]
if (error.toolName === 'fetch' && message === INVALID_URL_SENTINEL) {
return { message: INVALID_URL, retryable: false }
}
if (message === BLOCKED_URL_SENTINEL) {
return { message: BLOCKED_URL, retryable: false }
}
if (status === 403 || /\b403\b|\bforbidden\b/i.test(message)) {
return { message: REFUSED(subject), retryable: false }
}
if (status === 404 || /\b404\b|\bnot found\b/i.test(message)) {
return { message: NOT_FOUND(subject), retryable: false }
}
if (
status === 429 ||
/\b429\b|too many requests|rate[_\s-]?limit/i.test(message)
) {
return { message: RATE_LIMITED(subject), retryable: true }
}
if (
(status !== undefined && status >= 500 && status <= 599) ||
/\b5\d{2}\b|service unavailable|bad gateway/i.test(message)
) {
return { message: UNAVAILABLE(subject), retryable: true }
}
if (/timeout|timed out|abort/i.test(message)) {
return { message: TOO_SLOW(subject), retryable: true }
}
if (/unsupported content type/i.test(message)) {
return { message: UNREADABLE_TYPE, retryable: false }
}
if (
/no results returned from content extraction service/i.test(message) ||
/no data returned from jina reader api/i.test(message)
) {
return { message: NO_CONTENT, retryable: true }
}
return {
message: error.toolName === 'fetch' ? FETCH_FALLBACK : SEARCH_FALLBACK,
retryable: true
}
}
export function getToolFailureMessage(error: ToolFailureError): string {
return classifyToolFailure(error).message
}
export function serializeToolFailure(error: ToolFailureError): string {
const { message, retryable } = classifyToolFailure(error)
const payload: PublicErrorPayload = {
error: message,
code: 'tool_failed',
type: 'general',
retryable
}
return JSON.stringify(payload)
}