agent-block 0.11.1

# Trace Context Architecture

This document defines the runtime-wide observability context contract for
`agent-block`.

## Goal

Standardize correlation metadata so every bridge (`llm`, `http`, `mcp`,
`mesh`, `tool`) can be joined by the same identifiers in log backends.

## Non-goals

- `agent-block` does not own workflow/task trees.
- `agent-block` does not model external orchestration lifecycles.
- `agent-block` does not carry arbitrary user payload in trace metadata.

## Canonical Keys

The canonical context is:

- `trace_id` (required by policy; generated when absent if allowed)
- `run_id` (recommended)
- `agent_id` (recommended)
- `agent_name` (optional label)

`task_id` is deprecated and accepted only as a compatibility fallback mapped to
`trace_id`.

## Resolution Order

For each key:

1. `agent.run({ log_meta = { ... } })`
2. Environment variable (`AGENT_BLOCK_TRACE_ID`, etc.)
3. Runtime fallback (for `agent_id`, `std.env.agent_id()`; for others, nil unless policy requires generation)

## Runtime Contract

Each runtime event MUST emit fixed-order key/value logs:

1. `prefix=ab.llm` (current family marker; planned generalization to `ab.obs`)
2. `event=<request|response|summary|...>`
3. Correlation fields in fixed order: `trace_id`, `agent_id`, `agent_name`, `run_id`
4. Component-specific fields

Values containing spaces or `=` must be escaped as JSON strings.

## Bridge Propagation Rules (Target State)

- `llm`:
  - emit context on request/response/summary logs
- `http`:
  - add outbound headers: `x-trace-id`, `x-run-id`, `x-agent-id`, `x-agent-name`
  - emit request/response logs with the same context
- `mcp`:
  - pass context via metadata envelope (or reserved argument field if metadata channel is unavailable)
  - emit call/result logs
- `mesh`:
  - include context under message metadata
  - preserve incoming context when relaying
- `tool`:
  - inject context into tool-dispatch log events
  - expose read-only context to handlers in a consistent Lua API

## Safety Constraints

- Never include secrets in trace context.
- Keep context values short and printable (`[A-Za-z0-9._:-]` preferred).
- If validation fails, log warning and either sanitize or drop the value.

## Migration Policy

- `task_id` fallback remains supported temporarily with warning:
  - `log_meta.task_id -> trace_id`
  - `AGENT_BLOCK_TASK_ID -> AGENT_BLOCK_TRACE_ID`
- Remove fallback in a future minor release after deprecation window.