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.

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

Custom connectors can call validateAgentActivityConformancefrom @autodevops/verifier-portal-client before live ingest. Connector test suites can also run the package JSONL validator or autodevops-agent-activity-conformance ./events.jsonl after package install. Use the default profile for per-event validation, or --profile core --format json when a release or adoption artifact must prove coverage of the full public core event suite. Use autodevops-agent-activity-conformance --print-schema to materialize the public JSON Schema for downstream connector tests. The repository includes a core JSONL fixture suite for session, prompt, model, tool, hook, approval, Intent Fidelity, and Agent Run Audit events. These checks validate the public event contract without exposing proprietary scoring weights, anomaly fingerprints, or policy logic.