Developers Lifecycle events

Lifecycle events

An agent provider maps its private journal format to this small, provider-neutral event model. Publish events from an AgentJsonlSession.mapRecord() callback after binding the session.

Publish events

TypeScript

mapRecord(record, session) {
  const event = record as { type?: string; tool?: string };
  if (event.type === 'turn_started') {
    return session.publish.turnStarted({ turnId: crypto.randomUUID() });
  }
  if (event.type === 'tool_started' && event.tool) {
    return session.publish.toolStarted({
      toolId: crypto.randomUUID(),
      name: event.tool,
    });
  }
  if (event.type === 'complete') {
    return session.publish.done({ outcome: 'success' });
  }
}

session.publish is an AgentLifecyclePublisher. Every helper returns void | Promise<void>. All event timestamps are optional ISO strings in occurredAt; if omitted, the host supplies ordering.

Event and helper	Required fields	Optional fields
`session.started` · `sessionStarted()`	—	title, promptText, model
`agent.metadata` · `metadataChanged()`	—	agentId, title, promptText, model
`turn.started` · `turnStarted()`	turnId	agentId, promptText
`tool.started` · `toolStarted()`	toolId, name	agentId, description
`tool.finished` · `toolFinished()`	toolId	agentId, outcome
`wait.started` · `waitStarted()`	waitId, state	agentId, reason
`wait.finished` · `waitFinished()`	waitId	agentId
`agent.done` · `done()`	outcome	agentId, summary
`agent.exited` · `exited()`	—	agentId, exitCode, signal
`session.stopped` · `publish()`	—	reason
`subagent.started` · `subagentStarted()`	subagentId	parentAgentId, title, promptText, model
`subagent.done` · `subagentDone()`	subagentId, outcome	summary

Shared event values

Value	Shape
`outcome`	`'success' \| 'error' \| 'cancelled'`
`wait.state`	`'waiting' \| 'blocked'`
`model`	`{ id, displayName?, reasoningEffort?, contextWindowTokens? }`; `id` is required.
`agentId`	Optional stable agent identifier for agent, turn, tool, wait, completion, and exit events.

JSONL mapping context

Member	Meaning
`binding`	The opaque root `AgentSessionBinding` created by `terminal.bindSession()`.
`journal`	`{ role: 'root' }` for the primary watcher, or `{ role: 'child', childId }` for a declared/discovered child journal.
`publish`	The lifecycle publisher for this bound session.
`signal`	Cancellation signal for this observation lifetime.

A JSONL watcher emits raw chunks, not parsed records. Use createJsonlRecordDecoder(maxRecordBytes?) to obtain a bounded UTF-8 decoder with push(chunk, reset?) and reset(); reset it after a replace or truncate chunk.

Validation and mapping helpers

Export	Purpose
`createAgentLifecyclePublisher(sink)`	Builds a validating publisher around `(event: AgentLifecycleEvent) => void \| Promise<void>`.
`assertAgentLifecycleEvent(value)`	Validates and returns an `AgentLifecycleEvent`, or throws before an invalid event reaches the host.
`safeAgentString(value, maximum?)`	Returns a non-empty, display-safe string within the configured limit, or `undefined`; it never truncates identity values.
`selectAgentMapping(mappings, providerVersion)`	Selects the greatest known `AgentMapping<T>` version no newer than the provider version. If the version is unparsable, it uses the newest known mapping.

Keep provider-specific parsing inside mapRecord; publish only the normalized lifecycle events above. See Agent providers for binding and session setup.