agent-first-data 0.12.2 → 0.13.0

package/dist/cli.js

@@ -71,10 +71,7 @@ export function cliOutputWithOptions(value, format, outputOptions) {
 export function buildCliError(message, hint) {
     const m = {
         code: "error",
-        error_code: "invalid_request",
         error: message,
-        retryable: false,
-        trace: { duration_ms: 0 },
     };
     if (hint !== undefined)
         m.hint = hint;

package/dist/format.d.ts

@@ -1,10 +1,10 @@
 /**
  * AFDATA output formatting and protocol templates.
  *
- * 18 public APIs and 4 types: protocol builders, value redactors (copy and
+ * 19 public APIs and 4 types: protocol builders, value redactors (copy and
  * in-place; cover _secret and _url fields), output formatters, URL-string
- * redactors (redactUrlSecrets / WithOptions), parseSize, RedactionPolicy,
- * RedactionOptions, OutputStyle, and OutputOptions.
+ * redactors (redactUrlSecrets / WithOptions), parseSize, normalizeUtcOffset,
+ * RedactionPolicy, RedactionOptions, OutputStyle, and OutputOptions.
  */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
@@ -17,8 +17,7 @@ export declare function buildJsonError(message: string, hint?: string, trace?: J
 export declare function buildJson(code: string, fields: JsonValue, trace?: JsonValue): JsonValue;
 export declare enum RedactionPolicy {
     RedactionTraceOnly = "RedactionTraceOnly",
-    RedactionNone = "RedactionNone",
-    RedactionStrict = "RedactionStrict"
+    RedactionNone = "RedactionNone"
 }
 export type RedactionOptions = {
     /** Optional scoped policy. Omitted means default full redaction. */
@@ -56,9 +55,9 @@ export declare function outputPlain(value: JsonValue): string;
 /** Format as single-line logfmt with explicit output options. */
 export declare function outputPlainWithOptions(value: JsonValue, outputOptions: OutputOptions): string;
 /** Redact _secret fields in-place. */
-export declare function internalRedactSecrets(value: JsonValue): void;
+export declare function redactSecretsInPlace(value: JsonValue): void;
 /** Redact secret fields in-place using explicit redaction options. */
-export declare function internalRedactSecretsWithOptions(value: JsonValue, redactionOptions: RedactionOptions): void;
+export declare function redactSecretsInPlaceWithOptions(value: JsonValue, redactionOptions: RedactionOptions): void;
 /** Return a JSON-safe copy with default _secret redaction applied. */
 export declare function redactedValue(value: unknown): JsonValue;
 /** Return a JSON-safe copy with an explicit redaction policy applied. */
@@ -89,3 +88,9 @@ export declare function redactUrlSecretsWithOptions(url: string, redactionOption
  * Case-insensitive. Trims whitespace. Returns null for invalid input.
  */
 export declare function parseSize(s: string): number | null;
+/**
+ * Normalize a fixed UTC offset string to "UTC" or ±HH:MM.
+ * This helper handles fixed offsets only; IANA timezone names and DST rules
+ * are intentionally out of scope.
+ */
+export declare function normalizeUtcOffset(value: string): string | null;

package/dist/format.js

@@ -1,10 +1,10 @@
 /**
  * AFDATA output formatting and protocol templates.
  *
- * 18 public APIs and 4 types: protocol builders, value redactors (copy and
+ * 19 public APIs and 4 types: protocol builders, value redactors (copy and
  * in-place; cover _secret and _url fields), output formatters, URL-string
- * redactors (redactUrlSecrets / WithOptions), parseSize, RedactionPolicy,
- * RedactionOptions, OutputStyle, and OutputOptions.
+ * redactors (redactUrlSecrets / WithOptions), parseSize, normalizeUtcOffset,
+ * RedactionPolicy, RedactionOptions, OutputStyle, and OutputOptions.
  */
 // ═══════════════════════════════════════════
 // Public API: Protocol Builders
@@ -40,7 +40,6 @@ export var RedactionPolicy;
 (function (RedactionPolicy) {
     RedactionPolicy["RedactionTraceOnly"] = "RedactionTraceOnly";
     RedactionPolicy["RedactionNone"] = "RedactionNone";
-    RedactionPolicy["RedactionStrict"] = "RedactionStrict";
 })(RedactionPolicy || (RedactionPolicy = {}));
 export var OutputStyle;
 (function (OutputStyle) {
@@ -91,18 +90,18 @@ export function outputPlainWithOptions(value, outputOptions) {
     }
     pairs.sort(([a], [b]) => jcsCompare(a, b));
     return pairs
-        .map(([k, v]) => `${k}=${quoteLogfmtValue(v)}`)
+        .map(([k, v]) => `${quoteLogfmtKey(k)}=${quoteLogfmtValue(v)}`)
         .join(" ");
 }
 // ═══════════════════════════════════════════
 // Public API: Redaction & Utility
 // ═══════════════════════════════════════════
 /** Redact _secret fields in-place. */
-export function internalRedactSecrets(value) {
+export function redactSecretsInPlace(value) {
     redactSecrets(value);
 }
 /** Redact secret fields in-place using explicit redaction options. */
-export function internalRedactSecretsWithOptions(value, redactionOptions) {
+export function redactSecretsInPlaceWithOptions(value, redactionOptions) {
     applyRedactionOptions(value, redactionOptions);
 }
 /** Return a JSON-safe copy with default _secret redaction applied. */
@@ -172,7 +171,7 @@ export function parseSize(s) {
     else {
         return null;
     }
-    if (!numStr)
+    if (!numStr || !/^(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(numStr))
         return null;
     const n = Number(numStr);
     if (isNaN(n) || n < 0 || !isFinite(n))
@@ -182,6 +181,49 @@ export function parseSize(s) {
         return null;
     return result;
 }
+/**
+ * Normalize a fixed UTC offset string to "UTC" or ±HH:MM.
+ * This helper handles fixed offsets only; IANA timezone names and DST rules
+ * are intentionally out of scope.
+ */
+export function normalizeUtcOffset(value) {
+    const s = value.trim();
+    if (s.toLowerCase() === "utc" || s.toLowerCase() === "z")
+        return "UTC";
+    if (!s || (s[0] !== "+" && s[0] !== "-"))
+        return null;
+    const parsed = parseUtcOffsetBody(s.slice(1));
+    if (parsed === null)
+        return null;
+    const [hours, minutes] = parsed;
+    if (hours > 23 || minutes > 59)
+        return null;
+    if (hours === 0 && minutes === 0)
+        return "UTC";
+    return `${s[0]}${hours.toString().padStart(2, "0")}:${minutes.toString().padStart(2, "0")}`;
+}
+function parseUtcOffsetBody(body) {
+    if (!body)
+        return null;
+    if (body.includes(":")) {
+        const parts = body.split(":");
+        if (parts.length !== 2)
+            return null;
+        const [hours, minutes] = parts;
+        if (!hours || hours.length > 2 || minutes.length !== 2)
+            return null;
+        if (!/^[0-9]+$/.test(hours) || !/^[0-9]+$/.test(minutes))
+            return null;
+        return [Number(hours), Number(minutes)];
+    }
+    if (!/^[0-9]+$/.test(body))
+        return null;
+    if (body.length === 1 || body.length === 2)
+        return [Number(body), 0];
+    if (body.length === 4)
+        return [Number(body.slice(0, 2)), Number(body.slice(2))];
+    return null;
+}
 const DEFAULT_CONTEXT = {
     secretNames: new Set(),
 };
@@ -200,54 +242,35 @@ function keyHasUrlSuffix(key) {
 function isSecretKey(key, secretNames) {
     return keyHasSecretSuffix(key) || secretNames.has(key);
 }
-function redactSecrets(value, context = DEFAULT_CONTEXT) {
+const MAX_DEPTH = 256;
+function redactSecrets(value, context = DEFAULT_CONTEXT, depth = 0) {
+    if (depth >= MAX_DEPTH)
+        return;
     if (isObject(value)) {
         for (const k of Object.keys(value)) {
             const v = value[k];
             if (isSecretKey(k, context.secretNames)) {
-                if (isObject(v) || Array.isArray(v)) {
-                    redactSecrets(v, context);
+                value[k] = "***";
+            }
+            else if (keyHasUrlSuffix(k)) {
+                if (typeof v === "string") {
+                    value[k] = redactUrlFieldValue(v, context.secretNames);
                 }
                 else {
-                    value[k] = "***";
+                    value[k] = depth + 1 >= MAX_DEPTH ? "***" : (redactSecrets(v, context, depth + 1), v);
                 }
             }
-            else if (keyHasUrlSuffix(k) && typeof v === "string") {
-                const redacted = redactUrlInStr(v, context.secretNames);
-                if (redacted !== null)
-                    value[k] = redacted;
-            }
             else {
-                redactSecrets(v, context);
+                value[k] = depth + 1 >= MAX_DEPTH ? "***" : (redactSecrets(v, context, depth + 1), v);
             }
         }
     }
     else if (Array.isArray(value)) {
         for (let i = 0; i < value.length; i++) {
-            redactSecrets(value[i], context);
-        }
-    }
-}
-function redactSecretsStrict(value, context = DEFAULT_CONTEXT) {
-    if (isObject(value)) {
-        for (const k of Object.keys(value)) {
-            const v = value[k];
-            if (isSecretKey(k, context.secretNames)) {
-                value[k] = "***";
-            }
-            else if (keyHasUrlSuffix(k) && typeof v === "string") {
-                const redacted = redactUrlInStr(v, context.secretNames);
-                if (redacted !== null)
-                    value[k] = redacted;
-            }
-            else {
-                redactSecretsStrict(v, context);
-            }
-        }
-    }
-    else if (Array.isArray(value)) {
-        for (let i = 0; i < value.length; i++) {
-            redactSecretsStrict(value[i], context);
+            if (depth + 1 >= MAX_DEPTH)
+                value[i] = "***";
+            else
+                redactSecrets(value[i], context, depth + 1);
         }
     }
 }
@@ -266,9 +289,6 @@ function applyRedactionPolicyWithContext(value, redactionPolicy, context) {
             break;
         case RedactionPolicy.RedactionNone:
             break;
-        case RedactionPolicy.RedactionStrict:
-            redactSecretsStrict(value, context);
-            break;
         default:
             // Empty/unknown policy falls back to default full redaction.
             redactSecrets(value, context);
@@ -332,12 +352,31 @@ function redactUrlInStr(s, secretNames) {
     }
     return `${scheme}://${newAuthority}${newRemainder}`;
 }
+function redactUrlFieldValue(s, secretNames) {
+    const redacted = redactUrlInStr(s, secretNames);
+    if (redacted !== null)
+        return redacted;
+    const trimmed = s.trim();
+    if (trimmed !== s) {
+        const trimmedRedacted = redactUrlInStr(trimmed, secretNames);
+        if (trimmedRedacted !== null)
+            return trimmedRedacted;
+    }
+    // Fail closed: a _url value we could not parse as a clean scheme-prefixed
+    // URL, yet which carries a credential sigil ('@' userinfo) or internal
+    // whitespace, is redacted wholesale rather than passed through. A schemeless
+    // connection string like user:pass@host/db has no scheme anchor for the
+    // surgical span logic above, so blanket redaction is the safe default.
+    if (/\s/.test(s) || s.includes("@"))
+        return "***";
+    return s;
+}
 /**
  * Replace the userinfo password (user:pass@) with "***", preserving the
  * username. Authority without '@', or userinfo without ':', is unchanged.
  */
 function redactUserinfoPassword(authority) {
-    const at = authority.indexOf("@");
+    const at = authority.lastIndexOf("@");
     if (at < 0)
         return authority;
     const userinfo = authority.slice(0, at);
@@ -444,20 +483,29 @@ function tryProcessField(key, value) {
     // Group 1: compound timestamp suffixes
     stripped = stripSuffixCI(key, "_epoch_ms");
     if (stripped !== null) {
-        if (isInt(value))
-            return [stripped, formatRfc3339Ms(value)];
+        if (isInt(value)) {
+            const formatted = formatRfc3339Ms(value);
+            if (formatted !== null)
+                return [stripped, formatted];
+        }
         return null;
     }
     stripped = stripSuffixCI(key, "_epoch_s");
     if (stripped !== null) {
-        if (isInt(value))
-            return [stripped, formatRfc3339Ms(value * 1000)];
+        if (isInt(value)) {
+            const formatted = formatRfc3339Ms(value * 1000);
+            if (formatted !== null)
+                return [stripped, formatted];
+        }
         return null;
     }
     stripped = stripSuffixCI(key, "_epoch_ns");
     if (stripped !== null) {
-        if (isInt(value))
-            return [stripped, formatRfc3339Ms(Math.floor(value / 1_000_000))];
+        if (isInt(value)) {
+            const formatted = formatRfc3339Ms(Math.floor(value / 1_000_000));
+            if (formatted !== null)
+                return [stripped, formatted];
+        }
         return null;
     }
     // Group 2: compound currency suffixes
@@ -530,9 +578,6 @@ function tryProcessField(key, value) {
             return [stripped, `${plainScalar(value)}%`];
         return null;
     }
-    stripped = stripSuffixCI(key, "_secret");
-    if (stripped !== null)
-        return [stripped, "***"];
     // Group 5: short suffixes (last to avoid false positives)
     stripped = stripSuffixCI(key, "_btc");
     if (stripped !== null) {
@@ -576,6 +621,11 @@ function tryProcessField(key, value) {
 function processObjectFields(obj) {
     const entries = [];
     for (const [k, v] of Object.entries(obj)) {
+        const secretStripped = stripSuffixCI(k, "_secret");
+        if (secretStripped !== null) {
+            entries.push({ stripped: secretStripped, original: k, value: v, formatted: null });
+            continue;
+        }
         const result = tryProcessField(k, v);
         if (result !== null) {
             entries.push({ stripped: result[0], original: k, value: v, formatted: result[1] });
@@ -617,14 +667,15 @@ function formatMsValue(value) {
         return formatMsAsSeconds(value);
     return `${plainScalar(value)}ms`;
 }
+const MIN_RFC3339_MS = -62135596800000;
+const MAX_RFC3339_MS = 253402300799999;
 function formatRfc3339Ms(ms) {
-    try {
-        const d = new Date(ms);
-        return d.toISOString().replace(/(\.\d{3})\d*Z$/, "$1Z");
-    }
-    catch {
-        return String(ms);
-    }
+    if (ms < MIN_RFC3339_MS || ms > MAX_RFC3339_MS)
+        return null;
+    const d = new Date(ms);
+    if (Number.isNaN(d.getTime()))
+        return null;
+    return d.toISOString().replace(/(\.\d{3})\d*Z$/, "$1Z");
 }
 /**
  * Round to `digits` decimals using round-half-to-even (banker's rounding) and
@@ -687,7 +738,7 @@ function extractCurrencyCode(key) {
     if (idx < 0)
         return null;
     const code = withoutCents.slice(idx + 1);
-    if (!code)
+    if (!/^[A-Za-z]{3,4}$/.test(code))
         return null;
     return code;
 }
@@ -702,23 +753,23 @@ function renderYamlProcessed(value, indent, lines) {
     }
     for (const pf of processObjectFields(value)) {
         if (pf.formatted !== null) {
-            lines.push(`${prefix}${pf.key}: "${escapeYamlStr(pf.formatted)}"`);
+            lines.push(`${prefix}${yamlKey(pf.key)}: "${escapeYamlStr(pf.formatted)}"`);
         }
         else if (isObject(pf.value)) {
             if (Object.keys(pf.value).length > 0) {
-                lines.push(`${prefix}${pf.key}:`);
+                lines.push(`${prefix}${yamlKey(pf.key)}:`);
                 renderYamlProcessed(pf.value, indent + 1, lines);
             }
             else {
-                lines.push(`${prefix}${pf.key}: {}`);
+                lines.push(`${prefix}${yamlKey(pf.key)}: {}`);
             }
         }
         else if (Array.isArray(pf.value)) {
             if (pf.value.length === 0) {
-                lines.push(`${prefix}${pf.key}: []`);
+                lines.push(`${prefix}${yamlKey(pf.key)}: []`);
             }
             else {
-                lines.push(`${prefix}${pf.key}:`);
+                lines.push(`${prefix}${yamlKey(pf.key)}:`);
                 for (const item of pf.value) {
                     if (isObject(item)) {
                         lines.push(`${prefix}  -`);
@@ -731,7 +782,7 @@ function renderYamlProcessed(value, indent, lines) {
             }
         }
         else {
-            lines.push(`${prefix}${pf.key}: ${yamlScalar(pf.value)}`);
+            lines.push(`${prefix}${yamlKey(pf.key)}: ${yamlScalar(pf.value)}`);
         }
     }
 }
@@ -752,24 +803,24 @@ function renderYamlRaw(value, indent, lines) {
 function renderYamlFieldRaw(prefix, key, value, indent, lines) {
     if (isObject(value)) {
         if (Object.keys(value).length > 0) {
-            lines.push(`${prefix}${key}:`);
+            lines.push(`${prefix}${yamlKey(key)}:`);
             renderYamlRaw(value, indent + 1, lines);
         }
         else {
-            lines.push(`${prefix}${key}: {}`);
+            lines.push(`${prefix}${yamlKey(key)}: {}`);
         }
     }
     else if (Array.isArray(value)) {
         if (value.length > 0) {
-            lines.push(`${prefix}${key}:`);
+            lines.push(`${prefix}${yamlKey(key)}:`);
             renderYamlArrayRaw(value, indent + 1, lines);
         }
         else {
-            lines.push(`${prefix}${key}: []`);
+            lines.push(`${prefix}${yamlKey(key)}: []`);
         }
     }
     else {
-        lines.push(`${prefix}${key}: ${yamlScalar(value)}`);
+        lines.push(`${prefix}${yamlKey(key)}: ${yamlScalar(value)}`);
     }
 }
 function renderYamlArrayRaw(arr, indent, lines) {
@@ -799,7 +850,17 @@ function renderYamlArrayRaw(arr, indent, lines) {
     }
 }
 function escapeYamlStr(s) {
-    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+    return s
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r")
+        .replace(/\t/g, "\\t")
+        .replace(/\f/g, "\\f")
+        .replace(/\v/g, "\\v");
+}
+function yamlKey(key) {
+    return /^[A-Za-z0-9_.-]+$/.test(key) ? key : `"${escapeYamlStr(key)}"`;
 }
 function yamlScalar(value) {
     if (typeof value === "string")
@@ -810,7 +871,7 @@ function yamlScalar(value) {
         return value.toString();
     if (typeof value === "number")
         return value.toString();
-    return `"${String(value).replace(/"/g, '\\"')}"`;
+    return `"${escapeYamlStr(JSON.stringify(sortJsonValue(value)))}"`;
 }
 // ═══════════════════════════════════════════
 // Plain Rendering (logfmt)
@@ -866,7 +927,7 @@ function plainScalar(value) {
         return value.toString();
     if (typeof value === "number")
         return value.toString();
-    return String(value);
+    return JSON.stringify(sortJsonValue(value));
 }
 function plainScalarRaw(value) {
     if (isObject(value) || Array.isArray(value)) {
@@ -884,13 +945,20 @@ function quoteLogfmtValue(value) {
         .replace(/"/g, '\\"')
         .replace(/\n/g, "\\n")
         .replace(/\r/g, "\\r")
-        .replace(/\t/g, "\\t");
+        .replace(/\t/g, "\\t")
+        .replace(/\f/g, "\\f")
+        .replace(/\v/g, "\\v");
     return `"${escaped}"`;
 }
+function quoteLogfmtKey(key) {
+    return /^[A-Za-z0-9_.-]+$/.test(key) ? key : quoteLogfmtValue(key);
+}
 // ═══════════════════════════════════════════
 // Utilities
 // ═══════════════════════════════════════════
-function sanitizeForJson(value, stack = new WeakSet()) {
+function sanitizeForJson(value, stack = new WeakSet(), depth = 0) {
+    if (depth >= MAX_DEPTH)
+        return "***";
     if (value === null)
         return null;
     const t = typeof value;
@@ -918,7 +986,7 @@ function sanitizeForJson(value, stack = new WeakSet()) {
         if (stack.has(value))
             return "<unsupported:circular>";
         stack.add(value);
-        const out = value.map((item) => sanitizeForJson(item, stack));
+        const out = value.map((item) => sanitizeForJson(item, stack, depth + 1));
         stack.delete(value);
         return out;
     }
@@ -929,7 +997,7 @@ function sanitizeForJson(value, stack = new WeakSet()) {
         stack.add(obj);
         const out = {};
         for (const [k, v] of Object.entries(obj)) {
-            out[k] = sanitizeForJson(v, stack);
+            out[k] = sanitizeForJson(v, stack, depth + 1);
         }
         stack.delete(obj);
         return out;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates.
  */
-export { buildJsonOk, buildJsonError, buildJson, type JsonValue, RedactionPolicy, type RedactionOptions, OutputStyle, type OutputOptions, outputJson, outputJsonWith, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, internalRedactSecrets, internalRedactSecretsWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, redactUrlSecrets, redactUrlSecretsWithOptions, parseSize, } from "./format.js";
+export { buildJsonOk, buildJsonError, buildJson, type JsonValue, RedactionPolicy, type RedactionOptions, OutputStyle, type OutputOptions, outputJson, outputJsonWith, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, redactSecretsInPlace, redactSecretsInPlaceWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, redactUrlSecrets, redactUrlSecretsWithOptions, parseSize, normalizeUtcOffset, } from "./format.js";
 export { log, span, initJson, initPlain, initYaml } from "./afdata_logging.js";
 export { type OutputFormat, cliParseOutput, cliParseLogFilters, cliOutput, cliOutputWithOptions, buildCliError, } from "./cli.js";
 export { type SkillSpec, type SkillAction, type SkillScope, type SkillAgentSelection, type SkillAgent, type SkillOptions, type SkillTargetStatus, type SkillUninstallStatus, type SkillReport, SkillError, runSkillAdmin, } from "./skill.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 /**
  * Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates.
  */
-export { buildJsonOk, buildJsonError, buildJson, RedactionPolicy, OutputStyle, outputJson, outputJsonWith, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, internalRedactSecrets, internalRedactSecretsWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, redactUrlSecrets, redactUrlSecretsWithOptions, parseSize, } from "./format.js";
+export { buildJsonOk, buildJsonError, buildJson, RedactionPolicy, OutputStyle, outputJson, outputJsonWith, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, redactSecretsInPlace, redactSecretsInPlaceWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, redactUrlSecrets, redactUrlSecretsWithOptions, parseSize, normalizeUtcOffset, } from "./format.js";
 export { log, span, initJson, initPlain, initYaml } from "./afdata_logging.js";
 export { cliParseOutput, cliParseLogFilters, cliOutput, cliOutputWithOptions, buildCliError, } from "./cli.js";
 export { SkillError, runSkillAdmin, } from "./skill.js";