create-spatius-app 0.1.2 → 0.1.3-beta.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-spatius-app",
-  "version": "0.1.2",
-  "description": "Create a Spatius app with a web frontend, Cloudflare Worker, and LiveKit agent.",
+  "version": "0.1.3-beta.2",
+  "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"
@@ -60,7 +60,7 @@
     "@eslint/js": "^10.0.1",
     "@types/node": "^26.4.1",
     "@vercel/detect-agent": "1.2.5",
-    "@vitest/coverage-v8": "4.1.11",
+    "@vitest/coverage-v8": "5.0.0",
     "ajv": "8.20.0",
     "commander": "^15.0.0",
     "concurrently": "10.0.5",
@@ -73,7 +73,7 @@
     "tsx": "^4.23.13",
     "typescript": "^6.0.2",
     "typescript-eslint": "^8.69.0",
-    "vitest": "^4.1.11",
+    "vitest": "^5.0.0",
     "yaml": "2.9.0"
   }
 }

package/schemas/result-v3.schema.json

@@ -26,6 +26,7 @@
         "actions",
         "packageManagers",
         "nextSteps",
+        "stack",
         "humanSteps"
       ],
       "properties": {
@@ -48,7 +49,7 @@
           "type": "string"
         },
         "template": {
-          "const": "default"
+          "type": "string"
         },
         "created": {
           "type": "array",
@@ -81,7 +82,7 @@
         "packageManagers": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["javascript", "python"],
+          "required": ["javascript"],
           "properties": {
             "javascript": {
               "enum": ["npm", "pnpm", "bun"]
@@ -97,6 +98,9 @@
             "type": "string"
           }
         },
+        "stack": {
+          "type": "string"
+        },
         "humanSteps": {
           "type": "array",
           "description": "Human prerequisites before running the app. Commands run from projectDirectory. On dry runs these are planned steps after creation, not actions already performed.",

package/schemas/result-v4.schema.json

@@ -0,0 +1,170 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "create-spatius-app result v4",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/success"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "success": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "ok",
+        "command",
+        "dryRun",
+        "generatorVersion",
+        "projectDirectory",
+        "created",
+        "wouldCreate",
+        "actions",
+        "packageManagers",
+        "nextSteps",
+        "stack",
+        "humanSteps"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": 4
+        },
+        "ok": {
+          "const": true
+        },
+        "command": {
+          "const": "create"
+        },
+        "dryRun": {
+          "type": "boolean"
+        },
+        "generatorVersion": {
+          "type": "string"
+        },
+        "projectDirectory": {
+          "type": "string"
+        },
+        "created": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "wouldCreate": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "actions": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["dependenciesInstalled", "gitInitialized", "deployed"],
+          "properties": {
+            "dependenciesInstalled": {
+              "type": "boolean"
+            },
+            "gitInitialized": {
+              "const": false
+            },
+            "deployed": {
+              "const": false
+            }
+          }
+        },
+        "packageManagers": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["javascript"],
+          "properties": {
+            "javascript": {
+              "enum": ["npm", "pnpm", "bun"]
+            },
+            "python": {
+              "enum": ["pip", "uv"]
+            }
+          }
+        },
+        "nextSteps": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "stack": {
+          "type": "string"
+        },
+        "humanSteps": {
+          "type": "array",
+          "description": "Human prerequisites before running the app. Commands run from projectDirectory. On dry runs these are planned steps after creation, not actions already performed.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["command", "reason", "requiresHuman", "requiresTty"],
+            "properties": {
+              "command": {
+                "type": "string"
+              },
+              "reason": {
+                "type": "string"
+              },
+              "requiresHuman": {
+                "const": true
+              },
+              "requiresTty": {
+                "const": true
+              }
+            }
+          }
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "ok", "error"],
+      "properties": {
+        "schemaVersion": {
+          "const": 4
+        },
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["code", "message"],
+          "properties": {
+            "code": {
+              "enum": [
+                "CANCELLED",
+                "FILESYSTEM_ERROR",
+                "INSTALL_FAILED",
+                "INVALID_ARGUMENT",
+                "PACKAGE_MANAGER_NOT_FOUND",
+                "PACKAGE_MANAGER_UNAVAILABLE",
+                "TARGET_NOT_DIRECTORY",
+                "TARGET_NOT_EMPTY",
+                "TEMPLATE_NOT_FOUND",
+                "UNSAFE_TARGET",
+                "UNKNOWN_ERROR"
+              ]
+            },
+            "message": {
+              "type": "string"
+            },
+            "path": {
+              "type": "string"
+            },
+            "recovery": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

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/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

package/templates/cloudflare-livekit/agent/env.example

@@ -6,3 +6,6 @@ LIVEKIT_API_SECRET=your-livekit-api-secret
 # Spatius credentials
 SPATIUS_API_KEY=your-spatius-api-key
 SPATIUS_APP_ID=your-spatius-app-id
+
+# Companion only: public web API origin (local Vite default).
+SPATIUS_API_ORIGIN=http://localhost:5173

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

@@ -25,10 +25,11 @@ load_dotenv(".env.local")
 
 
 class Assistant(Agent):
-    def __init__(self) -> None:
+    def __init__(self, instructions: str | None = None) -> None:
         super().__init__(
             llm=inference.LLM(model="google/gemma-4-31b-it"),
-            instructions=textwrap.dedent(
+            instructions=instructions
+            or textwrap.dedent(
                 """\
                 You are a warm, concise voice assistant speaking through a digital
                 avatar. Help the user directly and conversationally.
@@ -42,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")
@@ -82,8 +84,9 @@ async def spatius_agent(ctx: JobContext) -> None:
     avatar = spatius.AvatarSession(avatar_id=dispatch_metadata.avatar_id)
     await avatar.start(session, room=ctx.room)
 
+    assistant = Assistant()
     await session.start(
-        agent=Assistant(),
+        agent=assistant,
         room=ctx.room,
         room_options=room_io.RoomOptions(
             audio_input=room_io.AudioInputOptions(

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