PublicAiEvent

An event safe to expose across Koru's public AI boundary.

Provider tool calls are deliberately absent: their arguments and reasoning continuity data remain inside the worker. Clients observe only the minimal [ToolActivity] projection: stable target ids and a bounded public failure summary, never raw tool arguments or results.

Type object or object or object or object or object or object or object or object or object or object or object or object or object or object

Shape

One of 14 shapes:

type: "started"

Field	Type	Description
attempt_idrequired	InferenceAttemptId	InferenceAttemptId - a client-minted UUID v4, never derived from content or location.
provider_response_id	string or null
request_payload_bytes	integer (uint64, >= 0) or null	Default `null`
resolved_model	string or null
effective_reasoning	ReasoningChoice or null
atrequired	Timestamp	Epoch milliseconds, UTC. Signed, so instants before 1970 are representable.
typerequired	"started"

type: "text_delta"

Field	Type	Description
attempt_idrequired	InferenceAttemptId	InferenceAttemptId - a client-minted UUID v4, never derived from content or location.
textrequired	string
atrequired	Timestamp	Epoch milliseconds, UTC. Signed, so instants before 1970 are representable.
typerequired	"text_delta"

type: "reasoning_delta"

Field	Type	Description
attempt_idrequired	InferenceAttemptId	InferenceAttemptId - a client-minted UUID v4, never derived from content or location.
textrequired	string
atrequired	Timestamp	Epoch milliseconds, UTC. Signed, so instants before 1970 are representable.
typerequired	"reasoning_delta"

type: "usage"
Field Type Description
attempt_idrequired InferenceAttemptId
InferenceAttemptId - a client-minted UUID v4, never derived from content or location.
usagerequired AiUsage
typerequired "usage"

type: "context_usage"

Field	Type	Description
attempt_idrequired	InferenceAttemptId	InferenceAttemptId - a client-minted UUID v4, never derived from content or location.
usedrequired	integer (uint64, >= 0)
sizerequired	integer (uint64, >= 0)
typerequired	"context_usage"

type: "tool_activity"

Field	Type	Description
attempt_idrequired	InferenceAttemptId	InferenceAttemptId - a client-minted UUID v4, never derived from content or location.
activityrequired	ToolActivity	Durable and public tool activity. Raw arguments, results, queries, titles, paths, and workspace content deliberately have no field in this type. The stable target ids and bounded public error summary are the only context kept for an auditable, useful activity row.
typerequired	"tool_activity"

type: "agent_notice"

A local agent's status line beside its reply, as the chat keeps it (koru-ai D69): not part of the reply's text.

Field	Type	Description
attempt_idrequired	InferenceAttemptId	InferenceAttemptId - a client-minted UUID v4, never derived from content or location.
noticerequired	AgentNotice	A short status line a local agent said during a reply that is not part of the reply (koru-ai D69, AI schema 12): Devin's Hook failed: … about a hook on the person's machine. Kept with the reply it came with, in the order it came, and where in the reply it came.
typerequired	"agent_notice"

type: "agent_commands"

A local agent changed the current session's command listing.

Field	Type	Description
attempt_idrequired	InferenceAttemptId	InferenceAttemptId - a client-minted UUID v4, never derived from content or location.
chatrequired	ChatId	ChatId - a client-minted UUID v4, never derived from content or location.
commandsrequired	array of AgentCommandView
typerequired	"agent_commands"

type: "notice"

A one-line fact about the attempt the surface shows and nothing stores: a local agent could not be reattached and a replacement was started with the conversation so far.

Field	Type	Description
attempt_idrequired	InferenceAttemptId	InferenceAttemptId - a client-minted UUID v4, never derived from content or location.
noticerequired	AttemptNotice	A fact about the attempt the surface shows as one line and nothing stores.
atrequired	Timestamp	Epoch milliseconds, UTC. Signed, so instants before 1970 are representable.
typerequired	"notice"

type: "web_search"

Field	Type	Description
attempt_idrequired	InferenceAttemptId	InferenceAttemptId - a client-minted UUID v4, never derived from content or location.
call_idrequired	string
phaserequired	WebSearchPhase
atrequired	Timestamp	Epoch milliseconds, UTC. Signed, so instants before 1970 are representable.
typerequired	"web_search"

type: "citation"

Field	Type	Description
attempt_idrequired	InferenceAttemptId	InferenceAttemptId - a client-minted UUID v4, never derived from content or location.
sourcerequired	SourceLink
atrequired	Timestamp	Epoch milliseconds, UTC. Signed, so instants before 1970 are representable.
typerequired	"citation"

type: "completed"

Field	Type	Description
attempt_idrequired	InferenceAttemptId	InferenceAttemptId - a client-minted UUID v4, never derived from content or location.
stop_reason	string or null
atrequired	Timestamp	Epoch milliseconds, UTC. Signed, so instants before 1970 are representable.
typerequired	"completed"

type: "failed"

Field	Type	Description
attempt_idrequired	InferenceAttemptId	InferenceAttemptId - a client-minted UUID v4, never derived from content or location.
errorrequired	AiError
atrequired	Timestamp	Epoch milliseconds, UTC. Signed, so instants before 1970 are representable.
typerequired	"failed"

type: "cancelled"

Field	Type	Description
attempt_idrequired	InferenceAttemptId	InferenceAttemptId - a client-minted UUID v4, never derived from content or location.
atrequired	Timestamp	Epoch milliseconds, UTC. Signed, so instants before 1970 are representable.
typerequired	"cancelled"

Example

{
  "attempt_id": "00000000-0000-4000-8000-000000000000",
  "provider_response_id": "string",
  "request_payload_bytes": 0,
  "resolved_model": "string",
  "effective_reasoning": "default",
  "at": 0,
  "type": "started"
}

The contract has no example values, so example bodies are generated from each schema: every field is shown with a placeholder of its type.

Generated from contract version 1. Last updated November 12, 2026.