Agent event APIs and @keeptrusts/agent 0.1.0 limit

:::danger Do not use the 0.1.0 observability helpers

This unlisted page is retained to document their contract mismatch. Use the authenticated API examples below or kt events.

:::

The live control plane supports request-level event queries and agent statistics. @keeptrusts/agent 0.1.0's tracing primitives model the request headers correctly, but its event, stats, request-lookup, and spend helpers do not model the current API responses.

Use the authenticated API contract below until those helpers are corrected.

Correlation fields

Send these headers with a gateway model request:

Header	Purpose
x-keeptrusts-agent-id	Attributes the request to an existing agent.
x-request-id	Carries the caller's request ID on the gateway exchange. Use a UUID so it can also identify trail records.
traceparent	Carries W3C distributed-trace context.

withTracing creates all three values for the SDK transport implementation. The supported TypeScript workflow shows the same contract without importing the blocked 0.1.0 entrypoint.

The gateway trims a supplied ID, limits it to 128 characters, and echoes that normalized transport ID in its x-request-id response header. It then uses a canonical value in control-plane records. A UUID becomes 32 lowercase hexadecimal characters without hyphens. An already canonical 32-character lowercase hexadecimal value is unchanged. Any other non-empty normalized text becomes the first 16 bytes of its SHA-256 digest, encoded as 32 lowercase hexadecimal characters.

Query the matching event

GET /v1/events requires since. It supports agent_id, request_id, and limit, performs an exact request-ID text match, and returns an events array. For the UUID generated by withTracing, derive the event form before querying:

export KEEPTRUSTS_EVENT_REQUEST_ID="${KEEPTRUSTS_REQUEST_ID//-/}"

curl -sS \
  --get "$KEEPTRUSTS_API_URL/v1/events" \
  --header "Authorization: Bearer $KEEPTRUSTS_CONTROL_PLANE_TOKEN" \
  --data-urlencode "since=1h" \
  --data-urlencode "agent_id=$KEEPTRUSTS_AGENT_ID" \
  --data-urlencode "request_id=$KEEPTRUSTS_EVENT_REQUEST_ID" \
  --data-urlencode "limit=1"

The shell transformation above applies only to UUIDs. If an integration sends arbitrary request-ID text, query with the gateway's SHA-256-derived canonical value instead. Prefer generating a UUID or a 32-character lowercase hexadecimal ID so correlation stays predictable.

The response contract is:

interface EventPage {
  events: Array<{
    event_id: string;
    event_type: string;
    request_id: string;
    timestamp: string;
    verdict: string;
    reason_code: string;
    config_version: string;
    event_attribution: {
      owner_org_id: string;
      agent_id?: string;
    };
    event_cost_attribution?: {
      total_cost_usd?: number;
      currency?: string;
      source_spend_log_id?: string;
    };
  }>;
  next_cursor: string | null;
}

Cost fields are omitted when cost attribution is unavailable. Do not infer per-request cost from an organization wallet balance.

Read agent statistics

GET /v1/agents/{id}/stats accepts an optional since value. It does not accept until, and the response is flat:

curl -sS \
  --get "$KEEPTRUSTS_API_URL/v1/agents/$KEEPTRUSTS_AGENT_ID/stats" \
  --header "Authorization: Bearer $KEEPTRUSTS_CONTROL_PLANE_TOKEN" \
  --data-urlencode "since=24h"

Field	Type
total_events	integer
block_count	integer
allow_count	integer
escalate_count	integer
redact_count	integer
last_event_at	RFC3339 string or null
open_escalations	integer
resolved_escalations	integer
avg_quality_percent	number or null

These values describe the selected event window. This route does not return an agent_id, window, or nested totals object.

Why the 0.1.0 helpers fail

Helper	Contract mismatch
getAgentEvents	Allows a missing since, sends unsupported until and source_spend_log_id filters, sends a caller-supplied UUID without converting it to the event's canonical request ID, expects data, and types id/occurred_at instead of event_id/timestamp.
getAgentStats	Sends unsupported until and types a nested response the API does not return.
getSpendAttribution	Depends on getAgentEvents, so it fails before aggregating live events.
lookupRequestEvent	Treats trail lookup as a normalized list with digest_id; the API returns trail events in an events wrapper.

Do not cast those responses to the SDK types or silently substitute defaults; that would hide contract drift.

Operational checks

1. Retain the UUID request ID before sending the model call.
2. Remove the UUID hyphens to derive the control-plane event request ID.
3. Confirm the event request_id exactly matches that canonical value.
4. Confirm event_attribution.agent_id matches the agent header.
5. Read policy outcome from verdict and reason_code.
6. Read cost only from event_cost_attribution when present.

Next steps

• Supported TypeScript Agent Workflow
• Evidence & Audit
• Capabilities
• kt events