@wibly/sdk 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # `@wibly/sdk` — Changelog
 
+## 0.1.2 — 2026-06-08
+
+### Added
+
+- `session.host.abort()` — a universal mid-game abort. Emits the new
+  `host.abort` control verb; the Runtime force-jumps to the manifest's
+  `workflow.abortPhaseId` (or the last declared phase when omitted) from
+  any phase. Games no longer need per-phase abort transitions.
+
 ## 0.1.1 — 2026-05-30
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wibly/sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Wibly @wibly/sdk",
   "type": "module",
   "main": "./src/index.ts",
@@ -18,9 +18,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@wibly/internal-manifest": "0.1.1",
-    "@wibly/internal-protocol": "0.1.1",
-    "@wibly/internal-shared": "0.1.1",
+    "@wibly/internal-manifest": "0.1.2",
+    "@wibly/internal-protocol": "0.1.2",
+    "@wibly/internal-shared": "0.1.2",
     "zod": "^3.25.76"
   },
   "peerDependencies": {

package/src/client.ts

@@ -181,6 +181,25 @@ export type Session = {
     readonly advancePhase: (
       detail?: unknown,
     ) => Result<{ readonly id: string }, SdkError>;
+    /**
+     * Universal mid-game abort. The Runtime force-jumps to the
+     * manifest's abort/terminal phase (`workflow.abortPhaseId`, else
+     * the last declared phase) from wherever the session currently is.
+     * No per-phase wiring required.
+     */
+    readonly abort: () => Result<{ readonly id: string }, SdkError>;
+    readonly reportTtsPlayback: (detail: {
+      readonly state: 'active' | 'idle';
+    }) => Result<{ readonly id: string }, SdkError>;
+    readonly reportTtsBeat: (detail: {
+      readonly beatId: string;
+      readonly event: 'clip_start' | 'clip_end';
+      readonly clipId?: string;
+      readonly reveal?: {
+        readonly kind: 'none' | 'player_submission';
+        readonly playerId?: string;
+      };
+    }) => Result<{ readonly id: string }, SdkError>;
     readonly reclaim: () => Result<{ readonly id: string }, SdkError>;
   };
   readonly inference: SessionInference;
@@ -310,9 +329,11 @@ export const createSession = (config: SessionConfig): Session => {
           ? 'host'
           : 'system';
       store.setSessionPaused(true, via);
+      time.freeze();
     }
     if (payload.transition === 'continued') {
       store.setSessionPaused(false, null);
+      time.unfreeze();
     }
     if (payload.transition === 'seat.recovery_code_issued') {
       const detail = payload.detail;
@@ -481,6 +502,8 @@ export const createSession = (config: SessionConfig): Session => {
       audioBase64: string;
       contentType?: unknown;
       durationMs?: unknown;
+      beat?: unknown;
+      cues?: unknown;
     },
     caption: string | null | undefined,
   ): void => {
@@ -499,6 +522,11 @@ export const createSession = (config: SessionConfig): Session => {
             ? data.durationMs
             : estimateAudioDurationMs(data.audioBase64),
         caption: caption === undefined ? null : caption,
+        // Carry in-phase beat + lip-sync cues through to the Host shell.
+        // These drive Experience reveal choreography via `reportTtsBeat`
+        // → `onTtsBeat`; dropping them here silently breaks beat reveals.
+        ...(data.beat !== undefined ? { beat: data.beat } : {}),
+        ...(data.cues !== undefined ? { cues: data.cues } : {}),
       },
     });
   };
@@ -510,37 +538,57 @@ export const createSession = (config: SessionConfig): Session => {
       contentType?: string;
       durationMs?: number;
       kind?: string;
+      beat?: unknown;
+      cues?: unknown;
     } | null;
-    if (!data || typeof data.causeMessageId !== 'string') return;
-    const causeId = data.causeMessageId as unknown as MessageId;
-    const pending = pendingVoice.get(causeId);
-    const caption = pending?.caption;
-    const audioBase64 = data.audioBase64;
+    if (!data) return;
 
-    if (
+    const audioBase64 = data.audioBase64;
+    const isSpeakResult =
       payload.eventType === 'voice.speak.result' &&
-      typeof audioBase64 === 'string'
-    ) {
+      typeof audioBase64 === 'string';
+
+    const causeId = (() => {
+      if (typeof data.causeMessageId === 'string' && data.causeMessageId.length > 0) {
+        return data.causeMessageId as MessageId;
+      }
+      if (isSpeakResult) {
+        return `voice-server-${audioBase64.length}-${audioBase64.slice(0, 12)}` as MessageId;
+      }
+      return null;
+    })();
+
+    if (isSpeakResult && causeId !== null) {
+      const pending =
+        typeof data.causeMessageId === 'string' && data.causeMessageId.length > 0
+          ? pendingVoice.get(data.causeMessageId as MessageId)
+          : undefined;
       dispatchVoiceAudio(
         causeId,
         {
           audioBase64,
           contentType: data.contentType,
           durationMs: data.durationMs,
+          beat: data.beat,
+          cues: data.cues,
         },
-        caption ?? null,
+        pending?.caption ?? null,
       );
     }
 
+    if (typeof data.causeMessageId !== 'string' || data.causeMessageId.length === 0) {
+      return;
+    }
+
+    const causeMessageId = data.causeMessageId as MessageId;
+    const pending = pendingVoice.get(causeMessageId);
+
     if (pending === undefined) return;
     pending.cancelTimeout();
-    pendingVoice.delete(causeId);
-    transport.confirmSend(causeId);
+    pendingVoice.delete(causeMessageId);
+    transport.confirmSend(causeMessageId);
 
-    if (
-      payload.eventType === 'voice.speak.result' &&
-      typeof audioBase64 === 'string'
-    ) {
+    if (isSpeakResult) {
       pending.resolve(
         ok({
           audioBase64,
@@ -711,6 +759,32 @@ export const createSession = (config: SessionConfig): Session => {
         const sent = transport.send('emit', payload);
         return ok({ id: sent.id as unknown as string });
       },
+      abort: () => {
+        const payload = buildHostEmitPayload(
+          config.sessionId,
+          HOST_EVENT_TYPES.abort,
+        );
+        const sent = transport.send('emit', payload);
+        return ok({ id: sent.id as unknown as string });
+      },
+      reportTtsPlayback: (detail) => {
+        const payload = buildHostEmitPayload(
+          config.sessionId,
+          HOST_EVENT_TYPES.ttsPlayback,
+          detail,
+        );
+        const sent = transport.send('emit', payload);
+        return ok({ id: sent.id as unknown as string });
+      },
+      reportTtsBeat: (detail) => {
+        const payload = buildHostEmitPayload(
+          config.sessionId,
+          HOST_EVENT_TYPES.ttsBeat,
+          detail,
+        );
+        const sent = transport.send('emit', payload);
+        return ok({ id: sent.id as unknown as string });
+      },
       reclaim: () => {
         const payload = buildHostEmitPayload(
           config.sessionId,
@@ -805,7 +879,7 @@ const buildInferenceVerbs = (
     });
     const sent = transport.send('emit', {
       sessionId,
-      eventType: `${INFERENCE_EVENT_PREFIX}${input.callKind}`,
+      eventType: `${INFERENCE_EVENT_PREFIX}${input.templateId}`,
       data: serialised,
     });
     pending.set(sent.id, resolveFn);
@@ -824,16 +898,6 @@ const buildInferenceVerbs = (
   };
   return {
     call,
-    // Convenience wrappers map to the most-common manifest `CallKind`s
-    // (per `@platform/manifest`'s `CallKindSchema` and
-    // `docs/conventions/prompt-composition.md`). Bundles that need a
-    // less-common kind (`host_resolve`, `host_recap`, `judge_funniness`,
-    // `compose_clue`, `narrate_event`) call `inference.call({ callKind,
-    // ... })` directly — the wrappers are a comfort for the dominant
-    // open-phase + judge paths, not an exhaustive cover.
-    host: (input) => call({ ...input, callKind: 'host_open_phase' }),
-    judge: (input) => call({ ...input, callKind: 'host_judge' }),
-    classify: (input) => call({ ...input, callKind: 'classify' }),
   };
 };
 

package/src/control.ts

@@ -15,6 +15,9 @@
  *   - `host.resume`         — resume from pause.
  *   - `host.advancePhase`  — request the next phase. The Runtime
  *                             may reject if no transition matches.
+ *   - `host.abort`          — universal mid-game abort. The Runtime
+ *                             force-jumps to the manifest's abort/
+ *                             terminal phase (no per-phase wiring).
  *   - `host.reclaim`        — reclaim the host slot from a hung
  *                             host (the player who fires this
  *                             becomes the new host if allowed).
@@ -26,6 +29,9 @@ export const HOST_EVENT_TYPES = {
   pause: 'host.pause',
   resume: 'host.resume',
   advancePhase: 'host.advancePhase',
+  abort: 'host.abort',
+  ttsPlayback: 'host.ttsPlayback',
+  ttsBeat: 'host.ttsBeat',
   reclaim: 'host.reclaim',
 } as const;
 

package/src/index.ts

@@ -67,7 +67,6 @@ export {
   buildInferenceRequest,
   type InferenceCallInput,
   type InferenceCallSuccess,
-  type SdkCallKind,
   type SdkQualityTier,
   type SerialisedInferenceRequest,
   type SessionInference,
@@ -79,6 +78,9 @@ export {
   type SessionVoice,
   type SpeakInput,
   type SpeakSuccess,
+  type TtsBeatMeta,
+  type TtsBeatReveal,
+  type VoiceAudioPayload,
 } from './voice.js';
 
 export {

package/src/inference.ts

@@ -1,98 +1,25 @@
 /**
- * Inference verbs (per chunk B7 build: "inference.ts — typed call
- * helpers: session.inference.host(slots), .judge(slots),
- * .classify(slots), etc. — calls the Gateway through the Runtime
- * (the SDK never holds the gateway-auth key).").
- *
- * The chunk-B7 contract is:
- *
- *   1. The caller invokes `session.inference.<verb>({ slots, output,
- *      qualityTier? })`.
- *   2. The SDK serialises any caller-declared Zod output schema to
- *      JSON Schema (via `@platform/shared/json-schema.ts`).
- *   3. The SDK sends an `emit` frame with a reserved `inference.*`
- *      event type. The Runtime (chunk B8a) receives it, signs the
- *      request, forwards to the Gateway, and emits a follow-up
- *      `event` frame with the result keyed by the original message
- *      id.
- *   4. The SDK matches the inbound event against the pending call's
- *      id and resolves the typed result.
- *
- * **Why `emit` and not a new wire kind?** The protocol already
- * carries `emit` for asynchronous client → server work; reserving an
- * `inference.*` namespace on `eventType` keeps the surface compact
- * and avoids a `PROTOCOL_VERSION` bump. The chunk-B8a Runtime is
- * what enforces the gating + signing.
- *
- * Until chunk B8a wires the Runtime-side handler, the SDK's
- * inference verbs return `Err({ kind: 'runtime_not_wired' })`. The
- * SDK still serialises the schema + payload so the chunk-B7 surface
- * is testable (the JSON Schema + outbound `emit` shape are
- * regression-protected); the runtime-side roundtrip lights up with
- * B8a.
+ * Inference verbs — game code calls by manifest `templateId`.
  */
 
+import type { QualityTier } from '@wibly/internal-manifest';
 import type { z, ZodTypeAny } from 'zod';
 
 import { zodToJsonSchema, type JsonSchema } from '@wibly/internal-shared';
 import type { Result } from '@wibly/internal-shared';
-import type { CallKind, QualityTier } from '@wibly/internal-manifest';
 
 import type { SdkError } from './errors.js';
 
-/**
- * Quality tier surfaced on the SDK boundary. Type-only re-export of
- * `@platform/manifest`'s `QualityTier` so the manifest stays the
- * single source of truth for the on-the-wire enum. The `import type`
- * is erased at compile time, so the SDK still does not pull in the
- * manifest's Zod runtime — only the type literals.
- *
- * The B7 close note ("kept as a string literal here so the SDK
- * doesn't pull in the manifest's full Zod runtime") was right about
- * the runtime concern but wrong to duplicate the literals — the
- * duplication had already drifted from the manifest's enum at chunk
- * close. Type-only re-export gives the same runtime weight (zero)
- * with the contract honoured at compile time.
- */
-export type SdkQualityTier = QualityTier;
-
-/**
- * Recognised call kinds. Type-only re-export of `@platform/manifest`'s
- * `CallKind`; the manifest's `CallKindSchema` (enumerating
- * `host_open_phase`, `host_judge`, `host_resolve`, `host_recap`,
- * `judge_funniness`, `narrate_event`, `classify`, `compose_clue`) is
- * the canonical wire-side set. New `callKind`s land in
- * `@platform/manifest` and `docs/conventions/prompt-composition.md`
- * in the same commit per chunk B4's convention; the SDK's enum
- * follows automatically because it's a type alias.
- *
- * The trailing `(string & {})` widening preserves the chunk-B7
- * authoring-aid behaviour ("the SDK accepts any string at runtime")
- * while keeping the literal set as IntelliSense-discoverable
- * autocompletes for in-tree game bundles.
- */
-export type SdkCallKind = CallKind | (string & {});
-
 export type InferenceCallInput<TOutput extends ZodTypeAny> = {
-  readonly callKind: SdkCallKind;
+  readonly templateId: string;
   readonly slots: Readonly<Record<string, unknown>>;
   readonly output?: TOutput;
-  readonly qualityTier?: SdkQualityTier;
-  /**
-   * Optional idempotency key. The Runtime forwards it to the
-   * Gateway's `metadata.idempotencyKey`. Use case: a host that
-   * wants to retry without double-billing.
-   */
   readonly idempotencyKey?: string;
 };
 
 export type InferenceCallSuccess<TOutput extends ZodTypeAny> = {
-  /** Raw model output (the Gateway's `output`). */
   readonly output: string;
-  /** Parsed structured response. `null` if no schema was provided. */
   readonly structured: TOutput extends ZodTypeAny ? z.infer<TOutput> | null : null;
-  /** Gateway usage block. Surface for debug; the operator-side
-   * dashboards use the audit ledger instead. */
   readonly usage: {
     readonly model: string;
     readonly tokensIn: number;
@@ -103,8 +30,7 @@ export type InferenceCallSuccess<TOutput extends ZodTypeAny> = {
 };
 
 export type SerialisedInferenceRequest = {
-  readonly callKind: SdkCallKind;
-  readonly qualityTier: SdkQualityTier;
+  readonly templateId: string;
   readonly slots: Readonly<Record<string, unknown>>;
   readonly outputSchema: JsonSchema | undefined;
   readonly idempotencyKey: string | undefined;
@@ -112,37 +38,19 @@ export type SerialisedInferenceRequest = {
 
 export const INFERENCE_EVENT_PREFIX = 'inference.' as const;
 
-/**
- * Build the wire payload for an inference call. Surfaced as a pure
- * helper so the testkit can assert the serialised shape without
- * spinning a transport.
- */
 export const buildInferenceRequest = <TOutput extends ZodTypeAny>(
   input: InferenceCallInput<TOutput>,
 ): SerialisedInferenceRequest => ({
-  callKind: input.callKind,
-  qualityTier: input.qualityTier ?? 'standard',
+  templateId: input.templateId,
   slots: input.slots,
   outputSchema: input.output ? zodToJsonSchema(input.output) : undefined,
   idempotencyKey: input.idempotencyKey,
 });
 
-/**
- * The async `Session.inference` namespace. Each verb is bound by
- * `client.ts` to the live transport; the Runtime wires up the
- * server-side response under chunk B8a.
- */
+export type SdkQualityTier = QualityTier;
+
 export type SessionInference = {
   readonly call: <TOutput extends ZodTypeAny = ZodTypeAny>(
     input: InferenceCallInput<TOutput>,
   ) => Promise<Result<InferenceCallSuccess<TOutput>, SdkError>>;
-  readonly host: <TOutput extends ZodTypeAny = ZodTypeAny>(
-    input: Omit<InferenceCallInput<TOutput>, 'callKind'>,
-  ) => Promise<Result<InferenceCallSuccess<TOutput>, SdkError>>;
-  readonly judge: <TOutput extends ZodTypeAny = ZodTypeAny>(
-    input: Omit<InferenceCallInput<TOutput>, 'callKind'>,
-  ) => Promise<Result<InferenceCallSuccess<TOutput>, SdkError>>;
-  readonly classify: <TOutput extends ZodTypeAny = ZodTypeAny>(
-    input: Omit<InferenceCallInput<TOutput>, 'callKind'>,
-  ) => Promise<Result<InferenceCallSuccess<TOutput>, SdkError>>;
 };

package/src/time.ts

@@ -24,6 +24,10 @@ export type ServerTimeSource = {
   readonly recordedEvents: () => readonly RecordedEvent[];
   /** Internal: update the measured skew on a fresh pong. */
   readonly updateSkew: (skewMs: number) => void;
+  /** Freeze `serverNow()` while the session is paused. */
+  readonly freeze: () => void;
+  /** Resume advancing `serverNow()` after a pause. */
+  readonly unfreeze: () => void;
 };
 
 export type RecordedEvent = {
@@ -40,10 +44,14 @@ export const createServerTimeSource = (
 ): ServerTimeSource => {
   const nowFn = opts.now ?? (() => Date.now());
   let skew = 0;
+  let frozenServerNow: number | null = null;
   const events: RecordedEvent[] = [];
 
   return {
-    serverNow: () => nowFn() + skew,
+    serverNow: () => {
+      if (frozenServerNow !== null) return frozenServerNow;
+      return nowFn() + skew;
+    },
     recordEvent: (eventId) => {
       const clientTs = nowFn();
       events.push({ eventId, clientTs });
@@ -54,5 +62,13 @@ export const createServerTimeSource = (
     updateSkew: (newSkew) => {
       skew = newSkew;
     },
+    freeze: () => {
+      if (frozenServerNow === null) {
+        frozenServerNow = nowFn() + skew;
+      }
+    },
+    unfreeze: () => {
+      frozenServerNow = null;
+    },
   };
 };

package/src/voice.ts

@@ -47,6 +47,27 @@ export type SpeakSuccess = {
   readonly durationMs: number;
 };
 
+/** Optional beat metadata for in-phase TTS choreography (chunk B26). */
+export type TtsBeatReveal = {
+  readonly kind: 'none' | 'player_submission';
+  readonly playerId?: string;
+};
+
+export type TtsBeatMeta = {
+  readonly beatId: string;
+  readonly sequence: number;
+  readonly reveal?: TtsBeatReveal;
+};
+
+/** Wire shape on `voice.audio` events (Host + Experience bundles). */
+export type VoiceAudioPayload = SpeakSuccess & {
+  readonly id?: string;
+  readonly causeMessageId?: string;
+  readonly caption?: string | null;
+  readonly beat?: TtsBeatMeta;
+  readonly cues?: ReadonlyArray<{ readonly at: number; readonly kind: string }>;
+};
+
 export type SessionVoice = {
   readonly speak: (input: SpeakInput) => Promise<Result<SpeakSuccess, SdkError>>;
 };