Skip to content
Agent Archaeology

Telltale

Schemas

Telltale uses two schemas: the SIEM event schema for emitted telemetry and the normalization schema for internal record types. Both preserve provenance and avoid unnecessary raw sensitive content.

SIEM event schema

The event schema defines the structure of telemetry written to the default JSONL sink (an OS-standard per-user path under the user path profile, or an explicit --log-path). Each event follows schemas/event.schema.json.

Artifact Paths

Required fields

schema_version, event_id, event_type, timestamp, severity, risk_score, client, session_id

Every event must include these fields.

Event types

activity, detection, triage, scanner_error, health, correlation, operational_alert, session_risk_summary

Enum of supported event_type values.

Severity levels

informational, low, medium, high, critical, warning

Enum of supported severity values.

Evidence structure

Detection events include an evidence array with redacted values and optional hashes:

  • field: the source field name that matched
  • redacted_value: the redacted excerpt (required)
  • hash: optional cryptographic fingerprint for correlation
  • rule_id: optional reference to the matching rule

Triage structure

Optional triage object for LLM-based review:

  • required: boolean indicating if triage was needed
  • verdict: one of pending, safe, benign, suspicious, malicious, not_required, config_missing
  • confidence: number between 0 and 1
  • reason: redacted explanation string
  • timeline_anchors: array of entry references with rule_ids, categories, and evidence_fields

Response contract

Detection events include a deterministic response object for SIEM workflows:

  • recommended_action: one of monitor, review, investigate, investigate_immediately
  • response_playbook: stable Telltale playbook identifier
  • investigation_summary: short redaction-safe summary
  • escalation: routine_review or security_review_required

Normalization schema

The internal normalization contract is NormalizedRecordV1. It sits between source-specific parsers and downstream detection, triage, and export code.

Artifact Paths

conversation.message

User, assistant, system, developer, or tool-result content

Required: meta, content. Optional: content_parts.

tool.call

Tool name plus normalized arguments and raw evidence hash

Required: meta, tool_name. Optional: arguments, arguments_string, call_id.

tool.result

Exit status, stdout/stderr summary, file metadata, or error

Required: meta. Optional: tool_name, result, result_string, call_id, is_error.

detection.event

Rule matches and score before optional triage

Internal detection record.

triage.event

LLM/guard decision with model metadata and redacted rationale

Optional triage output.

Shared metadata

Every NormalizedRecordV1 variant carries RecordMeta:

  • session_id: required source session identifier
  • client: required client id (codex, opencode, copilot, etc.)
  • agent: optional agent name when distinguished from client
  • model: optional model id
  • provider: optional provider id
  • timestamp: optional source timestamp string
  • provenance: required bundle with source path hash, optional source event id, and optional offset/fingerprint
  • extensions: source-specific or conversion-specific extra data

Design principles

Normalize enough to compare events across tools, but keep links or hashes that allow an authorized reviewer to return to the source artifact. Do not make raw full transcripts the default SIEM payload. Use redacted excerpts and controlled access to originals.