agent-first-data 0.5.0 → 0.6.0

package/README.md

@@ -75,8 +75,8 @@ type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string
 // Success (result)
 buildJsonOk(result: JsonValue, trace?: JsonValue): JsonValue
 
-// Error (simple message)
-buildJsonError(message: string, trace?: JsonValue): JsonValue
+// Error (simple message, optional hint)
+buildJsonError(message: string, hint?: string, trace?: JsonValue): JsonValue
 
 // Generic (any code + fields)
 buildJson(code: string, fields: JsonValue, trace?: JsonValue): JsonValue
@@ -106,7 +106,10 @@ const response = buildJsonOk(
 );
 
 // Error
-const error = buildJsonError("user not found", { duration_ms: 5 });
+const error = buildJsonError("user not found", undefined, { duration_ms: 5 });
+
+// Error with hint
+const errorHint = buildJsonError("wallet not found", "list wallets with: afpay wallet list", { duration_ms: 5 });
 
 // Specific error code
 const notFound = buildJson(
@@ -197,7 +200,7 @@ type OutputFormat = "json" | "yaml" | "plain"
 cliParseOutput(s: string): OutputFormat             // Parse --output flag; throws on unknown
 cliParseLogFilters(entries: string[]): string[]     // Normalize --log: trim, lowercase, dedup, remove empty
 cliOutput(value: JsonValue, format: OutputFormat): string  // Dispatch to outputJson/Yaml/Plain
-buildCliError(message: string): JsonValue           // {code:"error", error_code:"invalid_request", retryable:false, trace:{duration_ms:0}}
+buildCliError(message: string, hint?: string): JsonValue  // {code:"error", error_code:"invalid_request", hint?, retryable:false, trace:{duration_ms:0}}
 ```
 
 **Canonical pattern** — parse all flags before doing work, emit JSONL errors to stdout:

package/dist/cli.d.ts

@@ -39,4 +39,4 @@ export declare function cliOutput(value: JsonValue, format: OutputFormat): strin
  * console.log(outputJson(err));
  * process.exit(2);
  */
-export declare function buildCliError(message: string): JsonValue;
+export declare function buildCliError(message: string, hint?: string): JsonValue;

package/dist/cli.js

@@ -57,12 +57,15 @@ export function cliOutput(value, format) {
  * console.log(outputJson(err));
  * process.exit(2);
  */
-export function buildCliError(message) {
-    return {
+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;
+    return m;
 }

package/dist/format.d.ts

@@ -8,8 +8,8 @@ export type JsonValue = string | number | boolean | null | JsonValue[] | {
 };
 /** Build {code: "ok", result, trace?}. */
 export declare function buildJsonOk(result: JsonValue, trace?: JsonValue): JsonValue;
-/** Build {code: "error", error: message, trace?}. */
-export declare function buildJsonError(message: string, trace?: JsonValue): JsonValue;
+/** Build {code: "error", error: message, hint?, trace?}. */
+export declare function buildJsonError(message: string, hint?: string, trace?: JsonValue): JsonValue;
 /** Build {code: "<custom>", ...fields, trace?}. */
 export declare function buildJson(code: string, fields: JsonValue, trace?: JsonValue): JsonValue;
 export declare enum RedactionPolicy {

package/dist/format.js

@@ -13,9 +13,11 @@ export function buildJsonOk(result, trace) {
         m.trace = trace;
     return m;
 }
-/** Build {code: "error", error: message, trace?}. */
-export function buildJsonError(message, trace) {
+/** Build {code: "error", error: message, hint?, trace?}. */
+export function buildJsonError(message, hint, trace) {
     const m = { code: "error", error: message };
+    if (hint !== undefined)
+        m.hint = hint;
     if (trace !== undefined)
         m.trace = trace;
     return m;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-first-data",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates for AI agents",
   "license": "MIT",
   "repository": {