create-spatius-app 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-spatius-app",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Create a Spatius app with a web frontend, Cloudflare Worker, and LiveKit agent.",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "pnpm@11.1.2",
+  "packageManager": "pnpm@11.25.0",
   "publishConfig": {
     "access": "public",
     "provenance": true

package/templates/cloudflare-livekit/README.md

@@ -34,4 +34,6 @@ a matching voice. This configures local development only, not deployment.
 __SPATIUS_DEV_COMMAND__
 ```
 
-This starts the frontend, Cloudflare Worker, and Python agent together.
+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.

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.7.1",
+  "livekit-agents[spatius]~=1.8.0",
   "livekit-plugins-noise-cancellation~=0.2.6",
   "python-dotenv>=1.2.1,<2",
 ]

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

@@ -1,5 +1,7 @@
 import logging
+import os
 import textwrap
+from pathlib import Path
 
 from dotenv import load_dotenv
 from livekit import rtc
@@ -43,6 +45,14 @@ class Assistant(Agent):
 server = AgentServer()
 
 
+@server.on("worker_registered")
+def report_dev_ready(_worker_id: str, _server_info: object) -> None:
+    # Only the root dev supervisor supplies this per-run path. Registration,
+    # not process launch or the local health endpoint, releases web startup.
+    if ready_file := os.environ.get("SPATIUS_DEV_READY_FILE"):
+        Path(ready_file).touch()
+
+
 @server.rtc_session(agent_name="spatius-agent")
 async def spatius_agent(ctx: JobContext) -> None:
     ctx.log_context_fields = {"room": ctx.room.name}

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

@@ -207,5 +207,26 @@ class AgentStartupTests(unittest.IsolatedAsyncioTestCase):
         )
 
 
+class DevReadinessTests(unittest.TestCase):
+    def test_registration_writes_only_the_supervisors_ready_file(self) -> None:
+        with (
+            patch.dict(
+                "os.environ", {"SPATIUS_DEV_READY_FILE": "/tmp/test-agent-ready"}
+            ),
+            patch.object(agent_module, "Path") as path,
+        ):
+            agent_module.server.emit("worker_registered", "worker-test", object())
+        path.assert_called_once_with("/tmp/test-agent-ready")
+        path.return_value.touch.assert_called_once_with()
+
+    def test_standalone_agent_does_not_write_a_ready_file(self) -> None:
+        with (
+            patch.dict("os.environ", {}, clear=True),
+            patch.object(agent_module, "Path") as path,
+        ):
+            agent_module.server.emit("worker_registered", "worker-test", object())
+        path.assert_not_called()
+
+
 if __name__ == "__main__":
     unittest.main()

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

@@ -777,7 +777,7 @@ wheels = [
 
 [[package]]
 name = "livekit"
-version = "1.1.15"
+version = "1.1.17"
 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/ae/0d/383cb1ff9dd0f5de8e8046f0a83aa37e7d137f47552973395aa17871163e/livekit-1.1.15.tar.gz", hash = "sha256:8fe6d06127cecbe8d56c83b0c09c4604ea33cbab826508785bfd8dea5d5e1a4a", size = 378304, upload-time = "2026-08-24T17:19:00.999Z" }
+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" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/a6/8c/5cd2de868eea3065821a8ecb615b2676f7076db74cea437dd9ee83d98c22/livekit-1.1.15-py3-none-macosx_10_15_x86_64.whl", hash = "sha256:f7e8485bb91d6f74c893ffc8545301e049d5c056f863e1ce72b857ed040db218", size = 10199958, upload-time = "2026-08-24T17:18:50.276Z" },
-    { url = "https://files.pythonhosted.org/packages/48/e0/2027d03398c0b1d57345a040356109b3e49491e679605ae4f42f3ebc1bb9/livekit-1.1.15-py3-none-macosx_11_0_arm64.whl", hash = "sha256:285f3ef28e8ce78d8a9ae909571a67511e55ccaa81e7769822e024036d307f56", size = 9023382, upload-time = "2026-08-24T17:18:52.828Z" },
-    { url = "https://files.pythonhosted.org/packages/a9/a5/72b4bedfc09df365d5e016979815b4791af1ca08781dd99e087626f3d550/livekit-1.1.15-py3-none-manylinux_2_28_aarch64.whl", hash = "sha256:4cb3894030cce1940ef5a6407d6e9d3049eb7150e204bf327fbc37eb903af4d5", size = 10046135, upload-time = "2026-08-24T17:18:54.602Z" },
-    { url = "https://files.pythonhosted.org/packages/72/a4/563813a9282c827363e9add8f24785e65514f04c9d8e04d7ac3ad7a3b5b0/livekit-1.1.15-py3-none-manylinux_2_28_x86_64.whl", hash = "sha256:d0c72f36906f9d46b4c69d28cb39ecd847022e990df77037cbdd4ebf4d8db50c", size = 11449550, upload-time = "2026-08-24T17:18:56.744Z" },
-    { url = "https://files.pythonhosted.org/packages/7c/14/88d9d90144b426e75d9ba6111d623063fae4ac714d36bd61349e8684bd3f/livekit-1.1.15-py3-none-win_amd64.whl", hash = "sha256:4b6027b986ec0abdc57fed0796b6ebb4d03011ada446a77efe158d9c2ed0bb5f", size = 10770308, upload-time = "2026-08-24T17:18:58.875Z" },
+    { 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" },
 ]
 
 [[package]]
 name = "livekit-agents"
-version = "1.7.1"
+version = "1.8.0"
 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/6d/ed/1d6909828103892de4ad94261a682d11f739a91ce0dd656432fab626d20e/livekit_agents-1.7.1.tar.gz", hash = "sha256:89bb7dc3d2b8b28671c846a80cec9265b699ddee805d790ef2d00a5e3129b8dd", size = 2662477, upload-time = "2026-08-27T03:33:39.986Z" }
+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" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/20/33/ec05c835192728f55aa571675912d81c01b423f8f24a98273f148c904e63/livekit_agents-1.7.1-py3-none-any.whl", hash = "sha256:f64ce088f22f115faa3b92448d335569b101d9d96fe6481781fd82f06c413b2e", size = 2777164, upload-time = "2026-08-27T03:33:37.048Z" },
+    { 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" },
 ]
 
 [package.optional-dependencies]
@@ -935,15 +935,15 @@ wheels = [
 
 [[package]]
 name = "livekit-plugins-spatius"
-version = "1.7.1"
+version = "1.8.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "livekit-agents" },
     { name = "spatius", extra = ["opus"] },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/35/9c/99d24076ffc28065a582ae87953d220967c7a816da69257152b93c2fb05b/livekit_plugins_spatius-1.7.1.tar.gz", hash = "sha256:c6239cf47ff87729ae22e1e3b2db8a1d32b16d26b711d530dc09cd0fc525bc25", size = 8601, upload-time = "2026-08-27T03:35:40.562Z" }
+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" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/17/94/5951e01cbd34d73c22e75c8c52471c01be996957ba434288afc851b1421e/livekit_plugins_spatius-1.7.1-py3-none-any.whl", hash = "sha256:59a0e4ca9f80fb81683e3d8fa4e05a212276ad79d478a0a0cb73c57f6655235e", size = 8712, upload-time = "2026-08-27T03:35:39.411Z" },
+    { 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" },
 ]
 
 [[package]]
@@ -1891,7 +1891,7 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "livekit-agents", extras = ["spatius"], specifier = "~=1.7.1" },
+    { name = "livekit-agents", extras = ["spatius"], specifier = "~=1.8.0" },
     { name = "livekit-plugins-noise-cancellation", specifier = "~=0.2.6" },
     { name = "python-dotenv", specifier = ">=1.2.1,<2" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.15,<1" },

package/templates/cloudflare-livekit/npmrc

@@ -1,4 +1 @@
-auto-install-peers=false
-prefer-frozen-lockfile=true
 save-exact=true
-strict-peer-dependencies=true

package/templates/cloudflare-livekit/package.json

@@ -10,7 +10,7 @@
     "cf-typegen": "wrangler types --env-interface CloudflareBindings",
     "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test && pnpm test:dev && pnpm build",
     "deploy": "pnpm build && wrangler deploy",
-    "dev": "concurrently --kill-others --names web,agent \"pnpm run dev:web\" \"pnpm run agent:dev\"",
+    "dev": "node scripts/dev.mjs \"pnpm run dev:web\" \"pnpm run agent:dev\"",
     "dev:web": "node scripts/dev-web.mjs",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -25,7 +25,7 @@
   "engines": {
     "node": ">=22.12"
   },
-  "packageManager": "pnpm@11.1.2",
+  "packageManager": "pnpm@11.25.0",
   "dependencies": {
     "@livekit/components-react": "2.9.24",
     "@spatius/avatarkit": "1.3.8",

package/templates/cloudflare-livekit/scripts/dev-web.mjs

@@ -1,7 +1,19 @@
 import { join } from 'node:path';
 import { projectDirectory } from './agent-runtime.mjs';
+import { waitForAgent } from './wait-for-agent.mjs';
 import { runProcess } from './managed-process.mjs';
 
+try {
+  if (process.env.SPATIUS_DEV_READY_FILE) {
+    console.log('Waiting for the LiveKit agent to register…');
+    await waitForAgent(process.env.SPATIUS_DEV_READY_FILE);
+    console.log('LiveKit agent registered. Starting frontend and Worker…');
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}
+
 const result = await runProcess(
   process.execPath,
   [

package/templates/cloudflare-livekit/scripts/dev.mjs

@@ -0,0 +1,29 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { projectDirectory } from './agent-runtime.mjs';
+import { runProcess } from './managed-process.mjs';
+
+// A fresh directory prevents a previous run or another project from releasing
+// this run's startup gate. Keep it outside the agent's auto-reload watch tree.
+const directory = await mkdtemp(join(tmpdir(), 'spatius-dev-'));
+try {
+  const result = await runProcess(
+    'concurrently',
+    ['--kill-others', '--names', 'web,agent', ...process.argv.slice(2)],
+    {
+      cwd: projectDirectory,
+      env: {
+        ...process.env,
+        SPATIUS_DEV_READY_FILE: join(directory, 'agent-ready'),
+      },
+    },
+  );
+  if (result.failed)
+    console.error(
+      'Could not start development services. Install JavaScript dependencies and try again.',
+    );
+  process.exitCode = result.code;
+} finally {
+  await rm(directory, { recursive: true, force: true });
+}

package/templates/cloudflare-livekit/scripts/wait-for-agent.mjs

@@ -0,0 +1,20 @@
+import { access } from 'node:fs/promises';
+import { performance } from 'node:perf_hooks';
+import { setTimeout as delay } from 'node:timers/promises';
+
+export async function waitForAgent(path, timeout = 60_000) {
+  const deadline = performance.now() + timeout;
+  while (true) {
+    try {
+      await access(path);
+      return;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    if (performance.now() >= deadline)
+      throw new Error(
+        'LiveKit agent did not register within 60 seconds. Check the agent logs, credentials, and network connection, then run dev again.',
+      );
+    await delay(Math.min(100, Math.max(0, deadline - performance.now())));
+  }
+}

package/templates/cloudflare-livekit/tests/dev-fixtures.mjs

@@ -25,7 +25,7 @@ export const credentials = {
 };
 
 const fakeRuntime = `
-import { appendFileSync, existsSync } from 'node:fs';
+import { appendFileSync, existsSync, writeFileSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 const role = process.argv[2];
 const args = process.argv.slice(3);
@@ -57,6 +57,17 @@ if (role === 'lk' && args[0] === '--version') {
 } else if (role === 'grandchild') {
   hold(); ready();
 } else {
+  if (role !== 'web' && process.env.SPATIUS_DEV_READY_FILE && process.env.DEV_TEST_RUNTIME_HOLD === '1') {
+    const register = () => {
+      event('registered');
+      writeFileSync(process.env.SPATIUS_DEV_READY_FILE, '');
+    };
+    if (process.env.DEV_TEST_REGISTER) {
+      const poll = setInterval(() => {
+        if (existsSync(process.env.DEV_TEST_REGISTER)) { clearInterval(poll); register(); }
+      }, 20);
+    } else register();
+  }
   if (process.env.DEV_TEST_GRANDCHILD === '1') {
     spawnGrandchild();
   }

package/templates/cloudflare-livekit/tests/dev-supervision.test.mjs

@@ -37,7 +37,7 @@ async function supervise(f, extraEnv) {
   const sourcePackage = JSON.parse(
     await readFile(join(templateDirectory, 'package.json'), 'utf8'),
   );
-  // Exercise the production script composition with npm, available alongside
+  // Exercise the production startup gate and supervisor with npm, available alongside
   // Node in both generated projects and root CI. Only PM selection changes.
   const scripts = Object.fromEntries(
     ['dev', 'dev:web', 'agent:dev'].map((name) => [
@@ -102,7 +102,7 @@ for (const [name, side, code] of [
   ['agent fails', 'agent', '29'],
 ]) {
   test(
-    `real concurrently: ${name} stops its sibling and all grandchildren`,
+    `root dev supervisor: ${name} stops its sibling and all grandchildren`,
     { timeout: 15000 },
     async (t) => {
       const f = await fixture(t);
@@ -128,12 +128,14 @@ for (const [name, side, code] of [
       assert.match(result.output, /SIGTERM/);
       assertNoCredentials(result.output);
       await assertStopped(events.map(({ pid }) => pid));
+      // A bounded CLI probe may select Python fallback on a busy machine.
+      // Supervision must launch exactly one runtime through either supported path.
       assert.equal(
         (await readEvents(f.events)).filter(
           ({ role, args, type }) =>
-            role === 'lk' &&
+            ['lk', 'uv', 'python'].includes(role) &&
             type === 'invoked' &&
-            args.at(-1) === 'src/agent.py',
+            args.includes('src/agent.py'),
         ).length,
         1,
       );
@@ -142,7 +144,7 @@ for (const [name, side, code] of [
 }
 
 test(
-  'real concurrently: Ctrl+C stops both services and their grandchildren',
+  'root dev supervisor: Ctrl+C stops both services and their grandchildren',
   {
     timeout: 15000,
     skip:
@@ -201,3 +203,104 @@ test(
     assertNoCredentials(result.output);
   },
 );
+
+for (const fallback of [false, true]) {
+  test(
+    `web waits for registration (${fallback ? 'Python fallback' : 'lk'})`,
+    { timeout: 15000 },
+    async (t) => {
+      const f = await fixture(t, { uv: true });
+      const registration = join(f.root, 'register');
+      const run = await supervise(f, {
+        DEV_TEST_RUNTIME_HOLD: '1',
+        DEV_TEST_REGISTER: registration,
+        DEV_TEST_WEB_EXIT: '0',
+        ...(fallback ? { DEV_TEST_VERSION: 'lk version 2.17.0' } : {}),
+      });
+      const before = await waitForEvents(f.events, (events) =>
+        events.some(
+          ({ role, type }) =>
+            role === (fallback ? 'uv' : 'lk') && type === 'ready',
+        ),
+      );
+      await delay(200);
+      assert.ok(
+        !(await readEvents(f.events)).some(({ role }) => role === 'web'),
+      );
+      const readyPath = before.find(({ env }) => env.SPATIUS_DEV_READY_FILE)
+        ?.env.SPATIUS_DEV_READY_FILE;
+      assert.ok(readyPath);
+      await writeFile(registration, 'register');
+      const after = await waitForEvents(f.events, (events) =>
+        events.some(({ role, type }) => role === 'web' && type === 'ready'),
+      );
+      assert.ok(
+        after.findIndex(({ type }) => type === 'registered') <
+          after.findIndex(({ role }) => role === 'web'),
+      );
+      await writeFile(f.env.DEV_TEST_RELEASE, 'exit');
+      const result = await run.done;
+      assert.match(result.output, /LiveKit agent registered/);
+      assertNoCredentials(result.output);
+      await assert.rejects(readFile(readyPath), { code: 'ENOENT' });
+      await assertStopped(after.map(({ pid }) => pid));
+    },
+  );
+}
+
+test(
+  'agent failure before registration never starts web',
+  { timeout: 15000 },
+  async (t) => {
+    const f = await fixture(t);
+    const run = await supervise(f, { DEV_TEST_RUNTIME_EXIT: '29' });
+    const result = await run.done;
+    assert.notEqual(result.code, 0);
+    assert.ok(!(await readEvents(f.events)).some(({ role }) => role === 'web'));
+    assertNoCredentials(result.output);
+  },
+);
+
+test(
+  'registration timeout stops the agent without starting web',
+  { timeout: 15000 },
+  async (t) => {
+    const f = await fixture(t);
+    // Accelerate only the copied fixture's deadline; exercise the real web gate.
+    const path = join(f.root, 'scripts', 'wait-for-agent.mjs');
+    await writeFile(
+      path,
+      (await readFile(path, 'utf8')).replace('60_000', '1500'),
+    );
+    const run = await supervise(f, {
+      DEV_TEST_RUNTIME_HOLD: '1',
+      DEV_TEST_REGISTER: join(f.root, 'never-register'),
+    });
+    const result = await run.done;
+    assert.notEqual(result.code, 0);
+    assert.match(result.output, /LiveKit agent did not register/);
+    const events = await readEvents(f.events);
+    assert.ok(!events.some(({ role }) => role === 'web'));
+    await assertStopped(events.map(({ pid }) => pid));
+    assertNoCredentials(result.output);
+  },
+);
+
+test(
+  'Ctrl+C while waiting for registration stops the agent without starting web',
+  { timeout: 15000, skip: windows },
+  async (t) => {
+    const f = await fixture(t);
+    const run = await supervise(f, {
+      DEV_TEST_RUNTIME_HOLD: '1',
+      DEV_TEST_REGISTER: join(f.root, 'never-register'),
+    });
+    const events = await waitForEvents(f.events, (events) =>
+      events.some(({ role, type }) => role === 'lk' && type === 'ready'),
+    );
+    process.kill(-run.child.pid, 'SIGINT');
+    await run.done;
+    assert.ok(!(await readEvents(f.events)).some(({ role }) => role === 'web'));
+    await assertStopped(events.map(({ pid }) => pid));
+  },
+);