Event schema

Emit agent_activity.v1 events.

The event schema is the contract between SDK surfaces and the customer-owned portal ledger. Add fields carefully, preserve compatibility, and keep sensitive values scrubbed.

Canonical families

These event types are covered by the current builder proof or portal projections.

Event	Use
`session.started`	Open a governed agent session and attach team, repo, source, and developer context.
`tool.started`	Record that a capability or third-party tool call is about to run.
`tool.finished`	Record outcome, command preview, file preview, cost, and capability metadata after execution.
`model.completed`	Record model call metadata when the connector can see it without becoming a proxy.
`approval.requested`	Create reviewable evidence for a confirm-level decision.
`hook.blocked`	Show enforced PreToolUse policy decisions from hook packs.
`agent_run_audit.source_snapshot`	Provide TS/JS source evidence for Agent Run Audit projections.
`agent_run_audit.file_change`	Attach changed-file context to the governed session.
`session.finished`	Close the session with final status and outcome summary.

Session start

A connector should start by naming the source and attaching provenance that can be audited later.

json

{
  "schema_version": "agent_activity.v1",
  "event_id": "evt-custom-session-started",
  "event_type": "session.started",
  "event_family": "session",
  "team_id": "00000000-0000-4000-8000-000000000000",
  "source": {
    "kind": "custom_connector",
    "name": "internal-agent-connector",
    "version": "0.1.0"
  },
  "agent": {
    "id": "internal-agent",
    "name": "Internal Agent",
    "provider": "customer-internal"
  },
  "developer": {
    "id": "developer-123"
  },
  "session": {
    "id": "custom-session-1",
    "environment": "local",
    "status": "running"
  },
  "actor_chain": [
    {
      "type": "user",
      "id": "developer-123",
      "display_name": "Developer",
      "attested_by": "internal-agent-connector",
      "occurred_at": "2026-05-25T10:00:00.000Z"
    },
    {
      "type": "agent",
      "id": "internal-agent",
      "display_name": "Internal Agent",
      "session_id": "custom-session-1",
      "attested_by": "internal-agent-connector",
      "occurred_at": "2026-05-25T10:00:01.000Z"
    }
  ],
  "attributes": {
    "source_classification": "customer_internal",
    "connector_id": "internal-agent-connector",
    "connector_version": "0.1.0",
    "policy_pack_id": "regulated-baseline",
    "policy_pack_version": "2026-05-16",
    "autodevops_provenance": {
      "source_classification": "customer_internal",
      "connector_id": "internal-agent-connector",
      "connector_version": "0.1.0",
      "policy_pack_id": "regulated-baseline",
      "policy_pack_version": "2026-05-16"
    }
  }
}

Actor chain

Use actor_chain when an event has crossed developer, agent, tool, or workload boundaries and the portal needs ordered lineage.

actor_chain is optional and additive; older events can omit it.
Each emitter should preserve the inbound chain order and append only its own segment.
Supported segment types are user, agent, tool, and workload.
Treat the chain as signed lineage metadata, not as a standalone authentication or cryptographic identity proof.
Keep free-form segment metadata scrubbed; raw prompts, secrets, tokens, and credentials do not belong in actor-chain attributes.

Connector convention

Across process boundaries, emitters can pass the current chain through AUTODEVOPS_ACTOR_CHAIN as JSON or base64-encoded JSON, then append their own segment before signing the next event.

SDK-boundary secret redaction

AutoDevOps redacts secret values at the SDK boundary before telemetry leaves the developer workstation or enters customer cloud storage.

Content-bearing subtrees (tool, model, attributes, policy, body) undergo inline secret scanning before event emission.
Deterministic pattern catalog redacts AWS access keys, GitHub/GitLab tokens, Slack tokens, Google API keys, Stripe keys, JWTs, Bearer headers, connection strings, and PEM private keys into class markers (e.g. [redacted:aws_access_key_id]).
Conservative Shannon-entropy fallback (≥40 chars, ≥4.0 bits/char) catches unstructured random tokens while preserving lowercase 64-hex SHA-256 content hashes.
Structural fields and identifiers (STRUCTURAL_KEYS: event_id, session_id, tool_call_id, trace_id, name, model, commit, sha, branch) skip the entropy fallback so non-secret identifiers remain untouched, while deterministic patterns still run unconditionally.
Emitted events populate an append-only redaction sub-object recording secrets_redacted (count) and classes (de-duplicated array of redacted classes).

Data privacy guarantee

The SDK redacts secrets before building signed JSON payloads. Raw credentials, API tokens, and private keys never land in Supabase tables, audit logs, or portal views.

Compatibility rules

The portal stores raw events and builds projections from known fields.

Additive fields are allowed in agent_activity.v1.
Removing fields, renaming fields, or making optional fields required needs a new schema version.
Older connector payload fixtures must continue to ingest.
Portal projections should ignore unknown fields unless those fields are security-sensitive.
Raw emails, secrets, tokens, and credentials must remain scrubbed or rejected.

Backward compatibility test

The repository includes a legacy connector fixture to prove older agent_activity.v1 payloads still ingest and project even when they do not include the newer provenance fields.

Conformance helper

Validate before you ship. Call validateAgentActivityConformance from @autodevops/verifier-portal-client before live ingest, or run autodevops-agent-activity-conformance ./events.jsonl in your connector test suite. Add --profile core --format json when a release artifact must prove coverage of the full public core event suite, and --print-schema to materialize the public JSON Schema for downstream tests. A core JSONL fixture suite covers session, prompt, model, tool, hook, approval, Intent Fidelity, and Agent Run Audit events.