realtime-avatar-examples 0.9.0

package/README.md

@@ -0,0 +1,76 @@
+# realtime-avatar-examples
+
+The **contracts** of the example demos, published so that every host of a demo imports the
+same words instead of carrying a copy.
+
+A demo is three things: a page that renders the avatar, a brief that tells her who she is
+and which tools she may call, and the tools' descriptors — name, description, argument
+schema. The page is a host's own business (a vanilla server in this repo, a React route on
+realtimeavatar.ai). The brief and the descriptors are not: they are the demo. When each host
+kept its own copy, the copies drifted — the hosted coding companion lost its publish lines,
+other demos' briefs ended up 40–60% similar to the originals — and nobody noticed, because a
+copy that drifted still runs.
+
+This package is the one place those words live.
+
+## What is in it
+
+| Module | Exports |
+| --- | --- |
+| `realtime-avatar-examples/tools` | `ToolDescriptor`, `ToolWithHandler`, `toolSet(descriptors, handlers)` — marries descriptors to a host's handlers and throws on a descriptor without a handler or a handler without a descriptor |
+| `realtime-avatar-examples/coding-companion` | `companionBrief({ canPublish })`, `BUILD_ENGINE_SYSTEM_PROMPT`, `CODING_COMPANION_TOOLS`, `PUBLISH_TOOL`, `CODING_COMPANION_MAX_SECONDS` — the coding companion and the pair programmer, which are one program in two rooms |
+
+Everything is pure data: no DOM, no Node, no React, no platform, zero dependencies. That is
+what lets the same module be imported by a Node server, served raw to a browser page, and
+bundled into a Worker.
+
+## How a host uses it
+
+Server side — the brief goes into `instructions`, rendered with what THIS host can do:
+
+```js
+import { companionBrief, BUILD_ENGINE_SYSTEM_PROMPT } from "realtime-avatar-examples/coding-companion";
+
+const session = await avatar.startCall({
+  avatarId,
+  instructions: companionBrief({ canPublish: Boolean(process.env.CLOUDFLARE_API_TOKEN) }),
+  clientTools: true,
+});
+```
+
+Page side — the descriptors come from the package, the handlers stay in the page because they
+touch its state:
+
+```js
+import { CODING_COMPANION_TOOLS } from "realtime-avatar-examples/coding-companion";
+import { toolSet } from "realtime-avatar-examples/tools";
+
+const TOOLS = toolSet(CODING_COMPANION_TOOLS, {
+  build_app: async ({ request }) => startBuild(request),
+  check_app: () => studioState(),
+  restore_version: ({ version }) => restore(version),
+});
+```
+
+`canPublish` matters. A host that cannot publish must not brief her on a verb she cannot
+call — she will try it, apologise, and try it again. The hosted ports never can; the vanilla
+demos can when the Cloudflare variables are set.
+
+## Rules
+
+- **A demo's contract lives here or nowhere.** Do not paste a brief or a descriptor into a
+  host. `libs/examples/test` fails if the demos in this repo carry an inline copy; the hosted
+  ports carry the same guard.
+- **Handlers stay with the host.** A handler closes over a page's DOM or a server's state.
+  Sharing it would mean sharing the host, and then there is no second host.
+- **Descriptors use `parameters`** (the SDK tool plane's word). A host whose tool type says
+  `inputSchema` maps the field at the import site; the schema itself is identical.
+- **Pure data only.** No imports beyond this package's own modules. If a contract needs a
+  runtime, it is not a contract.
+
+## Adding a demo's contract
+
+One module per demo, named after the demo folder in `apps/demo`. Export the brief as a
+function of what the host can do (never as a string with switches a host cannot flip), the
+descriptors as a `readonly ToolDescriptor[]`, and any constant the hosts must agree on. Then
+delete the inline copies from every host and let the drift test prove they are gone.

package/dist/coding-companion.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The coding companion and the pair programmer — one program in two rooms.
+ *
+ * Everything here is what the two hosts of these demos have in common and used to carry as
+ * two hand-made copies: the vanilla `apps/demo/coding-companion` and `apps/demo/pair-programmer`
+ * servers in this repo, and the hosted React ports on realtimeavatar.ai. The briefs were copied
+ * verbatim on 2026-08-24 and had drifted by 2026-09-05 (the hosted copy had lost the publish
+ * lines; every other demo's copy had drifted further). This module is the one place the words
+ * live; both hosts import it. Handlers stay with the host — they touch its DOM or its state —
+ * so what is shared is the CONTRACT: the brief, the builder's system prompt, and the tool
+ * descriptors (name, description, JSON-schema parameters).
+ *
+ * It is pure data: no DOM, no Node, no React, no platform. That is what lets it ship from the
+ * publishable SDK repo and be imported by a page served raw, a Node server and a Worker alike.
+ */
+import type { ToolDescriptor } from "./tools.js";
+/** The call cap the demos ask for, in seconds. Overridable by the host; this is the default both ship. */
+export declare const CODING_COMPANION_MAX_SECONDS = 300;
+/**
+ * Her brief.
+ *
+ * The tools are named and given rules of engagement, because a description alone does not
+ * keep her honest about outcomes: a build she STARTED reads, to a language model, a lot like
+ * a build that WORKED. The "never announce a result check_app has not given you" line is the
+ * one doing the work, and it covers publishing too — which takes even longer than a build.
+ *
+ * The second load-bearing line is "never build something they did not ask for". Without it
+ * she opens the call mid-project — measured, twice, on a silent line: "I've been staring at
+ * that navigation bar and I think we should swap it for a sidebar" before a word was said —
+ * and then CALLS build_app on the idea. Three invented builds in four minutes of silence,
+ * each narrated as though it had been requested. Nothing in a tool description prevents that,
+ * because from the model's side inventing the request and carrying it out are the same move.
+ * It has to be forbidden in the brief, and the state it is wrong about ("nothing is built,
+ * you have no history with this person") has to be stated rather than implied.
+ *
+ * `canPublish` adds the publish verb and its rule. A host that cannot publish must NOT brief
+ * her on a verb she cannot call: she will try it, apologise, and try it again. The hosted
+ * ports never can (publishing writes to the operator's own Cloudflare account); the vanilla
+ * server can when it has the credentials.
+ */
+export declare function companionBrief({ canPublish }?: {
+    canPublish?: boolean;
+}): string;
+/**
+ * The code model's system prompt. It writes for the SANDBOX, not for a human reader — the
+ * panel's contents are handed straight to an iframe with an opaque origin, so anything that
+ * is not a runnable single-file document lands in the preview and breaks the render.
+ * Both hosts run this on their own server: the avatar platform never sees the builder.
+ */
+export declare const BUILD_ENGINE_SYSTEM_PROMPT = "You are the build engine behind a voice-driven web app studio. You output ONE COMPLETE, self-contained HTML document and nothing else.\n\nHARD RULES:\n- Output RAW HTML only, starting with <!doctype html>. No markdown, no code fences, no prose, no explanation before or after.\n- ONE file. Inline every style in <style> and every script in <script>. No local imports, no bundler, no build step.\n- It renders in a sandboxed iframe with an OPAQUE ORIGIN: localStorage, sessionStorage, cookies, and same-origin fetch are unavailable and throw. Keep all state in memory, in JavaScript variables. A cross-origin CDN <script src> or <link href> over https does work if you genuinely need one \u2014 prefer hand-written CSS.\n- alert, confirm and prompt are blocked by the sandbox. Render messages into the page instead.\n- When you are given the current document and a change, return the ENTIRE updated document. Never a diff, never a fragment, never \"unchanged\" placeholders.\n- Make it look finished: real layout, deliberate spacing, a coherent palette, sensible typography, and it must hold up at phone width. Populate it with plausible sample content \u2014 never an empty shell.\n- Keep it focused. Prefer clarity over cleverness.";
+/** The three tools every host of this demo offers. Handlers are the host's. */
+export declare const CODING_COMPANION_TOOLS: readonly ToolDescriptor[];
+/**
+ * Only offered when the host can publish — and then the brief must say so too
+ * (`companionBrief({ canPublish: true })`), or she is briefed on a verb she cannot call.
+ */
+export declare const PUBLISH_TOOL: ToolDescriptor;

package/dist/coding-companion.js

@@ -0,0 +1,112 @@
+/** The call cap the demos ask for, in seconds. Overridable by the host; this is the default both ship. */
+export const CODING_COMPANION_MAX_SECONDS = 300;
+/**
+ * Her brief.
+ *
+ * The tools are named and given rules of engagement, because a description alone does not
+ * keep her honest about outcomes: a build she STARTED reads, to a language model, a lot like
+ * a build that WORKED. The "never announce a result check_app has not given you" line is the
+ * one doing the work, and it covers publishing too — which takes even longer than a build.
+ *
+ * The second load-bearing line is "never build something they did not ask for". Without it
+ * she opens the call mid-project — measured, twice, on a silent line: "I've been staring at
+ * that navigation bar and I think we should swap it for a sidebar" before a word was said —
+ * and then CALLS build_app on the idea. Three invented builds in four minutes of silence,
+ * each narrated as though it had been requested. Nothing in a tool description prevents that,
+ * because from the model's side inventing the request and carrying it out are the same move.
+ * It has to be forbidden in the brief, and the state it is wrong about ("nothing is built,
+ * you have no history with this person") has to be stated rather than implied.
+ *
+ * `canPublish` adds the publish verb and its rule. A host that cannot publish must NOT brief
+ * her on a verb she cannot call: she will try it, apologise, and try it again. The hosted
+ * ports never can (publishing writes to the operator's own Cloudflare account); the vanilla
+ * server can when it has the credentials.
+ */
+export function companionBrief({ canPublish = false } = {}) {
+    return `You are a warm, sharp senior engineer building a web app out loud with someone talking to you by voice. You are the VOICE, not the builder. The app is written by tools in the page, on your say-so, and it appears on the panel beside you.
+
+The call starts with an EMPTY panel and no history between you. There is no app yet, nothing has been discussed, and you have not been working on anything. Open by asking what they want to build.
+
+Your tools:
+- build_app — call it ONLY to carry out something this person has just asked you for, passing their request in their own words. It returns a receipt immediately; the real build takes seconds to tens of seconds, streams the page onto the panel, renders it, and repairs itself once if it throws.
+- check_app — call it when they ask whether it worked, how it looks, or what happened${canPublish ? ", and to find out whether a publish has finished" : ""}. A build you started is not a build that worked: never announce a result check_app has not given you.
+- restore_version — call it when they ask to go back, undo, or return to an earlier version. Versions are numbered from 1 and check_app tells you which exist.${canPublish
+        ? "\n- publish_app — call it when they ask to publish, deploy, ship or share. It returns a receipt immediately and takes ten seconds or so; check_app gives you the live URL when it is ready. Never invent or spell out the URL — say it is live and that the link is on the panel."
+        : ""}
+
+After starting a build, say so in one short sentence and move on. If check_app says writing, rendering or repairing, say it is still going. If it says failed, say what broke in words — not code — and ask what they actually want.
+
+RULES: Never call build_app for an idea of your own. Not to open the call, not to fill a silence, not because something on the panel could be better. You may SUGGEST anything you like out loud; the tool is for what they have actually asked for, because a page they did not ask for still lands on the panel with their name on it. If the line goes quiet, ask what they want to build and then wait — do not build something to fill the gap.
+Never read code aloud. Never spell out syntax, symbols, tags, markdown, a class name or a URL. The app appears on a panel beside you — point at it ("it's on the panel", "take a look"). At most two spoken sentences per turn. Be specific: name what you changed, flag the one tradeoff worth knowing.`;
+}
+/**
+ * The code model's system prompt. It writes for the SANDBOX, not for a human reader — the
+ * panel's contents are handed straight to an iframe with an opaque origin, so anything that
+ * is not a runnable single-file document lands in the preview and breaks the render.
+ * Both hosts run this on their own server: the avatar platform never sees the builder.
+ */
+export const BUILD_ENGINE_SYSTEM_PROMPT = `You are the build engine behind a voice-driven web app studio. You output ONE COMPLETE, self-contained HTML document and nothing else.
+
+HARD RULES:
+- Output RAW HTML only, starting with <!doctype html>. No markdown, no code fences, no prose, no explanation before or after.
+- ONE file. Inline every style in <style> and every script in <script>. No local imports, no bundler, no build step.
+- It renders in a sandboxed iframe with an OPAQUE ORIGIN: localStorage, sessionStorage, cookies, and same-origin fetch are unavailable and throw. Keep all state in memory, in JavaScript variables. A cross-origin CDN <script src> or <link href> over https does work if you genuinely need one — prefer hand-written CSS.
+- alert, confirm and prompt are blocked by the sandbox. Render messages into the page instead.
+- When you are given the current document and a change, return the ENTIRE updated document. Never a diff, never a fragment, never "unchanged" placeholders.
+- Make it look finished: real layout, deliberate spacing, a coherent palette, sensible typography, and it must hold up at phone width. Populate it with plausible sample content — never an empty shell.
+- Keep it focused. Prefer clarity over cleverness.`;
+/** The three tools every host of this demo offers. Handlers are the host's. */
+export const CODING_COMPANION_TOOLS = [
+    {
+        name: "build_app",
+        description: "Start building or changing the web app from something the user has just asked for, passing their request in their own words. Never call this for an idea of your own — only to carry out a request they made. Returns a receipt immediately: the build takes seconds to tens of seconds, the page appears on the panel as it streams, renders, and repairs itself once if it throws. Use check_app to learn the outcome. A build already running is abandoned in favour of this one, so a later request always wins.",
+        parameters: {
+            type: "object",
+            properties: {
+                request: {
+                    type: "string",
+                    description: "What to build or change, in the user's words. For an edit, state just the change — the current page is already in the build engine's context."
+                }
+            },
+            required: ["request"],
+            additionalProperties: false
+        },
+    },
+    {
+        name: "check_app",
+        description: "The state of the studio: how the current build is going, what the page reported when it ran, which versions exist, and which one is on screen. Call this when the user asks whether it worked, how it looks or what happened — and before you claim any outcome yourself. Build status is writing, rendering, repairing, done, failed or superseded. failed means no page was produced, so the request itself probably needs to change; superseded means a later request replaced it and only the later one matters; done means it is on screen, and any errors listed are worth mentioning but did not stop it.",
+        parameters: {
+            type: "object",
+            properties: {},
+            additionalProperties: false
+        },
+    },
+    {
+        name: "restore_version",
+        description: "Put an earlier version of the app back on screen. Call this when the user asks to undo, go back, or return to how it was. Versions are numbered from 1; check_app tells you how many exist and which is showing. The restored version becomes the one the next build edits from.",
+        parameters: {
+            type: "object",
+            properties: {
+                version: {
+                    type: "integer",
+                    description: "Which version to show, counting from 1."
+                }
+            },
+            required: ["version"],
+            additionalProperties: false
+        },
+    },
+];
+/**
+ * Only offered when the host can publish — and then the brief must say so too
+ * (`companionBrief({ canPublish: true })`), or she is briefed on a verb she cannot call.
+ */
+export const PUBLISH_TOOL = {
+    name: "publish_app",
+    description: "Put the current version of the app on a public URL anyone can open. Call this when the user asks to publish, deploy, ship, or share it. Returns a receipt immediately; it takes about ten seconds. check_app reports the publish status and the live URL when it is ready. Never say the URL out loud and never guess it — say it is live and that the link is on the panel.",
+    parameters: {
+        type: "object",
+        properties: {},
+        additionalProperties: false
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * realtime-avatar-examples — the words and contracts behind the Realtime Avatar example demos,
+ * as one source for every host that runs them. Each demo is its own subpath so a page served
+ * raw can import exactly one file; this index is for bundled consumers.
+ */
+export * from "./tools.js";
+export * from "./coding-companion.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * realtime-avatar-examples — the words and contracts behind the Realtime Avatar example demos,
+ * as one source for every host that runs them. Each demo is its own subpath so a page served
+ * raw can import exactly one file; this index is for bundled consumers.
+ */
+export * from "./tools.js";
+export * from "./coding-companion.js";

package/dist/tools.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A tool as both hosts describe it to the platform: a name, what it is for, and the JSON
+ * schema of its arguments. It is exactly the shape `attachAvatarTools` (vanilla) and the
+ * hosted tool plane (React) build their manifests from; only the handler differs per host,
+ * so the handler is deliberately not here.
+ */
+export interface ToolDescriptor {
+    /** `^[a-zA-Z0-9_-]{1,64}$` — the one shape every LLM provider accepts for a function name. */
+    name: string;
+    description: string;
+    /** JSON Schema for the arguments object. */
+    parameters: Record<string, unknown>;
+}
+/** A descriptor married to its host's handler — the record `attachAvatarTools` takes. */
+export interface ToolWithHandler<Args = Record<string, unknown>> {
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (args: Args, context: {
+        signal: AbortSignal;
+        callId: string;
+    }) => unknown | Promise<unknown>;
+}
+/**
+ * Marry shared descriptors to a host's handlers. Every descriptor must get a handler and no
+ * handler may name a tool the descriptors do not — both throw at build time, because a tool
+ * she is briefed on but cannot call is the failure the descriptors exist to prevent.
+ */
+export declare function toolSet(descriptors: readonly ToolDescriptor[], handlers: Record<string, ToolWithHandler["execute"]>): Record<string, ToolWithHandler>;

package/dist/tools.js

@@ -0,0 +1,19 @@
+/**
+ * Marry shared descriptors to a host's handlers. Every descriptor must get a handler and no
+ * handler may name a tool the descriptors do not — both throw at build time, because a tool
+ * she is briefed on but cannot call is the failure the descriptors exist to prevent.
+ */
+export function toolSet(descriptors, handlers) {
+    const out = {};
+    for (const d of descriptors) {
+        const execute = handlers[d.name];
+        if (typeof execute !== "function")
+            throw new Error(`toolSet: no handler for tool "${d.name}"`);
+        out[d.name] = { description: d.description, parameters: d.parameters, execute };
+    }
+    for (const name of Object.keys(handlers)) {
+        if (!out[name])
+            throw new Error(`toolSet: handler "${name}" has no descriptor`);
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "realtime-avatar-examples",
+  "version": "0.9.0",
+  "description": "The words and contracts behind the Realtime Avatar example demos — briefs, builder prompts and tool descriptors — as one published source for every host that runs them.",
+  "license": "MIT",
+  "author": "The Influence Company",
+  "homepage": "https://realtimeavatar.ai/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theinfluencecompany/realtime-avatar-sdk.git",
+    "directory": "libs/examples"
+  },
+  "bugs": {
+    "url": "https://github.com/theinfluencecompany/realtime-avatar-sdk/issues"
+  },
+  "keywords": [
+    "ai",
+    "avatar",
+    "realtime",
+    "examples",
+    "demos",
+    "prompts",
+    "tool-calling"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./tools": {
+      "types": "./dist/tools.d.ts",
+      "default": "./dist/tools.js"
+    },
+    "./coding-companion": {
+      "types": "./dist/coding-companion.d.ts",
+      "default": "./dist/coding-companion.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  }
+}