@jskit-ai/assistant-voice 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+# Assistant voice
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Optional duplex voice for Vue 3/Vuetify applications. One shell controller owns
+microphone, playback, active destination and modal. Applications retain their
+conversations, permissions, message admission and history. No Vibe64 or Genesis
+runtime is required.
+
+Install `@jskit-ai/assistant-voice` with Vue and Vuetify. Run your own speech
+service, or use `@jskit-ai/assistant-voice-sherpa` for local native inference.
+The native engine and model downloads are not dependencies of this package.
+
+## Supplied conversation integration
+
+For ordinary conversations, use `AssistantConversationClientElement` from
+`@jskit-ai/assistant-runtime/client` with the common conversation runtime. Its
+`composer-tools` slot supplies the retained runtime used by the five-chat
+`examples/conversation/` starter. That example forwards voice text and Stop through
+`runtime.send()` and `runtime.cancel()`, retains the same reader when text closes,
+and uses `projectConversationVoiceState` for canonical speech presentation.
+Application code supplies the speech endpoint, label and navigation. It needs no
+engine-specific imports, separate transcript or conversation connection.
+
+### Custom conversation bindings
+
+Applications with an existing authorized reader can supply the following binding.
+Create one controller above routed screens, then mount `VoiceConversationHost`
+once within your application's Vuetify app:
+
+```js
+import { createVoiceConversationController } from '@jskit-ai/assistant-voice/client';
+
+const controller = createVoiceConversationController({
+  connectSpeech: conversation => `/api/conversations/${conversation.id}/voice`
+});
+
+await controller.open({ conversation: {
+  id: conversationId,
+  label: 'Planning',
+  get state() { return store.conversations[conversationId]; },
+  get available() { return store.canUse(conversationId); },
+  captureContext: () => ({ conversationId }),
+  submitText: (text, { messageId, context }) =>
+    store.send(context.conversationId, { text, messageId }),
+  cancelWork: () => store.stop(conversationId)
+} });
+```
+
+```vue
+<VoiceConversationHost :controller="controller" />
+```
+
+`state` contains `messages`, optional `streamingReply`, and `status` (`working`
+while the agent runs). Messages have stable `id`, `role` and `text`. A streamed
+reply and its saved replacement must share the same ID. Only user/assistant
+content belongs here; exclude reasoning, tools and private operational output.
+
+`submitText` resolves on canonical acceptance and rejects failures. Preserve its
+message ID on uncertain retries and deduplicate in your existing server admission.
+The recording's captured context remains fixed across navigation. Update state
+from your ordinary reader; voice never owns or reconstructs saved history.
+
+Optional `openText()` opens the application's text conversation. When supplied,
+the shared modal shows Talk and Text controls at the top. Selecting Text calls
+that operation and minimizes voice; capture and playback keep their current state.
+Applications may open voice as their default conversation view without starting
+the microphone.
+
+Optional synchronous `retain()` / `release()` keep the conversation reader alive
+outside its screen. `available = false` releases the active voice session. Dispose
+the controller on app teardown or identity replacement. IDs must include the
+identity scope when different people can use the same conversation ID.
+
+Optional defaults: `mode` (`push-to-talk` or `hands-free`), `talkMode` (`tap` or
+`hold` for one-off recording), `reviewBeforeSend`, and an installed `voiceId`.
+One-off recordings started through `startHeldRecording()` require review; the
+modal's push-to-talk gesture uses `reviewBeforeSend`. `avatar` and `onVisual`/`onTranscript`
+allow presentation in the surrounding app without adding another audio owner.
+The host's `avatar` slot receives state, mouthLevel, mouthPose, avatar and binding.
+`useVoiceAvatar` supplies shared animation cues; applications may supply artwork.
+
+## Lifecycle
+
+Opening a target does not start capture. Tap Talk for hands-free, or hold it for
+push-to-talk and release to send; connection setup is automatic.
+Pause finishes the current utterance, flushing the audio tail before muting.
+Completed words follow the captured review policy; resume opens a fresh recording.
+Automatic sends keep the call layout fixed. A failed send exposes the retained
+transcript for review and retry with the same message identity. Captions,
+review, explicit microphone/sound controls and bounded reconnection share one
+session. Opening the same ID reveals it. Switching targets releases the previous
+audio first; unfinished words require completion or explicit discard. A pending
+send cannot be switched away by the discard action. `minimize()` preserves the
+session; `end()` releases it after pending words are resolved. `dispose()` releases
+it unconditionally. The controller serializes these operations. The host's X calls `end({ discard: true })`,
+so closing stops voice and discards unsent speech. Minus minimizes instead.
+
+`ConversationDialog` provides the same fixed header, icon tabs and bounds for
+application Text views, with full screen below 600 pixels and no mode transition.
+The backdrop also stays constant during a mode change. The host and shared dialog
+accept an optional `activator` DOM element: clicking that covered launcher
+minimizes an open conversation instead of closing it.
+The host's `reopen` slot lets an application replace the floating reopen control
+with its own header indicator and `controller.reveal()` action.
+
+Stop speaking cancels playback and queued speech. Stop agent work calls the app's
+separate cancellation operation. Reconnect does not resend audio or messages,
+replay history or automatically restart capture. If a service advertises several
+voices, the Voice settings cog offers Speaking voice for the next reply's speaker; an in-flight reply keeps
+its original speaker through all streamed phrases.
+
+## Server connection
+
+Register an authenticated WebSocket route with Fastify's WebSocket plugin:
+
+```js
+import { registerVoiceProxyRoute, resolveVoiceProxyConfig }
+  from '@jskit-ai/assistant-voice/server';
+
+registerVoiceProxyRoute(fastify, {
+  route: '/api/conversations/:id/voice',
+  proxyConfig: resolveVoiceProxyConfig({ endpoint, accessTokenFile }),
+  async authorize(request) {
+    await checkOrigin(request);
+    await requireConversationAccess(request.user, request.params.id);
+  }
+});
+```
+
+The route's authorization is mandatory and runs before upstream connection.
+Keep endpoint and token file server-side. The token grants speech-service use,
+not access to a conversation or permission to run an agent. Browsers need a secure
+origin (HTTPS or a browser-recognized localhost origin) and microphone permission.
+
+`createVoiceDaemon({ engine, accessKey, ... })` runs the bounded protocol service.
+The engine supplies a recognizer, asynchronous synthesis and optionally a public
+voice catalogue. A host may supply synchronous `authorize(token)` and
+`handleRequest(request, response)` for its own grant policy. An authorized
+principal has `tenant` and optional `parentTenant`; both connection quotas apply.
+`revokeTenant(id)` ends current child or parent sessions as well as pending work.
+The host must reject future requests for revoked grants in its authorizer.
+
+## Example and testing
+
+`examples/conversation/` composes the supplied conversation server integration,
+client binding and one shared realtime connection for five file-backed chats.
+Text and voice retain the same conversation; an optional headless task uses the
+same runtime directly. Its README covers packed-package setup, launch and the
+local origin policy. No Vibe64, Genesis or database runtime is required.
+
+Focused package checks run one file at a time, for example:
+`npm test --workspace packages/assistant-voice -- test/voiceController.test.js`.
+Native speech and physical microphone/speaker testing are separate. Browser echo
+cancellation plus local text filters cannot guarantee acoustic isolation on every
+device; test hands-free interruption with your actual hardware.
+
+### Application-owned voice preferences
+
+`VoiceConversationHost` has an optional `settings` slot for an application-owned
+selector. Persist the voice choice in your application, then supply its current
+value through reactive `binding.defaults.voiceId`. Changes apply to subsequent
+replies. An unavailable ID uses the server default without rewriting the saved
+choice; reconnecting can restore it if the voice returns. An empty string selects
+the server default. The built-in selector remains local to the voice session.
+
+`readVoiceCatalogue(proxyConfig)` from `/server` retrieves the daemon's authorized
+`GET /voices` metadata without reserving an audio connection. Expose it only
+through an application-authorized route; credentials stay on the server. The
+result contains `voices` (IDs, labels and optional languages) and `defaultVoice`,
+matching the WebSocket greeting. Listing voices does not synthesize or load
+additional voice models.

package/examples/conversation/App.vue

@@ -0,0 +1,94 @@
+<script setup>
+import { inject, nextTick, onScopeDispose, ref } from "vue";
+import { createVoiceConversationController, projectConversationVoiceState, VoiceConversationHost } from "@jskit-ai/assistant-voice/client";
+import { ShellErrorHost } from "@jskit-ai/shell-web/client";
+import Conversation from "./Conversation.vue";
+
+const example = inject("example.application");
+const closed = ref([]);
+const views = new Map();
+const error = ref("");
+const controller = createVoiceConversationController({ connectSpeech: binding => binding.socketUrl });
+async function openText(id) {
+  closed.value = closed.value.filter(value => value !== id);
+  await nextTick();
+  views.get(id)?.focus();
+}
+function voiceBinding(runtime, label) {
+  const identity = runtime.identity;
+  let retained;
+  return {
+    id: JSON.stringify([identity.actorKey, identity.conversationId]), label,
+    socketUrl: `/api/conversations/${encodeURIComponent(identity.conversationId)}/voice`,
+    get state() { return projectConversationVoiceState({ turns: runtime.turns.value, status: runtime.snapshot.value?.status }); },
+    get available() { return runtime.available.value; },
+    captureContext: () => ({ ...identity }),
+    retain() { retained = runtime.retain(); runtime = retained.runtime; },
+    release() { retained?.release(); retained = null; },
+    submitText(text, { messageId, context } = {}) {
+      if (context?.actorKey !== identity.actorKey || context?.conversationId !== identity.conversationId) {
+        throw new Error("This recording belongs to another conversation.");
+      }
+      return runtime.send({ message: text }, { messageId });
+    },
+    cancelWork: () => runtime.cancel(),
+    openText: () => openText(identity.conversationId)
+  };
+}
+async function openVoice(runtime, label) {
+  try { await controller.open({ conversation: voiceBinding(runtime, label) }); error.value = ""; }
+  catch (cause) { error.value = cause.message; }
+}
+onScopeDispose(() => { void controller.dispose(); });
+</script>
+
+<template>
+  <v-app>
+    <main class="example">
+      <h1>Voice conversations</h1>
+      <p>{{ example.provider }}</p>
+      <p>Each chat has its own history and controls. Voice keeps its original target when you close or focus another text view.</p>
+      <nav aria-label="Open a text conversation" class="example__navigation">
+        <v-btn
+          v-for="conversation in example.conversations" :key="conversation.id" variant="tonal"
+          @click="openText(conversation.id)"
+        >
+          {{ conversation.label }}
+        </v-btn>
+      </nav>
+      <p v-if="error" role="alert">{{ error }}</p>
+      <div class="example__grid">
+        <section
+          v-for="conversation in example.conversations.filter(value => !closed.includes(value.id))"
+          :key="conversation.id" :aria-label="`${conversation.label} chat`" class="example__card"
+        >
+          <header>
+            <h2>{{ conversation.label }}</h2>
+            <v-btn
+              size="small" variant="text" :aria-label="`Close ${conversation.label} text view`"
+              @click="closed.push(conversation.id)"
+            >
+              Close text
+            </v-btn>
+          </header>
+          <Conversation
+            :ref="value => value ? views.set(conversation.id, value) : views.delete(conversation.id)"
+            :id="conversation.id" :label="conversation.label" @voice="runtime => openVoice(runtime, conversation.label)"
+          />
+        </section>
+      </div>
+    </main>
+    <VoiceConversationHost :controller="controller" />
+    <ShellErrorHost />
+  </v-app>
+</template>
+
+<style scoped>
+.example { width: min(100% - 32px, 1500px); margin: 24px auto; }
+p { margin-block: 12px; }
+.example__navigation { display: flex; gap: 8px; flex-wrap: wrap; margin-bottom: 16px; }
+.example__grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 400px), 1fr)); gap: 16px; }
+.example__card { display: flex; flex-direction: column; min-width: 0; height: min(720px, 85dvh); padding: 12px; border: 1px solid rgb(var(--v-theme-outline)); border-radius: 12px; }
+header { display: flex; align-items: center; justify-content: space-between; gap: 8px; margin-bottom: 8px; }
+h2 { font-size: 1.1rem; }
+</style>

package/examples/conversation/Conversation.vue

@@ -0,0 +1,28 @@
+<script setup>
+import { ref } from "vue";
+import { AssistantConversationClientElement } from "@jskit-ai/assistant-runtime/client";
+
+defineProps({ id: { type: String, required: true }, label: { type: String, required: true } });
+const emit = defineEmits(["voice"]);
+const view = ref(null);
+defineExpose({ focus: () => view.value?.focus() });
+</script>
+
+<template>
+  <AssistantConversationClientElement
+    ref="view" :conversation-id="id" :assistant-label="label" class="example-conversation"
+  >
+    <template #composer-tools="{ runtime }">
+      <v-btn
+        size="small" variant="text" :disabled="!runtime?.available.value"
+        @click="emit('voice', runtime)"
+      >
+        Voice chat with {{ label }}
+      </v-btn>
+    </template>
+  </AssistantConversationClientElement>
+</template>
+
+<style scoped>
+.example-conversation { height: 100%; min-height: 0; }
+</style>

package/examples/conversation/README.md

@@ -0,0 +1,181 @@
+# Independent voice conversation example
+
+This Vue/Vuetify and Fastify application uses the supplied JSKIT conversation
+server integration, client binding and shared realtime connection. Planning,
+Notes, Research, Writing and Review have separate file-backed histories. One
+root voice modal retains its target independently of mounted text cards.
+Vibe64, Genesis and a database are not required.
+
+## Install and start
+
+Use a coordinated set of packed packages containing the conversation integration
+changes. The migration source and existing package numbers alone are not a fresh
+installation proof; candidate verification records the exact archives and pins.
+The application imports public package entrypoints only, with no source aliases.
+Its Vite configuration uses JSKIT's supplied client plugin for installed-package
+dependency scanning and shared client dependencies.
+
+1. Run `npm install` in this directory using that candidate's package versions.
+2. Copy `integrations.example.json` to your own configuration file. Choose a model
+   key from the existing JSKIT AI catalogue. Set the referenced `ASSISTANT_API_KEY`
+   in the server environment using your secret manager or protected shell session.
+   Keep the key out of JSON configuration and browser environment variables.
+3. For voice, prepare a speech service using the assistant-voice-sherpa README,
+   or obtain a speech endpoint and application token from its operator. Supply
+   its endpoint and protected tenant token file to this example's server.
+4. Start the server with your protected configuration paths:
+
+```sh
+ASSISTANT_INTEGRATIONS=/path/to/integrations.json \
+ASSISTANT_STORAGE_DIRECTORY=/path/to/private/conversations \
+SPEECH_ENDPOINT=ws://127.0.0.1:3092/v1/voice \
+SPEECH_TOKEN_FILE=/run/secrets/example-speech-token npm run server
+```
+
+5. In another terminal run `npm run dev` and open `http://127.0.0.1:5176`.
+   Each text card uses `AssistantConversationClientElement`. Send a short request in two
+   cards to see independent output and Stop controls on the one connection.
+6. Open **Voice chat with Planning**. Tap Talk for hands-free listening or hold
+   it for push-to-talk. The speech connection starts automatically when needed.
+   Connect a microphone and speakers and grant browser permission yourself.
+7. Minimize voice, then close Planning's text card or focus Notes. Voice retains
+   Planning. Use another card's Voice chat button to switch explicitly; unfinished
+   words require completion or discard. The voice modal's Text control reopens
+   its original text card. Closing voice stops its audio; minimizing preserves it.
+
+The speech WebSocket is separate from the shared conversation realtime channel.
+It carries audio, not a second conversation subscription or transcript store.
+Leave speech configuration unset to use text without running a speech service.
+
+## Configuration and storage
+
+`ASSISTANT_INTEGRATIONS` uses the existing JSKIT integration configuration and
+credential resolver for every engine. `ASSISTANT_INTEGRATION_ID` selects its
+connection; supplying an integration file without an ID selects `assistant`.
+The server passes one configuration shape: `systemPrompt`, optional
+`integrationId`, `model` and `effort`. The runtime normalizes new configuration
+inputs and uses the example's explicit `defaultIntegrationId: "assistant"` for
+API/OpenCode; Claude/Codex retain native login when no file or ID is supplied.
+Opening existing history does not rewrite its saved configuration.
+The existing `ASSISTANT_NATIVE_MODEL` and `ASSISTANT_NATIVE_EFFORT` variables fill
+the common model and effort fields for any engine. Model IDs stay exact and each
+engine checks its supported choices; setting a model cannot override the
+authorized connection's model.
+
+The API starter can open and display empty conversations before a connection is
+configured. Missing connections or credentials fail on Send without selecting
+another model. An explicitly supplied invalid integration file fails setup.
+`config.js` owns the five IDs, labels and home surface. Existing Planning and
+Notes IDs and history paths are preserved.
+
+History and configuration live in `ASSISTANT_STORAGE_DIRECTORY` (default
+`.assistant/conversations`). Keep it private and retain it across restarts.
+The supplied file adapter supports one writer process. Multi-process hosts must
+supply their transactional store. Text drafts remain in the retained browser
+conversation while any text or voice reader retains that target; unfinished
+recordings remain voice-owned. A full page reload does not persist either draft.
+
+For Claude or Codex, install its CLI and log in as the server's operating-system
+identity. Use `claude auth login` and `ASSISTANT_ENGINE=claude`, or `codex login`
+and `ASSISTANT_ENGINE=codex`. With no integration selected, omitted model and
+effort use the CLI defaults. Alternatively supply the same integration file and
+ID as API/OpenCode, using a provider/model that the native engine supports.
+Changing the engine does not require a different configuration object.
+Codex requires paginated history support; version 0.159.3 was verified earlier.
+Codex conversations share the supplied account/runtime app-server while keeping
+separate threads and Stop controls.
+
+For OpenCode, install version 1.18.31 and set `ASSISTANT_ENGINE=opencode` with the
+same integration configuration as the API path. JSKIT owns its loopback server,
+private credential home, instruction hook and history handling. Preserve
+`.assistant/native/opencode` beneath `ASSISTANT_WORKDIR` with application storage.
+
+Native engines require a POSIX host. `ASSISTANT_WORKDIR` defaults to this directory
+and must stay stable across restarts. Use a separate storage directory when
+trying a different engine: saved conversations retain their engine and identity.
+The example leaves native coding tools disabled. Goal controls appear only when
+the runtime advertises them. Authorized model selection and native replacement
+remain application policy; this example does not add a browser engine selector.
+
+## Delivery, realtime and voice ownership
+
+`server.js` calls `registerFastifyConversations` with its runtime, `appConfig`,
+environment, explicit request authentication and bootstrap labels. This is
+configurable shorthand for the existing JSKIT feature and HTTP/action/realtime
+providers. The starter does not assemble those providers or wrap their router.
+It still creates its file storage and runtime, initializes its five identities,
+chooses models and checks the local Origin itself. It closes its runtime when
+Fastify closes; the helper closes its hosting first.
+
+No database runtime, Knex or migrations are used. Conversation
+read/send/cancel/inspection/goal routes and socket subscriptions belong to the
+supplied feature. Applications already hosted by JSKIT register `AssistantFeature`
+on their existing host and shared connection instead of using the standalone
+helper. Lower-level route/action/subscription facilities remain available for
+custom hosts. The only example-specific data connection is its authorized speech
+proxy.
+
+`main.js` uses `bootClientModules`, `ShellWebClientProvider` and
+`RealtimeClientProvider` for real placement, bootstrap and connection recovery.
+`main.js` also creates one application HTTP/API client using the local server's
+Origin policy. `Conversation.vue` renders `AssistantConversationClientElement`
+with that shared client, the subject key from bootstrap and
+`clear-draft-on="accepted"`. Its `composer-tools` slot receives the same retained
+`runtime` used by the element and passes it to the voice button. The component
+owns loading, errors, draft and delivery state; the example has no polling,
+event parser, receipt map or adapter implementation.
+
+`App.vue` binds the retained runtime to the existing
+voice controller and `projectConversationVoiceState`. Stable spoken turn IDs
+survive transient-to-saved output; voice uses the same send/cancel operations.
+The standard component also exposes `focus()` to reopen the original text card.
+Use `useAssistantConversation()` with `AssistantConversationElement` only when
+custom presentation needs the lower-level adapter; the starter needs only the
+standard component and its slot.
+
+Closing one text card releases its observer without disconnecting its peers or
+stopping server work. Reopening reads current state. Reconnect subscribes and
+reads; it never resends a message. Lost delivery remains **Check delivery** until
+canonical history or explicit inspection proves acceptance. Inspection uses the
+supplied POST `/api/assistant/home/conversations/:conversationId/deliveries/:messageId/inspect`
+and cannot dispatch another prompt. Provider failures remain errors, not saved
+assistant answers. Interrupted or uncertain native work is not silently replayed.
+A failed process cleanup blocks further work; restore its execution host and
+retry Stop. An unknown process after a hard crash needs host-level cleanup.
+
+This is a loopback, single-user example, not a hosted authentication system.
+Writes and socket/voice handshakes require `APP_ORIGIN` (default
+`http://127.0.0.1:5176`). Ordinary GETs may omit Origin; a supplied foreign Origin
+is rejected. The helper applies this same host guard to canonical routes, actions
+and conversation subscriptions. Server-only context identity permits
+only the five browser targets; no actor, scope or room comes from request bodies.
+Runtime authorization rechecks that host context for operations and observations.
+The client's `local-user` scope comes from application bootstrap and is not a
+fabricated authenticated actor. Local events carry no authenticated actor.
+A hosted application supplies its authenticated request/action policy instead.
+
+## A headless task in the same process
+
+Optionally start the server with a direct task:
+
+```sh
+npm run server -- --headless "Give me three short planning questions."
+```
+
+Use the same environment configuration as above. The server opens the separate
+`headless` target through the same runtime and file store, calls `send()` and
+`wait()` directly, and prints its result. No internal HTTP request, browser
+subscription or extra store is involved. Browser access to this target is denied.
+The task runs only when explicitly requested on that server invocation; startup
+does not retry previous unfinished work. Leave the flag off on ordinary restart.
+Do not start another server against the same file directory.
+
+## Verification
+
+`npm run build` checks the client build. Focused integration checks must exercise
+the actual server and browser with fresh packed dependencies, including five
+subscriptions on one socket, independent close/Stop, origin and target denial,
+reconnect and inspection without replay, retained voice/text targeting, and the
+headless path. Source migration is not evidence that those candidate checks passed.
+Physical microphone, speaker and mobile hands-free behavior need real-device
+checks; browser fixture responses do not establish real model or speech behavior.

package/examples/conversation/config.js

@@ -0,0 +1,15 @@
+import { defineAssistantSurface } from "@jskit-ai/assistant-runtime/shared";
+
+// Application-owned identities, labels and the existing home surface.
+export const conversations = Object.freeze([
+  { id: "planning", label: "Planning" },
+  { id: "notes", label: "Notes" },
+  { id: "research", label: "Research" },
+  { id: "writing", label: "Writing" },
+  { id: "review", label: "Review" }
+]);
+
+export const appConfig = Object.freeze({
+  ...defineAssistantSurface("home"),
+  realtimeClient: { options: { transports: ["websocket"] } }
+});

package/examples/conversation/index.html

@@ -0,0 +1 @@
+<!doctype html><html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Voice conversations</title></head><body><div id="app"></div><script type="module" src="/main.js"></script></body></html>

package/examples/conversation/integrations.example.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "assistant": {
+      "provider": "ai",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:ASSISTANT_API_KEY"
+      },
+      "settings": { "model": "deepseek/deepseek-flash" }
+    }
+  }
+}

package/examples/conversation/main.js

@@ -0,0 +1,58 @@
+import { createApp, shallowRef } from "vue";
+import { createPinia } from "pinia";
+import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query";
+import { createRouter, createWebHistory } from "vue-router";
+import { createVuetify } from "vuetify";
+import * as components from "vuetify/components";
+import * as directives from "vuetify/directives";
+import { aliases, mdi } from "vuetify/iconsets/mdi-svg";
+import { bootClientModules } from "@jskit-ai/kernel/client/moduleBootstrap";
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { createSurfaceRuntime } from "@jskit-ai/kernel/shared/surface/runtime";
+import { ShellWebClientProvider } from "@jskit-ai/shell-web/client";
+import { RealtimeClientProvider } from "@jskit-ai/realtime/client";
+import { configureAssistantConversations } from "@jskit-ai/assistant-runtime/client";
+import { createHttpClient } from "@jskit-ai/http-runtime/client";
+import "vuetify/styles";
+import App from "./App.vue";
+import { appConfig } from "./config.js";
+
+globalThis.__JSKIT_CLIENT_APP_CONFIG__ = appConfig;
+const example = shallowRef({ subjectId: "", conversations: [], provider: "Loading application configuration…" });
+// This local app uses its existing Origin guard, rather than a hosted CSRF session.
+const http = createHttpClient({ credentials: "include", csrf: { enabled: false } });
+const ExampleClientProvider = defineProvider({
+  id: "example.client",
+  requires: { shell: "client.shell", vueApp: "client.vue" },
+  setup({ shell, vueApp }) {
+    shell.bootstrapHandlers.register({ handlerId: "example.application", applyBootstrapPayload({ payload }) {
+      example.value = payload.example;
+    } });
+    vueApp.provide("example.application", example);
+    return {};
+  }
+});
+const app = createApp(App);
+configureAssistantConversations(app, {
+  actorKey: () => example.value.subjectId, request: http.request, clearDraftOn: "accepted"
+});
+const pinia = createPinia();
+const queryClient = new QueryClient();
+const router = createRouter({ history: createWebHistory(), routes: [{ path: "/:pathMatch(.*)*", component: App }] });
+app.use(pinia).use(VueQueryPlugin, { queryClient }).use(router)
+  .use(createVuetify({ components, directives, icons: { defaultSet: "mdi", aliases, sets: { mdi } } }));
+const modules = await bootClientModules({
+  app, pinia, queryClient, router, env: import.meta.env, surfaceMode: "home",
+  surfaceRuntime: createSurfaceRuntime({ defaultSurfaceId: "home", surfaces: appConfig.surfaceDefinitions }),
+  clientModules: [
+    { packageId: "@jskit-ai/shell-web", module: { ShellWebClientProvider },
+      packageMetadataClientProviders: [{ export: "ShellWebClientProvider" }] },
+    { packageId: "@jskit-ai/realtime", module: { RealtimeClientProvider },
+      packageMetadataClientProviders: [{ export: "RealtimeClientProvider" }] },
+    { packageId: "example", module: { ExampleClientProvider },
+      packageMetadataClientProviders: [{ export: "ExampleClientProvider" }] }
+  ]
+});
+await router.isReady();
+app.mount("#app");
+if (import.meta.hot) import.meta.hot.dispose(() => { app.unmount(); void modules.runtime.shutdown(); });

package/examples/conversation/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "assistant-voice-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host=127.0.0.1 --port=5176 --strictPort",
+    "server": "node server.js",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "@fastify/websocket": "^11.2.0",
+    "@jskit-ai/assistant-core": "0.1.202",
+    "@jskit-ai/assistant-runtime": "0.1.195",
+    "@jskit-ai/assistant-voice": "0.1.2",
+    "@jskit-ai/connectors-catalog": "0.1.41",
+    "@jskit-ai/http-runtime": "0.1.222",
+    "@jskit-ai/kernel": "0.1.224",
+    "@jskit-ai/realtime": "0.1.221",
+    "@jskit-ai/shell-web": "0.1.228",
+    "@mdi/js": "^7.4.47",
+    "@tanstack/vue-query": "^5.90.5",
+    "fastify": "^5.8.0",
+    "pinia": "^4.0.3",
+    "vue": "^3.5.43",
+    "vue-router": "^5.3.1",
+    "vuetify": "^4.0.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.7",
+    "vite": "^8.2.1"
+  }
+}