@magic6/dsh-web-fallback-chain 0.0.0-stage → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,159 @@
1
+ /**
2
+ * Search-chain execution: run the legs in order, take the first real answer.
3
+ *
4
+ * The search-side counterpart of `./fetch.js`. It differs in two ways that matter:
5
+ * an empty `sources[]` is a **miss** rather than a success (a leg answering 200
6
+ * with nothing would otherwise stop the chain), and the provenance marker goes on
7
+ * the first source's snippet — a search result has no single body, and the first
8
+ * snippet is where an answer's lead usually is.
9
+ *
10
+ * @module dsh-web-fallback-chain/chains/search
11
+ */
12
+
13
+ /** Shorten a message for the attempt record. */
14
+ function shorten(value) {
15
+ const text = String(value ?? '')
16
+ return text.length > 300 ? `${text.slice(0, 300)}…` : text
17
+ }
18
+
19
+ /** Machine-routable code of a failure. */
20
+ function codeOf(error) {
21
+ return typeof error?.code === 'string' && error.code.length > 0 ? error.code : 'WEB_PROVIDER_ERROR'
22
+ }
23
+
24
+ /** One attempt, rendered for the marker and the error. */
25
+ export function describeAttempts(attempts) {
26
+ return attempts
27
+ .map((a) => `${a.leg}=${a.outcome}${a.code ? `(${a.code})` : ''}${a.count !== undefined ? `[${a.count}]` : ''}`)
28
+ .join(', ')
29
+ }
30
+
31
+ import { capText } from '../policy/index.js'
32
+
33
+ /**
34
+ * Cap every source's text to the mode's budget.
35
+ *
36
+ * Applied here rather than in the leg so all legs obey one rule: a leg that
37
+ * returns more than the mode asked for must not cost the caller more context.
38
+ *
39
+ * @param result - a search result (`{sources[], truncated?}`).
40
+ * @param cap - per-source character budget, or null for none.
41
+ * @returns the result with sources capped and `truncated` widened if needed.
42
+ */
43
+ export function capSources(result, cap) {
44
+ if (cap === null || cap === undefined || !Array.isArray(result?.sources)) return result
45
+ let changed = false
46
+ const sources = result.sources.map((source) => {
47
+ const { text, truncated } = capText(source?.snippet ?? source?.text ?? '', cap)
48
+ if (!truncated) return source
49
+ changed = true
50
+ return { ...source, snippet: text, ...(source.text === undefined ? {} : { text }) }
51
+ })
52
+ return changed ? { ...result, sources, truncated: result.truncated === true } : result
53
+ }
54
+
55
+ /**
56
+ * Append the provenance marker to the first source's text.
57
+ *
58
+ * A search result has no single body: the truthful place to record "this answer
59
+ * came from the third-choice index" is the material the model reads, so the
60
+ * marker goes onto the first source's snippet, which is where an answer's lead
61
+ * usually is. Kept to one short line for the same reason the fetch chain does.
62
+ *
63
+ * @param result - the winning result.
64
+ * @param attempts - every attempt, winner last.
65
+ * @param annotate - whether to append.
66
+ * @returns the result, annotated when a fallback happened.
67
+ */
68
+ export function finalize(result, attempts, annotate) {
69
+ if (!annotate || attempts.length <= 1 || !Array.isArray(result?.sources) || result.sources.length === 0) return result
70
+ const winner = attempts[attempts.length - 1].leg
71
+ const earlier = describeAttempts(attempts.slice(0, -1))
72
+ const marker = `\n\n---\n[search-chain] these results came from the "${winner}" leg; earlier legs did not serve: ${earlier}`
73
+ const [first, ...rest] = result.sources
74
+ const key = first.snippet === undefined ? 'text' : 'snippet'
75
+ return { ...result, sources: [{ ...first, [key]: `${first[key] ?? ''}${marker}` }, ...rest] }
76
+ }
77
+
78
+ /**
79
+ * Run the legs in order and return the first result that has sources.
80
+ *
81
+ * An empty `sources[]` is a miss, not a success: a search leg answering 200 with
82
+ * zero results would otherwise stop the chain and leave the caller with nothing.
83
+ *
84
+ * @param legs - resolved legs, in order.
85
+ * @param missing - configured ids with no registered provider.
86
+ * @param options - `{annotateFallback, cap}`.
87
+ * @param request - the seam's search request.
88
+ * @param signal - cancellation signal forwarded to every leg.
89
+ * @returns the winning result.
90
+ * @throws a `WebError`-shaped error carrying `attempts` when nothing served.
91
+ */
92
+ export async function runSearchChain(legs, missing, options, request, signal) {
93
+ const attempts = missing.map((id) => ({ leg: id, outcome: 'unregistered', code: 'WEB_PROVIDER_CONFIGURED_MISSING' }))
94
+ if (legs.length === 0) {
95
+ const error = new Error(
96
+ `web search chain has no usable leg for "${request?.query ?? ''}": ${describeAttempts(attempts) || 'none configured'}`,
97
+ )
98
+ error.code = 'WEB_PROVIDER_UNAVAILABLE'
99
+ error.attempts = attempts
100
+ throw error
101
+ }
102
+ let firstError
103
+ for (const leg of legs) {
104
+ let usable = false
105
+ try {
106
+ usable = leg.provider.available() === true
107
+ } catch (error) {
108
+ attempts.push({ leg: leg.label, outcome: 'unavailable', code: codeOf(error), message: shorten(error?.message) })
109
+ continue
110
+ }
111
+ if (!usable) {
112
+ attempts.push({ leg: leg.label, outcome: 'unavailable', code: 'WEB_PROVIDER_UNAVAILABLE' })
113
+ continue
114
+ }
115
+ try {
116
+ const raw = await leg.provider.search(request, signal)
117
+ const count = Array.isArray(raw?.sources) ? raw.sources.length : 0
118
+ if (count === 0) {
119
+ attempts.push({ leg: leg.label, outcome: 'empty', code: 'WEB_PROVIDER_EMPTY' })
120
+ continue
121
+ }
122
+ attempts.push({ leg: leg.label, outcome: 'served', count })
123
+ return finalize(capSources(raw, options?.cap), attempts, options?.annotateFallback !== false)
124
+ } catch (error) {
125
+ attempts.push({ leg: leg.label, outcome: 'failed', code: codeOf(error), message: shorten(error?.message) })
126
+ if (firstError === undefined) firstError = error
127
+ if (signal?.aborted) throw error
128
+ }
129
+ }
130
+ const error = new Error(
131
+ `web search chain failed for "${request?.query ?? ''}": ${describeAttempts(attempts)}`,
132
+ )
133
+ error.code = attempts.some((a) => a.outcome === 'failed') ? 'WEB_PROVIDER_ERROR' : 'WEB_PROVIDER_UNAVAILABLE'
134
+ error.attempts = attempts
135
+ if (firstError !== undefined) error.cause = firstError
136
+ throw error
137
+ }
138
+
139
+ /** Resolve configured ids against the live registry, reporting misses. */
140
+ export function resolveLegs(registry, order, selfId) {
141
+ const legs = []
142
+ const missing = []
143
+ for (const id of order ?? []) {
144
+ if (id === selfId) {
145
+ throw Object.assign(new Error(`web search chain cannot include itself ("${selfId}")`), { code: 'WEB_PROVIDER_ERROR' })
146
+ }
147
+ const provider = registry?.get?.(id)
148
+ if (provider === undefined) missing.push(id)
149
+ else legs.push({ label: id, provider })
150
+ }
151
+ return { legs, missing }
152
+ }
153
+
154
+ /**
155
+ * Register the chain with `ctx.web`.
156
+ *
157
+ * @param ctx - context whose `web` service receives the provider.
158
+ * @param config - resolved plugin configuration (values or volatile getters).
159
+ */