agent-first-data 0.2.4__tar.gz → 0.4.0__tar.gz

{agent_first_data-0.2.4/agent_first_data.egg-info → agent_first_data-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.2.4
-Summary: Agent-First Data (AFD) — suffix-driven output formatting and protocol templates for AI agents
+Version: 0.4.0
+Summary: Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates for AI agents
 License-Expression: MIT
 Project-URL: Repository, https://github.com/cmnspore/agent-first-data
 Requires-Python: >=3.9
@@ -9,7 +9,7 @@ Description-Content-Type: text/markdown
 
 # agent-first-data
 
-**Agent-First Data (AFD)** — Suffix-driven output formatting and protocol templates for AI agents.
+**Agent-First Data (AFDATA)** — Suffix-driven output formatting and protocol templates for AI agents.
 
 The field name is the schema. Agents read `latency_ms` and know milliseconds, `api_key_secret` and know to redact, no external schema needed.
 
@@ -27,24 +27,39 @@ A backup tool invoked from the CLI — flags, env vars, and config all use the s
 API_KEY_SECRET=sk-1234 cloudback --timeout-s 30 --max-file-size-bytes 10737418240 /data/backup.tar.gz
 ```
 
-The tool reads env vars, flags, and config — all with AFD suffixes — and emits a startup message:
+For CLI diagnostics, enable log categories explicitly:
+
+```bash
+--log startup,request,progress,retry,redirect
+--verbose   # shorthand for all categories
+```
+
+Without these flags, startup diagnostics should stay off by default.
+
+The tool reads env vars, flags, and config — all with AFDATA suffixes — and can emit a startup diagnostic event:
 
 ```python
 from agent_first_data import *
 import os
 
-startup = build_json_startup(
-    {"timeout_s": 30, "max_file_size_bytes": 10737418240},
-    {"input_path": "/data/backup.tar.gz"},
-    {"API_KEY_SECRET": os.environ.get("API_KEY_SECRET")},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"timeout_s": 30, "max_file_size_bytes": 10737418240},
+        "args": {"input_path": "/data/backup.tar.gz"},
+        "env": {"API_KEY_SECRET": os.environ.get("API_KEY_SECRET")},
+    },
+    trace=None,
 )
 ```
 
 Three output formats, same data:
 
 ```
-JSON:  {"code":"startup","args":{"input_path":"/data/backup.tar.gz"},"config":{"max_file_size_bytes":10737418240,"timeout_s":30},"env":{"API_KEY_SECRET":"***"}}
-YAML:  code: "startup"
+JSON:  {"code":"log","event":"startup","args":{"input_path":"/data/backup.tar.gz"},"config":{"max_file_size_bytes":10737418240,"timeout_s":30},"env":{"API_KEY_SECRET":"***"}}
+YAML:  code: "log"
+       event: "startup"
        args:
          input_path: "/data/backup.tar.gz"
        config:
@@ -52,23 +67,20 @@ YAML:  code: "startup"
          timeout: "30s"
        env:
          API_KEY: "***"
-Plain: args.input_path=/data/backup.tar.gz code=startup config.max_file_size=10.0GB config.timeout=30s env.API_KEY=***
+Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_file_size=10.0GB config.timeout=30s env.API_KEY=***
 ```
 
 `--timeout-s` → `timeout_s` → `timeout: 30s`. `API_KEY_SECRET` → `API_KEY: "***"`. The suffix is the schema.
 
 ## API Reference
 
-Total: **9 public APIs** + **AFD logging** (4 protocol builders + 3 output functions + 1 internal + 1 utility)
+Total: **12 public APIs and 1 type** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat`)
 
 ### Protocol Builders (returns dict)
 
-Build AFD protocol structures. Return dict objects for API responses.
+Build AFDATA protocol structures. Return dict objects for API responses.
 
 ```python
-# Startup (configuration)
-build_json_startup(config: Any, args: Any, env: Any) -> dict
-
 # Success (result)
 build_json_ok(result: Any, trace: Any = None) -> dict
 
@@ -86,10 +98,15 @@ build_json(code: str, fields: Any, trace: Any = None) -> dict
 from agent_first_data import *
 
 # Startup
-startup = build_json_startup(
-    {"api_key_secret": "sk-123", "timeout_s": 30},
-    {"config_path": "config.yml"},
-    {"RUST_LOG": "info"},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"api_key_secret": "sk-123", "timeout_s": 30},
+        "args": {"config_path": "config.yml"},
+        "env": {"RUST_LOG": "info"},
+    },
+    trace=None,
 )
 
 # Success (always include trace)
@@ -170,6 +187,41 @@ assert parse_size("1.5K") == 1536
 assert parse_size("512") == 512
 ```
 
+### CLI Helpers (for tools built on AFDATA)
+
+Shared helpers that prevent flag-parsing drift between CLI tools. Use these instead of reimplementing `--output` and `--log` handling in each tool.
+
+```python
+class OutputFormat(enum.Enum):  # JSON="json", YAML="yaml", PLAIN="plain"
+
+cli_parse_output(s: str) -> OutputFormat         # Parse --output flag; raises ValueError on unknown
+cli_parse_log_filters(entries: list[str]) -> list[str]  # Normalize --log: trim, lowercase, dedup, remove empty
+cli_output(value: Any, format: OutputFormat) -> str     # Dispatch to output_json/yaml/plain
+build_cli_error(message: str) -> dict            # {code:"error", error_code:"invalid_request", retryable:False, trace:{duration_ms:0}}
+```
+
+**Canonical pattern** — parse all flags before doing work, emit JSONL errors to stdout:
+
+```python
+import sys
+from agent_first_data import (
+    OutputFormat, cli_parse_output, cli_parse_log_filters,
+    cli_output, build_cli_error, output_json,
+)
+
+try:
+    fmt = cli_parse_output(args.output)
+except ValueError as e:
+    print(output_json(build_cli_error(str(e))))
+    sys.exit(2)
+
+log = cli_parse_log_filters(args.log.split(",") if args.log else [])
+# ... do work ...
+print(cli_output(result, fmt))
+```
+
+See `examples/agent_cli.py` for the complete working example (`pytest examples/agent_cli.py`).
+
 ## Usage Examples
 
 ### Example 1: REST API
@@ -196,14 +248,20 @@ async def get_user(user_id: int):
 from agent_first_data import *
 
 # 1. Startup
-startup = build_json_startup(
-    {"api_key_secret": "sk-sensitive-key", "timeout_s": 30},
-    {"input_path": "data.json"},
-    {"RUST_LOG": "info"},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"api_key_secret": "sk-sensitive-key", "timeout_s": 30},
+        "args": {"input_path": "data.json"},
+        "env": {"RUST_LOG": "info"},
+    },
+    trace=None,
 )
 print(output_yaml(startup))
 # ---
-# code: "startup"
+# code: "log"
+# event: "startup"
 # args:
 #   input_path: "data.json"
 # config:
@@ -253,6 +311,7 @@ result = build_json_ok(
 )
 
 # Print JSONL to stdout (secrets redacted, one JSON object per line)
+# Channel policy: machine-readable protocol/log events must not use stderr.
 print(output_json(result))
 # {"code":"ok","result":{"status":"success"},"trace":{"api_key_secret":"***","duration_ms":250}}
 ```
@@ -294,23 +353,23 @@ print(output_plain(data))
 # api_key=*** cache_ttl=3600s count=42 created_at=2025-02-07T00:00:00.000Z file_size=5.0MB payment=50000000msats price=$99.99 request_timeout=5.0s success_rate=95.5% user_name=alice
 ```
 
-## AFD Logging
+## AFDATA Logging
 
-AFD-compliant structured logging via Python's `logging` module. Every log line is formatted using the library's own `output_json`/`output_plain`/`output_yaml` functions. Span fields are carried via `contextvars` (async-safe), automatically flattened into each log line.
+AFDATA-compliant structured logging via Python's `logging` module. Every log line is formatted using the library's own `output_json`/`output_plain`/`output_yaml` functions. Span fields are carried via `contextvars` (async-safe), automatically flattened into each log line.
 
 ### API
 
 ```python
 from agent_first_data import init_logging_json, init_logging_plain, init_logging_yaml
-from agent_first_data.afd_logging import AfdHandler, get_logger, span
+from agent_first_data.afdata_logging import AfdataHandler, get_logger, span
 
-# Convenience initializers — set up the root logger with AFD output to stdout
+# Convenience initializers — set up the root logger with AFDATA output to stdout
 init_logging_json(level="INFO")    # Single-line JSONL (secrets redacted, original keys)
 init_logging_plain(level="INFO")   # Single-line logfmt (keys stripped, values formatted)
 init_logging_yaml(level="INFO")    # Multi-line YAML (keys stripped, values formatted)
 
 # Low-level — create a handler for custom logger stacks
-AfdHandler(format="json")  # format: "json" | "plain" | "yaml"
+AfdataHandler(format="json")  # format: "json" | "plain" | "yaml"
 
 # Logger with default fields (returns logging.LoggerAdapter)
 get_logger(name, **fields)
@@ -391,8 +450,8 @@ The `code` field defaults to the log level. Override with an explicit field:
 from agent_first_data import get_logger
 
 logger = get_logger("myapp")
-logger.info("Server ready", extra={"code": "startup"})
-# {"timestamp_epoch_ms":...,"message":"Server ready","target":"myapp","code":"startup"}
+logger.info("Server ready", extra={"code": "log", "event": "startup"})
+# {"timestamp_epoch_ms":...,"message":"Server ready","target":"myapp","code":"log","event":"startup"}
 ```
 
 ### Output Fields
@@ -410,7 +469,7 @@ Every log line contains:
 
 ### Log Output Formats
 
-All three formats use the library's own output functions, so AFD suffix processing applies to log fields too:
+All three formats use the library's own output functions, so AFDATA suffix processing applies to log fields too:
 
 | Format | Function | Keys | Values | Use case |
 |:-------|:---------|:-----|:-------|:---------|
@@ -444,8 +503,8 @@ All formats automatically redact `_secret` fields.
 
 This package is part of the [agent-first-data](https://github.com/cmnspore/agent-first-data) repository, which also contains:
 
-- **`spec/`** — Full AFD specification with suffix definitions, protocol format rules, and cross-language test fixtures
-- **`skills/`** — Claude Code skill for AI agents working with AFD conventions
+- **`spec/`** — Full AFDATA specification with suffix definitions, protocol format rules, and cross-language test fixtures
+- **`skills/`** — AI coding agent skill for working with AFDATA conventions
 
 To run tests, clone the full repository (tests use shared cross-language fixtures from `spec/fixtures/`):
 

agent_first_data-0.2.4/PKG-INFO → agent_first_data-0.4.0/README.md

@@ -1,15 +1,6 @@
-Metadata-Version: 2.4
-Name: agent-first-data
-Version: 0.2.4
-Summary: Agent-First Data (AFD) — suffix-driven output formatting and protocol templates for AI agents
-License-Expression: MIT
-Project-URL: Repository, https://github.com/cmnspore/agent-first-data
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-
 # agent-first-data
 
-**Agent-First Data (AFD)** — Suffix-driven output formatting and protocol templates for AI agents.
+**Agent-First Data (AFDATA)** — Suffix-driven output formatting and protocol templates for AI agents.
 
 The field name is the schema. Agents read `latency_ms` and know milliseconds, `api_key_secret` and know to redact, no external schema needed.
 
@@ -27,24 +18,39 @@ A backup tool invoked from the CLI — flags, env vars, and config all use the s
 API_KEY_SECRET=sk-1234 cloudback --timeout-s 30 --max-file-size-bytes 10737418240 /data/backup.tar.gz
 ```
 
-The tool reads env vars, flags, and config — all with AFD suffixes — and emits a startup message:
+For CLI diagnostics, enable log categories explicitly:
+
+```bash
+--log startup,request,progress,retry,redirect
+--verbose   # shorthand for all categories
+```
+
+Without these flags, startup diagnostics should stay off by default.
+
+The tool reads env vars, flags, and config — all with AFDATA suffixes — and can emit a startup diagnostic event:
 
 ```python
 from agent_first_data import *
 import os
 
-startup = build_json_startup(
-    {"timeout_s": 30, "max_file_size_bytes": 10737418240},
-    {"input_path": "/data/backup.tar.gz"},
-    {"API_KEY_SECRET": os.environ.get("API_KEY_SECRET")},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"timeout_s": 30, "max_file_size_bytes": 10737418240},
+        "args": {"input_path": "/data/backup.tar.gz"},
+        "env": {"API_KEY_SECRET": os.environ.get("API_KEY_SECRET")},
+    },
+    trace=None,
 )
 ```
 
 Three output formats, same data:
 
 ```
-JSON:  {"code":"startup","args":{"input_path":"/data/backup.tar.gz"},"config":{"max_file_size_bytes":10737418240,"timeout_s":30},"env":{"API_KEY_SECRET":"***"}}
-YAML:  code: "startup"
+JSON:  {"code":"log","event":"startup","args":{"input_path":"/data/backup.tar.gz"},"config":{"max_file_size_bytes":10737418240,"timeout_s":30},"env":{"API_KEY_SECRET":"***"}}
+YAML:  code: "log"
+       event: "startup"
        args:
          input_path: "/data/backup.tar.gz"
        config:
@@ -52,23 +58,20 @@ YAML:  code: "startup"
          timeout: "30s"
        env:
          API_KEY: "***"
-Plain: args.input_path=/data/backup.tar.gz code=startup config.max_file_size=10.0GB config.timeout=30s env.API_KEY=***
+Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_file_size=10.0GB config.timeout=30s env.API_KEY=***
 ```
 
 `--timeout-s` → `timeout_s` → `timeout: 30s`. `API_KEY_SECRET` → `API_KEY: "***"`. The suffix is the schema.
 
 ## API Reference
 
-Total: **9 public APIs** + **AFD logging** (4 protocol builders + 3 output functions + 1 internal + 1 utility)
+Total: **12 public APIs and 1 type** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat`)
 
 ### Protocol Builders (returns dict)
 
-Build AFD protocol structures. Return dict objects for API responses.
+Build AFDATA protocol structures. Return dict objects for API responses.
 
 ```python
-# Startup (configuration)
-build_json_startup(config: Any, args: Any, env: Any) -> dict
-
 # Success (result)
 build_json_ok(result: Any, trace: Any = None) -> dict
 
@@ -86,10 +89,15 @@ build_json(code: str, fields: Any, trace: Any = None) -> dict
 from agent_first_data import *
 
 # Startup
-startup = build_json_startup(
-    {"api_key_secret": "sk-123", "timeout_s": 30},
-    {"config_path": "config.yml"},
-    {"RUST_LOG": "info"},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"api_key_secret": "sk-123", "timeout_s": 30},
+        "args": {"config_path": "config.yml"},
+        "env": {"RUST_LOG": "info"},
+    },
+    trace=None,
 )
 
 # Success (always include trace)
@@ -170,6 +178,41 @@ assert parse_size("1.5K") == 1536
 assert parse_size("512") == 512
 ```
 
+### CLI Helpers (for tools built on AFDATA)
+
+Shared helpers that prevent flag-parsing drift between CLI tools. Use these instead of reimplementing `--output` and `--log` handling in each tool.
+
+```python
+class OutputFormat(enum.Enum):  # JSON="json", YAML="yaml", PLAIN="plain"
+
+cli_parse_output(s: str) -> OutputFormat         # Parse --output flag; raises ValueError on unknown
+cli_parse_log_filters(entries: list[str]) -> list[str]  # Normalize --log: trim, lowercase, dedup, remove empty
+cli_output(value: Any, format: OutputFormat) -> str     # Dispatch to output_json/yaml/plain
+build_cli_error(message: str) -> dict            # {code:"error", error_code:"invalid_request", retryable:False, trace:{duration_ms:0}}
+```
+
+**Canonical pattern** — parse all flags before doing work, emit JSONL errors to stdout:
+
+```python
+import sys
+from agent_first_data import (
+    OutputFormat, cli_parse_output, cli_parse_log_filters,
+    cli_output, build_cli_error, output_json,
+)
+
+try:
+    fmt = cli_parse_output(args.output)
+except ValueError as e:
+    print(output_json(build_cli_error(str(e))))
+    sys.exit(2)
+
+log = cli_parse_log_filters(args.log.split(",") if args.log else [])
+# ... do work ...
+print(cli_output(result, fmt))
+```
+
+See `examples/agent_cli.py` for the complete working example (`pytest examples/agent_cli.py`).
+
 ## Usage Examples
 
 ### Example 1: REST API
@@ -196,14 +239,20 @@ async def get_user(user_id: int):
 from agent_first_data import *
 
 # 1. Startup
-startup = build_json_startup(
-    {"api_key_secret": "sk-sensitive-key", "timeout_s": 30},
-    {"input_path": "data.json"},
-    {"RUST_LOG": "info"},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"api_key_secret": "sk-sensitive-key", "timeout_s": 30},
+        "args": {"input_path": "data.json"},
+        "env": {"RUST_LOG": "info"},
+    },
+    trace=None,
 )
 print(output_yaml(startup))
 # ---
-# code: "startup"
+# code: "log"
+# event: "startup"
 # args:
 #   input_path: "data.json"
 # config:
@@ -253,6 +302,7 @@ result = build_json_ok(
 )
 
 # Print JSONL to stdout (secrets redacted, one JSON object per line)
+# Channel policy: machine-readable protocol/log events must not use stderr.
 print(output_json(result))
 # {"code":"ok","result":{"status":"success"},"trace":{"api_key_secret":"***","duration_ms":250}}
 ```
@@ -294,23 +344,23 @@ print(output_plain(data))
 # api_key=*** cache_ttl=3600s count=42 created_at=2025-02-07T00:00:00.000Z file_size=5.0MB payment=50000000msats price=$99.99 request_timeout=5.0s success_rate=95.5% user_name=alice
 ```
 
-## AFD Logging
+## AFDATA Logging
 
-AFD-compliant structured logging via Python's `logging` module. Every log line is formatted using the library's own `output_json`/`output_plain`/`output_yaml` functions. Span fields are carried via `contextvars` (async-safe), automatically flattened into each log line.
+AFDATA-compliant structured logging via Python's `logging` module. Every log line is formatted using the library's own `output_json`/`output_plain`/`output_yaml` functions. Span fields are carried via `contextvars` (async-safe), automatically flattened into each log line.
 
 ### API
 
 ```python
 from agent_first_data import init_logging_json, init_logging_plain, init_logging_yaml
-from agent_first_data.afd_logging import AfdHandler, get_logger, span
+from agent_first_data.afdata_logging import AfdataHandler, get_logger, span
 
-# Convenience initializers — set up the root logger with AFD output to stdout
+# Convenience initializers — set up the root logger with AFDATA output to stdout
 init_logging_json(level="INFO")    # Single-line JSONL (secrets redacted, original keys)
 init_logging_plain(level="INFO")   # Single-line logfmt (keys stripped, values formatted)
 init_logging_yaml(level="INFO")    # Multi-line YAML (keys stripped, values formatted)
 
 # Low-level — create a handler for custom logger stacks
-AfdHandler(format="json")  # format: "json" | "plain" | "yaml"
+AfdataHandler(format="json")  # format: "json" | "plain" | "yaml"
 
 # Logger with default fields (returns logging.LoggerAdapter)
 get_logger(name, **fields)
@@ -391,8 +441,8 @@ The `code` field defaults to the log level. Override with an explicit field:
 from agent_first_data import get_logger
 
 logger = get_logger("myapp")
-logger.info("Server ready", extra={"code": "startup"})
-# {"timestamp_epoch_ms":...,"message":"Server ready","target":"myapp","code":"startup"}
+logger.info("Server ready", extra={"code": "log", "event": "startup"})
+# {"timestamp_epoch_ms":...,"message":"Server ready","target":"myapp","code":"log","event":"startup"}
 ```
 
 ### Output Fields
@@ -410,7 +460,7 @@ Every log line contains:
 
 ### Log Output Formats
 
-All three formats use the library's own output functions, so AFD suffix processing applies to log fields too:
+All three formats use the library's own output functions, so AFDATA suffix processing applies to log fields too:
 
 | Format | Function | Keys | Values | Use case |
 |:-------|:---------|:-----|:-------|:---------|
@@ -444,8 +494,8 @@ All formats automatically redact `_secret` fields.
 
 This package is part of the [agent-first-data](https://github.com/cmnspore/agent-first-data) repository, which also contains:
 
-- **`spec/`** — Full AFD specification with suffix definitions, protocol format rules, and cross-language test fixtures
-- **`skills/`** — Claude Code skill for AI agents working with AFD conventions
+- **`spec/`** — Full AFDATA specification with suffix definitions, protocol format rules, and cross-language test fixtures
+- **`skills/`** — AI coding agent skill for working with AFDATA conventions
 
 To run tests, clone the full repository (tests use shared cross-language fixtures from `spec/fixtures/`):
 

{agent_first_data-0.2.4 → agent_first_data-0.4.0}/agent_first_data/__init__.py

@@ -1,7 +1,6 @@
-"""Agent-First Data (AFD) — suffix-driven output formatting and protocol templates."""
+"""Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates."""
 
 from agent_first_data.format import (
-    build_json_startup,
     build_json_ok,
     build_json_error,
     build_json,
@@ -12,9 +11,9 @@ from agent_first_data.format import (
     parse_size,
 )
 
-from agent_first_data.afd_logging import (
-    AfdHandler,
-    AfdJsonHandler,
+from agent_first_data.afdata_logging import (
+    AfdataHandler,
+    AfdataJsonHandler,
     init_json as init_logging_json,
     init_plain as init_logging_plain,
     init_yaml as init_logging_yaml,
@@ -22,8 +21,15 @@ from agent_first_data.afd_logging import (
     span,
 )
 
+from agent_first_data.cli import (
+    OutputFormat,
+    cli_parse_output,
+    cli_parse_log_filters,
+    cli_output,
+    build_cli_error,
+)
+
 __all__ = [
-    "build_json_startup",
     "build_json_ok",
     "build_json_error",
     "build_json",
@@ -32,11 +38,16 @@ __all__ = [
     "output_plain",
     "internal_redact_secrets",
     "parse_size",
-    "AfdHandler",
-    "AfdJsonHandler",
+    "AfdataHandler",
+    "AfdataJsonHandler",
     "init_logging_json",
     "init_logging_plain",
     "init_logging_yaml",
     "get_logger",
     "span",
+    "OutputFormat",
+    "cli_parse_output",
+    "cli_parse_log_filters",
+    "cli_output",
+    "build_cli_error",
 ]

agent_first_data-0.2.4/agent_first_data/afd_logging.py → agent_first_data-0.4.0/agent_first_data/afdata_logging.py

@@ -1,4 +1,4 @@
-"""AFD-compliant structured logging.
+"""AFDATA-compliant structured logging.
 
 Outputs log events using agent-first-data formatting functions:
 - JSON: single-line JSONL via output_json (secrets redacted, original keys)
@@ -8,7 +8,7 @@ Outputs log events using agent-first-data formatting functions:
 Span fields are carried via contextvars (async-safe).
 
 Usage:
-    from agent_first_data.afd_logging import init_json, init_plain, init_yaml, span
+    from agent_first_data.afdata_logging import init_json, init_plain, init_yaml, span
     import logging
 
     init_json("INFO")   # or init_plain("INFO") or init_yaml("DEBUG")
@@ -25,7 +25,7 @@ from typing import Any
 
 from agent_first_data.format import output_json, output_plain, output_yaml
 
-_span_fields: ContextVar[dict[str, Any]] = ContextVar("afd_span", default={})
+_span_fields: ContextVar[dict[str, Any]] = ContextVar("afdata_span", default={})
 
 _LEVEL_TO_CODE = {
     "CRITICAL": "error",
@@ -38,8 +38,8 @@ _LEVEL_TO_CODE = {
 }
 
 
-class AfdHandler(logging.Handler):
-    """Logging handler that outputs AFD-compliant log lines to stdout.
+class AfdataHandler(logging.Handler):
+    """Logging handler that outputs AFDATA-compliant log lines to stdout.
 
     Formats output using the library's own output_json/output_plain/output_yaml.
     """
@@ -64,7 +64,7 @@ class AfdHandler(logging.Handler):
 
         # Event fields (passed via extra= in logging calls)
         has_code = False
-        extra = getattr(record, "_afd_fields", None)
+        extra = getattr(record, "_afdata_fields", None)
         if extra:
             for k, v in extra.items():
                 if k == "code":
@@ -88,11 +88,11 @@ class AfdHandler(logging.Handler):
 
 
 # Keep old name as alias for backwards compat
-AfdJsonHandler = AfdHandler
+AfdataJsonHandler = AfdataHandler
 
 
-class _AfdLoggerAdapter(logging.LoggerAdapter):
-    """Logger adapter that passes extra fields to AfdHandler."""
+class _AfdataLoggerAdapter(logging.LoggerAdapter):
+    """Logger adapter that passes extra fields to AfdataHandler."""
 
     def process(self, msg: str, kwargs: Any) -> tuple[str, Any]:
         extra = kwargs.get("extra", {})
@@ -100,29 +100,29 @@ class _AfdLoggerAdapter(logging.LoggerAdapter):
             merged = {**self.extra, **extra}
         else:
             merged = extra
-        kwargs["extra"] = {"_afd_fields": merged}
+        kwargs["extra"] = {"_afdata_fields": merged}
         return msg, kwargs
 
 
 def _init_with_format(format: str, level: str = "INFO") -> None:
-    handler = AfdHandler(format=format)
+    handler = AfdataHandler(format=format)
     root = logging.getLogger()
     root.handlers = [handler]
     root.setLevel(getattr(logging, level.upper(), logging.INFO))
 
 
 def init_json(level: str = "INFO") -> None:
-    """Initialize the root logger with AFD JSON output to stdout."""
+    """Initialize the root logger with AFDATA JSON output to stdout."""
     _init_with_format("json", level)
 
 
 def init_plain(level: str = "INFO") -> None:
-    """Initialize the root logger with AFD plain/logfmt output to stdout."""
+    """Initialize the root logger with AFDATA plain/logfmt output to stdout."""
     _init_with_format("plain", level)
 
 
 def init_yaml(level: str = "INFO") -> None:
-    """Initialize the root logger with AFD YAML output to stdout."""
+    """Initialize the root logger with AFDATA YAML output to stdout."""
     _init_with_format("yaml", level)
 
 
@@ -133,7 +133,7 @@ def get_logger(name: str, **fields: Any) -> logging.LoggerAdapter:
     Use for per-module or per-component fields.
     """
     base = logging.getLogger(name)
-    return _AfdLoggerAdapter(base, fields)
+    return _AfdataLoggerAdapter(base, fields)
 
 
 class span:

agent_first_data-0.4.0/agent_first_data/cli.py

@@ -0,0 +1,92 @@
+"""AFDATA CLI helpers — output format parsing, log filter normalization, error building."""
+
+from __future__ import annotations
+
+import enum
+from typing import Any
+
+from agent_first_data.format import output_json, output_yaml, output_plain
+
+
+class OutputFormat(enum.Enum):
+    """Output format for CLI and pipe/MCP modes."""
+
+    JSON = "json"
+    YAML = "yaml"
+    PLAIN = "plain"
+
+
+def cli_parse_output(s: str) -> OutputFormat:
+    """Parse the --output flag value into an OutputFormat.
+
+    Raises ValueError with a message suitable for build_cli_error on unknown values.
+
+    >>> cli_parse_output("json")
+    <OutputFormat.JSON: 'json'>
+    >>> cli_parse_output("xml")
+    Traceback (most recent call last):
+        ...
+    ValueError: invalid --output format 'xml': expected json, yaml, or plain
+    """
+    try:
+        return OutputFormat(s)
+    except ValueError:
+        raise ValueError(
+            f"invalid --output format {s!r}: expected json, yaml, or plain"
+        )
+
+
+def cli_parse_log_filters(entries: list[str]) -> list[str]:
+    """Normalize --log flag entries: trim, lowercase, deduplicate, remove empty.
+
+    Accepts pre-split entries (e.g. after splitting on comma).
+
+    >>> cli_parse_log_filters(["Query", " error ", "query"])
+    ['query', 'error']
+    """
+    out: list[str] = []
+    for entry in entries:
+        s = entry.strip().lower()
+        if s and s not in out:
+            out.append(s)
+    return out
+
+
+def cli_output(value: Any, format: OutputFormat) -> str:
+    """Dispatch output formatting by OutputFormat.
+
+    Equivalent to calling output_json, output_yaml, or output_plain directly.
+
+    >>> import json
+    >>> v = {"code": "ok"}
+    >>> cli_output(v, OutputFormat.JSON).startswith('{"code"')
+    True
+    """
+    if format is OutputFormat.YAML:
+        return output_yaml(value)
+    if format is OutputFormat.PLAIN:
+        return output_plain(value)
+    return output_json(value)
+
+
+def build_cli_error(message: str) -> dict:
+    """Build a standard CLI parse error value.
+
+    Use when argument parsing fails or a flag value is invalid.
+    Print with output_json and exit with code 2.
+
+    >>> v = build_cli_error("--output: invalid value 'xml'")
+    >>> v["code"]
+    'error'
+    >>> v["error_code"]
+    'invalid_request'
+    >>> v["retryable"]
+    False
+    """
+    return {
+        "code": "error",
+        "error_code": "invalid_request",
+        "error": message,
+        "retryable": False,
+        "trace": {"duration_ms": 0},
+    }

{agent_first_data-0.2.4 → agent_first_data-0.4.0}/agent_first_data/format.py

@@ -1,6 +1,6 @@
-"""AFD output formatting and protocol templates.
+"""AFDATA output formatting and protocol templates.
 
-9 public APIs: 4 protocol builders + 3 output formatters + 1 redaction + 1 utility.
+8 public APIs: 3 protocol builders + 3 output formatters + 1 redaction + 1 utility.
 """
 
 from __future__ import annotations
@@ -16,11 +16,6 @@ from typing import Any
 # ═══════════════════════════════════════════
 
 
-def build_json_startup(config: Any, args: Any, env: Any) -> dict:
-    """Build {code: "startup", config, args, env}."""
-    return {"code": "startup", "config": config, "args": args, "env": env}
-
-
 def build_json_ok(result: Any, trace: Any = None) -> dict:
     """Build {code: "ok", result, trace?}."""
     m: dict = {"code": "ok", "result": result}

agent_first_data-0.2.4/README.md → agent_first_data-0.4.0/agent_first_data.egg-info/PKG-INFO

@@ -1,6 +1,15 @@
+Metadata-Version: 2.4
+Name: agent-first-data
+Version: 0.4.0
+Summary: Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates for AI agents
+License-Expression: MIT
+Project-URL: Repository, https://github.com/cmnspore/agent-first-data
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
 # agent-first-data
 
-**Agent-First Data (AFD)** — Suffix-driven output formatting and protocol templates for AI agents.
+**Agent-First Data (AFDATA)** — Suffix-driven output formatting and protocol templates for AI agents.
 
 The field name is the schema. Agents read `latency_ms` and know milliseconds, `api_key_secret` and know to redact, no external schema needed.
 
@@ -18,24 +27,39 @@ A backup tool invoked from the CLI — flags, env vars, and config all use the s
 API_KEY_SECRET=sk-1234 cloudback --timeout-s 30 --max-file-size-bytes 10737418240 /data/backup.tar.gz
 ```
 
-The tool reads env vars, flags, and config — all with AFD suffixes — and emits a startup message:
+For CLI diagnostics, enable log categories explicitly:
+
+```bash
+--log startup,request,progress,retry,redirect
+--verbose   # shorthand for all categories
+```
+
+Without these flags, startup diagnostics should stay off by default.
+
+The tool reads env vars, flags, and config — all with AFDATA suffixes — and can emit a startup diagnostic event:
 
 ```python
 from agent_first_data import *
 import os
 
-startup = build_json_startup(
-    {"timeout_s": 30, "max_file_size_bytes": 10737418240},
-    {"input_path": "/data/backup.tar.gz"},
-    {"API_KEY_SECRET": os.environ.get("API_KEY_SECRET")},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"timeout_s": 30, "max_file_size_bytes": 10737418240},
+        "args": {"input_path": "/data/backup.tar.gz"},
+        "env": {"API_KEY_SECRET": os.environ.get("API_KEY_SECRET")},
+    },
+    trace=None,
 )
 ```
 
 Three output formats, same data:
 
 ```
-JSON:  {"code":"startup","args":{"input_path":"/data/backup.tar.gz"},"config":{"max_file_size_bytes":10737418240,"timeout_s":30},"env":{"API_KEY_SECRET":"***"}}
-YAML:  code: "startup"
+JSON:  {"code":"log","event":"startup","args":{"input_path":"/data/backup.tar.gz"},"config":{"max_file_size_bytes":10737418240,"timeout_s":30},"env":{"API_KEY_SECRET":"***"}}
+YAML:  code: "log"
+       event: "startup"
        args:
          input_path: "/data/backup.tar.gz"
        config:
@@ -43,23 +67,20 @@ YAML:  code: "startup"
          timeout: "30s"
        env:
          API_KEY: "***"
-Plain: args.input_path=/data/backup.tar.gz code=startup config.max_file_size=10.0GB config.timeout=30s env.API_KEY=***
+Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_file_size=10.0GB config.timeout=30s env.API_KEY=***
 ```
 
 `--timeout-s` → `timeout_s` → `timeout: 30s`. `API_KEY_SECRET` → `API_KEY: "***"`. The suffix is the schema.
 
 ## API Reference
 
-Total: **9 public APIs** + **AFD logging** (4 protocol builders + 3 output functions + 1 internal + 1 utility)
+Total: **12 public APIs and 1 type** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat`)
 
 ### Protocol Builders (returns dict)
 
-Build AFD protocol structures. Return dict objects for API responses.
+Build AFDATA protocol structures. Return dict objects for API responses.
 
 ```python
-# Startup (configuration)
-build_json_startup(config: Any, args: Any, env: Any) -> dict
-
 # Success (result)
 build_json_ok(result: Any, trace: Any = None) -> dict
 
@@ -77,10 +98,15 @@ build_json(code: str, fields: Any, trace: Any = None) -> dict
 from agent_first_data import *
 
 # Startup
-startup = build_json_startup(
-    {"api_key_secret": "sk-123", "timeout_s": 30},
-    {"config_path": "config.yml"},
-    {"RUST_LOG": "info"},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"api_key_secret": "sk-123", "timeout_s": 30},
+        "args": {"config_path": "config.yml"},
+        "env": {"RUST_LOG": "info"},
+    },
+    trace=None,
 )
 
 # Success (always include trace)
@@ -161,6 +187,41 @@ assert parse_size("1.5K") == 1536
 assert parse_size("512") == 512
 ```
 
+### CLI Helpers (for tools built on AFDATA)
+
+Shared helpers that prevent flag-parsing drift between CLI tools. Use these instead of reimplementing `--output` and `--log` handling in each tool.
+
+```python
+class OutputFormat(enum.Enum):  # JSON="json", YAML="yaml", PLAIN="plain"
+
+cli_parse_output(s: str) -> OutputFormat         # Parse --output flag; raises ValueError on unknown
+cli_parse_log_filters(entries: list[str]) -> list[str]  # Normalize --log: trim, lowercase, dedup, remove empty
+cli_output(value: Any, format: OutputFormat) -> str     # Dispatch to output_json/yaml/plain
+build_cli_error(message: str) -> dict            # {code:"error", error_code:"invalid_request", retryable:False, trace:{duration_ms:0}}
+```
+
+**Canonical pattern** — parse all flags before doing work, emit JSONL errors to stdout:
+
+```python
+import sys
+from agent_first_data import (
+    OutputFormat, cli_parse_output, cli_parse_log_filters,
+    cli_output, build_cli_error, output_json,
+)
+
+try:
+    fmt = cli_parse_output(args.output)
+except ValueError as e:
+    print(output_json(build_cli_error(str(e))))
+    sys.exit(2)
+
+log = cli_parse_log_filters(args.log.split(",") if args.log else [])
+# ... do work ...
+print(cli_output(result, fmt))
+```
+
+See `examples/agent_cli.py` for the complete working example (`pytest examples/agent_cli.py`).
+
 ## Usage Examples
 
 ### Example 1: REST API
@@ -187,14 +248,20 @@ async def get_user(user_id: int):
 from agent_first_data import *
 
 # 1. Startup
-startup = build_json_startup(
-    {"api_key_secret": "sk-sensitive-key", "timeout_s": 30},
-    {"input_path": "data.json"},
-    {"RUST_LOG": "info"},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"api_key_secret": "sk-sensitive-key", "timeout_s": 30},
+        "args": {"input_path": "data.json"},
+        "env": {"RUST_LOG": "info"},
+    },
+    trace=None,
 )
 print(output_yaml(startup))
 # ---
-# code: "startup"
+# code: "log"
+# event: "startup"
 # args:
 #   input_path: "data.json"
 # config:
@@ -244,6 +311,7 @@ result = build_json_ok(
 )
 
 # Print JSONL to stdout (secrets redacted, one JSON object per line)
+# Channel policy: machine-readable protocol/log events must not use stderr.
 print(output_json(result))
 # {"code":"ok","result":{"status":"success"},"trace":{"api_key_secret":"***","duration_ms":250}}
 ```
@@ -285,23 +353,23 @@ print(output_plain(data))
 # api_key=*** cache_ttl=3600s count=42 created_at=2025-02-07T00:00:00.000Z file_size=5.0MB payment=50000000msats price=$99.99 request_timeout=5.0s success_rate=95.5% user_name=alice
 ```
 
-## AFD Logging
+## AFDATA Logging
 
-AFD-compliant structured logging via Python's `logging` module. Every log line is formatted using the library's own `output_json`/`output_plain`/`output_yaml` functions. Span fields are carried via `contextvars` (async-safe), automatically flattened into each log line.
+AFDATA-compliant structured logging via Python's `logging` module. Every log line is formatted using the library's own `output_json`/`output_plain`/`output_yaml` functions. Span fields are carried via `contextvars` (async-safe), automatically flattened into each log line.
 
 ### API
 
 ```python
 from agent_first_data import init_logging_json, init_logging_plain, init_logging_yaml
-from agent_first_data.afd_logging import AfdHandler, get_logger, span
+from agent_first_data.afdata_logging import AfdataHandler, get_logger, span
 
-# Convenience initializers — set up the root logger with AFD output to stdout
+# Convenience initializers — set up the root logger with AFDATA output to stdout
 init_logging_json(level="INFO")    # Single-line JSONL (secrets redacted, original keys)
 init_logging_plain(level="INFO")   # Single-line logfmt (keys stripped, values formatted)
 init_logging_yaml(level="INFO")    # Multi-line YAML (keys stripped, values formatted)
 
 # Low-level — create a handler for custom logger stacks
-AfdHandler(format="json")  # format: "json" | "plain" | "yaml"
+AfdataHandler(format="json")  # format: "json" | "plain" | "yaml"
 
 # Logger with default fields (returns logging.LoggerAdapter)
 get_logger(name, **fields)
@@ -382,8 +450,8 @@ The `code` field defaults to the log level. Override with an explicit field:
 from agent_first_data import get_logger
 
 logger = get_logger("myapp")
-logger.info("Server ready", extra={"code": "startup"})
-# {"timestamp_epoch_ms":...,"message":"Server ready","target":"myapp","code":"startup"}
+logger.info("Server ready", extra={"code": "log", "event": "startup"})
+# {"timestamp_epoch_ms":...,"message":"Server ready","target":"myapp","code":"log","event":"startup"}
 ```
 
 ### Output Fields
@@ -401,7 +469,7 @@ Every log line contains:
 
 ### Log Output Formats
 
-All three formats use the library's own output functions, so AFD suffix processing applies to log fields too:
+All three formats use the library's own output functions, so AFDATA suffix processing applies to log fields too:
 
 | Format | Function | Keys | Values | Use case |
 |:-------|:---------|:-----|:-------|:---------|
@@ -435,8 +503,8 @@ All formats automatically redact `_secret` fields.
 
 This package is part of the [agent-first-data](https://github.com/cmnspore/agent-first-data) repository, which also contains:
 
-- **`spec/`** — Full AFD specification with suffix definitions, protocol format rules, and cross-language test fixtures
-- **`skills/`** — Claude Code skill for AI agents working with AFD conventions
+- **`spec/`** — Full AFDATA specification with suffix definitions, protocol format rules, and cross-language test fixtures
+- **`skills/`** — AI coding agent skill for working with AFDATA conventions
 
 To run tests, clone the full repository (tests use shared cross-language fixtures from `spec/fixtures/`):
 

{agent_first_data-0.2.4 → agent_first_data-0.4.0}/agent_first_data.egg-info/SOURCES.txt

@@ -1,11 +1,14 @@
 README.md
 pyproject.toml
 agent_first_data/__init__.py
-agent_first_data/afd_logging.py
+agent_first_data/afdata_logging.py
+agent_first_data/cli.py
 agent_first_data/format.py
 agent_first_data.egg-info/PKG-INFO
 agent_first_data.egg-info/SOURCES.txt
 agent_first_data.egg-info/dependency_links.txt
 agent_first_data.egg-info/top_level.txt
-tests/test_afd_logging.py
-tests/test_format.py
+tests/test_afdata_logging.py
+tests/test_cli.py
+tests/test_format.py
+tests/test_no_stderr_policy.py

{agent_first_data-0.2.4 → agent_first_data-0.4.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "agent-first-data"
-version = "0.2.4"
-description = "Agent-First Data (AFD) — suffix-driven output formatting and protocol templates for AI agents"
+version = "0.4.0"
+description = "Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates for AI agents"
 license = "MIT"
 readme = "README.md"
 requires-python = ">=3.9"

agent_first_data-0.2.4/tests/test_afd_logging.py → agent_first_data-0.4.0/tests/test_afdata_logging.py

@@ -1,4 +1,4 @@
-"""Tests for AFD logging module."""
+"""Tests for AFDATA logging module."""
 
 import json
 import logging
@@ -6,7 +6,7 @@ import sys
 from io import StringIO
 from unittest.mock import patch
 
-from agent_first_data.afd_logging import AfdHandler, AfdJsonHandler, init_json, init_plain, init_yaml, span, get_logger
+from agent_first_data.afdata_logging import AfdataHandler, AfdataJsonHandler, init_json, init_plain, init_yaml, span, get_logger
 
 
 def capture_log(fn):
@@ -20,9 +20,9 @@ def capture_log(fn):
 
 
 def make_logger(name="test"):
-    """Create a fresh logger with AfdJsonHandler."""
+    """Create a fresh logger with AfdataJsonHandler."""
     logger = logging.getLogger(name)
-    logger.handlers = [AfdJsonHandler()]
+    logger.handlers = [AfdataJsonHandler()]
     logger.setLevel(logging.DEBUG)
     return logger
 
@@ -108,15 +108,16 @@ class TestCodeOverride:
         logger = make_logger("test_code")
         adapter = get_logger("test_code")
 
-        m = capture_log(lambda: adapter.info("ready", extra={"code": "startup"}))
-        assert m["code"] == "startup"
+        m = capture_log(lambda: adapter.info("ready", extra={"code": "log", "event": "startup"}))
+        assert m["code"] == "log"
+        assert m["event"] == "startup"
 
 
 class TestGetLogger:
     def test_default_fields(self):
-        # Ensure root logger has AfdJsonHandler
+        # Ensure root logger has AfdataJsonHandler
         root = logging.getLogger()
-        root.handlers = [AfdJsonHandler()]
+        root.handlers = [AfdataJsonHandler()]
         root.setLevel(logging.DEBUG)
 
         adapter = get_logger("test_adapter", component="myservice")
@@ -137,7 +138,7 @@ def capture_raw(fn):
 class TestPlainFormat:
     def test_plain_output(self):
         logger = logging.getLogger("test_plain")
-        logger.handlers = [AfdHandler(format="plain")]
+        logger.handlers = [AfdataHandler(format="plain")]
         logger.setLevel(logging.DEBUG)
 
         output = capture_raw(lambda: logger.info("hello"))
@@ -157,7 +158,7 @@ class TestPlainFormat:
 class TestYamlFormat:
     def test_yaml_output(self):
         logger = logging.getLogger("test_yaml")
-        logger.handlers = [AfdHandler(format="yaml")]
+        logger.handlers = [AfdataHandler(format="yaml")]
         logger.setLevel(logging.DEBUG)
 
         output = capture_raw(lambda: logger.info("hello"))

agent_first_data-0.4.0/tests/test_cli.py

@@ -0,0 +1,98 @@
+"""Tests for agent_first_data CLI helpers."""
+import pytest
+from agent_first_data import (
+    OutputFormat,
+    cli_parse_output,
+    cli_parse_log_filters,
+    cli_output,
+    build_cli_error,
+    output_json,
+)
+
+
+# ── cli_parse_output ──────────────────────────────────────────────────────────
+
+def test_parse_output_all_formats():
+    assert cli_parse_output("json") is OutputFormat.JSON
+    assert cli_parse_output("yaml") is OutputFormat.YAML
+    assert cli_parse_output("plain") is OutputFormat.PLAIN
+
+
+def test_parse_output_rejects_unknown():
+    with pytest.raises(ValueError):
+        cli_parse_output("xml")
+    with pytest.raises(ValueError):
+        cli_parse_output("JSON")
+    with pytest.raises(ValueError):
+        cli_parse_output("")
+
+
+def test_parse_output_error_contains_value():
+    with pytest.raises(ValueError, match="toml"):
+        cli_parse_output("toml")
+    with pytest.raises(ValueError, match="json"):
+        cli_parse_output("toml")
+
+
+# ── cli_parse_log_filters ─────────────────────────────────────────────────────
+
+def test_parse_log_filters_trims_and_lowercases():
+    assert cli_parse_log_filters(["  Query  ", "ERROR"]) == ["query", "error"]
+
+
+def test_parse_log_filters_deduplicates():
+    assert cli_parse_log_filters(["query", "error", "Query", "query"]) == ["query", "error"]
+
+
+def test_parse_log_filters_removes_empty():
+    assert cli_parse_log_filters(["", "query", "  "]) == ["query"]
+
+
+def test_parse_log_filters_empty_list():
+    assert cli_parse_log_filters([]) == []
+
+
+def test_parse_log_filters_preserves_order():
+    assert cli_parse_log_filters(["startup", "request", "retry"]) == ["startup", "request", "retry"]
+
+
+# ── build_cli_error ───────────────────────────────────────────────────────────
+
+def test_build_cli_error_required_fields():
+    v = build_cli_error("missing --sql")
+    assert v["code"] == "error"
+    assert v["error_code"] == "invalid_request"
+    assert v["error"] == "missing --sql"
+    assert v["retryable"] is False
+    assert v["trace"]["duration_ms"] == 0
+
+
+def test_build_cli_error_is_valid_json():
+    import json
+    v = build_cli_error("oops")
+    s = output_json(v)
+    parsed = json.loads(s)
+    assert parsed["code"] == "error"
+
+
+# ── cli_output ────────────────────────────────────────────────────────────────
+
+def test_cli_output_dispatches_json():
+    v = {"code": "ok", "size_bytes": 1024}
+    out = cli_output(v, OutputFormat.JSON)
+    assert "size_bytes" in out   # json: raw keys, no suffix processing
+    assert "\n" not in out
+
+
+def test_cli_output_dispatches_yaml():
+    v = {"code": "ok", "size_bytes": 1024}
+    out = cli_output(v, OutputFormat.YAML)
+    assert out.startswith("---")
+    assert "size:" in out        # yaml: suffix stripped
+
+
+def test_cli_output_dispatches_plain():
+    v = {"code": "ok"}
+    out = cli_output(v, OutputFormat.PLAIN)
+    assert "\n" not in out
+    assert "code=ok" in out

{agent_first_data-0.2.4 → agent_first_data-0.4.0}/tests/test_format.py

@@ -1,10 +1,9 @@
-"""Tests for AFD output formatting — driven by shared spec/fixtures."""
+"""Tests for AFDATA output formatting — driven by shared spec/fixtures."""
 
 import json
 import os
 
 from agent_first_data import (
-    build_json_startup,
     build_json_ok,
     build_json_error,
     build_json,
@@ -52,8 +51,6 @@ def test_protocol_fixtures():
             result = build_json_error(args["message"])
         elif typ == "error_trace":
             result = build_json_error(args["message"], args["trace"])
-        elif typ == "startup":
-            result = build_json_startup(args["config"], args["args"], args["env"])
         elif typ == "status":
             result = build_json(args["code"], args.get("fields"))
         else:

agent_first_data-0.4.0/tests/test_no_stderr_policy.py

@@ -0,0 +1,23 @@
+"""Policy test: runtime library sources must not emit protocol/log events to stderr."""
+
+from pathlib import Path
+import re
+
+
+DISALLOWED = re.compile(
+    r"\bsys\.stderr\b|\bfile\s*=\s*sys\.stderr\b|\bstderr\.write\s*\(",
+)
+
+
+def test_no_stderr_usage_in_runtime_sources() -> None:
+    root = Path(__file__).resolve().parents[1] / "agent_first_data"
+    files = sorted(root.glob("*.py"))
+    assert files, "no python source files found"
+
+    violations: list[str] = []
+    for path in files:
+        for lineno, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+            if DISALLOWED.search(line):
+                violations.append(f"{path.name}:{lineno}: {line.strip()}")
+
+    assert not violations, "stderr usage is disallowed:\n" + "\n".join(violations)