# Runtime events

Runtime events describe what happened across package boundaries.
The Runtime Package owns Trace Events, Policy Decisions, Approval Requests, runtime capability handles, and wait-until behavior carried through [Runtime Context](https://vitehub.dev/docs/reference/runtime-context).

## Trace Event

`TraceEvent` is the shared observability event shape.
It can describe policy, approval, capability, error, lifecycle, or run activity.

```ts [@vite-hub/runtime]
interface TraceEvent {
  activity?: {
    owner: 'agent' | 'vitehub'
    phase: 'setup' | 'execution' | 'delivery' | 'teardown'
  }
  attributes?: Record<string, unknown>
  name: string
  payload?:
    | { value: unknown, visibility: 'public' }
    | { summary: string, visibility: 'summary' }
    | { visibility: 'redacted' | 'private' }
  timestamp?: Date | string
  trace?: {
    id: string
    parentId?: string
    sampled?: boolean
  }
  type: 'approval' | 'capability' | 'error' | 'lifecycle' | 'policy' | 'run'
}
```

`activity` separates work performed by an Agent from ViteHub runtime work and places it in a stable lifecycle phase. For example, Workspace materialization is `vitehub/setup`, an Agent tool call is `agent/execution`, and posting the result is `agent/delivery`. Trace logs also expose these values as `vitehub.activity.owner` and `vitehub.activity.phase` attributes for ordinary telemetry consumers.

Use the tagged `payload` field when an event needs structured detail. Payload visibility is an explicit producer decision:

| Visibility | Trace behavior |
| --- | --- |
| `public` | Retains `value` in metadata and content traces. Use only for data that is safe in every configured trace sink. |
| `summary` | Retains only the supplied `summary`; no raw value is accepted. |
| `redacted` | Records that a payload was intentionally redacted. |
| `private` | Records only the private visibility marker. This is also the fallback for malformed payload descriptors. |

The payload contract is independent of `attributes`. Existing attribute content remains metadata-only by default and still requires the existing content policy to opt a trusted sink into inputs or outputs.

Attribute projection reads own data properties without invoking getters. In metadata mode, this also applies to nested objects and array entries: content keys are recorded as omitted, and other accessors are skipped. Content mode keeps nested attribute values unchanged.

## Runtime lifecycle hooks

Runtime lifecycle hooks are host-provided callbacks for observing shared runtime behavior.
They do not replace package-owned hooks such as Agent Finish Hooks.

| Hook | Payload |
| --- | --- |
| `request` | Runtime Host Context before work starts. |
| `approval` | Approval Request and runtime context. |
| `trace` | Trace Event and runtime context. |
| `error` | Error and runtime context. |
| `finish` | Runtime Host Context after work finishes. |

## Policy and approvals

Policy Decisions are runtime outcomes, not generic booleans.
An Approval Request is created only when policy requires external approval.
An omitted policy resolves to `allow`.

| Value | Meaning |
| --- | --- |
| `allow` | Continue the operation. |
| `deny` | Stop the operation. |
| `require-approval` | Stop until an Approval Decision permits execution. |
| `retryable-failure` | Treat the operation as failed but retryable. |

## Agent stream events

Agent stream output is package-owned Agent behavior.
The current event stream includes text deltas, data parts, tool input and result events, progress events, approval events, errors, finish events, and usage events.

| Event family | Use |
| --- | --- |
| `text-delta` | Stream assistant text. |
| `tool-call` and `tool-result` | Represent model-facing tool execution. `tool-result.durationMs` can report elapsed tool time. |
| `progress` | Represent non-tool runtime progress such as `workspace.prepare`. |
| `approval-request` and `approval-decision` | Represent approval-shaped tool policy. |
| `data-agent-input` | Carries provider questions as `{ requestId, questions, status: "requested" }`; replies use `{ requestId, answers }`. |
| `error` | Represent recoverable or terminal stream errors. |
| `finish` | Mark completion. |
| `usage` | Carry an Agent Usage Record when an Agent Driver reports usage. |

## Agent Usage Record

Agent Usage Records normalize usage across model-backed, provider-backed, and custom-run-backed Agent Drivers when usage exists.
Token fields appear only when the provider reports them or ViteHub can derive them safely.
The record keeps canonical model identity, execution provider, and transport separate. It preserves provider-reported cost or carries a best-effort estimate when the Usage Capability can match catalog pricing.

Streams can carry the full Agent Usage Record through `{ type: "usage", usageRecord }`.
At finish time, read the normalized Agent Usage Record from `event.invocation.usage` in an Agent Finish Hook or `context.invocation.usage` in a Channel Delivery finish effect.
Applications format that data when a product surface needs text, UI, notes, billing records, or comments.

## Related

- [Agent Evals](https://vitehub.dev/docs/agents/evals)
- [CLI inspection](https://vitehub.dev/docs/development/cli)
- [Errors and diagnostics](https://vitehub.dev/docs/reference/errors-diagnostics)