Phase 7a: hand off large chat requests to a one-time workflow (server, 0.261.238)

application/single_app/admin_settings_fields.py

@@ -134,6 +134,9 @@
     normalize_terms_of_use_text,
 )
 from functions_workflow_limits import (
+    CHAT_ORCHESTRATION_MAX_HANDOFFS_PER_DAY_DEFAULT,
+    CHAT_ORCHESTRATION_MAX_HANDOFFS_PER_DAY_MAX,
+    CHAT_ORCHESTRATION_MAX_HANDOFFS_PER_DAY_MIN,
     CHAT_ORCHESTRATION_MAX_WORKFLOWS_DEFAULT,
     CHAT_ORCHESTRATION_MAX_WORKFLOWS_MAX,
     CHAT_ORCHESTRATION_MAX_WORKFLOWS_MIN,
@@ -150,6 +153,7 @@
     WORKFLOW_REPEAT_ITERATIONS_MAX,
     WORKFLOW_REPEAT_ITERATIONS_MIN,
     WorkflowLoopLimitError,
+    validate_chat_orchestration_max_workflow_handoffs_per_day,
     validate_chat_orchestration_max_workflows_per_user,
     validate_chat_orchestration_min_workflow_interval_seconds,
     validate_workflow_max_loop_items,
@@ -3806,6 +3810,29 @@
                 {"key": "allow_user_workflows", "equals": True},
             ],
         },
+        {
+            "key": "enable_chat_orchestration_workflow_handoff",
+            "type": "switch",
+            "label": "Hand Off Large Work From Chat",
+            "help": (
+                "When a request is too large for a chat plan, such as reviewing hundreds of "
+                "documents, a plan can hand the work to a one-time durable workflow instead. The "
+                "user approves the plan, then approves a hand-off card that names the documents, "
+                "or says how many matching documents at most, the workflow will review. Approving "
+                "the card creates the workflow turned off, so it never runs on a schedule, and "
+                "starts it once; when the run finishes, its result is posted back into the "
+                "conversation. The daily limit under Limits applies. Off by default, because a "
+                "hand-off starts background work that keeps running with the user's access after "
+                "the chat turn ends. Requires Chat Orchestration, Enable Personal Workflows, "
+                "Propose Workflows From Chat, Run Workflows From Chat and Use Workflow Results "
+                "In Chat."
+            ),
+            "default": False,
+            "depends_on": [
+                {"key": "enable_chat_orchestration", "equals": True},
+                {"key": "allow_user_workflows", "equals": True},
+            ],
+        },
         {
             "key": "chat_orchestration_enabled_capabilities",
             "type": "checkbox_set",
@@ -3819,7 +3846,9 @@
                 "requires Enable Action Access. Propose workflows also requires Propose "
                 "Workflows From Chat and personal workflows. Run workflows also requires Run "
                 "Workflows From Chat and personal workflows. Read workflow results also "
-                "requires Use Workflow Results In Chat and personal workflows."
+                "requires Use Workflow Results In Chat and personal workflows. Hand off large "
+                "work also requires Hand Off Large Work From Chat, Propose Workflows From Chat, "
+                "Run Workflows From Chat, Use Workflow Results In Chat and personal workflows."
             ),
             "default": [],
             "options": [
@@ -3841,6 +3870,7 @@
                 {"value": "workflow_propose", "label": "Propose workflows"},
                 {"value": "workflow_run", "label": "Run workflows"},
                 {"value": "workflow_results", "label": "Read workflow results"},
+                {"value": "workflow_handoff", "label": "Hand off large work"},
             ],
             "depends_on": {"key": "enable_chat_orchestration", "equals": True},
         },
@@ -3961,6 +3991,28 @@
             "depends_on": {"key": "enable_chat_orchestration", "equals": True},
             "group": {"id": "limits", "label": "Limits", "variant": "limits"},
         },
+        {
+            "key": "chat_orchestration_max_workflow_handoffs_per_day",
+            "type": "number",
+            "label": "Hand-Offs From Chat Per User Per Day",
+            "help": (
+                "How many hand-offs one user may start from chat in any rolling 24 hours. Each "
+                "hand-off creates a one-time workflow and starts a durable run, so this bounds "
+                "how much background work one user can start from chat. Hand-off workflows do "
+                "not count toward Workflows Created From Chat Per User. Default is 5; "
+                "supported range is 1 to 100."
+            ),
+            "default": CHAT_ORCHESTRATION_MAX_HANDOFFS_PER_DAY_DEFAULT,
+            "min": CHAT_ORCHESTRATION_MAX_HANDOFFS_PER_DAY_MIN,
+            "max": CHAT_ORCHESTRATION_MAX_HANDOFFS_PER_DAY_MAX,
+            "step": 1,
+            "depends_on": [
+                {"key": "enable_chat_orchestration", "equals": True},
+                {"key": "allow_user_workflows", "equals": True},
+                {"key": "enable_chat_orchestration_workflow_handoff", "equals": True},
+            ],
+            "group": {"id": "limits", "label": "Limits", "variant": "limits"},
+        },
     ],
     "chat-orchestration-planner-model-section": [
         # One dropdown writes the four planner keys below as a set. They stay declared, as
@@ -6982,6 +7034,12 @@
         except WorkflowLoopLimitError as error:
             return None, error.public_message, None
 
+    if key == "chat_orchestration_max_workflow_handoffs_per_day":
+        try:
+            return validate_chat_orchestration_max_workflow_handoffs_per_day(value), None, None
+        except WorkflowLoopLimitError as error:
+            return None, error.public_message, None
+
     if key == "chat_orchestration_min_workflow_interval_seconds":
         try:
             return validate_chat_orchestration_min_workflow_interval_seconds(value), None, None

application/single_app/config.py

@@ -101,7 +101,7 @@
 EXECUTOR_TYPE = 'thread'
 EXECUTOR_MAX_WORKERS = 30
 SESSION_TYPE = 'filesystem'
-VERSION = "0.261.248"
+VERSION = "0.261.250"
 IS_DEVELOPMENT = is_development_env_enabled()
 
 # Opt-out for deployments where App Service Easy Auth is active but the platform

application/single_app/functions_orchestration_adapters.py

@@ -93,6 +93,7 @@
     CAPABILITY_TABULAR_MERGE,
     CAPABILITY_URL_FETCH,
     CAPABILITY_WEB_SEARCH,
+    CAPABILITY_WORKFLOW_HANDOFF,
     CAPABILITY_WORKFLOW_PROPOSE,
     CAPABILITY_WORKFLOW_RESULTS,
     CAPABILITY_WORKFLOW_RUN,
@@ -2139,6 +2140,19 @@ def run_workflow_results(step, context, *, settings, user_id, emit=None, cancel_
     )
 
 
+def run_workflow_handoff(step, context, *, settings, user_id, emit=None, cancel_requested=None):
+    """Prepare a one-time workflow hand-off for the user's approval; nothing is created or queued.
+
+    The workflow draft service loads only when a plan hands work off, so resolving this adapter
+    imports nothing beyond this module.
+    """
+    from functions_orchestration_workflow_handoffs import adapter_workflow_handoff
+
+    return adapter_workflow_handoff(
+        step, context, settings=settings, user_id=user_id, emit=emit, cancel_requested=cancel_requested,
+    )
+
+
 # Keyed by capability id, which is also each descriptor's declared ``adapter`` name, so the
 # executor can look an adapter up straight from the step's capability without a second map.
 ADAPTER_REGISTRY = {
@@ -2157,6 +2171,7 @@ def run_workflow_results(step, context, *, settings, user_id, emit=None, cancel_
     CAPABILITY_WORKFLOW_PROPOSE: run_workflow_propose,
     CAPABILITY_WORKFLOW_RUN: run_workflow_run,
     CAPABILITY_WORKFLOW_RESULTS: run_workflow_results,
+    CAPABILITY_WORKFLOW_HANDOFF: run_workflow_handoff,
 }
 
 

application/single_app/functions_orchestration_deliverables.py

@@ -46,6 +46,7 @@
     CAPABILITY_RENDER_FILE,
     CAPABILITY_TABULAR_INSPECT,
     CAPABILITY_TABULAR_MERGE,
+    CAPABILITY_WORKFLOW_HANDOFF,
     CAPABILITY_WORKFLOW_PROPOSE,
     CAPABILITY_WORKFLOW_RESULTS,
     CAPABILITY_WORKFLOW_RUN,
@@ -477,6 +478,21 @@
                 f'{WORKFLOW_RESULTS_UNAVAILABLE_REASONS[_workflow_results_reason(unavailable)]} '
                 'When the user asks what a saved workflow found, say why in the answer.'
             )
+    # Handing work off is described only when this request offers it; otherwise the planner is told
+    # exactly what it was before.
+    if CAPABILITY_WORKFLOW_HANDOFF in available:
+        facts.append(
+            'workflow_handoff hands work that is too big for one chat plan to a one-time workflow. The '
+            'user reviews its hand-off card after approving the plan, and nothing is created or run until '
+            'the user approves that card; the run\'s summary is posted back into this conversation when it '
+            'finishes. The server adds a note about the hand-off to the reply, so never say that the work '
+            'was done, started or scheduled.'
+        )
+        recipes.append({'for': 'Work too big for one chat plan', 'steps': (
+            'one workflow_handoff step with no depends_on, no inputs and no deliverable. When the request '
+            'is only the hand-off, declare no deliverables and no final_response; otherwise the compose '
+            'final_response answers only what the other steps can answer now.'
+        )})
     truth.update({'unavailable_reasons': unavailable_reasons, 'facts': facts, 'recipes': recipes})
     return truth
 

application/single_app/functions_orchestration_execution.py

@@ -153,8 +153,8 @@
     resolve_orchestration_model,
 )
 from functions_orchestration_registry import (
-    CAPABILITY_WORKFLOW_RESULTS, CapabilityResolutionError, resolve_admitted_export_catalog,
-    resolve_available_capability_ids,
+    CAPABILITY_WORKFLOW_HANDOFF, CAPABILITY_WORKFLOW_RESULTS, CapabilityResolutionError,
+    resolve_admitted_export_catalog, resolve_available_capability_ids,
 )
 from functions_orchestration_result_contracts import InputBinding, ResultContractError, ResultRef, TaskResult
 from functions_orchestration_result_runtime import read_complete_input, read_result_document_citations
@@ -1210,6 +1210,12 @@ def _reads_workflow_results(self):
             for step in self.record["plan"].get("steps") or []
         )
 
+    def _mentions_workflow_handoff(self):
+        plan = self.record["plan"]
+        return bool(plan.get("workflow_handoff_notes")) or any(
+            step.get("capability_id") == CAPABILITY_WORKFLOW_HANDOFF for step in plan.get("steps") or []
+        )
+
     def _workflow_result_lineage(self, record_state):
         """The workflow result contexts the answer read, re-authorized now; [] when it read none."""
         if not self._reads_workflow_results():
@@ -1339,6 +1345,15 @@ def _finalize(self, result, error, *, refreshes=0):
         )
         if workflow_runs:
             content.append(workflow_runs)
+        if self._mentions_workflow_handoff():
+            # Imported here, like the run step's module. Deterministic, model-free: the hand-off the
+            # plan prepared or left out, at every status, as its card says. Its note also keeps a
+            # hand-off-only plan from the "content is prepared" fallback.
+            from functions_orchestration_workflow_handoffs import workflow_handoff_note
+
+            workflow_handoff = workflow_handoff_note(self.record["plan"], current.get("execution_steps") or [])
+            if workflow_handoff:
+                content.append(workflow_handoff)
         # Only a reply that carries the composed answer names the results it read; any other reply
         # keeps just the fixed lines about results that were not read.
         workflow_result_reads = error is None and bool(prepared)

application/single_app/functions_orchestration_executor.py

@@ -64,8 +64,9 @@
 from functions_orchestration_deliverables import explicit_image_shortfalls
 from functions_orchestration_registry import (
     CAPABILITY_DOCUMENT_MERGE, CAPABILITY_TABULAR_ANALYZE, CAPABILITY_TABULAR_INSPECT, CAPABILITY_TABULAR_MERGE,
-    CAPABILITY_WORKFLOW_PROPOSE, CAPABILITY_WORKFLOW_RESULTS, CAPABILITY_WORKFLOW_RUN, DEPENDENCY_PLAN_CONTRACT_VERSION,
-    admitted_export_pairs, external_effect_capability_ids, get_capability, resolve_available_capability_ids,
+    CAPABILITY_WORKFLOW_HANDOFF, CAPABILITY_WORKFLOW_PROPOSE, CAPABILITY_WORKFLOW_RESULTS, CAPABILITY_WORKFLOW_RUN,
+    DEPENDENCY_PLAN_CONTRACT_VERSION, admitted_export_pairs, external_effect_capability_ids, get_capability,
+    resolve_available_capability_ids,
 )
 from functions_orchestration_result_contracts import (
     InputBinding, PartialInputNotAcceptedError, ProducerIdentity, ResultContractError, ResultRef, TaskResult, digest,
@@ -612,6 +613,9 @@
     if step.get('capability_id') == CAPABILITY_WORKFLOW_RESULTS and isinstance(result.get('workflow_results'), dict):
         # Server-only: the result read's lineage and reply descriptor; public_step_record drops it.
         record['workflow_results'] = deepcopy(result['workflow_results'])
+    if step.get('capability_id') == CAPABILITY_WORKFLOW_HANDOFF and isinstance(result.get('workflow_handoff'), dict):
+        # Server-only: the blueprint, handles and selections the hand-off routes read; public_step_record drops it.
+        record['workflow_handoff'] = deepcopy(result['workflow_handoff'])
     return record
 
 
@@ -697,6 +701,35 @@
     return {**result, 'workflow_results': sidecar} if isinstance(sidecar, dict) else result
 
 
+def _restore_workflow_handoff(step, context, status, result, *, settings, user_id):
+    """Describe again a completed hand-off whose step result came back without its sidecar.
+
+    A retained, recovered or reused result is rebuilt from the task result alone, which carries
+    the card but never the blueprint's handles or the captured selections. The rebuild dry-runs
+    the blueprint again and writes nothing.
+    """
+    if (
+        step.get('capability_id') != CAPABILITY_WORKFLOW_HANDOFF or status != STEP_STATUS_COMPLETED
+        or not isinstance(result, dict) or result.get('task_result') is None
+        or isinstance(result.get('workflow_handoff'), dict)
+    ):
+        return result
+    try:
+        from functions_orchestration_workflow_handoffs import rebuild_workflow_handoff
+
+        sidecar = rebuild_workflow_handoff(
+            step, context, settings=settings, user_id=user_id, task=result['task_result'],
+        )
+    except Exception as exc:
+        log_event(
+            f'{_LOG_PREFIX} A recovered workflow hand-off could not be described.',
+            level=logging.WARNING,
+            extra={**_step_log_context(context, step), 'error_type': type(exc).__name__},
+        )
+        return result
+    return {**result, 'workflow_handoff': sidecar} if isinstance(sidecar, dict) else result
+
+
 def _persist(persist, record_type, record):
     if not callable(persist):
         return
@@ -1554,6 +1587,7 @@
         result = _restore_workflow_proposal(step, context, status, result, settings=settings, user_id=user_id)
         result = _restore_workflow_run(step, context, status, result, user_id=user_id)
         result = _restore_workflow_results(step, context, status, result, user_id=user_id)
+        result = _restore_workflow_handoff(step, context, status, result, settings=settings, user_id=user_id)
         record = _step_record(context, step, index, status, result, started_at, completed_at, elapsed)
         record.update({
             'checkpoint_available': checkpoints is not None