@juspay/neurolink 12.57.0 → 12.58.1

package/dist/providers/catalog/schema.js

@@ -545,8 +545,50 @@ const decideMediaSchema = z
     path: ["videoKey"],
     message: "decide.media.videoKey must differ from imagesKey: one body key cannot carry both",
 });
+const GUARD_LIST_MAX = 8;
+const ambientGuardEnvNameSchema = z
+    .string()
+    .max(64)
+    .regex(/^[A-Z][A-Z0-9_]*$/, "an environment variable name must be upper-case letters, digits and underscores, and start with a letter");
+// Lower-case scheme, host labels and an optional port, nothing else: the
+// origin is compared after the same parsing a base URL gets, so a spelling
+// that URL would normalise (a trailing slash, a path, an upper-case host) is
+// refused here instead of being quietly accepted.
+const AMBIENT_GUARD_ORIGIN_PATTERN = /^https?:\/\/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*(?::[0-9]{1,5})?$/;
+function parsesAsUrl(value) {
+    try {
+        new URL(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const ambientGuardOriginSchema = z
+    .string()
+    .max(100)
+    .regex(AMBIENT_GUARD_ORIGIN_PATTERN, "a trusted origin must be an http(s) origin: a lower-case scheme, host and optional port, with no path, query, fragment or userinfo")
+    .refine(parsesAsUrl, {
+    message: "a trusted origin must parse as a URL (a valid host, port 0 to 65535)",
+});
+const ambientGuardCredentialKeySchema = z
+    .string()
+    .max(64)
+    .regex(/^[a-zA-Z][a-zA-Z0-9]*$/, "a credentials key must be letters and digits, and start with a letter");
+const ambientKeyGuardSchema = z.strictObject({
+    baseURLEnvVars: z.array(ambientGuardEnvNameSchema).min(1).max(GUARD_LIST_MAX),
+    trustedOrigins: z.array(ambientGuardOriginSchema).min(1).max(GUARD_LIST_MAX),
+    credentialBaseURLs: z
+        .array(z.strictObject({
+        key: ambientGuardCredentialKeySchema,
+        field: z.literal("baseURL"),
+    }))
+        .min(1)
+        .max(GUARD_LIST_MAX)
+        .optional(),
+});
 const decideBlockSchema = z.strictObject({
-    dialect: z.enum(["system-one"]),
+    dialect: z.enum(["system-one", "openai-decisions"]),
     order: decidePositiveInt,
     baseURLRequired: z.boolean().optional(),
     baseURLNormalize: z
@@ -559,6 +601,7 @@ const decideBlockSchema = z.strictObject({
         alias: z.string().min(1).optional(),
     }),
     media: decideMediaSchema.optional(),
+    ambientKeyGuard: ambientKeyGuardSchema.optional(),
     requestIdHeaders: z.array(decideHeaderNameSchema).optional(),
     response: z
         .strictObject({ modelPaths: z.array(decidePathSchema).optional() })
@@ -705,18 +748,34 @@ const decideCatalogJsonSchema = z
     }
     const mediaKeys = decide.media;
     const mediaAllowance = entry.decisionLimits?.media;
-    if (mediaKeys !== undefined && mediaAllowance === undefined) {
-        issue(["decide", "media"], "decide.media needs decisionLimits.media: without an allowance the base class refuses every image and video, so these keys would never be written");
-    }
-    if (mediaKeys === undefined && mediaAllowance !== undefined) {
-        issue(["decisionLimits", "media"], "decisionLimits.media needs decide.media: without body keys the engine would prepare a request's media and then leave it out of the body");
+    if (decide.dialect === "openai-decisions") {
+        // This dialect writes images into the request input itself, so it has no
+        // body keys to name, and the input has no video part. The allowance
+        // alone is how many images a request may carry.
+        if (mediaKeys !== undefined) {
+            issue(["decide", "media"], "decide.media is not valid with dialect openai-decisions: that dialect places images in the request input itself and has no body keys for them");
+        }
+        if (mediaAllowance?.video === true) {
+            issue(["decisionLimits", "media", "video"], "decisionLimits.media.video must be false with dialect openai-decisions: its request input has no video part");
+        }
+        if (placement !== "body") {
+            issue(["decide", "model", "placement"], "decide.model.placement must be body with dialect openai-decisions: the model is always a field of the request");
+        }
     }
-    if (mediaKeys !== undefined && mediaAllowance !== undefined) {
-        if (mediaAllowance.video && mediaKeys.videoKey === undefined) {
-            issue(["decide", "media", "videoKey"], "decide.media.videoKey is required when decisionLimits.media.video is true");
+    else {
+        if (mediaKeys !== undefined && mediaAllowance === undefined) {
+            issue(["decide", "media"], "decide.media needs decisionLimits.media: without an allowance the base class refuses every image and video, so these keys would never be written");
         }
-        if (!mediaAllowance.video && mediaKeys.videoKey !== undefined) {
-            issue(["decide", "media", "videoKey"], "decide.media.videoKey must be omitted when decisionLimits.media.video is false");
+        if (mediaKeys === undefined && mediaAllowance !== undefined) {
+            issue(["decisionLimits", "media"], "decisionLimits.media needs decide.media: without body keys the engine would prepare a request's media and then leave it out of the body");
+        }
+        if (mediaKeys !== undefined && mediaAllowance !== undefined) {
+            if (mediaAllowance.video && mediaKeys.videoKey === undefined) {
+                issue(["decide", "media", "videoKey"], "decide.media.videoKey is required when decisionLimits.media.video is true");
+            }
+            if (!mediaAllowance.video && mediaKeys.videoKey !== undefined) {
+                issue(["decide", "media", "videoKey"], "decide.media.videoKey must be omitted when decisionLimits.media.video is false");
+            }
         }
     }
     if (decide.baseURLRequired === true &&
@@ -738,6 +797,28 @@ const decideCatalogJsonSchema = z
         }
         seenHeaders.add(header.toLowerCase());
     });
+    const guard = decide.ambientKeyGuard;
+    if (guard !== undefined) {
+        const ownBaseURLVar = wire.envOverrides?.baseURL ??
+            `${entry.id.toUpperCase().replace(/-/g, "_")}_BASE_URL`;
+        const lists = [
+            ["baseURLEnvVars", guard.baseURLEnvVars, "variable"],
+            ["trustedOrigins", guard.trustedOrigins, "origin"],
+        ];
+        for (const [field, values, noun] of lists) {
+            if (new Set(values).size !== values.length) {
+                issue(["decide", "ambientKeyGuard", field], `lists the same ${noun} twice`);
+            }
+        }
+        const credentialFields = guard.credentialBaseURLs ?? [];
+        if (new Set(credentialFields.map((c) => `${c.key}.${c.field}`)).size !==
+            credentialFields.length) {
+            issue(["decide", "ambientKeyGuard", "credentialBaseURLs"], "lists the same credentials field twice");
+        }
+        if (guard.baseURLEnvVars.includes(ownBaseURLVar)) {
+            issue(["decide", "ambientKeyGuard", "baseURLEnvVars"], `must not list the provider's own base-URL variable ${ownBaseURLVar}: setting it already exempts the key`);
+        }
+    }
     for (const key of UNSUPPORTED_DECIDE_WIRE_KEYS) {
         if (wire[key] !== undefined) {
             issue(["wire", key], `wire.${key} is not supported on decide entries yet; ConfiguredDecisionProvider does not read it`);

package/dist/providers/configuredDecision.js

@@ -75,20 +75,15 @@ export class ConfiguredDecisionProvider extends SystemOneDecisionProvider {
     }
     buildDecisionBody(state, questions, model, media) {
         const { placement, alias } = this.entry.decide.model;
-        const body = placement === "body-unless-alias" && model === alias
-            ? { state, questions }
-            : { model, state, questions };
-        const keys = this.entry.decide.media;
-        if (!keys || !media) {
-            return body;
-        }
-        // A key is written only for media the request carries: a server may refuse
-        // an empty `images`.
-        return {
-            ...body,
-            ...(media.images.length > 0 ? { [keys.imagesKey]: media.images } : {}),
-            ...(media.video && keys.videoKey ? { [keys.videoKey]: media.video } : {}),
-        };
+        return this.dialect().buildBody({
+            state,
+            questions,
+            model: placement === "body-unless-alias" && model === alias
+                ? undefined
+                : model,
+            media,
+            mediaKeys: this.entry.decide.media,
+        });
     }
     parseDecisionError(status, payload, requestId) {
         return classifyDecisionError(this.entry.decide.errors, {

package/dist/providers/decide/dialects/index.js

@@ -1,5 +1,7 @@
+import { openaiDecisionsDialect } from "./openaiDecisions.js";
 import { systemOneDialect } from "./systemOne.js";
 const DIALECTS = {
     "system-one": systemOneDialect,
+    "openai-decisions": openaiDecisionsDialect,
 };
 export const getDecisionDialect = (name) => DIALECTS[name];

package/dist/providers/decide/dialects/openaiDecisions.d.ts

@@ -0,0 +1,2 @@
+import type { DecisionDialect } from "../../../types/index.js";
+export declare const openaiDecisionsDialect: DecisionDialect;

package/dist/providers/decide/dialects/openaiDecisions.js

@@ -0,0 +1,228 @@
+import { asNumber, isRecord } from "../guards.js";
+const PROBABILITY_SUM_TOLERANCE = 0.01;
+// A sum one tolerance away (0.99, 1.01) lands a rounding error past the
+// tolerance in floating point; it is within it.
+const SUM_ROUNDING_SLACK = 1e-9;
+const text = (value) => typeof value === "string" ? value : JSON.stringify(value);
+const described = (value) => value === null || value === undefined ? {} : { description: text(value) };
+function encodeQuestion(question) {
+    if (question.type === "boolean") {
+        // The wire has no per-side text, so each side joins the instructions.
+        const { true: whenTrue, false: whenFalse } = question.criteria ?? {};
+        return {
+            type: "predicate",
+            instructions: text(question.instructions) +
+                (whenTrue === null || whenTrue === undefined
+                    ? ""
+                    : `\n\nAnswer true when: ${text(whenTrue)}`) +
+                (whenFalse === null || whenFalse === undefined
+                    ? ""
+                    : `\nAnswer false when: ${text(whenFalse)}`),
+        };
+    }
+    if (question.type === "choice") {
+        return {
+            type: "choice",
+            instructions: text(question.instructions),
+            choices: Object.entries(question.criteria).map(([value, rubric]) => ({
+                value,
+                ...described(rubric),
+            })),
+        };
+    }
+    // The index is the label so a returned `value` and `label` can never
+    // disagree about which level it is; the rubric text rides in `description`.
+    return {
+        type: "score",
+        instructions: text(question.instructions),
+        levels: question.criteria.map((rubric, index) => ({
+            label: String(index),
+            ...described(rubric),
+        })),
+    };
+}
+const inUnitRange = (value) => value >= 0 && value <= 1;
+/**
+ * The answer's distribution keyed by the keys that were asked, or null unless
+ * it names each asked key exactly once, with probabilities that sum to one.
+ * The result is in asked order, not the server's.
+ */
+function readDistribution(raw, asked, keyOf) {
+    if (!Array.isArray(raw) || raw.length !== asked.length) {
+        return null;
+    }
+    const expected = new Set(asked);
+    const seen = new Map();
+    for (const entry of raw) {
+        if (!isRecord(entry)) {
+            return null;
+        }
+        const key = keyOf(entry.value);
+        const probability = asNumber(entry.probability);
+        if (key === undefined ||
+            probability === undefined ||
+            !inUnitRange(probability) ||
+            !expected.has(key) ||
+            seen.has(key)) {
+            return null;
+        }
+        seen.set(key, probability);
+    }
+    let sum = 0;
+    for (const probability of seen.values()) {
+        sum += probability;
+    }
+    if (Math.abs(sum - 1) > PROBABILITY_SUM_TOLERANCE + SUM_ROUNDING_SLACK) {
+        return null;
+    }
+    return Object.fromEntries(asked.map((key) => [key, seen.get(key) ?? 0]));
+}
+const peak = (probabilities) => Math.max(...Object.values(probabilities));
+/** The answer's own confidence, else the peak; null when its own is outside 0 to 1. */
+function readConfidence(raw, probabilities) {
+    const own = asNumber(raw);
+    if (own === undefined) {
+        return peak(probabilities);
+    }
+    return inUnitRange(own) ? own : null;
+}
+function readChoice(question, raw) {
+    const options = Object.keys(question.criteria);
+    if (typeof raw.choice !== "string" || !options.includes(raw.choice)) {
+        return null;
+    }
+    const probabilities = readDistribution(raw.probabilities, options, (value) => typeof value === "string" ? value : undefined);
+    if (!probabilities) {
+        return null;
+    }
+    const confidence = readConfidence(raw.confidence, probabilities);
+    return confidence === null
+        ? null
+        : { type: "choice", choice: raw.choice, confidence, probabilities };
+}
+function readScore(question, raw) {
+    const score = asNumber(raw.score);
+    const levels = question.criteria.map((_rubric, index) => String(index));
+    const probabilities = readDistribution(raw.probabilities, levels, (value) => typeof value === "number" && Number.isInteger(value)
+        ? String(value)
+        : undefined);
+    // The probability-weighted mean of the level indices cannot leave 0 to n-1.
+    if (score === undefined ||
+        score < 0 ||
+        score > levels.length - 1 ||
+        !probabilities) {
+        return null;
+    }
+    const confidence = readConfidence(raw.confidence, probabilities);
+    if (confidence === null) {
+        return null;
+    }
+    return {
+        type: "score",
+        score,
+        confidence,
+        legend: Object.fromEntries(question.criteria.map((rubric, index) => [
+            String(index),
+            rubric === null || rubric === undefined ? "" : text(rubric),
+        ])),
+        probabilities,
+    };
+}
+function readAnswer(question, raw) {
+    if (question.type === "boolean") {
+        const probability = asNumber(raw.probability);
+        return raw.type === "predicate" &&
+            probability !== undefined &&
+            inUnitRange(probability)
+            ? { type: "boolean", probability }
+            : null;
+    }
+    if (question.type === "choice") {
+        return raw.type === "choice" ? readChoice(question, raw) : null;
+    }
+    return raw.type === "score" ? readScore(question, raw) : null;
+}
+/** Number of answers carrying each asked name, so a repeated one can be refused. */
+function countAskedNames(raw, asked) {
+    const counts = new Map();
+    for (const item of raw) {
+        const name = isRecord(item) ? item.name : undefined;
+        if (typeof name === "string" && Object.hasOwn(asked, name)) {
+            counts.set(name, (counts.get(name) ?? 0) + 1);
+        }
+    }
+    return counts;
+}
+export const openaiDecisionsDialect = {
+    name: "openai-decisions",
+    encodeQuestion,
+    buildBody: ({ state, questions, model, media }) => {
+        const images = media?.images ?? [];
+        const stateText = text(state);
+        return {
+            ...(model === undefined ? {} : { model }),
+            input: images.length === 0
+                ? stateText
+                : [
+                    {
+                        role: "user",
+                        content: [
+                            ...(stateText === ""
+                                ? []
+                                : [{ type: "input_text", text: stateText }]),
+                            ...images.map((url) => ({
+                                type: "input_image",
+                                image_url: url,
+                            })),
+                        ],
+                    },
+                ],
+            questions: Object.entries(questions).map(([name, question]) => ({
+                ...question,
+                name,
+            })),
+        };
+    },
+    // The wire echoes each question's `name`, and the server's answer is checked
+    // against the question asked: one that fails any check is dropped and named,
+    // never repaired, so the other answers in the batch survive.
+    readAnswers: (decoded, _reportedConfidence, asked) => {
+        const raw = decoded.answers;
+        if (!Array.isArray(raw)) {
+            return undefined;
+        }
+        const counts = countAskedNames(raw, asked);
+        const answers = new Map();
+        const dropped = [];
+        const refused = [];
+        raw.forEach((item, index) => {
+            const record = isRecord(item) ? item : undefined;
+            const name = typeof record?.name === "string" ? record.name : undefined;
+            const question = name !== undefined && Object.hasOwn(asked, name)
+                ? asked[name]
+                : undefined;
+            if (!record || name === undefined || !question) {
+                dropped.push(`#${index}`);
+                return;
+            }
+            if ((counts.get(name) ?? 0) > 1) {
+                if (!dropped.includes(name)) {
+                    dropped.push(name);
+                }
+                return;
+            }
+            if (record.type === "refusal") {
+                refused.push(name);
+                return;
+            }
+            const answer = readAnswer(question, record);
+            if (answer) {
+                answers.set(name, answer);
+            }
+            else {
+                dropped.push(name);
+            }
+        });
+        return { answers: Object.fromEntries(answers), dropped, refused };
+    },
+};

package/dist/providers/decide/dialects/systemOne.js

@@ -83,6 +83,23 @@ function encodeQuestion(question) {
 export const systemOneDialect = {
     name: "system-one",
     encodeQuestion,
+    buildBody: ({ state, questions, model, media, mediaKeys }) => {
+        const body = model === undefined ? { state, questions } : { model, state, questions };
+        if (!mediaKeys || !media) {
+            return body;
+        }
+        // A key is written only for media the request carries: a server may refuse
+        // an empty `images`.
+        return {
+            ...body,
+            ...(media.images.length > 0
+                ? { [mediaKeys.imagesKey]: media.images }
+                : {}),
+            ...(media.video && mediaKeys.videoKey
+                ? { [mediaKeys.videoKey]: media.video }
+                : {}),
+        };
+    },
     readAnswers: (decoded, reportedConfidence) => {
         const raw = decoded.answers;
         if (!isRecord(raw)) {

package/dist/providers/systemOneDecision.js

@@ -297,7 +297,7 @@ export class SystemOneDecisionProvider extends BaseProvider {
                 }
                 const decoded = this.readDecisionPayload(payload);
                 const reading = isRecord(decoded)
-                    ? this.dialect().readAnswers(decoded, this.reportedConfidence(decoded))
+                    ? this.dialect().readAnswers(decoded, this.reportedConfidence(decoded), request.questions)
                     : undefined;
                 if (!isRecord(decoded) || !reading) {
                     throw this.decisionError({
@@ -313,6 +313,11 @@ export class SystemOneDecisionProvider extends BaseProvider {
                         requestId,
                     });
                 }
+                for (const id of reading.refused ?? []) {
+                    logger.warn(`${label}: the model declined to answer "${id}"`, {
+                        requestId,
+                    });
+                }
                 const answers = { ...reading.answers };
                 const usage = isRecord(decoded.usage) ? decoded.usage : {};
                 return {

package/dist/telemetry/attributes.d.ts

@@ -130,6 +130,12 @@ export declare const LANGFUSE_ATTR: {
 };
 /** Default ceiling for serialized span attribute values. */
 export declare const SPAN_ATTRIBUTE_MAX_CHARS = 40000;
+/**
+ * The ceiling in force: `NEUROLINK_SPAN_ATTRIBUTE_MAX_CHARS` when it is a
+ * positive whole number (raised to the minimum if lower), otherwise the
+ * default. Read on every call, so a change applies to the next span.
+ */
+export declare function spanAttributeMaxChars(): number;
 /**
  * Returns a copy of `value` with credentials masked: values under keys such as
  * `access_token`, `password`, `authorization` or `set-cookie`, bearer tokens
@@ -161,8 +167,9 @@ export declare function spanJsonAttribute(value: unknown, maxChars?: number): st
  *
  * A head cut keeps the system prompt and drops everything after it, so a long
  * system prompt hides every message, the user's question included. Here the
- * prompt and the newest messages are budgeted first, older messages are
- * dropped whole and counted, and the system prompt gets whatever room is left.
- * The result is always valid JSON.
+ * prompt, the current question and this turn's newest messages are budgeted
+ * first, earlier messages are dropped whole and counted, and the system prompt
+ * gets whatever room is left. A tool result is never kept without the call it
+ * answers. The result is always valid JSON.
  */
 export declare function spanModelRequestAttribute(rawRequest: SpanModelRequest, maxChars?: number): string;