session-state_skill

Overview

This skill manages session state transitions for an internal orchestration engine. It validates and executes state changes according to the defined session state machine and is intended for use only within the runtime harness. Do not use this skill for user-facing session management, login state, or general application state handling.

How this skill works

The skill inspects incoming transition requests and checks them against the session orchestration rules to determine validity. When valid, it applies the transition, updates the session record, and emits the appropriate lifecycle events; when invalid, it rejects the change and returns diagnostics. It also supports special transitions for error escalation, stop, and resume flows.

When to use it

• At phase boundaries in the internal work orchestration pipeline (e.g., before/after executing a work unit).
• When an internal error requires escalating the session state to an error-handling workflow.
• When terminating a session to ensure a clean 'stopped' state and resource release.
• When resuming a paused session and needing to restore the 'initialized' or prior state.
• When enforcing invariant checks on state transitions as part of automated coordination.

Best practices

• Only invoke this skill from trusted internal components; avoid exposing it to external clients.
• Always query the current session state before requesting a transition to prevent races.
• Handle rejected transitions gracefully by logging diagnostics and triggering fallback logic.
• Use emitted lifecycle events to drive side effects (metrics, cleanup, notifications) instead of embedding them here.
• Keep transition requests idempotent where possible to tolerate retries.

Example use cases

• Orchestrator triggers a transition from 'planning' to 'working' at the start of a work cycle.
• Automatic escalation to an 'escalated' state when a worker encounters a non-recoverable error.
• Graceful shutdown sequence switching sessions to 'stopped' and releasing allocated resources.
• Resuming a suspended session by validating and moving it back to 'initialized' for review.