[knit (knitvoger)]

Summary

Add a Python foreground/background conversation-engine variant at
bring-your-own/conversation_engine/foreground_background, based on main at dd8d6b97 after #1124 merged.

The original Responses sample at
bring-your-own/voicelive/foreground-background-agents-responses-voicelive
remains unchanged. All 16 original files are byte-identical to the PR base; this is an addition, not a relocation.

• The new variant uses voice_conversation_engine:1.0.0 and the typed /voice_conversation_engine WebSocket handler; the original sample keeps its Responses ingress. Bridge message version stays 1.0; legacy Bridge metadata is not required.
• Preserve the model deployment, runtime directory, Router meta-tools, five-round Worker loop, Worker system prompt, four domain-tool schemas and mock results. The CE variant uses distinct Hosted Agent foreground-background-agents-ce and Voice wrapper foreground-background-agents-ce-voice names, so both samples can coexist in one project without replacing the original Agent. This is not a story/Echo replacement or a .NET sample.
• Use asynchronous foreground model calls and connection-scoped task/history state. Keep control callbacks responsive, reconcile heard_text, and record assistant history only after successful sends.
• Track delivered task IDs explicitly, including paraphrases, and commit delivery after successful response.done. Session teardown signals cooperative Worker cancellation and retains in-flight work until shutdown drains it before closing model clients.
• Add a Voice wrapper declaration, dedicated smoke client, build-readiness commands, portable dependency lock, documentation and behavior contract. The shared HTTP-only cloud runner cannot invoke CE; the deployment skiplist matches the existing CE samples, without skipping local build/unit validation.

Adjacent drain fix

The CE shutdown regression exposed an existing Python CE drain loop that can spin when all retained tasks are already complete: asyncio.gather() can return synchronously before ownership-release callbacks run.

Add a cooperative checkpoint to the foreground/background copy and all four existing Python CE copies, with a regression test in each. The corresponding .NET drain loops already contain Task.Yield() and are unchanged. This adds no new lifecycle ownership mechanism.

Validation

• Follow-up coexistence validation: all 16 original files match the PR base byte-for-byte; the original retains responses:2.0.0, while the CE variant declares voice_conversation_engine:1.0.0 under distinct Agent names. The 24 CE tests, Ruff, lock and committed policy checks passed again after restoration.

• Foreground/background: 24 tests passed, including the real SDK dispatcher, original Worker tool loop, connection isolation, barge-in/timeout, failed-send history/delivery, cooperative Worker shutdown and a real local WebSocket smoke with fake models.

• Existing Python CE regression suites: Basic 144, LangChain 128, LangGraph 128, Adapter Mode 215 tests passed (639 total, including foreground/background).

• All declared sample.yaml build, validate and test commands executed successfully; Ruff and compile/import checks passed.

• Committed dependency-policy check passed with --resolve.

• Hosted-agent contract policy passed; the behavior fixture also passed schema validation and raw-assertion planning. Planning is not execution by a CE-capable cloud harness.

• Confirmed the original Worker prompt, four tool schemas and mock return values remain unchanged.

• git diff --check passed.

An initial shutdown run hung and one process crashed before the drain checkpoint fix. A bounded probe reproduced the original drain hang; the complete affected suites passed after the fix without changing Python settings or suppressing tests.

Deployment prerequisites / limits

No cloud model call, managed-audio test, resource change or deployment was performed. Unit tests use fake model clients and zero-latency tool doubles; the domain tools remain mock implementations.

Deployment requires matching Hosted Agent ingress and Voice Live CE support, the Foundry model deployment and model-inference permissions. The new Voice wrapper exists only in the manifest until deployment. Verify those prerequisites, deploy the Hosted Agent and Voice wrapper, and run real audio/interruption validation separately. Per-connection task/history state is in memory and is not restored across disconnected sockets or host replacement.

[Copilot]

🟡 Changes recommended

Active issues leave Workers running during terminal-send backpressure and concatenate acknowledgment, progress, and result text without separators, affecting cancellation and spoken output.

2 open issues

• Separate acknowledgment, progress, and Worker-result chunks · New
• Detach Workers when terminal-send capacity is exhausted · New

What changed in this PR

Migrates the model-backed foreground/background VoiceLive sample to the conversation-engine infrastructure introduced in #1124, while preserving its Router/Worker workflow and mock domain tools.

Changes:

• Replaces Responses HTTP ingress with typed conversation-engine WebSocket handling, connection-scoped history, explicit delivery tracking, and cooperative Worker shutdown.
• Adds a Voice wrapper manifest, dedicated smoke client, behavior contract, and local validation commands.
• Adds cooperative shutdown checkpoints and regression tests across all five Python conversation-engine samples.

For compactness, paths use these prefixes:

• BYO = samples/python/hosted-agents/bring-your-own
• CE = BYO/conversation_engine
• FG = CE/foreground_background
• SRC = FG/src/foreground-background-agents-voicelive
• OLD = BYO/voicelive/foreground-background-agents-responses-voicelive

File	Description
OLD/​src/​foreground-background-agents-voicelive/​worker_agent.py	Removes the former Worker location.
OLD/​src/​foreground-background-agents-voicelive/​pyproject.toml	Removes the former dependency manifest.
OLD/​src/​foreground-background-agents-voicelive/​main.py	Removes the Responses HTTP implementation.
OLD/​README.md	Removes the former setup guide.
OLD/​azure.yaml	Removes the Responses deployment manifest.
OLD/​AGENTS.md	Removes the former contributor guidance.
CE/​README.md	Lists and explains the model-backed variant.
CE/​langgraph/​src/​voice-live-bridge-langgraph-python/​tests/​test_shutdown_checkpoint.py	Adds drain-progress regression coverage.
CE/​langgraph/​src/​voice-live-bridge-langgraph-python/​response_coordinator.py	Yields during detached-task draining.
CE/​langchain/​src/​voice-live-bridge-langchain-python/​tests/​test_shutdown_checkpoint.py	Adds drain-progress regression coverage.
CE/​langchain/​src/​voice-live-bridge-langchain-python/​response_coordinator.py	Yields during detached-task draining.
SRC/​worker_agent.py	Preserves domain tools and adds completion bookkeeping.
SRC/​voice_runtime.py	Provides typed Voice lifecycle callbacks.
SRC/​uv.toml	Configures certificates and prerelease resolution.
SRC/​tests/​test_shutdown_checkpoint.py	Covers completed-task drain progress.
SRC/​tests/​test_conversation_engine.py	Tests routing, history, delivery, interruption, and shutdown.
SRC/​task_store.py	Scopes tasks per connection and tracks terminal retention.
SRC/​state.py	Defines bounded protocol state and response ownership.
SRC/​scripts/​smoke_test.py	Adds a dedicated WebSocket protocol client.
SRC/​router_agent.py	Adds explicit task IDs for paraphrased result delivery.
SRC/​route_worker_agent.md	Documents the migrated workflow and lifecycle.
SRC/​response_telemetry.py	Records sanitized response outcomes and duration.
SRC/​response_coordinator.py	Coordinates streaming, cancellation, sequencing, and draining.
SRC/​pyproject.toml	Declares Python 3.13, Voice SDK, and development dependencies.
SRC/​main.py	Starts the conversation-engine application.
SRC/​Dockerfile	Updates the container to Python 3.13.
SRC/​conversation_runtime.py	Connects business state and delivery tracking to Voice callbacks.
SRC/​azdignore.txt	Excludes local manifest and environment-template files from packaging.
SRC/​agent_logic.py	Implements asynchronous Router calls and retained Worker execution.
SRC/​.gitignore	Excludes local environments, caches, and secrets.
SRC/​.env.example	Documents model and telemetry configuration.
SRC/​.dockerignore	Excludes local artifacts and credentials from images.
FG/​sample.yaml	Declares build, validation, and test commands.
FG/​README.md	Documents setup, lifecycle guarantees, and deployment limits.
FG/​CLAUDE.md	Retains the shared contributor-guidance import.
FG/​azure.yaml	Declares conversation-engine ingress and a Voice wrapper.
FG/​AGENTS.md	Documents migration-specific implementation constraints.
CE/​basic/​src/​voice-live-bridge-basic-python/​tests/​test_shutdown_checkpoint.py	Adds drain-progress regression coverage.
CE/​basic/​src/​voice-live-bridge-basic-python/​response_coordinator.py	Yields during detached-task draining.
CE/​adapter_mode/​src/​voice-live-adapter-python/​tests/​test_shutdown_checkpoint.py	Adds drain-progress regression coverage.
CE/​adapter_mode/​src/​voice-live-adapter-python/​adapter/​response_coordinator.py	Yields during detached-task draining.
.azure-pipelines/​scripts/​hosted-agent-samples-ci-skiplist	Excludes the sample from HTTP-only cloud invocation.
.azure-pipelines/​hosted-agent-tests/​python/​bring-your-own/​conversation_engine/​foreground_background/​test-spec.yml	Defines direct-response and background-result behavior assertions.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

A completion race can leave Worker results undelivered, while terminal-send saturation can leave terminating conversations attached and Workers running without cancellation.

3 open issues

• Deliver tasks completed while awaiting the Router response · New
• Detach Workers when terminal-send capacity is exhausted
• Separate acknowledgment, progress, and Worker-result chunks

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The model-backed CE/Voice integration has only local fake-model validation, leaving platform ingress, managed-identity model access, and real audio/interruption behavior unverified until deployment validation.

No open issues 🎉

3 resolved since last review

• Deliver tasks completed while awaiting the Router response
• Detach Workers when terminal-send capacity is exhausted
• Separate acknowledgment, progress, and Worker-result chunks

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Cancellation or barge-in can truncate valid assistant replies in conversation history, silently discarding technical instructions the caller actually heard.

1 open issue

• Prevent truncating heard replies beyond the input character limit · New

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Maintainer validation is needed for deployed CE/Voice compatibility, model permissions, and active managed-audio interruption because current evidence is limited to local, fake-model testing.

No open issues 🎉

1 resolved since last review

• Prevent truncating heard replies beyond the input character limit

_{Review effort: Balanced}