command-center/agent/managed-skills/omp-lifecycle-event-selection/SKILL.md

name, description

name	description
omp-lifecycle-event-selection	Pick the right omp harness lifecycle event for narration/telemetry: agent_end is a settle, turn_end waits for tool results, message_end is earliest with content, after_provider_response carries no content.

Choosing an omp lifecycle event (narration, telemetry, hooks)

Re-derived twice from the installed typings/sources (@oh-my-pi/pi-coding-agent, @oh-my-pi/pi-agent-core) while fixing dankvoice. Read this before wiring a handler; verify against the installed version's src/extensibility/extensions/types.ts and pi-agent-core/src/agent-loop.ts when precision matters.

event	payload you can use	when it fires	traps
after_provider_response	status, headers, requestId, metadata only	response headers arrive, before the stream body is consumed	No message content at all: useless for anything that speaks or summarizes text. Right for latency telemetry, non-200/abort detection, requestId correlation.
message_end	full message (assistant, user, tool-result, gate-stop, error)	the moment that message is built (agent-loop.ts, assistant case)	Earliest event carrying assistant text. Fires for non-assistant messages too → gate message.role === "assistant". Payload is cloned for extensions.
turn_end	turnIndex, message, toolResults	after that turn's tool results come back	Stale by the tool duration: a 14 s tool delays a turn_end trigger 14 s. Extension event has no willContinue (the turnIndex is numbered by the lifecycle mirror), so you cannot tell the terminal turn from here.
agent_end	messages, willContinue, awaitingAsyncWork	once per user prompt, when the loop settles	willContinue: true = the harness scheduled a continuation (auto-retry / empty-stop), not a user-visible settle — narrating it speaks an answer the model is about to redo. Silence-prone on long-running sessions.
agent_start	—	run begin	Use to reset per-run dedupe state, so a later answer with identical text is not swallowed.

Narration cadence pattern (what dankvoice ships)

• turn_end (or message_end if the tool-time lag matters) for mid-run commentary; agent_end only for the settled answer.
• Drop a mid-run trigger while audio/IO is busy — never queue, never interrupt.
• Dedupe the terminal text per run (agent_start resets), because the last turn and the settle carry the same string.
• Skip ctx.mode === "print" | "json" so benches stay silent.

Prove delivery, don't infer it

Audio/UI timing cannot show which events arrive. Link a throwaway extension that appends timestamps per event and run one real session: omp plugin link /tmp/probe (package.json with "pi": { "extensions": ["./index.js"] }), prompt a task with a slow tool, read the log, then omp plugin uninstall probe. Confirmed live 2026-10-19: extensions receive agent_start, turn_end, agent_end; turn_end landed seconds before agent_end.