Skip to main content

Voice skills

A voice skill is a package that provides the Voice Skill contract. Voice Hub doesn't know the package when it's built. It lists every provider of Voice Skill, and calls the tools of the contracts each one exposes, on that provider, as the person speaking.

Voice Skill's contract id is 00muxgugn6xvs8f2r80ru205t. Implement version 2. Version 1, with its catalog and invoke, is retired.

Providing Voice Skill​

Voice Hub declares Voice Skill in voice-hub/src/contracts/voice-skill.ts (VoiceSkill). Generate your copy of the declaration, and implement it with your widget and the contracts you expose:

npx peers-package contract add ../voice-hub/src/contracts/voice-skill.ts#VoiceSkill
import { implementContract, observable } from "@peers-app/peers-sdk/define";
import { VoiceSkill, type VoiceSkillObservables } from "./contracts/voice-skill.v2";

export const NewsVoiceSkill = implementContract(VoiceSkill, {
observables: {
widget: observable<VoiceSkillObservables["widget"]>({
peersUIId: newsWidgetId,
iconClassName: "bi-newspaper",
order: 40,
}),
},
exposes: [News],
});

// In definePackage:
pkg.provides(News);
pkg.provides(NewsVoiceSkill);
  • exposes lists contracts your package provides whose tools Voice Hub may call. Voice Skill itself has no tools. The rules are in Exposing your contracts through a hub's contract.
  • widget is your widget in Voice Hub, or null when you have none (below).
  • The contract add command works next to Voice Hub's source, as in the Peers repository. Without it, generate the copy from a skill's dist/package.bundle.js (add --contract 00muxgugn6xvs8f2r80ru205t@2) or from a running Peers with a skill installed: see Getting a declaration you don't have.

Once a stable package release freezes Voice Skill v2, a provider with a different shape fails to install. exposes isn't part of that shape: it's yours, and changes with your package's releases.

What Voice Hub gives the model​

Each contract you expose becomes one group of tools for Voice Hub's model:

  • Its name goes in the prompt ("You can use these skills: News, Weather, Timer Controls") and before each of its tools' descriptions ("News: Return cached headlines…").
  • Its tools are offered as <slug>__<tool>, where the slug is made from the contract's name: news__headlines, timer-controls__set-timer. When two groups would share a slug, the later one is numbered (news-2). The complete tool name must use only letters, digits, underscores, and hyphens and fit within 64 characters; tools outside those limits are omitted.
  • Each tool gets its own usageDescription, and its input schema as the arguments' JSON Schema. Write them for a model: what the tool does, its units, and its defaults.
  • Only the tools the person speaking may run are offered: a Reader isn't offered a Writer tool. The Runtime checks every call again.

A tool's output is what the model answers from, so return what a person would want said. Weather exposes a summary tool that describes the forecast in the group's unit, and Timers' list-timers gives each timer's time left in words as well as in milliseconds. Keep outputs small.

When a tool only changes something, Voice Hub confirms it with a tone and an emoji rather than speech. When the person asked a question, Voice Hub's model answers from your tool's output. Failed calls use the failed tone, and Voice Hub keeps the error so the person can ask what went wrong.

Expose a small contract when your main one has tools a voice model shouldn't reach. Timers exposes Timer Controls (set-timer, add-time, pause-timer, resume-timer, cancel-timers, list-timers), not its main contract, whose fire-timer is the scheduler's callback. The small contract's tools work for the assistant and the CLI too.

Contextual widget​

widget holds:

{
"peersUIId": "<25-character UI id>",
"title": "News",
"iconClassName": "bi-newspaper",
"order": 40
}

Everything but peersUIId is optional. title defaults to your package's name, the icon to a generic one, and order to 100. The card's description, shown when it's focused, comes from the first exposed contract with a description, so write that description for the person using Voice Hub as well as for developers. Lower order values appear first when attention and recency are equal. Omit appNavs when the package should appear only as a widget. Voice Hub subscribes to widget while it's open, so changing it to another widget or to null updates the context picker.

Give the widget a route in your routes bundle, next to your screen's. Voice Hub finds the package that owns a peersUIId through its route. Without one, the card shows "Could not find package that owns peersUIId" on any device where your screen hasn't been opened yet:

const widgetRoute: IPeersUIRoute = {
packageId,
peersUIId: newsWidgetId,
path: `package-nav/${packageId}/widget`,
uiCategory: "other",
};

Voice Hub renders the widget through PeersUI with these props:

{
"view": "summary",
"active": false,
"host": "voice-hub"
}

view is summary on Overview and focus when the user or a voice action selects the context. active is true for the focused widget. host lets a reusable UI make small host-specific choices without importing Voice Hub.

Other hubs show your widget too. Family Hub's screensaver puts each widget's focus view beside its photos, with active: true and host: "family-hub", for about 20 seconds at a time, then hides it (display: none) until its next turn. The screensaver covers the widget there, so taps don't reach it. A tap on it opens a second copy of the same focus view on its own, in a tall card about 760 pixels wide, covered until someone taps Edit; then it's in use until it goes untouched for 20 seconds. Make the focus view read well at a glance without interaction, such as what's left on a list or what's next, keep it working while it's mounted but hidden, and let it fill a tall container. A dialog the view opens should be position: fixed in place, not portaled to document.body, so it stays above a full-screen host.

A summary should be quick to mount, compact, and useful from cached or local state. Keep freshness in the provider rather than the view: Weather's provider books its next refresh through System Scheduler after each one, and its widget only calls refresh({ ifStale: true }) when it opens, which the provider skips while the forecast is fresh. Don't start an unconditional network refresh on every summary mount.

A focus view should provide the package's common touch actions with targets of at least 44 pixels, and no keyboard-only or hover-only behavior. Voice Hub owns the card header and context selection; the package owns all domain UI and writes.

After one of your tools succeeds, Voice Hub focuses your widget.

Alert​

Emit alert when a skill needs the user's attention now. Its payload is kind, title, and an optional detail. Alerts work even when widget is null. When a widget is present, Voice Hub focuses it, marks its context, and ranks it first on Overview until the user opens it. When detail is set and voice output is on, Voice Hub speaks it once, with no tone before it; without a detail, it plays the done tone. Alerts wait for an active voice turn and for each other. Voice Hub doesn't branch on kind: keep package-specific wording in detail.

Send it with the declaration's event:

import { voiceSkillAlert } from "./contracts/voice-skill.v2";

await voiceSkillAlert.emit({ kind: "timer-expired", title: "Tea", detail: "Your Tea timer is done." });

Timers waits to chime until Voice Hub finishes speaking the alert. This sound coordination applies within one application window.

Use alerts sparingly, for time-sensitive state such as an expired timer, not for routine refreshes or every successful call.

Discovery​

Voice Hub consumes Voice Skill v2 as optional and lists its providers with the Contract Catalog's listContractProviders, which includes the contracts each one exposes, with the tools the caller may run. A package that doesn't provide Voice Skill isn't a skill. Voice Hub's screen finds skills when it opens, then checks again every 30 seconds and whenever it comes back into view, so a skill installed or removed while Voice Hub is open shows up or goes away within half a minute.

News, Weather, Timers, and Groceries in official-packages/, and Tasks (in the peers-core repo), provide Voice Skill v2. Groceries exposes Grocery List and Tasks exposes Task List: small contracts with the tools a person asks for by voice, which the assistant and the CLI can use too.

Keep actions that Voice Hub shouldn't offer in a separate contract. Groceries and Tasks use Groceries Screen and Tasks Screen for those actions, which Voice Skill doesn't expose. Their widgets can still share exposed tools, such as Task List's create-task, when the same action makes sense by voice and on screen.

Who a call runs as​

Voice Hub's calls to exposed tools run as the person speaking, in the active group, and never with more than that person's own level: a Reader can read the news but can't refresh it, and a Writer can do both. By default, an exposed tool's calls to other tools are capped at its own access level. A tool declared with authorityPropagation: "preserve" passes through the caller's authority instead; each target still checks its own required level. A call names your package as the provider and runs only on it. Installing your package into a group is the trust decision: there's no separate grant.

Turn cancellation​

Voice Hub checks for cancellation before each model request and each skill call. A skill call already running may finish, but no later call in that turn starts. Cancellation doesn't roll back package changes, so keep a tool's changes atomic where it matters.

Spoken listening cancellation happens earlier: a whole utterance of “never mind”, “nevermind”, “cancel listening”, or “stop listening” is checked after endpointing and transcription, before the model or any skill. A leading or trailing “please” and the configured wake phrase are supported, including “please Sterling, never mind” and “Sterling, please stop listening”. Matching ignores case, punctuation, and extra whitespace; underscores in the wake model name are treated as spaces. It ends the current recording and any manual conversation without a history entry. It can't interrupt processing or playback, or undo a skill call. Bare “stop” and “cancel”, “go back to sleep”, timer commands, and longer requests such as “cancel my timer”, “add never mind to my list”, or “stop listening now” still reach the model. See Voice Hub for the Cancel button for active turns.

Voice Skill v1​

Retired: nothing provides or reads it, and the Runtime no longer supports its action aliases (pkg.actionAliases). Version 1 had a catalog observable and an invoke tool that routed to the skill's own tools. A skill on v1 should move to v2 and expose its contracts. A package whose manifest still lists action aliases is refused at install and at load ("manifest.actionAliases is not supported"); move it to v2 and rebuild it.