Skip to content

OSSS.ai.orchestration.protocol.turn_controller

OSSS.ai.orchestration.protocol.turn_controller

TurnController

TurnController (InteractionProtocolService)

Best-practice contract
  • pending_action is the ONLY gate for “awaiting a reply”.
  • Interprets yes/no/cancel ONLY when: pending_action.type == "confirm_yes_no" AND pending_action.awaiting is True
  • On yes/no/cancel:
    • write a one-shot pending_action_result
    • consume the pending_action by setting awaiting=False
    • ensure future code does NOT treat presence of pending_action as "still pending" (we preserve the object but mark it as cleared)
    • clear any stale final/answer/response fields so the previous prompt can't be re-served
  • On unclear:
    • DO NOT consume; reprompt and keep awaiting=True
    • route-lock + suppress_history so planner/classifier doesn't drift

preprocess(exec_state, raw_user_text)

Called at the TOP of TurnNormalizer.normalize().

If we are awaiting a confirm_yes_no reply
  • YES => emit pending_action_result(decision=yes) + consume gate + lock route + suppress_history canonical_user_text = pending_question
  • NO/CANCEL => emit pending_action_result(decision=no|cancel) + consume gate + suppress_history canonical_user_text = ""
  • UNCLEAR => keep awaiting=True, reprompt, lock route, suppress_history

consume(exec_state, *, owner)

Agent helper: consume one-shot pending_action_result for this owner.

ask_confirm_yes_no(exec_state, *, owner, pending_question, prompt, resume_route, resume_pattern, context=None, reason=None)

Convenience wrapper to create a confirm_yes_no pending action.

wizard_step_migration_heal(wizard_state)

Migration helper
  • prefer step
  • fallback legacy pending_action/status
  • block confirm_table/pending_confirmation