Assistant Standard Kit

What this is

The checklist and reference implementation for an in-app AI assistant worth shipping — distilled from three production assistants that each solved a different piece and each got a different piece wrong first.

The three hard parts

Actuation, not advice. Most assistants explain the steps. The actuator layer performs them — navigate, fill, click, scroll, highlight — resolving against a declared action registry *before* falling back to a model loop. Model-first navigation is slower, costs more, and fails in ways users can't predict, which is worse than failing predictably.

Tours that demonstrate. The tour engine runs the assistant through real steps in the real UI, narrating, pausable at every step. A tour that points at things is forgotten immediately; an assistant that fills the form for you once is understood forever.

Permission tiers that survive users. Every action is declared with a tier (no-approval / confirm / never) and at least two spoken-phrase fixtures, validated by JSON Schema in CI. A command grammar keeps "stop", "cancel", "never mind", and "wait" all meaning stop.

Also included

The context object contract — one shape for "what is the user looking at right now", passed into every turn. It's the difference between an assistant that answers and one that answers about this page. And `ASSISTANT_STANDARD.md`, the capability checklist, so you can tell whether what you built is actually finished.

Pairs with

The Push-to-Talk Voice Kit (the voice half, done properly) and the Voice Provider Layer (swap STT/LLM/TTS per stage, see the cost before you build).

Honest limits

Not a framework. Not a RAG implementation. It does not pick your model. And it does not promise safety — confirm gates and permission tiers reduce blast radius; they don't make an assistant trustworthy on their own.

Delivery

Source delivered as a private repository invite within 24 hours of purchase. Single-product commercial license: use and modify in one shipped product; no redistribution or resale of the source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function isAllowGrantEligible( action: Pick<RegistryAction, 'approval_tier' | 'undo'>, ): boolean;
  export function grantMatches( grant: AllowGrant, appId: string, actionName: string, argsHash: string | null, now: Date = new Date(), ): boolean;
  export function matchGrammar(normalizedUtterance: string): GrammarEntry | null;
  export function isContextStale( ctx: Pick<ContextObject, 'observedAt'>, thresholdMs: number = CONTEXT_STALENESS_DEFAULT_MS, now: Date = new Date(), ): boolean;
  export function staleContextReadback(entity: ContextEntity | null): string;
  export function clickByText(text: string, nth = 1, role: ClickRole = "any"): ActuatorResult;
  export function findInput(hint: string): HTMLElement | null;
  export function typeText(hint: string, text: string, submit = false): ActuatorResult;
  export function scroll( direction: "up" | "down", amount: "page" | "half" | "top" | "bottom" = "page" ): ActuatorResult;
  export function navBack(routerBack?: ();
  export function highlight(selector: string, ms = 2400): ActuatorResult;
  export function tourKickoff(tour: Tour): string;

  export type ApprovalTier = (typeof APPROVAL_TIERS)[number];
  export type RiskLevel = 'low' | 'medium' | 'high' | 'critical';
  export type RegistrySurface = 'chat' | 'voice' | 'slack' | 'desktop' | 'palette';
  export type ContextApp = string;
  export type ContextSource = 'mint' | 'push' | 'poll' | 'pull';
  export type ActuatorResult = { ok: boolean;