Skip to content
Agent Archaeology

Telltale

Architecture

Telltale runs a repeatable batch pipeline: discover session stores, ingest new or changed files, parse client-specific formats, normalize into shared records, detect risky patterns, score findings, optionally triage with LLM, and emit JSONL events.

Pipeline stages

Each stage has a stable interface so new sources and rules can be added without disrupting existing detections.

  • Discover: enumerate known session stores for enabled clients.
  • Ingest: read new or changed files/databases using offsets, mtimes, or content fingerprints.
  • Parse: convert client-specific transcript formats into normalized conversation records.
  • Context Window: attach bounded preceding user/assistant messages to each tool call.
  • Detect: run static regex filters over tool names, command strings, arguments, paths, URLs, and adjacent messages.
  • Score: aggregate rule scores and modifiers into a risk result.
  • Triage: call Llama Guard and a small triage model only above configured thresholds.
  • Emit: send canonical events through an event sink. The default sink appends local JSONL for SIEM shippers.

Module boundaries

Artifact Paths

discovery

Knows where each agent stores sessions

Client-specific path resolution.

parsers

Client-specific transcript/database parsing

Format-specific extraction.

normalizer

Creates common records with stable field names

Schema V1 contract.

rules

Loads and evaluates regex rules

YAML-defined detections.

scoring

Combines matches, context, and thresholds

Risk aggregation.

triage

OpenAI-compatible client and prompts

LLM-based triage.

event

Redaction, schema-shaped event builders, evidence hashes, and local JSONL serialization

Event construction.

sink

Vendor-neutral event delivery boundary

Sink-specific envelopes.

state

Scan checkpoints and duplicate suppression

Idempotency.

Explicit per-source parser direction

Current Telltale support uses a static per-agent source-definition and install registry, with parser dispatch still keyed by SourceKind and selected source-specific helpers. The post-0.2.0 refactor keeps the external pipeline stable while moving semantic parsing to explicit `(ClientId, source_id)` registrations.

Adding an agent sourceSource adapter refactor plan

Normalized record types

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

  • conversation.message: user, assistant, system, developer, or tool-result content.
  • tool.call: tool name plus normalized arguments and raw evidence hash.
  • tool.result: exit status, stdout/stderr summary, file metadata, or error.
  • detection.event: rule matches and score before optional triage.
  • triage.event: LLM/guard decision with model metadata and redacted rationale.

Triage context package

The triage agent receives a bounded context package, not full raw transcripts:

  • Client, agent, model, provider, workspace, session id, and timestamps
  • Matched tool call details
  • Matched rule ids and explanations
  • Preceding bounded user/assistant messages
  • Redacted file paths, command lines, URLs, and tool results
  • Prior related detections from the same scan window

Design intent

The architecture favors deterministic, fixture-tested behavior first, with richer triage only after thresholds justify it.