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

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

@@ -54,7 +54,7 @@ if (role === 'lk' && args[0] === '--version') {
 } else if (role === 'lk' && args.includes('--help')) {
   if (process.env.DEV_TEST_PROBE === 'help-hang') { hold(); ready(); }
   else { console.log(process.env.DEV_TEST_HELP ?? 'NAME: lk agent dev\\nUSAGE: lk agent dev [entrypoint]'); process.exit(Number(process.env.DEV_TEST_HELP_EXIT ?? 0)); }
-} else if (role === 'grandchild') {
+} else if (role === 'grandchild' || role === 'api') {
   hold(); ready();
 } else {
   if (role !== 'web' && process.env.SPATIUS_DEV_READY_FILE && process.env.DEV_TEST_RUNTIME_HOLD === '1') {
@@ -129,6 +129,7 @@ export async function fixture(
     await writeFile(path, body, { mode: 0o755 });
     return path;
   };
+  await executable('tsx', bin, 'api');
   if (lk) await executable('lk');
   if (uv) await executable('uv');
   if (python) {
@@ -206,8 +207,11 @@ export async function fixture(
 }
 
 export async function readEvents(path) {
-  return (await readFile(path, 'utf8'))
-    .trim()
+  // A concurrent append can be visible before its terminating newline.
+  // Parse only complete records; the next poll will read the finished tail.
+  const contents = await readFile(path, 'utf8');
+  return contents
+    .slice(0, contents.lastIndexOf('\n') + 1)
     .split('\n')
     .filter(Boolean)
     .map((line) => JSON.parse(line));

package/templates/cloudflare-livekit/tsconfig.web.json

@@ -2,6 +2,7 @@
   "compilerOptions": {
     "paths": { "@/*": ["./web/*"] },
     "composite": true,
+    "resolveJsonModule": true,
     "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.web.tsbuildinfo",
     "target": "ES2023",
     "useDefineForClassFields": true,

package/templates/cloudflare-livekit/tsconfig.worker.json

@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
     "composite": true,
+    "resolveJsonModule": true,
     "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.worker.tsbuildinfo",
     "target": "ES2023",
     "lib": ["ES2023", "WebWorker"],

package/templates/cloudflare-livekit/web/api.ts

@@ -1,4 +1,5 @@
 export interface VoiceSession {
+  session_capability?: string;
   participant_token: string;
   room_name: string;
   server_url: string;
@@ -67,3 +68,14 @@ export async function requestVoiceSession(
   }
   return payload;
 }
+
+export async function stopVoiceSession(capability?: string): Promise<void> {
+  if (!capability) return;
+  const response = await fetch('/api/session/stop', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ capability }),
+    keepalive: true,
+  });
+  if (!response.ok) throw new Error('Session cleanup failed');
+}

package/templates/cloudflare-livekit/web/components/agents-ui/agent-chat-transcript.tsx

@@ -1,14 +1,10 @@
 // Copyright LiveKit. Apache-2.0. Adapted from Agents UI; see ./PROVENANCE.md.
-import { useLayoutEffect, useRef, useState } from 'react';
-import type { AgentState, ReceivedMessage } from '@livekit/components-react';
-export type TranscriptMessage = Pick<
-  ReceivedMessage,
-  'id' | 'timestamp' | 'message'
-> & {
-  isUser: boolean;
-  source?: 'user' | 'agent' | 'avatar';
-  senderIdentity?: string;
-};
+import type { ReceivedMessage } from '@livekit/components-react';
+import type { TranscriptMessage } from '../transcript-view.js';
+export {
+  AgentChatTranscript,
+  type TranscriptMessage,
+} from '../transcript-view.js';
 export type ConversationParticipants = {
   agentIdentity?: string;
   avatarIdentity?: string;
@@ -63,83 +59,3 @@ export function snapshotMessages(
     ];
   });
 }
-export function AgentChatTranscript({
-  messages = [],
-  agentState,
-  agentName = 'Agent',
-}: {
-  messages?: readonly TranscriptMessage[];
-  agentState?: AgentState;
-  agentName?: string;
-}) {
-  const viewport = useRef<HTMLDivElement>(null);
-  const atBottom = useRef(true);
-  const [showLatest, setShowLatest] = useState(false);
-  const scrollToLatest = () => {
-    const element = viewport.current;
-    if (element) element.scrollTop = element.scrollHeight;
-    atBottom.current = true;
-    setShowLatest(false);
-  };
-  useLayoutEffect(() => {
-    if (atBottom.current) scrollToLatest();
-    else setShowLatest(true);
-  }, [messages, agentState]);
-  return (
-    <div className="transcript-container">
-      <div
-        ref={viewport}
-        className="transcript-scroll"
-        role="log"
-        aria-label="Conversation transcript"
-        aria-live="polite"
-        onScroll={(event) => {
-          const element = event.currentTarget;
-          atBottom.current =
-            element.scrollHeight - element.scrollTop - element.clientHeight <
-            48;
-          if (atBottom.current) setShowLatest(false);
-        }}
-      >
-        {messages.length === 0 && (
-          <p className="transcript-empty">
-            Your conversation will appear here as you speak or type.
-          </p>
-        )}
-        {messages.map(({ id, timestamp, isUser, message, source }) => (
-          <article
-            key={id}
-            className="transcript-message"
-            data-speaker={isUser ? 'user' : 'agent'}
-            data-source={source}
-          >
-            <div className="message-meta">
-              <span>{isUser ? 'You' : agentName}</span>
-              <time dateTime={new Date(timestamp).toISOString()}>
-                {new Date(timestamp).toLocaleTimeString([], {
-                  hour: '2-digit',
-                  minute: '2-digit',
-                })}
-              </time>
-            </div>
-            <p>{message}</p>
-          </article>
-        ))}
-        {agentState === 'thinking' && (
-          <p className="thinking-indicator" role="status">
-            Thinking<span aria-hidden="true">…</span>
-          </p>
-        )}
-      </div>
-      {showLatest && (
-        <button
-          className="jump-to-latest"
-          type="button"
-          onClick={scrollToLatest}
-        >
-          Latest messages ↓
-        </button>
-      )}
-    </div>
-  );
-}

package/templates/cloudflare-livekit/web/components/transcript-view.tsx

@@ -0,0 +1,90 @@
+// Copyright LiveKit. Apache-2.0. Adapted from Agents UI; see agents-ui/PROVENANCE.md.
+import { useLayoutEffect, useRef, useState } from 'react';
+export interface TranscriptMessage {
+  id: string;
+  timestamp: number;
+  message: string;
+  isUser: boolean;
+  source?: 'user' | 'agent' | 'avatar';
+  senderIdentity?: string;
+}
+export function AgentChatTranscript({
+  messages = [],
+  agentState,
+  agentName = 'Agent',
+}: {
+  messages?: readonly TranscriptMessage[];
+  agentState?: string;
+  agentName?: string;
+}) {
+  const viewport = useRef<HTMLDivElement>(null);
+  const atBottom = useRef(true);
+  const [showLatest, setShowLatest] = useState(false);
+  const scrollToLatest = () => {
+    const element = viewport.current;
+    if (element) element.scrollTop = element.scrollHeight;
+    atBottom.current = true;
+    setShowLatest(false);
+  };
+  useLayoutEffect(() => {
+    if (atBottom.current) scrollToLatest();
+    else setShowLatest(true);
+  }, [messages, agentState]);
+  return (
+    <div className="transcript-container">
+      <div
+        ref={viewport}
+        className="transcript-scroll"
+        role="log"
+        aria-label="Conversation transcript"
+        aria-live="polite"
+        onScroll={(event) => {
+          const element = event.currentTarget;
+          atBottom.current =
+            element.scrollHeight - element.scrollTop - element.clientHeight <
+            48;
+          if (atBottom.current) setShowLatest(false);
+        }}
+      >
+        {messages.length === 0 && (
+          <p className="transcript-empty">
+            Your conversation will appear here as you speak or type.
+          </p>
+        )}
+        {messages.map(({ id, timestamp, isUser, message, source }) => (
+          <article
+            key={id}
+            className="transcript-message"
+            data-speaker={isUser ? 'user' : 'agent'}
+            data-source={source}
+          >
+            <div className="message-meta">
+              <span>{isUser ? 'You' : agentName}</span>
+              <time dateTime={new Date(timestamp).toISOString()}>
+                {new Date(timestamp).toLocaleTimeString([], {
+                  hour: '2-digit',
+                  minute: '2-digit',
+                })}
+              </time>
+            </div>
+            <p>{message}</p>
+          </article>
+        ))}
+        {agentState === 'thinking' && (
+          <p className="thinking-indicator" role="status">
+            Thinking<span aria-hidden="true">…</span>
+          </p>
+        )}
+      </div>
+      {showLatest && (
+        <button
+          className="jump-to-latest"
+          type="button"
+          onClick={scrollToLatest}
+        >
+          Latest messages ↓
+        </button>
+      )}
+    </div>
+  );
+}

package/templates/cloudflare-livekit/web/session-attempt.ts

@@ -1,5 +1,9 @@
 import { Room, TokenSource, Track } from 'livekit-client';
-import { requestVoiceSession, type VoiceSession } from './api.js';
+import {
+  requestVoiceSession,
+  stopVoiceSession,
+  type VoiceSession,
+} from './api.js';
 import type { AvatarSessionController } from './avatar-session.js';
 
 export type PreparedSession = {
@@ -30,6 +34,16 @@ export class SessionAttempt {
   stage: 'bootstrap' | 'avatar' = 'bootstrap';
   readonly room: Room;
   readonly abort = new AbortController();
+  private capability?: string;
+  private readonly unload = () => {
+    if (this.capability)
+      navigator.sendBeacon?.(
+        '/api/session/stop',
+        new Blob([JSON.stringify({ capability: this.capability })], {
+          type: 'application/json',
+        }),
+      );
+  };
   private avatar?: AvatarSessionController;
   private disposal?: Promise<void>;
   constructor(private readonly deps: AttemptDependencies = dependencies) {
@@ -41,7 +55,12 @@ export class SessionAttempt {
   ): Promise<PreparedSession> {
     const { signal } = this.abort;
     const credentials = await this.deps.request(signal);
-    signal.throwIfAborted();
+    this.capability = credentials.session_capability;
+    if (signal.aborted) {
+      await stopVoiceSession(this.capability).catch(() => undefined);
+      signal.throwIfAborted();
+    }
+    globalThis.window?.addEventListener('pagehide', this.unload);
     // Warm LiveKit's region selection and connection while the avatar loads.
     // This does not join the room or acquire media; attach must still finish
     // before useSession starts the connection. A failed warmup is non-fatal.
@@ -100,7 +119,9 @@ export class SessionAttempt {
   dispose(): Promise<void> {
     this.abort.abort();
     this.disposal ??= (async () => {
+      globalThis.window?.removeEventListener('pagehide', this.unload);
       await Promise.allSettled([
+        stopVoiceSession(this.capability),
         this.room.disconnect(true),
         this.avatar?.dispose() ?? Promise.resolve(),
       ]);

package/templates/cloudflare-livekit/worker/capability.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it, vi } from 'vitest';
+import { signCapability, verifyCapability } from './capability.js';
+describe('session capabilities', () => {
+  it('binds purpose and expiry and rejects tampering', async () => {
+    const secret = 'test-only-signing-key';
+    const token = await signCapability(
+      secret,
+      { purpose: 'session', room: 'one' },
+      10,
+    );
+    expect(await verifyCapability(secret, token, 'session')).toMatchObject({
+      room: 'one',
+    });
+    await expect(verifyCapability(secret, token, 'memory')).rejects.toThrow();
+    await expect(
+      verifyCapability(secret, token + 'x', 'session'),
+    ).rejects.toThrow();
+    await expect(
+      verifyCapability('different-key', token, 'session'),
+    ).rejects.toThrow();
+    vi.useFakeTimers();
+    try {
+      vi.setSystemTime(Date.now() + 20000);
+      await expect(verifyCapability(secret, token, 'session')).rejects.toThrow(
+        'Expired',
+      );
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/templates/cloudflare-livekit/worker/capability.ts

@@ -0,0 +1,72 @@
+const encoder = new TextEncoder();
+function encode(value: Uint8Array): string {
+  return btoa(String.fromCharCode(...value))
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replaceAll('=', '');
+}
+function decode(value: string): Uint8Array<ArrayBuffer> {
+  return Uint8Array.from(
+    atob(value.replaceAll('-', '+').replaceAll('_', '/')),
+    (character) => character.charCodeAt(0),
+  );
+}
+async function key(secret: string) {
+  if (!secret) throw new Error('Session signing secret is missing');
+  return crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign', 'verify'],
+  );
+}
+export async function signCapability(
+  secret: string,
+  claims: Record<string, unknown>,
+  seconds = 3600,
+): Promise<string> {
+  const payload = encode(
+    encoder.encode(
+      JSON.stringify({
+        ...claims,
+        exp: Math.floor(Date.now() / 1000) + seconds,
+      }),
+    ),
+  );
+  const signature = await crypto.subtle.sign(
+    'HMAC',
+    await key(secret),
+    encoder.encode(payload),
+  );
+  return `${payload}.${encode(new Uint8Array(signature))}`;
+}
+export async function verifyCapability(
+  secret: string,
+  token: string,
+  purpose: string,
+): Promise<Record<string, unknown>> {
+  if (typeof token !== 'string' || token.length > 8192)
+    throw new Error('Invalid session authorization');
+  const parts = token.split('.');
+  if (
+    parts.length !== 2 ||
+    !(await crypto.subtle.verify(
+      'HMAC',
+      await key(secret),
+      decode(parts[1]),
+      encoder.encode(parts[0]),
+    ))
+  )
+    throw new Error('Invalid session authorization');
+  const value = JSON.parse(
+    new TextDecoder().decode(decode(parts[0])),
+  ) as Record<string, unknown>;
+  if (
+    value.purpose !== purpose ||
+    typeof value.exp !== 'number' ||
+    value.exp <= Date.now() / 1000
+  )
+    throw new Error('Expired session authorization');
+  return value;
+}

package/templates/cloudflare-livekit/worker/index.test.ts

@@ -30,7 +30,7 @@ describe('createSession', () => {
       ) as {
         roomConfig: { agents: Array<{ metadata: string }> };
       };
-      expect(JSON.parse(payload.roomConfig.agents[0].metadata)).toEqual({
+      expect(JSON.parse(payload.roomConfig.agents[0].metadata)).toMatchObject({
         version: 1,
         avatar: { id: TEST_ENV.SPATIUS_AVATAR_ID },
         voice: { id: voiceId },
@@ -145,7 +145,7 @@ describe('Worker routes', () => {
     expect(response.status).toBe(503);
     await expect(response.json()).resolves.toEqual({
       error:
-        'The voice session service is not configured. Check the Worker environment.',
+        'The voice session service is not configured. Check the server environment.',
     });
     consoleError.mockRestore();
   });

package/templates/cloudflare-livekit/worker/index.ts

@@ -1,4 +1,4 @@
-import { ConfigurationError, createSession } from './session.js';
+import { ConfigurationError, createSession, stopSession } from './session.js';
 
 const JSON_HEADERS = {
   'cache-control': 'no-store',
@@ -26,6 +26,18 @@ export async function handleRequest(
     return json({ ok: true });
   }
 
+  if (url.pathname === '/api/session/stop') {
+    if (request.method !== 'POST')
+      return json({ error: 'Method not allowed.' }, 405);
+    try {
+      const body: { capability?: string } = await request.json();
+      await stopSession(env, body.capability ?? '');
+      return json({ ok: true });
+    } catch {
+      return json({ error: 'Could not stop this session.' }, 403);
+    }
+  }
+
   if (url.pathname === '/api/session') {
     if (request.method !== 'POST') {
       return json({ error: 'Method not allowed.' }, 405);
@@ -42,13 +54,13 @@ export async function handleRequest(
         return json(
           {
             error:
-              'The voice session service is not configured. Check the Worker environment.',
+              'The voice session service is not configured. Check the server environment.',
           },
           503,
         );
       }
 
-      console.error('Could not create a voice session:', error);
+      console.error('Could not create a voice session.');
       return json({ error: 'Could not create a voice session.' }, 500);
     }
   }

package/templates/cloudflare-livekit/worker/session.ts

@@ -1,9 +1,11 @@
 import {
   AccessToken,
+  RoomServiceClient,
   RoomAgentDispatch,
   RoomConfiguration,
 } from 'livekit-server-sdk';
 
+import { signCapability, verifyCapability } from './capability.js';
 import { serializeAgentDispatchMetadata } from './dispatch-metadata.js';
 
 const TOKEN_TTL = '10m';
@@ -17,6 +19,7 @@ const REQUIRED_ENVIRONMENT_KEYS = [
 ] as const;
 
 export interface SessionResponse {
+  session_capability?: string;
   participant_token: string;
   room_name: string;
   server_url: string;
@@ -91,6 +94,10 @@ export async function createSession(
   });
 
   return {
+    session_capability: await signCapability(env.LIVEKIT_API_SECRET, {
+      purpose: 'session',
+      room: roomName,
+    }),
     participant_token: await accessToken.toJwt(),
     room_name: roomName,
     server_url: env.LIVEKIT_URL,
@@ -101,3 +108,30 @@ export async function createSession(
       : {}),
   };
 }
+
+export async function stopSession(
+  env: CloudflareBindings,
+  token: string,
+): Promise<void> {
+  const claims = await verifyCapability(
+    env.LIVEKIT_API_SECRET,
+    token,
+    'session',
+  );
+  if (typeof claims.room !== 'string') throw new Error('Invalid room');
+  const rooms = new RoomServiceClient(
+    env.LIVEKIT_URL.replace(/^wss:/, 'https:'),
+    env.LIVEKIT_API_KEY,
+    env.LIVEKIT_API_SECRET,
+  );
+  try {
+    await rooms.deleteRoom(claims.room);
+  } catch (error) {
+    if (!(
+      error instanceof Error &&
+      'code' in error &&
+      error.code === 'not_found'
+    ))
+      throw error;
+  }
+}

package/templates/layers/agora/AGENTS.md

@@ -0,0 +1,8 @@
+# Generated Agora application
+
+Use `__DEV__` for local development and `__CHECK__` for verification.
+The Node backend calls hosted Conversational AI over HTTP; do not add a Python
+worker. Browser audio uses Agora RTC, text input and transcripts use the official
+Agora client toolkit. Spatius renders the avatar locally.
+Keep secrets in .env.local or deployment environment variables. Preserve session
+cleanup on disconnect and failed startup. See DEPLOYMENT.md for Zeabur setup.

package/templates/layers/agora/README.md

@@ -0,0 +1,19 @@
+# Spatius voice assistant — Zeabur + Agora
+
+A minimal React avatar conversation with an HTTP backend and Agora Conversational AI.
+Requires Node.js 22.12+, an Agora project with Conversational AI and RTM enabled,
+a published English assistant pipeline, and Spatius credentials. No Python is needed.
+
+```sh
+__INSTALL__
+npx create-spatius-app setup . --interactive
+__DEV__
+```
+
+Open the Vite URL, start a conversation, and speak or type. Microphone permission
+is optional: typed messages go to the model through Agora RTM. The transcript
+stays visible after disconnecting. Configure the assistant persona, speech
+recognition language, model, and voice in the published Agora pipeline. Match
+AGORA_AVATAR_SAMPLE_RATE to that pipeline's TTS output.
+
+See DEPLOYMENT.md to deploy the frontend and API together to Zeabur.

package/templates/layers/agora/env.example

@@ -0,0 +1,9 @@
+AGORA_APP_ID=your-agora-app-id
+AGORA_APP_CERTIFICATE=your-agora-app-certificate
+AGORA_PIPELINE_ID=your-published-pipeline-id
+SPATIUS_APP_ID=your-spatius-app-id
+SPATIUS_API_KEY=your-spatius-api-key
+SPATIUS_AVATAR_ID=your-spatius-avatar-id
+SPATIUS_REGION=cn-beijing
+# Must match the published pipeline's TTS output.
+AGORA_AVATAR_SAMPLE_RATE=24000