create-spatius-app 0.1.3-beta.1 → 0.1.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-spatius-app",
-  "version": "0.1.3-beta.1",
-  "description": "Create a Spatius voice-avatar app with LiveKit or Agora and your choice of hosting.",
+  "version": "0.1.3",
+  "description": "Create a Spatius voice-avatar app with LiveKit or Agora Conversational AI on Cloudflare Workers.",
   "type": "module",
   "bin": {
     "create-spatius-app": "./dist/cli.js"
@@ -34,7 +34,7 @@
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "pnpm@12.3.4",
+  "packageManager": "pnpm@12.4.1",
   "publishConfig": {
     "access": "public",
     "provenance": true

package/templates/cloudflare-livekit/AGENTS.md

@@ -22,6 +22,8 @@ Run from the project root:
 
 All checks can run after dependency installation, before credential setup.
 Browser tests require Chromium; see README.md for the installation command.
+Wrangler generates the ignored `worker-configuration.d.ts` during installation
+and before lint, type checking, and builds. Update `wrangler.jsonc` to change bindings.
 
 ## Working guidelines
 

package/templates/cloudflare-livekit/README.md

@@ -54,6 +54,16 @@ This starts the Python agent first, then starts the frontend and Cloudflare
 Worker once the agent has registered with LiveKit. If registration takes more
 than 60 seconds, startup stops with an error.
 
+Press Ctrl+C once to stop both services. If shutdown logs cover the shell prompt
+and it looks as though another Ctrl+C is required, use pnpm 12.4.1 or later for
+both the executable on your PATH and the `packageManager` pin in `package.json`.
+An older launcher or project pin can return to the shell before the services
+finish shutting down; [pnpm 12.4.1 fixes signal forwarding and waiting](https://github.com/pnpm/pnpm/releases/tag/v12.4.1).
+For a Homebrew installation, run `brew update` followed by `brew upgrade pnpm`.
+Set `packageManager` to `pnpm@12.4.1`, then run `pnpm install` to refresh the
+package-manager lock entry. Changing only the project pin leaves an older
+launcher in use; upgrading only the launcher leaves an older project pin active.
+
 ## Validate without credentials
 
 After installing both dependency sets, you can run these checks before account

package/templates/cloudflare-livekit/agent/Dockerfile.pip

@@ -21,6 +21,11 @@ ENV PATH="/app/.venv/bin:$PATH" \
     PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1
 
+# Spatius encodes outgoing avatar audio with the native Opus library.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libopus0 \
+    && rm -rf /var/lib/apt/lists/*
+
 RUN useradd --create-home --uid 10001 appuser
 WORKDIR /app
 
@@ -28,4 +33,7 @@ COPY --from=builder --chown=appuser:appuser /app /app
 
 USER appuser
 
+# Fail the build if the runtime cannot load the native audio encoder.
+RUN python -c "import opuslib_next"
+
 CMD ["python", "-m", "src.agent", "start"]

package/templates/cloudflare-livekit/agent/Dockerfile.uv

@@ -19,6 +19,11 @@ FROM python:${PYTHON_VERSION}-slim-bookworm
 ENV PATH="/app/.venv/bin:$PATH" \
     PYTHONUNBUFFERED=1
 
+# Spatius encodes outgoing avatar audio with the native Opus library.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libopus0 \
+    && rm -rf /var/lib/apt/lists/*
+
 RUN useradd --create-home --uid 10001 appuser
 WORKDIR /app
 
@@ -26,4 +31,7 @@ COPY --from=builder --chown=appuser:appuser /app /app
 
 USER appuser
 
+# Fail the build if the runtime cannot load the native audio encoder.
+RUN python -c "import opuslib_next"
+
 CMD ["python", "-m", "src.agent", "start"]

package/templates/cloudflare-livekit/agent/README.md

@@ -6,6 +6,19 @@ and turn detection. The Spatius plugin sends the generated speech through the
 Spatius motion service and publishes synchronized avatar data into the same
 LiveKit room as the browser.
 
+## Session startup
+
+The worker runs `spatius.prewarm` through `AgentServer`'s `setup_fnc` when each
+job process initializes. It prepares automatic region selection, TLS connections,
+and a session token using the same Spatius environment variables as the avatar
+session, so a warm process can skip that setup when a room is dispatched.
+The avatar ID still comes from the job's dispatch metadata.
+
+Warm-up is best effort: missing configuration or a failed warm-up leaves normal
+session startup responsible for resolving the region and fetching a token.
+LiveKit keeps idle processes ready in production; development mode initializes
+processes on demand, so its first session still pays the warm-up cost.
+
 ## Voice configuration
 
 - TTS uses `cartesia/sonic-3.6` through LiveKit Inference. Setup offers
@@ -77,4 +90,6 @@ Use `lk agent deploy` for later releases. Keep `livekit.toml` local until you
 have reviewed the project-specific values it contains.
 
 The Docker image runs as a non-root user and downloads model support files at
-build time so startup does not need to fetch them.
+build time so startup does not need to fetch them. It also installs the native
+Opus library required for Spatius audio forwarding and checks that the Python
+binding can load it during the build.

package/templates/cloudflare-livekit/agent/pyproject.toml

@@ -5,7 +5,7 @@ description = "A LiveKit voice agent with a Spatius avatar"
 readme = "README.md"
 requires-python = ">=3.11,<3.15"
 dependencies = [
-  "livekit-agents[spatius]~=1.8.0",
+  "livekit-agents[spatius]~=1.8.1",
   "livekit-plugins-noise-cancellation~=0.3.0",
   "python-dotenv>=1.2.1,<2",
 ]

package/templates/cloudflare-livekit/agent/src/agent.py

@@ -43,7 +43,8 @@ class Assistant(Agent):
         )
 
 
-server = AgentServer()
+# Warm region, TLS, and session-token caches in each job process before dispatch.
+server = AgentServer(setup_fnc=spatius.prewarm)
 
 
 @server.on("worker_registered")

package/templates/cloudflare-livekit/agent/tests/test_agent_startup.py

@@ -11,6 +11,55 @@ with patch("dotenv.load_dotenv"):
     from src import agent as agent_module
 
 
+class ProcessPrewarmTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.enterContext(
+            patch.dict(
+                "os.environ",
+                {"SPATIUS_APP_ID": "app-test", "SPATIUS_API_KEY": "key-test"},
+                clear=True,
+            )
+        )
+        # Exercise the registered hook and installed plugin without provider calls.
+        self.sdk_prewarm = self.enterContext(
+            patch(
+                "spatius.prewarm",
+                new_callable=AsyncMock,
+                return_value=SimpleNamespace(
+                    region="test-region",
+                    tls_warmed=True,
+                    session_token_prefetched=True,
+                ),
+            )
+        )
+
+    def test_process_setup_warms_connection_state_without_an_avatar(self) -> None:
+        with patch.object(agent_module.spatius, "AvatarSession") as avatar:
+            agent_module.server.setup_fnc(SimpleNamespace())
+
+        self.sdk_prewarm.assert_awaited_once()
+        options = self.sdk_prewarm.call_args.kwargs
+        self.assertEqual(options["app_id"], "app-test")
+        self.assertEqual(options["api_key"], "key-test")
+        self.assertEqual(options["region"], "auto")
+        self.assertTrue(options["prefetch_session_token"])
+        avatar.assert_not_called()
+
+    def test_warmup_failure_does_not_fail_process_setup(self) -> None:
+        self.sdk_prewarm.side_effect = ConnectionError("warm-up unavailable")
+
+        with self.assertLogs("livekit.plugins.spatius", level="WARNING"):
+            agent_module.server.setup_fnc(SimpleNamespace())
+
+        self.sdk_prewarm.assert_awaited_once()
+
+    def test_process_setup_without_configuration_skips_warmup(self) -> None:
+        with patch.dict("os.environ", {}, clear=True):
+            agent_module.server.setup_fnc(SimpleNamespace())
+
+        self.sdk_prewarm.assert_not_awaited()
+
+
 class AgentStartupTests(unittest.IsolatedAsyncioTestCase):
     def setUp(self) -> None:
         self.events: list[str] = []

package/templates/cloudflare-livekit/agent/uv.lock

@@ -777,7 +777,7 @@ wheels = [
 
 [[package]]
 name = "livekit"
-version = "1.1.17"
+version = "1.1.18"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "aiofiles" },
@@ -786,18 +786,18 @@ dependencies = [
     { name = "protobuf" },
     { name = "types-protobuf" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/a6/bd/e20f97969cf21959061cdc6e1c89e3ad88e23693030398df283c236430fc/livekit-1.1.17.tar.gz", hash = "sha256:0553bfc9041dc8430029597a2278b43e4bb75594a72cb9dcc42bf3ee8e1689a0", size = 378467, upload-time = "2026-09-01T05:03:19.976Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/43/06/ed2cda99ce0c7f10f6599588b296d2bde08ec1235a97416e9986629ce131/livekit-1.1.18.tar.gz", hash = "sha256:1097b8613fa4625e3fb0bd4fe5b09a3b04b39151c08b78498831dfc57235d1d1", size = 386573, upload-time = "2026-09-08T01:50:55.05Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/fd/74/d93c5dd19ff2139c070eacb634e075cd2aff239a9cf692002afaa529a630/livekit-1.1.17-py3-none-macosx_10_15_x86_64.whl", hash = "sha256:39188ac6c805643c8ef952cccb96b2e81e430600e626dea9c6aa1faca7013fdb", size = 10468167, upload-time = "2026-09-01T05:03:06.001Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/3a/9f4f5e3f0c325d0d5d19c5dc1ae345f4bf1353369db3b42e265a1ee4dbc5/livekit-1.1.17-py3-none-macosx_11_0_arm64.whl", hash = "sha256:078d249974aed5e845b60f840802e36dc9d2c9c1dd606341fb95ee018749169e", size = 9289118, upload-time = "2026-09-01T05:03:09.011Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/d5/89293b55b7a719c7f7b7929d995c009bee7ce9f4d29876c77ee878fd9bf9/livekit-1.1.17-py3-none-manylinux_2_28_aarch64.whl", hash = "sha256:984c7c0efa3e1f917e973ce412a141ff8244baf98ff24587aa82c206b621054f", size = 10580945, upload-time = "2026-09-01T05:03:11.743Z" },
-    { url = "https://files.pythonhosted.org/packages/c9/4e/aad025688f8aceeecb4ec97aaae3541d64302e03454c84dc57e02bbaf5b9/livekit-1.1.17-py3-none-manylinux_2_28_x86_64.whl", hash = "sha256:100f2ddd8e433ea906ecf45f1d37063e43e72c7c2cff0b65ddddc11181bc8dd7", size = 11805780, upload-time = "2026-09-01T05:03:14.614Z" },
-    { url = "https://files.pythonhosted.org/packages/97/7a/5447238155494f2a2fd55ff0f7705b9769fe67e787b52150a5d269eeaa61/livekit-1.1.17-py3-none-win_amd64.whl", hash = "sha256:7a7b1bdb646775d8042ec97baec6c6b615c5828d6f9b6dd2adaa167841d6f6c2", size = 10968316, upload-time = "2026-09-01T05:03:17.671Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/b1/be04d760136480aa2d27f8247adc6d0a1e25395b146f04267fb8e716fe6a/livekit-1.1.18-py3-none-macosx_10_15_x86_64.whl", hash = "sha256:8337e956e9816814572c964e7553d66e4845bc3299cb5aeab8a0d671e293ed32", size = 10471856, upload-time = "2026-09-08T01:50:41.85Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/60/a0bf23774eecfc012b60bae84f329537053a0e0952d6f43dc6154d01ac5b/livekit-1.1.18-py3-none-macosx_11_0_arm64.whl", hash = "sha256:8557d6438da4b8968263b44920e7ab606a9ea34bc49fb8fd89054eb3e5cc162d", size = 9292804, upload-time = "2026-09-08T01:50:44.968Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/68/4b5e996660185f2db937a356c9e72981eab42c846f24ba992b997fa9f973/livekit-1.1.18-py3-none-manylinux_2_28_aarch64.whl", hash = "sha256:e9305aa097fe75f533db3205ab15868730e467130ffdda7d4adc3840f30b282a", size = 10584633, upload-time = "2026-09-08T01:50:47.735Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/5e/a0220ddf5e53bb3ee4f4969e9ca5e3a3e9567c584b66cd71355a45c069a8/livekit-1.1.18-py3-none-manylinux_2_28_x86_64.whl", hash = "sha256:dc2461b668ffa66ca504d05c88af7ea640372f53672ae367145412e374d6aff0", size = 11809468, upload-time = "2026-09-08T01:50:50.332Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/47/22455e01c76b271f7d9399546c2becabe4bf0f58a43e79859bb0ca4fc426/livekit-1.1.18-py3-none-win_amd64.whl", hash = "sha256:a61d4fd39392e7d28a7dbbe3b68be7b600115ed32501f5b016579846de945913", size = 10972019, upload-time = "2026-09-08T01:50:52.912Z" },
 ]
 
 [[package]]
 name = "livekit-agents"
-version = "1.8.0"
+version = "1.8.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "aiofiles" },
@@ -833,9 +833,9 @@ dependencies = [
     { name = "typing-extensions" },
     { name = "watchfiles" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/99/88/ace06ebd95b8cc45e25430a2a10ec7ccfb6b386b67907192ad421493858f/livekit_agents-1.8.0.tar.gz", hash = "sha256:132029af152a585770b58623a1a2ac7c8b1b9241b045e8cd220b30415fbcf2ad", size = 2688509, upload-time = "2026-09-05T00:10:03.294Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/5c/f1/cc1fcbc24da6f90cf38809c5ceafff1a1d1c1527a32431ce9b00e64deb95/livekit_agents-1.8.1.tar.gz", hash = "sha256:9319b4a7cf3891db4c1de9edd98fad4918919beadb2ceff5b3fbd34ae67384b5", size = 2712687, upload-time = "2026-09-10T18:59:30.729Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/f4/79/a1dce13ad49ab5b3248727b808ef265b2a535928c53161440d049a0b747d/livekit_agents-1.8.0-py3-none-any.whl", hash = "sha256:0da6c79c71eb7620af14d5c18adba1da796d6743338630813c341e9ce72f45c8", size = 2806075, upload-time = "2026-09-05T00:10:01.23Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/2c/29419a913c57b863eba93cbb41df2f3e58b57c3d8f790c6f97be81203ef7/livekit_agents-1.8.1-py3-none-any.whl", hash = "sha256:3e9e4e732ecebcf0512d5eec25621a365c3572289d1f136396d8a1c5ea78e2ac", size = 2832498, upload-time = "2026-09-10T18:59:28.67Z" },
 ]
 
 [package.optional-dependencies]
@@ -935,15 +935,15 @@ wheels = [
 
 [[package]]
 name = "livekit-plugins-spatius"
-version = "1.8.0"
+version = "1.8.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "livekit-agents" },
     { name = "spatius", extra = ["opus"] },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/c0/40/ce00a90cdfd3fd0840ef452e8706e88ae5da9ab2c2cc900a615bfae7abcf/livekit_plugins_spatius-1.8.0.tar.gz", hash = "sha256:76d80c79db4673da4c1ce84f51fbec986a0bd7b888226d8fced68992c7d798e8", size = 8601, upload-time = "2026-09-05T00:12:14.914Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/3f/a7/96d690fa9177fb29ae162fdd3957eee2c87ff3c0b9c4e85956532f94a779/livekit_plugins_spatius-1.8.1.tar.gz", hash = "sha256:d71b74eea79a58861c5893d67d4196d4a3deb2836c23cf4316759aae368b4b9d", size = 10093, upload-time = "2026-09-10T19:01:10.334Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/4d/34/bd44feacb043d16e18396bb7bb9ccb8f100348efce5090d853f8a6bfff1d/livekit_plugins_spatius-1.8.0-py3-none-any.whl", hash = "sha256:c852c7c1ec26b094cc207fa127de1f65e305c6def43d626ee65a250339a1bb69", size = 8712, upload-time = "2026-09-05T00:12:13.838Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/93/b562e8e3ff22b19f69575302b41649bcde379497b73b2fc003f76553a8c4/livekit_plugins_spatius-1.8.1-py3-none-any.whl", hash = "sha256:234d2d0817e43a0aa736c2bfc698b364f6ad64c2ba55c469bab35169099f928e", size = 11330, upload-time = "2026-09-10T19:01:09.016Z" },
 ]
 
 [[package]]
@@ -1891,7 +1891,7 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "livekit-agents", extras = ["spatius"], specifier = "~=1.8.0" },
+    { name = "livekit-agents", extras = ["spatius"], specifier = "~=1.8.1" },
     { name = "livekit-plugins-noise-cancellation", specifier = "~=0.3.0" },
     { name = "python-dotenv", specifier = ">=1.2.1,<2" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.15,<1" },

package/templates/cloudflare-livekit/gitignore

@@ -8,6 +8,7 @@ playwright-report/
 
 # Cloudflare
 .wrangler/
+worker-configuration.d.ts
 .dev.vars
 .dev.vars.*
 !.dev.vars.example