EmitPremier field guide

Emit events

Attach typed multi-actor evidence via CLI, SDK, or HTTP.

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 (`@premierstudio/trace`)

npm install @premierstudio/trace

import { emit, premier, isPremierActive } from "@premierstudio/trace";

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 }.

Stream directly to Premier Cloud

For production services, hosted agents, and long-running workers, create a project key under Dashboard → Team & billing → Cloud ingestion, then configure the process itself:

export PREMIER_COLLECTOR_URL="https://premier.dev/api/ingest/v1/events"
export PREMIER_COLLECTOR_TOKEN="prem_ing_…"
export PREMIER_TRACE_ID="conversation-or-run-id"
export PREMIER_RUN_NAME="Production support agent"
export PREMIER_ENVIRONMENT="production"

PREMIER_REPOSITORY, PREMIER_BRANCH, and PREMIER_STARTED_AT are optional; the SDK attaches them as run metadata the same way.

The SDK sends events straight to Cloudflare. D1 persists the run and its event evidence, and the authenticated dashboard receives run updates over a live WebSocket. Use a new PREMIER_TRACE_ID for each bounded run or conversation. Keep the project key in your secret manager—never in a trace payload or browser bundle.

GitHub and Bitbucket are optional destinations for summaries, checks, and deep links. They do not observe the agent; this instrumentation does.

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 '{
    "trace_id": "conversation-42",
    "run": { "name": "Production support agent", "environment": "production" },
    "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.

CLI (premier emit)