Typed events are how Premier becomes an agent reporter, not only a process log.

CLI (premier emit)

Must run under an active premier record (collector env present):

premier record -- sh -c '
  premier emit --kind agent.spawn --actor researcher --actor-type subagent --status running \
    --payload "{\"task\":\"find the first divergence\"}"
'

Raw JSON:

echo '{"kind":"tool.execution","actor_id":"coder","status":"ok","payload":{"tool":"rg"}}' \
  | premier emit --json -

Useful flags: --kind, --actor, --actor-type, --span, --parent-span, --status, --payload, --json, --source.

JavaScript / TypeScript (@premier/sdk)

npm install ./sdk/js
import { emit, premier, isPremierActive } from "@premier/sdk";

if (isPremierActive()) {
  await premier.spawn("researcher", { task: "find the first divergence" });
  await premier.model("researcher", {
    provider: "openai",
    model: "gpt-5",
    usage: { input_tokens: 1200, output_tokens: 400, total_tokens: 1600 },
    response: "…",
  });
  await emit({
    kind: "approval.request",
    actor_id: "coder",
    status: "pending",
    payload: { operation: "write", files: ["src/billing/ledger.ts"] },
  });
}

When Premier is not recording, emit returns null unless { required: true }.

Shell fallback

./sdk/shell/premier-emit.sh '{"kind":"agent.spawn","actor_id":"researcher","status":"running"}'

HTTP (curl)

curl -X POST "$PREMIER_COLLECTOR_URL" \
  -H "Authorization: Bearer $PREMIER_COLLECTOR_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "kind": "agent.spawn",
    "actor_id": "researcher",
    "actor_type": "subagent",
    "span_id": "research",
    "parent_span_id": "coordinator-turn-4",
    "status": "running",
    "payload": { "task": "find the first divergence" }
  }'

Event envelope fields

Field Role
kind e.g. agent.spawn, model.response, tool.execution, approval.request
actor_id / actor_type Who produced the evidence
parent_event_id, span_id, parent_span_id Causal structure
correlation_id, links Cross-links across actors
status, duration_ms Outcome timing
payload Structured evidence (prompts, usage, tool I/O, …)
timestamp Optional producer RFC3339 time

Model usage

Send the provider’s real usage object. Premier does not invent missing role-token splits. When input_tokens_by_role is absent, the viewer shows content/character evidence and marks role attribution as not captured.