Files
orca/docs/sidekick-animation-state-mapping.md
T
83b3369ea5 fix: Support Codex pet sidekick animations (#1533)
* Support Codex pet sidekick animations

* Refine Codex pet defaults and drop unused failed animation state

Always default spritesheetPath to spritesheet.webp when a manifest
omits it, even when explicit frame/animation metadata is present, so
non-Codex bundles still benefit from the standard sheet name.

Drop the 'failed' animation entirely — Orca has no failure state, so
mapping interrupted completions to 'failed' would conflate user
cancellation with agent failure. Codex spritesheets can still expose
a 'failed' row as an asset contract, but it's never selected at runtime.

Co-authored-by: Orca <help@stably.ai>

---------

Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Co-authored-by: Orca <help@stably.ai>
2026-05-07 23:50:20 -07:00

1.2 KiB

Sidekick animation state mapping

Orca's normalized agent status model has four hook-reported states: working, blocked, waiting, and done. interrupted is an optional flag on done, not a separate failure state.

Codex pet spritesheets can expose more visual rows than Orca has agent states. Sidekick should treat those row names as an asset contract, not as proof that Codex or Orca reports matching runtime states.

The current mapping is:

Orca condition Sidekick animation
Sidekick is being dragged jumping
Any fresh agent is blocked or waiting waiting
Any fresh agent is working running
Any fresh agent is done review
Any retained completed agent exists review
No fresh or retained agent state exists idle

SidekickAnimationName deliberately omits failed. Orca distinguishes interrupted completions from normal completions, but interruption can mean user cancellation rather than agent failure, so mapping it to failed would overstate the status until Orca has a real failure/error signal. Codex spritesheets may still expose a failed row — that row stays as part of the asset contract but is never selected at runtime.