@zq-silk/yui 0.15.3 → 0.15.6

package/dist/runtime/agentError.js

@@ -31,8 +31,11 @@ export function standardAgentError(input) {
         phase: input.phase,
         category: classification.category,
         code: requiredErrorText(classification.code, "Agent error code"),
-        message: requiredErrorText(input.message, "Agent error message"),
-        raw: requiredErrorText(input.raw, "Agent error raw payload"),
+        // Both readable fields pass the same redaction boundary. `message` is
+        // often a Provider string interpolated by a caller, so it can carry a
+        // credential even when `raw` is already clean.
+        message: redactAgentErrorText(requiredErrorText(input.message, "Agent error message")),
+        raw: redactAgentErrorText(requiredErrorText(input.raw, "Agent error raw payload")),
         inputDisposition: input.inputDisposition
             ?? classification.inputDisposition
             ?? "unknown",
@@ -46,6 +49,117 @@ export const UNKNOWN_AGENT_ERROR_CLASSIFICATION = Object.freeze({
     category: "unknown",
     code: "unknown"
 });
+export function providerDeliveryFailure(input) {
+    const raw = input.raw === undefined ? undefined : serializeAgentErrorRaw(input.raw);
+    return Object.freeze({
+        ...definedDeliveryFields(input),
+        detail: boundDisplayText(redactAgentErrorText(requiredErrorText(input.detail, "Provider delivery failure detail"))),
+        ...(raw === undefined ? {} : { raw }),
+        phase: input.phase,
+        inputDisposition: input.inputDisposition
+    });
+}
+/** Forward facts owned by the failing operation without parsing its prose. */
+export function providerDeliveryFailureFacts(failure) {
+    if (failure === undefined)
+        return {};
+    return {
+        ...(failure.sessionDisposition === undefined ? {} : { sessionDisposition: failure.sessionDisposition }),
+        ...(failure.registrationDisposition === undefined ? {} : { registrationDisposition: failure.registrationDisposition }),
+        ...(failure.errorName === undefined ? {} : { errorName: failure.errorName }),
+        ...(failure.causeName === undefined ? {} : { causeName: failure.causeName }),
+        ...(failure.hostState === undefined ? {} : { hostState: failure.hostState }),
+        ...(failure.expectedRuntimeGenerationId === undefined ? {} : { expectedRuntimeGenerationId: failure.expectedRuntimeGenerationId }),
+        ...(failure.observedRuntimeGenerationId === undefined ? {} : { observedRuntimeGenerationId: failure.observedRuntimeGenerationId }),
+        ...(failure.attemptId === undefined ? {} : { attemptId: failure.attemptId })
+    };
+}
+/**
+ * Builds a delivery failure from a thrown error, keeping the structured cause.
+ *
+ * Call sites used to interpolate `error.message` into a sentence, which
+ * discarded the class name and the whole `cause` chain. Here `detail` stays the
+ * readable projection while `raw`/`errorName`/`causeName` carry the structure.
+ */
+export function providerDeliveryFailureFrom(error, input) {
+    const causeName = innermostCauseName(error);
+    return providerDeliveryFailure({
+        ...input,
+        detail: input.detail ?? errorMessageText(error),
+        raw: serializeAgentErrorRaw(error),
+        ...(error instanceof Error ? { errorName: error.name } : {}),
+        ...(causeName === undefined ? {} : { causeName })
+    });
+}
+/**
+ * Class name of the innermost `cause`, which is usually the real reason a
+ * wrapped failure occurred. Bounded: a malformed chain must not spin here.
+ */
+export function innermostCauseName(error) {
+    let current = error instanceof Error ? error.cause : undefined;
+    let name;
+    for (let depth = 0; depth < 16 && current instanceof Error; depth += 1) {
+        name = current.name;
+        current = current.cause;
+    }
+    return name;
+}
+function errorMessageText(error) {
+    if (error instanceof Error) {
+        return error.message.trim().length > 0 ? error.message : error.name;
+    }
+    return String(error ?? "unknown error");
+}
+/**
+ * Renders a delivery failure as one readable line for a Turn summary. The
+ * complete record stays available on `runtime.agent-error`; this is the
+ * bounded projection, never a replacement for the original cause.
+ */
+export function formatProviderDeliveryFailure(failure) {
+    const fields = [
+        `phase=${failure.phase}`,
+        `inputDisposition=${failure.inputDisposition}`
+    ];
+    if (failure.hostState !== undefined)
+        fields.push(`hostState=${failure.hostState}`);
+    if (failure.errorName !== undefined)
+        fields.push(`error=${failure.errorName}`);
+    if (failure.causeName !== undefined)
+        fields.push(`cause=${failure.causeName}`);
+    if (failure.expectedRuntimeGenerationId !== undefined) {
+        fields.push(`expectedGeneration=${failure.expectedRuntimeGenerationId}`);
+    }
+    if (failure.observedRuntimeGenerationId !== undefined) {
+        fields.push(`observedGeneration=${failure.observedRuntimeGenerationId}`);
+    }
+    if (failure.attemptId !== undefined)
+        fields.push(`attemptId=${failure.attemptId}`);
+    if (failure.registrationDisposition !== undefined) {
+        fields.push(`registration=${failure.registrationDisposition}`);
+    }
+    if (failure.sessionDisposition !== undefined) {
+        fields.push(`sessionDisposition=${failure.sessionDisposition}`);
+    }
+    // A clipped projection must say where the complete cause is, or a reader
+    // takes the visible fragment for the whole reason.
+    if (isTruncatedText(failure.detail))
+        fields.push("detailTruncated=see-raw");
+    return `${failure.detail} (${fields.join(" ")})`;
+}
+/**
+ * Drops absent fields and passes every retained readable one through the same
+ * redaction and display bound as `detail`. These fields carry a class name or
+ * an id today, but they are persisted and publicly readable, so they must not
+ * be the one path that skips the boundary.
+ */
+function definedDeliveryFields(value) {
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, member]) => member !== undefined)
+        .map(([key, member]) => [
+        key,
+        typeof member === "string" ? boundDisplayText(redactAgentErrorText(member)) : member
+    ]));
+}
 export function isAgentErrorCategory(value) {
     return typeof value === "string"
         && AGENT_ERROR_CATEGORIES.includes(value);
@@ -73,14 +187,57 @@ export function isStandardAgentError(value) {
         && (error.retryAfterMs === undefined
             || (Number.isSafeInteger(error.retryAfterMs) && error.retryAfterMs >= 0));
 }
+/**
+ * Upper bound for one persisted raw payload. A Provider stack trace or a
+ * transport dump stays readable well below this; anything larger keeps its
+ * head and its tail with an explicit marker between them.
+ */
+const MAX_RAW_CHARS = 16_000;
+/**
+ * Bound for a one-line readable projection such as `detail` or a summary. The
+ * complete redacted chain lives in `raw`, so clipping here loses nothing.
+ */
+const MAX_DISPLAY_CHARS = 2_000;
+/**
+ * Bound for one field inside a serialized payload. Sized so a deep chain of
+ * wrapped errors still fits under `MAX_RAW_CHARS` with its causes intact.
+ */
+const MAX_FIELD_CHARS = 2_000;
+const TRUNCATION_MARKER = "…[truncated";
+/**
+ * Serializes any failure into one bounded, secret-redacted payload.
+ *
+ * `raw` is the authoritative cause and is persisted verbatim on
+ * `runtime.agent-error`, so it is the last boundary before a Provider
+ * credential could reach durable storage or a public read. Redaction happens
+ * here rather than at each call site: an unredacted path added later would
+ * otherwise silently leak. `cause` chains and non-enumerable Error fields are
+ * retained because they usually carry the real reason.
+ */
 export function serializeAgentErrorRaw(value) {
+    return boundRawPayload(redactAgentErrorText(rawPayloadText(value)));
+}
+function rawPayloadText(value) {
     if (typeof value === "string")
-        return requiredErrorText(value, "Agent error raw payload");
+        return value;
     if (value === undefined)
         return "Agent operation failed without an error payload.";
     try {
         const seen = new WeakSet();
-        const serialized = JSON.stringify(value, (_key, member) => {
+        const serialized = JSON.stringify(value, (key, member) => {
+            // Turn input is the Agent's prompt: Task context, quoted files, whatever
+            // the Role was told. It is not a failure fact, and it reaches the same
+            // durable, publicly-readable record as the rest of this payload. A
+            // transport client that echoes its own request into the thrown error
+            // carries it here without any call site intending to persist it.
+            if (PROVIDER_INPUT_KEYS.has(key))
+                return "[PROVIDER-INPUT-OMITTED]";
+            // Each field is clipped on its own so no single oversized message or
+            // stack can push the rest of the chain past the payload bound. Clipping
+            // the whole payload instead lost the innermost `cause`, which is the one
+            // field that usually states the real reason.
+            if (typeof member === "string")
+                return boundFieldText(member);
             if (typeof member === "bigint")
                 return member.toString();
             if (member !== null && typeof member === "object") {
@@ -88,21 +245,151 @@ export function serializeAgentErrorRaw(value) {
                     return "[Circular]";
                 seen.add(member);
                 if (member instanceof Error) {
-                    return Object.fromEntries(Object.getOwnPropertyNames(member).map((name) => [
-                        name,
-                        member[name]
-                    ]));
+                    // Error's own fields are non-enumerable, and `cause` is where a
+                    // wrapped transport/controller failure keeps its real reason.
+                    // `stack` is emitted last so a clip at any level takes the trace
+                    // before it takes the identifying fields or the nested cause.
+                    const own = Object.getOwnPropertyNames(member)
+                        .filter((name) => name !== "stack");
+                    return Object.fromEntries([
+                        ...own.map((name) => [
+                            name,
+                            member[name]
+                        ]),
+                        ...(typeof member.stack === "string" ? [["stack", member.stack]] : [])
+                    ]);
                 }
             }
             return member;
         });
-        return serialized === undefined
-            ? String(value)
-            : requiredErrorText(serialized, "Agent error raw payload");
+        return serialized === undefined ? String(value) : serialized;
     }
     catch {
-        return requiredErrorText(String(value), "Agent error raw payload");
+        return String(value);
+    }
+}
+/**
+ * Payload keys that carry Provider input rather than a failure fact. `text`
+ * and `body` are the shapes an HTTP or SDK client uses when it attaches the
+ * failed request to its error.
+ */
+const PROVIDER_INPUT_KEYS = new Set([
+    "boundedText",
+    "text",
+    "prompt",
+    "input",
+    "body",
+    "content",
+    "messages"
+]);
+const SECRET_LABEL = "api[_-]?key|access[_-]?token|refresh[_-]?token|secret|password|passwd|cookie|authorization";
+const SECRET_ASSIGNMENT_START = new RegExp(`(${SECRET_LABEL})(\\\\*["']?\\s*[=:]\\s*)`, "gi");
+/**
+ * `Authorization: Basic <base64>` and friends. The generic assignment pattern
+ * consumed only the scheme word and left the credential itself readable.
+ */
+const AUTH_SCHEME_PATTERN = /((?:authorization|proxy-authorization)(?:\\?["']?\s*[=:]\s*\\?["']?)\s*)(basic|bearer|token|digest|negotiate)(\s+)[A-Za-z0-9._~+/=-]{4,}/gi;
+// Word boundary keeps "task-5-…" workspace paths from being mistaken for keys.
+const PROVIDER_KEY_PATTERN = /\b(?:(?:sk|pat)-|(?:ghp|gho|ghs|github_pat)_)[A-Za-z0-9_-]{6,}/gu;
+// Digest credentials are an entire parameter list, not a single scheme token.
+// Cover raw headers and escaped headers embedded in JSON error strings without
+// consuming the enclosing serialized error and its subsequent cause fields.
+const DIGEST_AUTH_PATTERN = /((?:proxy-)?authorization(?:\\?["']?\s*[=:]\s*\\?["']?)\s*digest\s+)(?:[\w-]+\s*=\s*(?:\\"(?:[^"\\]|\\(?!"))*\\"|"(?:\\.|[^"\\])*"|'[^']*'|[^,\s"}]+)\s*(?:,\s*)?)+/gi;
+const BEARER_PATTERN = /\b(bearer\s+)[A-Za-z0-9._~+/-]{8,}=*/gi;
+/**
+ * Redacts credential-shaped text from a failure payload. This mirrors the
+ * launch-diagnostic redaction but is applied to the Agent error chain, whose
+ * payloads are persisted and publicly readable through the Task event.
+ */
+export function redactAgentErrorText(value) {
+    return redactSecretAssignments(value
+        .replace(PROVIDER_KEY_PATTERN, "[REDACTED]")
+        .replace(DIGEST_AUTH_PATTERN, "$1 [REDACTED]")
+        .replace(AUTH_SCHEME_PATTERN, "$1$2$3[REDACTED]")
+        .replace(BEARER_PATTERN, "$1[REDACTED]"));
+}
+/**
+ * A quoted diagnostic may itself be inside a JSON string. Its delimiter is
+ * then `\"`, not `"`, and a generic backslash escape regex can eat the closing
+ * delimiter and the rest of the cause. Match the opening escape depth, retain
+ * both delimiters, and replace only their secret value. This is also stable
+ * when already redacted raw crosses another error boundary.
+ */
+function redactSecretAssignments(value) {
+    let cursor = 0;
+    let redacted = "";
+    for (const match of value.matchAll(SECRET_ASSIGNMENT_START)) {
+        if (match.index < cursor)
+            continue;
+        const start = match.index + match[0].length;
+        if (value.startsWith("[REDACTED]", start))
+            continue;
+        const opening = /^(\\*)(["'])/u.exec(value.slice(start));
+        let end = start;
+        let replacement = "[REDACTED]";
+        if (opening !== null) {
+            const delimiter = opening[0];
+            const quote = opening[2];
+            const escapeDepth = opening[1].length;
+            let backslashes = 0;
+            end += delimiter.length;
+            for (; end < value.length; end += 1) {
+                const char = value[end];
+                if (char === "\\") {
+                    backslashes += 1;
+                    continue;
+                }
+                if (char === quote && backslashes % (2 * (escapeDepth + 1)) === escapeDepth)
+                    break;
+                backslashes = 0;
+            }
+            replacement = `${delimiter}[REDACTED]${end < value.length ? delimiter : ""}`;
+            if (end < value.length)
+                end += 1;
+        }
+        else {
+            // No explicit quote means spaces may be part of the credential.
+            while (end < value.length && !/[,;"'\\\n\r}\]]/u.test(value[end]))
+                end += 1;
+        }
+        if (end === start)
+            continue;
+        redacted += value.slice(cursor, start) + replacement;
+        cursor = end;
     }
+    return redacted + value.slice(cursor);
+}
+/**
+ * Clips a persisted payload while keeping both ends.
+ *
+ * Per-field clipping already keeps the cause chain within bounds, so this only
+ * guards a pathologically wide payload. Keeping a tail slice means a reader
+ * still sees how the record ends rather than only its head.
+ */
+function boundRawPayload(value) {
+    const text = isErrorText(value) ? value : "Agent operation failed without a readable error payload.";
+    if (text.length <= MAX_RAW_CHARS)
+        return text;
+    const headChars = Math.floor(MAX_RAW_CHARS * 0.75);
+    const tailChars = MAX_RAW_CHARS - headChars;
+    return `${text.slice(0, headChars)}${TRUNCATION_MARKER} ${text.length - MAX_RAW_CHARS} chars of ${text.length}]${text.slice(text.length - tailChars)}`;
+}
+function boundFieldText(value) {
+    if (value.length <= MAX_FIELD_CHARS)
+        return value;
+    return `${value.slice(0, MAX_FIELD_CHARS)}${TRUNCATION_MARKER} ${value.length - MAX_FIELD_CHARS} chars of ${value.length}]`;
+}
+/**
+ * Clips a one-line projection. Unlike `raw` this may lose content, so the
+ * marker is the reader's signal to consult the complete payload.
+ */
+function boundDisplayText(value) {
+    if (value.length <= MAX_DISPLAY_CHARS)
+        return value;
+    return `${value.slice(0, MAX_DISPLAY_CHARS)}${TRUNCATION_MARKER} ${value.length - MAX_DISPLAY_CHARS} chars of ${value.length}]`;
+}
+export function isTruncatedText(value) {
+    return value.includes(TRUNCATION_MARKER);
 }
 function isErrorText(value) {
     return typeof value === "string" && value.trim().length > 0 && !value.includes("\0");