dsh-lcx-codex 0.5.2 → 0.6.0-pre.2

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,106 @@
1
+ import { projectToolUpdates } from "@deepseek-ai/dsh-llm";
2
+ export const DEFAULT_TOOL_UPDATES = "addition-only";
3
+ /** Reason used when the route compat explicitly declines both declaration kinds; a deliberate configuration. */
4
+ export const COMPAT_OPT_OUT = "route compat opts out of additional_tools and tool_search";
5
+ /** Reason used when the route compat names no supported declaration shape at all; LCX does not guess one. */
6
+ export const COMPAT_SILENT = "route compat does not say whether the model supports additional_tools or tool_search";
7
+ /**
8
+ * Which declaration item carries a mid-session addition, from what the route compat states: `additional_tools`
9
+ * wins over `tool_search` when both are supported, as in Pi. A shape is never guessed: a compat that is silent
10
+ * about both (a model neither the bundled Pi catalog nor the profile describes) or that declines both yields
11
+ * no shape, and the request carries the complete tool list instead. DSH declares addition-only for models whose
12
+ * own catalog supports one of the two, but only the compat says which.
13
+ */
14
+ export function declarationKind(compat) {
15
+ if (compat?.supportsAdditionalTools === true)
16
+ return "additional_tools";
17
+ if (compat?.supportsToolSearch === true)
18
+ return "tool_search";
19
+ return undefined;
20
+ }
21
+ /** Remove the activation marker; the wire never carries it. */
22
+ export function withoutDeferLoading(tool) {
23
+ if (!("deferLoading" in tool))
24
+ return tool;
25
+ const { deferLoading: _deferred, ...rest } = tool;
26
+ return rest;
27
+ }
28
+ function full(messages, tools, toolHistory, fallbackReason, fallbackUnexpected) {
29
+ // Same projection DSH applies for a route without `toolUpdate`: developer updates are dropped and
30
+ // `deferLoading` is cleared, so every declared tool is immediately usable.
31
+ const projected = projectToolUpdates(messages, tools, undefined, toolHistory);
32
+ return {
33
+ messages: projected.messages,
34
+ tools: projected.tools,
35
+ anchored: false,
36
+ ...(fallbackReason === undefined ? {} : { fallbackReason, fallbackUnexpected: fallbackUnexpected === true }),
37
+ };
38
+ }
39
+ /**
40
+ * Decide the tool surface of one GPT Responses request.
41
+ *
42
+ * Addition-only is used only when every condition holds, otherwise the full current list is sent:
43
+ * the policy is on, DSH reports `toolUpdate: "addition-only"` with an in-history system prompt, the route
44
+ * compat names a supported declaration shape (`additional_tools` or `tool_search`; silence is not guessed
45
+ * at, see `declarationKind`), and DSH supplied its tool history. The host
46
+ * projection is then re-verified (LCX-owned self check); any inconsistency falls back to the full list.
47
+ * Removals and same-name redefinitions need no extra handling: the host history fold already yields a
48
+ * shrunken or fully redeclared baseline for them (one-time cache loss), which this function passes through.
49
+ */
50
+ export function planToolSurface(input) {
51
+ const { mode, messages, tools, toolHistory, facts, compat } = input;
52
+ const fallback = (reason) => full(messages, tools, toolHistory, mode === "addition-only" ? reason : undefined, facts.toolUpdate === "addition-only" && reason !== COMPAT_OPT_OUT);
53
+ if (mode !== "addition-only")
54
+ return full(messages, tools, toolHistory);
55
+ if (tools === undefined)
56
+ return fallback("no tools");
57
+ if (!facts.resolved)
58
+ return fallback("model information unavailable");
59
+ if (facts.toolUpdate !== "addition-only")
60
+ return fallback("route does not declare addition-only tool updates");
61
+ if (facts.systemPromptUpdate !== "in-history")
62
+ return fallback("route is not in-history");
63
+ const kind = declarationKind(compat);
64
+ if (kind === undefined)
65
+ return fallback(compat?.supportsAdditionalTools === false || compat?.supportsToolSearch === false ? COMPAT_OPT_OUT : COMPAT_SILENT);
66
+ if (toolHistory === undefined)
67
+ return fallback("no DSH tool history");
68
+ const projected = projectToolUpdates(messages, tools, "addition-only", toolHistory);
69
+ const projectedTools = projected.tools;
70
+ if (projectedTools === undefined)
71
+ return fallback("host projection returned no tools");
72
+ const added = new Set();
73
+ for (const message of projected.messages) {
74
+ if (message.role !== "developer")
75
+ continue;
76
+ for (const block of message.content) {
77
+ if (block.type !== "tool-addition")
78
+ return fallback(`unsupported developer block ${block.type}`);
79
+ if (added.has(block.toolName))
80
+ return fallback("duplicate tool addition");
81
+ added.add(block.toolName);
82
+ }
83
+ }
84
+ const deferred = new Set();
85
+ for (const tool of projectedTools) {
86
+ if (tool.deferLoading === true)
87
+ deferred.add(tool.name);
88
+ }
89
+ // Without any deferred tool or retained addition the request equals the full list; use the ordinary path
90
+ // so the common no-change turn stays byte-identical with the 0.5.1 behaviour.
91
+ if (deferred.size === 0 && added.size === 0)
92
+ return full(messages, tools, toolHistory);
93
+ if (deferred.size !== added.size || [...deferred].some((name) => !added.has(name)))
94
+ return fallback("deferred tools and retained additions disagree");
95
+ // The declared surface must equal the active surface; a mismatch means the history fold and the live
96
+ // header diverged (restore, fork or migration), where only the full list is known to be correct.
97
+ const active = new Set(tools.map((tool) => tool.name));
98
+ if (active.size !== projectedTools.length || projectedTools.some((tool) => !active.has(tool.name)))
99
+ return fallback("declared tools differ from the active tools");
100
+ return {
101
+ messages: projected.messages,
102
+ tools: projectedTools,
103
+ anchored: true,
104
+ compat: kind === "additional_tools" ? { supportsAdditionalTools: true } : { supportsAdditionalTools: false, supportsToolSearch: true },
105
+ };
106
+ }
package/lib/transport.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { abortError } from "./abort-error.js";
2
- const DEFAULT_TIMEOUT_MS = 300_000;
3
- const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
2
+ import { DEFAULTS } from "./defaults.js";
3
+ const DEFAULT_TIMEOUT_MS = DEFAULTS.requestTimeoutMs;
4
+ const DEFAULT_MAX_BYTES = DEFAULTS.maxResponseBytes;
4
5
  const MAX_ERROR_BYTES = 512 * 1024;
5
6
  function errorFacts(value) {
6
7
  return value instanceof Error ? value : new Error(String(value));
@@ -110,27 +111,31 @@ async function readLimited(response, maxBytes = DEFAULT_MAX_BYTES) {
110
111
  reader.releaseLock();
111
112
  }
112
113
  }
113
- export async function fetchJsonWithRetry(url, body, headers = {}, signal, timeoutMs = DEFAULT_TIMEOUT_MS, options = {}) {
114
- const maxAttempts = Math.max(1, Math.min(6, Number(options.maxAttempts ?? 3)));
115
- const maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MAX_BYTES;
114
+ /**
115
+ * The shared request core: POST with bounded retries. A non-2xx answer becomes a classified error (quota,
116
+ * retryable status, other) with its retry-after delay, a transport failure is retried with backoff, and a
117
+ * 2xx answer is handed to `onOk`, whose failures are classified like any other.
118
+ */
119
+ async function postWithRetry(url, body, headers, accept, signal, requestTimeoutMs, maxAttemptsOption, maxErrorBytes, onOk) {
120
+ const maxAttempts = Math.max(1, Math.min(DEFAULTS.maxAttemptsCap, Number(maxAttemptsOption ?? DEFAULTS.maxAttempts)));
116
121
  let last;
117
122
  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
118
123
  abortIfNeeded(signal);
119
124
  try {
120
- const requestSignal = combinedSignal(signal, timeoutMs);
125
+ const requestSignal = combinedSignal(signal, requestTimeoutMs);
121
126
  const response = await fetch(url, {
122
127
  method: "POST",
123
128
  headers: {
124
129
  "content-type": "application/json",
125
- accept: "application/json",
130
+ accept,
126
131
  ...headers,
127
132
  },
128
133
  body: JSON.stringify(body),
129
134
  signal: requestSignal,
130
135
  redirect: "error",
131
136
  });
132
- const text = await readLimited(response, response.ok ? maxResponseBytes : Math.min(maxResponseBytes, MAX_ERROR_BYTES));
133
137
  if (!response.ok) {
138
+ const text = await readLimited(response, maxErrorBytes);
134
139
  const quota = isQuotaError(text);
135
140
  const retryable = !quota && retryableStatus(response.status);
136
141
  const providerRetryAfterMs = retryAfterFromHeaders(response.headers);
@@ -144,20 +149,13 @@ export async function fetchJsonWithRetry(url, body, headers = {}, signal, timeou
144
149
  ? {}
145
150
  : { providerRetryAfterMs }),
146
151
  });
147
- if (!error.retryable || attempt >= maxAttempts)
152
+ if (!retryable || attempt >= maxAttempts)
148
153
  throw error;
149
154
  last = error;
150
155
  await sleep(delayFromHeaders(response.headers, attempt), signal);
151
156
  continue;
152
157
  }
153
- let parsed;
154
- try {
155
- parsed = text ? JSON.parse(text) : {};
156
- }
157
- catch (cause) {
158
- throw makeError(`invalid JSON response from ${url}`, "LCX_INVALID_JSON", { status: response.status, cause });
159
- }
160
- return parsed;
158
+ return await onOk(response, requestSignal);
161
159
  }
162
160
  catch (error) {
163
161
  if (signal?.aborted)
@@ -184,135 +182,107 @@ export async function fetchJsonWithRetry(url, body, headers = {}, signal, timeou
184
182
  }
185
183
  throw last ?? makeError("request failed", "LCX_REQUEST_FAILED");
186
184
  }
187
- export async function fetchSseWithRetry(url, body, headers = {}, signal, timeoutMs, options = {}) {
188
- const requestTimeoutMs = timeoutMs ??
189
- (options.applyDefaultTimeout === false ? undefined : DEFAULT_TIMEOUT_MS);
190
- const maxAttempts = Math.max(1, Math.min(6, Number(options.maxAttempts ?? 3)));
191
- let last;
192
- for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
193
- abortIfNeeded(signal);
185
+ export async function fetchJsonWithRetry(url, body, headers = {}, signal, timeoutMs = DEFAULT_TIMEOUT_MS, options = {}) {
186
+ const maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MAX_BYTES;
187
+ return postWithRetry(url, body, headers, "application/json", signal, timeoutMs, options.maxAttempts, Math.min(maxResponseBytes, MAX_ERROR_BYTES), async (response) => {
188
+ const text = await readLimited(response, maxResponseBytes);
194
189
  try {
195
- const requestSignal = combinedSignal(signal, requestTimeoutMs);
196
- const response = await fetch(url, {
197
- method: "POST",
198
- headers: {
199
- "content-type": "application/json",
200
- accept: "text/event-stream",
201
- ...headers,
202
- },
203
- body: JSON.stringify(body),
204
- signal: requestSignal,
205
- redirect: "error",
206
- });
207
- if (!response.ok) {
208
- const text = await readLimited(response, Math.min(options.maxResponseBytes ?? DEFAULT_MAX_BYTES, MAX_ERROR_BYTES));
209
- const quota = isQuotaError(text);
210
- const retryable = !quota && retryableStatus(response.status);
211
- const providerRetryAfterMs = retryAfterFromHeaders(response.headers);
212
- const error = makeError(`HTTP ${response.status}`, quota ? "LCX_INSUFFICIENT_QUOTA" : retryable ? "LCX_HTTP_RETRYABLE" : "LCX_HTTP_ERROR", {
213
- status: response.status,
214
- retryable,
215
- requestId: response.headers.get("x-request-id") ??
216
- response.headers.get("request-id") ??
217
- undefined,
218
- ...(providerRetryAfterMs === undefined
219
- ? {}
220
- : { providerRetryAfterMs }),
221
- });
222
- if (!retryable || attempt >= maxAttempts)
223
- throw error;
224
- last = error;
225
- await sleep(delayFromHeaders(response.headers, attempt), signal);
226
- continue;
227
- }
228
- if (typeof options.consume === "function")
229
- return await options.consume(response, { requestSignal });
230
- return response;
190
+ return text ? JSON.parse(text) : {};
231
191
  }
232
- catch (error) {
233
- if (signal?.aborted)
234
- throw abortError(signal, error);
235
- const details = errorFacts(error);
236
- const retryable = details.retryable === true ||
237
- details.code === "LCX_HTTP_RETRYABLE" ||
238
- error instanceof TypeError ||
239
- [
240
- "ECONNRESET",
241
- "ECONNREFUSED",
242
- "ETIMEDOUT",
243
- "EAI_AGAIN",
244
- "UND_ERR_CONNECT_TIMEOUT",
245
- ].includes(details.code ?? "");
246
- if (!retryable || attempt >= maxAttempts) {
247
- if (attempt >= maxAttempts && retryable)
248
- throw makeError(`request failed after ${maxAttempts} attempts`, "LCX_RETRY_EXHAUSTED", { cause: error, retryable: true });
249
- throw error;
250
- }
251
- last = error;
252
- await sleep(Math.min(10_000, 500 * 2 ** (attempt - 1)), signal);
192
+ catch (cause) {
193
+ throw makeError(`invalid JSON response from ${url}`, "LCX_INVALID_JSON", { status: response.status, cause });
253
194
  }
254
- }
255
- throw last ?? makeError("request failed", "LCX_REQUEST_FAILED");
195
+ });
256
196
  }
257
- export async function consumeSse(response, onEvent, options = {}) {
258
- if (!response.body)
259
- throw makeError("SSE response has no body", "LCX_INVALID_SSE");
260
- const maxBytes = options.maxResponseBytes ?? DEFAULT_MAX_BYTES;
197
+ export async function fetchSseWithRetry(url, body, headers = {}, signal, timeoutMs, options = {}) {
198
+ const requestTimeoutMs = timeoutMs ??
199
+ (options.applyDefaultTimeout === false ? undefined : DEFAULT_TIMEOUT_MS);
200
+ return postWithRetry(url, body, headers, "text/event-stream", signal, requestTimeoutMs, options.maxAttempts, Math.min(options.maxResponseBytes ?? DEFAULT_MAX_BYTES, MAX_ERROR_BYTES), async (response, requestSignal) => typeof options.consume === "function"
201
+ ? options.consume(response, { requestSignal })
202
+ : response);
203
+ }
204
+ /** `reader.read()` that settles with the abort as soon as `signal` aborts, whatever the stream does. */
205
+ async function readWithSignal(reader, signal) {
206
+ if (!signal)
207
+ return reader.read();
208
+ if (signal.aborted)
209
+ throw abortError(signal);
210
+ return new Promise((resolve, reject) => {
211
+ const onAbort = () => reject(abortError(signal));
212
+ signal.addEventListener("abort", onAbort, { once: true });
213
+ reader.read().then(resolve, reject).finally(() => {
214
+ signal.removeEventListener("abort", onAbort);
215
+ });
216
+ });
217
+ }
218
+ /**
219
+ * The one SSE event reader: yields each parsed JSON `data:` event (`[DONE]` yields nothing) with a byte limit.
220
+ * An abort interrupts a read that never settles in two ways: the pending read is rejected with the abort, and
221
+ * the underlying reader is cancelled so the connection is released; the abort is also re-checked around every
222
+ * read. The reader is always cancelled and released when the generator ends, however it ends.
223
+ */
224
+ export async function* readSseEvents(response, options) {
225
+ const { signal, errors } = options;
226
+ if (!response?.body)
227
+ throw errors.noBody(response);
228
+ const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
261
229
  const reader = response.body.getReader();
262
230
  const decoder = new TextDecoder();
263
231
  let pending = "";
264
232
  let dataLines = [];
265
233
  let bytes = 0;
266
- const dispatch = () => {
234
+ const decode = () => {
267
235
  if (dataLines.length === 0)
268
- return;
236
+ return undefined;
269
237
  const data = dataLines.join("\n");
270
238
  dataLines = [];
271
239
  if (data === "[DONE]")
272
- return;
273
- let event;
240
+ return undefined;
274
241
  try {
275
- event = JSON.parse(data);
242
+ return JSON.parse(data);
276
243
  }
277
244
  catch (cause) {
278
- throw makeError("malformed SSE JSON", "LCX_INVALID_SSE", { cause });
245
+ throw errors.malformed(cause);
279
246
  }
280
- onEvent(event);
281
247
  };
282
- // An abort must interrupt a read that never settles, not only be noticed between reads. Cancelling
283
- // the reader settles the pending read as done, so the abort is re-checked right after every read.
284
248
  const onAbort = () => {
285
- reader.cancel(options.signal?.reason).catch(() => { });
249
+ reader.cancel(signal?.reason).catch(() => { });
286
250
  };
287
- options.signal?.addEventListener("abort", onAbort, { once: true });
251
+ signal?.addEventListener("abort", onAbort, { once: true });
288
252
  try {
289
253
  while (true) {
290
- abortIfNeeded(options.signal);
291
- const { done, value } = await reader.read();
292
- abortIfNeeded(options.signal);
254
+ abortIfNeeded(signal);
255
+ const { done, value } = await readWithSignal(reader, signal);
256
+ abortIfNeeded(signal);
293
257
  if (done)
294
258
  break;
295
259
  bytes += value.byteLength;
296
260
  if (bytes > maxBytes)
297
- throw makeError(`SSE response exceeds ${maxBytes} bytes`, "LCX_RESPONSE_TOO_LARGE");
261
+ throw errors.tooLarge(maxBytes);
298
262
  pending += decoder.decode(value, { stream: true });
299
263
  let newline;
300
264
  while ((newline = pending.indexOf("\n")) >= 0) {
301
265
  const line = pending.slice(0, newline).replace(/\r$/u, "");
302
266
  pending = pending.slice(newline + 1);
303
- if (line === "")
304
- dispatch();
305
- else if (!line.startsWith(":") && line.startsWith("data:"))
267
+ if (line === "") {
268
+ const event = decode();
269
+ if (event !== undefined)
270
+ yield event;
271
+ }
272
+ else if (!line.startsWith(":") && line.startsWith("data:")) {
306
273
  dataLines.push(line.slice(5).replace(/^ /u, ""));
274
+ }
307
275
  }
308
276
  }
309
277
  pending += decoder.decode();
310
278
  if (pending.startsWith("data:"))
311
279
  dataLines.push(pending.slice(5).replace(/^ /u, ""));
312
- dispatch();
280
+ const event = decode();
281
+ if (event !== undefined)
282
+ yield event;
313
283
  }
314
284
  finally {
315
- options.signal?.removeEventListener("abort", onAbort);
285
+ signal?.removeEventListener("abort", onAbort);
316
286
  try {
317
287
  await reader.cancel();
318
288
  }
@@ -327,3 +297,15 @@ export async function consumeSse(response, onEvent, options = {}) {
327
297
  }
328
298
  }
329
299
  }
300
+ export async function consumeSse(response, onEvent, options = {}) {
301
+ for await (const event of readSseEvents(response, {
302
+ signal: options.signal,
303
+ maxBytes: options.maxResponseBytes,
304
+ errors: {
305
+ noBody: () => makeError("SSE response has no body", "LCX_INVALID_SSE"),
306
+ malformed: (cause) => makeError("malformed SSE JSON", "LCX_INVALID_SSE", { cause }),
307
+ tooLarge: (maxBytes) => makeError(`SSE response exceeds ${maxBytes} bytes`, "LCX_RESPONSE_TOO_LARGE"),
308
+ },
309
+ }))
310
+ onEvent(event);
311
+ }
@@ -21,5 +21,3 @@ export declare function mergeSearchMedia(structured: readonly SearchMediaItem[],
21
21
  * files are LCX's; everything else (pages, video sites) stays an ordinary link.
22
22
  */
23
23
  export declare function extractDirectMediaLinks(text: string): readonly SearchMediaItem[];
24
- /** Direct video files only (see `extractDirectMediaLinks`). */
25
- export declare function extractDirectVideoLinks(text: string): readonly SearchMediaItem[];
@@ -34,6 +34,8 @@ type LiveSettingsConfig = {
34
34
  grokNativeWebSearch: Volatile<boolean>;
35
35
  grokNativeXSearch: Volatile<boolean>;
36
36
  searchMediaPreview: Volatile<boolean>;
37
+ /** Defaults to true: addition-only tool updates on routes that support them. */
38
+ incrementalToolUpdates: Volatile<boolean>;
37
39
  };
38
40
  type HostContext = Context;
39
41
  export declare const Config: z<Schemastery.ObjectS<NoInfer<{
@@ -44,6 +46,7 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
44
46
  grokNativeWebSearch: z<boolean, boolean, "volatile-defined">;
45
47
  grokNativeXSearch: z<boolean, boolean, "volatile-defined">;
46
48
  searchMediaPreview: z<boolean, boolean, "volatile-defined">;
49
+ incrementalToolUpdates: z<boolean, boolean, "volatile-defined">;
47
50
  supportsLongCacheRetention: z<boolean, boolean, "defined">;
48
51
  supportsExplicitPromptCacheMode: z<boolean, boolean, "defined">;
49
52
  alphaCapabilityPath: z<string, string, "defined">;
@@ -71,6 +74,7 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
71
74
  grokNativeWebSearch: z<boolean, boolean, "volatile-defined">;
72
75
  grokNativeXSearch: z<boolean, boolean, "volatile-defined">;
73
76
  searchMediaPreview: z<boolean, boolean, "volatile-defined">;
77
+ incrementalToolUpdates: z<boolean, boolean, "volatile-defined">;
74
78
  supportsLongCacheRetention: z<boolean, boolean, "defined">;
75
79
  supportsExplicitPromptCacheMode: z<boolean, boolean, "defined">;
76
80
  alphaCapabilityPath: z<string, string, "defined">;
package/lib/util.js ADDED
@@ -0,0 +1,21 @@
1
+ /** Small value guards and error constructors shared by the host-side modules. */
2
+ /** A plain JSON-like object: not null and not an array. */
3
+ export function isRecord(value) {
4
+ return value !== null && typeof value === "object" && !Array.isArray(value);
5
+ }
6
+ /** A number that is a positive safe integer. */
7
+ export function isPositiveSafeInteger(value) {
8
+ return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
9
+ }
10
+ /** The value when it is a positive safe integer, otherwise the fallback. */
11
+ export function positiveSafeInteger(value, fallback) {
12
+ return isPositiveSafeInteger(value) ? value : fallback;
13
+ }
14
+ /** A finite number greater than zero. */
15
+ export function isPositiveFinite(value) {
16
+ return typeof value === "number" && Number.isFinite(value) && value > 0;
17
+ }
18
+ /** An Error carrying a stable machine-readable `code`. */
19
+ export function codedError(message, code) {
20
+ return Object.assign(new Error(message), { code });
21
+ }
@@ -184,6 +184,3 @@ export function outputPdfRefs(blocks) {
184
184
  }
185
185
  return refs;
186
186
  }
187
- export function blockPlainText(block) {
188
- return block.lines.map((line) => line.text).filter(Boolean).join(" ");
189
- }
@@ -1,8 +1,9 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import { isIP } from "node:net";
3
3
  import { ServiceMutex } from "./service-mutex.js";
4
- import { fetchJsonWithRetry } from "./transport.js";
5
4
  import { mergeWebRunLinks, outputDomains, outputLineRange, outputLinks, outputPdfRefs, parseWebRunOutput, } from "./web-run-output.js";
5
+ import { isRecord, codedError } from "./util.js";
6
+ import { DEFAULTS } from "./defaults.js";
6
7
  export const ALPHA_ACTIONS = [
7
8
  "search_query",
8
9
  "image_query",
@@ -113,10 +114,7 @@ export const ALPHA_PROBE_VERSION = 15;
113
114
  export const ALPHA_PROBE_QUERY = "Python official documentation docs.python.org/3/";
114
115
  export const ALPHA_PROBE_MAX_OPEN_CANDIDATES = 3;
115
116
  function failure(message, code = "WEB_INVALID_REQUEST") {
116
- return Object.assign(new Error(message), { code });
117
- }
118
- function isObject(v) {
119
- return v !== null && typeof v === "object" && !Array.isArray(v);
117
+ return codedError(message, code);
120
118
  }
121
119
  function text(value, field, max = 1000) {
122
120
  if (typeof value !== "string" || !value.trim() || value.trim().length > max)
@@ -159,7 +157,7 @@ function isAlphaAction(value) {
159
157
  return typeof value === "string" && ALPHA_ACTIONS.includes(value);
160
158
  }
161
159
  export function normalizeAlphaSearchArgs(args) {
162
- if (!isObject(args) || !isAlphaAction(args.action))
160
+ if (!isRecord(args) || !isAlphaAction(args.action))
163
161
  throw failure("websearch_alpha.action is invalid");
164
162
  // The advertised flat schema permits every declared field for every action.
165
163
  // Ignore fields owned by another action; never forward them to Alpha.
@@ -313,7 +311,7 @@ export function alphaActionCommand(args) {
313
311
  ...(args.responseLength ? { response_length: args.responseLength } : {}),
314
312
  };
315
313
  }
316
- export function buildAlphaSearchBody(args, model, sessionId, externalWebAccess = true, maxOutputTokens = 2500, input) {
314
+ export function buildAlphaSearchBody(args, model, sessionId, externalWebAccess = true, maxOutputTokens = DEFAULTS.alphaMaxOutputTokens, input) {
317
315
  if (typeof sessionId !== "string" || !sessionId)
318
316
  throw failure("websearch_alpha requires a DSH session", "LCX_ALPHA_SESSION_REQUIRED");
319
317
  return {
@@ -572,7 +570,7 @@ function artifacts(results, provenance) {
572
570
  const result = { refs: [], refRecords: [], sources: [], observations: new Map() };
573
571
  const seenSources = new Set();
574
572
  const visit = (value, inheritedArtifact) => {
575
- if (!isObject(value) && !Array.isArray(value))
573
+ if (!isRecord(value) && !Array.isArray(value))
576
574
  return;
577
575
  if (Array.isArray(value)) {
578
576
  value.forEach(item => visit(item, inheritedArtifact));
@@ -617,11 +615,11 @@ function structuredLinks(results) {
617
615
  value.forEach(visit);
618
616
  return;
619
617
  }
620
- if (!isObject(value))
618
+ if (!isRecord(value))
621
619
  return;
622
620
  if (Array.isArray(value.links)) {
623
621
  for (const item of value.links) {
624
- if (!isObject(item))
622
+ if (!isRecord(item))
625
623
  continue;
626
624
  const id = item.id ?? item.link_id ?? item.linkId;
627
625
  if (typeof id !== "number" || !Number.isSafeInteger(id))
@@ -688,7 +686,7 @@ function alphaCommandErrorEnvelope(output, action) {
688
686
  /\b(?:invalid|unavailable|not available|unresolved)\b/iu.test(reference[2]));
689
687
  }
690
688
  export function parseAlphaSearchResponse(response, options) {
691
- if (!isObject(response) ||
689
+ if (!isRecord(response) ||
692
690
  typeof response.output !== "string" ||
693
691
  (response.results !== undefined && !Array.isArray(response.results)))
694
692
  throw failure("LCX Alpha Web Search returned an invalid response", "LCX_ALPHA_INVALID_RESPONSE");
@@ -771,11 +769,11 @@ function sourceUrlForRef(sources, refId) {
771
769
  return typeof match?.url === "string" ? match.url : undefined;
772
770
  }
773
771
  export function renderAlphaSearchResult(value) {
774
- const data = isObject(value) ? value : {};
772
+ const data = isRecord(value) ? value : {};
775
773
  const parts = [];
776
774
  if (typeof data.content === "string")
777
775
  parts.push(data.content);
778
- const sources = Array.isArray(data.sources) ? data.sources.filter(isObject) : [];
776
+ const sources = Array.isArray(data.sources) ? data.sources.filter(isRecord) : [];
779
777
  const refs = opaqueRefList(data.refs);
780
778
  if (refs.length) {
781
779
  parts.push(`可继续操作的引用:\n${refs.map((ref) => {
@@ -784,7 +782,7 @@ export function renderAlphaSearchResult(value) {
784
782
  }).join("\n")}`);
785
783
  }
786
784
  const links = Array.isArray(data.links)
787
- ? data.links.filter((link) => isObject(link) && Number.isSafeInteger(link.id))
785
+ ? data.links.filter((link) => isRecord(link) && Number.isSafeInteger(link.id))
788
786
  : [];
789
787
  if (links.length) {
790
788
  parts.push(`可点击链接:\n${links.map((link) => {
@@ -824,7 +822,7 @@ export function remapAlphaResultRefs(value, handles) {
824
822
  }
825
823
  if (Array.isArray(input))
826
824
  return input.map((item) => replace(item));
827
- if (isObject(input))
825
+ if (isRecord(input))
828
826
  return Object.fromEntries(Object.entries(input).map(([field, item]) => [field, replace(item, field)]));
829
827
  return input;
830
828
  };
@@ -856,11 +854,8 @@ export async function runWithAlphaSessionLock(sessionId, signal, task) {
856
854
  alphaSessionLocks.delete(sessionId);
857
855
  }
858
856
  }
859
- export async function fetchAlphaSearchJson(options) {
860
- return runWithAlphaSessionLock(options.sessionId, options.signal, () => fetchJsonWithRetry(options.url, options.body, options.headers, options.signal, options.timeoutMs, alphaSearchRetryOptions(options.maxResponseBytes)));
861
- }
862
857
  function probeFailureState(error) {
863
- const detail = isObject(error) ? error : {};
858
+ const detail = isRecord(error) ? error : {};
864
859
  if ([404, 405].includes(detail.status) ||
865
860
  ["LCX_ALPHA_ACTION_UNAVAILABLE", "LCX_ALPHA_ACTION_FAILED"].includes(String(detail.code ?? "")) ||
866
861
  /channel does not support|unsupported action|not implemented/iu.test(String(detail.message ?? "")))
@@ -873,7 +868,7 @@ function alphaProbeStructuredResult(value, seen = new Set()) {
873
868
  seen.add(value);
874
869
  if (Array.isArray(value))
875
870
  return value.some((item) => alphaProbeStructuredResult(item, seen));
876
- if (!isObject(value))
871
+ if (!isRecord(value))
877
872
  return false;
878
873
  const refId = typeof value.ref_id === "string" && value.ref_id
879
874
  ? value.ref_id
@@ -887,7 +882,7 @@ function alphaProbeStructuredResult(value, seen = new Set()) {
887
882
  return Object.values(value).some((item) => alphaProbeStructuredResult(item, seen));
888
883
  }
889
884
  function alphaProbeStructuredBlock(block) {
890
- if (!isObject(block))
885
+ if (!isRecord(block))
891
886
  return false;
892
887
  const references = Array.isArray(block.references) ? block.references : [];
893
888
  const links = Array.isArray(block.links) ? block.links : [];
@@ -895,15 +890,15 @@ function alphaProbeStructuredBlock(block) {
895
890
  const lines = Array.isArray(block.lines) ? block.lines : [];
896
891
  if (references.some((ref) => typeof ref === "string" && ref && !isAlphaHttpUrl(ref)))
897
892
  return true;
898
- if (links.some((link) => isObject(link) && Number.isSafeInteger(link.id)))
893
+ if (links.some((link) => isRecord(link) && Number.isSafeInteger(link.id)))
899
894
  return true;
900
895
  if (metadata.some((item) => item === "HTML" || item === "PDF" || /^\d+ (?:lines|pages)$/u.test(String(item))))
901
896
  return true;
902
- return lines.some((line) => isObject(line) && (Number.isSafeInteger(line.line) || Number.isSafeInteger(line.page)));
897
+ return lines.some((line) => isRecord(line) && (Number.isSafeInteger(line.line) || Number.isSafeInteger(line.page)));
903
898
  }
904
899
  const ALPHA_PROBE_SEMANTIC_FAILURE = /\breference(?: id)?\s+(?:is\s+)?(?:invalid|unavailable)\b/iu;
905
900
  function alphaProbeResultHasEvidence(action, value) {
906
- const data = isObject(value) ? value : {};
901
+ const data = isRecord(value) ? value : {};
907
902
  if (alphaPageFetchFailed(data.content, action))
908
903
  return false;
909
904
  if (alphaCommandErrorEnvelope(data.content, action))
@@ -914,7 +909,7 @@ function alphaProbeResultHasEvidence(action, value) {
914
909
  const refs = Array.isArray(data.refs) &&
915
910
  data.refs.some((ref) => typeof ref === "string" && ref && !isAlphaHttpUrl(ref));
916
911
  const links = Array.isArray(data.links) &&
917
- data.links.some((link) => isObject(link) && Number.isSafeInteger(link.id));
912
+ data.links.some((link) => isRecord(link) && Number.isSafeInteger(link.id));
918
913
  const pdfRefs = Array.isArray(data.pdfRefs) &&
919
914
  data.pdfRefs.some((ref) => typeof ref === "string" && ref && !isAlphaHttpUrl(ref));
920
915
  const structuredResults = Array.isArray(data.results) &&
@@ -992,7 +987,7 @@ export async function probeAlphaCapabilities({ invoke, startChain, schemaFingerp
992
987
  break;
993
988
  }
994
989
  catch (error) {
995
- if (isObject(error) && error.code === "LCX_ALPHA_PAGE_FETCH_FAILED")
990
+ if (isRecord(error) && error.code === "LCX_ALPHA_PAGE_FETCH_FAILED")
996
991
  continue;
997
992
  actions.open = probeFailureState(error);
998
993
  result.classification = chain === 0 && actions.open === "unsupported" ? "emulated-search-only" : "unknown";
@@ -1034,7 +1029,7 @@ export async function probeAlphaCapabilities({ invoke, startChain, schemaFingerp
1034
1029
  const clickRefs = clickPage && Array.isArray(clickPage.refs) ? clickPage.refs : [];
1035
1030
  const clickLinks = clickPage && Array.isArray(clickPage.links) ? clickPage.links : [];
1036
1031
  const clickRef = clickRefs[0];
1037
- const linkId = isObject(clickLinks[0]) ? clickLinks[0].id : undefined;
1032
+ const linkId = isRecord(clickLinks[0]) ? clickLinks[0].id : undefined;
1038
1033
  if (clickRef && Number.isSafeInteger(linkId)) {
1039
1034
  try {
1040
1035
  const clicked = await invoke({
@@ -1,12 +1,10 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import { ALPHA_ACTIONS, ALPHA_PROBE_VERSION, ALPHA_SEARCH_PARAMETERS } from "./web-search-alpha.js";
3
3
  import { JsonStore } from "./json-store.js";
4
+ import { isRecord } from "./util.js";
4
5
  const VERSION = 1;
5
6
  const CLASSIFICATIONS = new Set(["native", "command-capable", "emulated-search-only", "unsupported", "unknown"]);
6
7
  const ACTION_STATES = new Set(["supported", "unsupported", "unknown"]);
7
- function isRecord(value) {
8
- return value !== null && typeof value === "object" && !Array.isArray(value);
9
- }
10
8
  function isClassification(value) { return typeof value === "string" && CLASSIFICATIONS.has(value); }
11
9
  function isActionState(value) { return typeof value === "string" && ACTION_STATES.has(value); }
12
10
  function isProvenance(value) { return value === "trusted-native" || value === "unavailable"; }