@pouchy_ai/world-sdk 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @pouchy_ai/world-sdk
 
+## 0.23.0
+
+- **`runTurn` gains `focusRoles?: string[]`** — narrow one beat to the named
+  roles: an interview, a one-on-one scene, a whispered aside. Before this,
+  every caller beat ran (and billed) every bound role up to the server cap,
+  and a one-on-one scene was impossible to express through the API.
+- **Shrink-only.** The server intersects the focus with the bound story cast,
+  mirroring the event lane's subscription routing: it can never widen a beat
+  past the roles the story declares or past the server's own cap. A focus
+  that matches no bound role is refused as `no selectable role` and spends
+  nothing.
+- Roles outside the focus are **not run and not billed**; the result's
+  `skippedRoles` records each as `'not focused'` — a new member of the skip
+  vocabulary — so the readback stays honest about who was passed over.
+- Absent or empty means every bound role answers, exactly as before. No
+  existing call changes behaviour.
+- Server-side this is world API 1.29.0.
+
 ## 0.22.0
 
 - **`startNextEpisode(environmentId, worldInstanceId)`** — start the next

package/README.md

@@ -115,6 +115,23 @@ await world.runTurn({
 no single commit for a deterministic write to ride, and sending patches to one
 answers 422 rather than dropping them quietly.
 
+**Focusing a beat on some of the cast.** By default every bound role answers a
+beat (up to the server cap). For an interview or a one-on-one scene, pass
+`focusRoles` and only those roles run — the rest are not billed and are
+recorded in `skippedRoles` as `'not focused'`:
+
+```ts
+const beat = await world.runTurn({
+  environmentId, worldInstanceId,
+  text: 'Amara, what did you see?',
+  focusRoles: ['amara']
+});
+```
+
+Shrink-only: the server intersects the focus with the bound story cast, so it
+can never widen a beat, and a focus matching no bound role is refused as
+`no selectable role` without spending anything.
+
 **Resuming after a crash.** `getTurn` returns the same fields the live result
 did — `nextOptions` included — so a recovered session can offer the audience
 the choices it was about to. To catch up on beats you missed entirely, store

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  *  a project is running — which is exactly the field you reach for when a
  *  customer's integration behaves like an older SDK than they say they have.
  *  It sat at '0.1.0' for eight releases before anything compared the two. */
-export declare const WORLD_SDK_VERSION = "0.22.0";
+export declare const WORLD_SDK_VERSION = "0.23.0";
 export declare const DEFAULT_BASE_URL = "https://pouchy.ai/v1";
 /** One direction a beat could take. The WHOLE of what a deliberation shows a
  *  player: no reasoning, no role secrets, no simulated effects, no scores. */
@@ -1320,6 +1320,15 @@ export declare class PouchyWorldClient {
         turnId?: string;
         text: string;
         sourceRoleId?: string;
+        /** Narrow this beat to the named roles — an interview, a one-on-one
+         *  scene, a whispered aside. Shrink-only: the server intersects it with
+         *  the bound story cast, so it can never widen the beat past the roles
+         *  the story declares or the server's own cap. Roles outside the focus
+         *  are not run and not billed; they appear in the result's
+         *  `skippedRoles` as `'not focused'`. A focus that matches no bound
+         *  role is refused as "no selectable role" and spends nothing. Absent
+         *  or empty means every bound role answers, exactly as before. */
+        focusRoles?: readonly string[];
         traceId?: string;
         /** PROVIDER-authored state changes, committed with this beat.
          *

package/dist/index.js

@@ -23,7 +23,7 @@ import { createHash, createHmac, randomUUID } from 'node:crypto';
  *  a project is running — which is exactly the field you reach for when a
  *  customer's integration behaves like an older SDK than they say they have.
  *  It sat at '0.1.0' for eight releases before anything compared the two. */
-export const WORLD_SDK_VERSION = '0.22.0';
+export const WORLD_SDK_VERSION = '0.23.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1';
 /** Read the commit turn id out of an envelope, so the signature covers the id
  *  the server will commit under. The payload half is base64url JSON; the
@@ -700,6 +700,7 @@ export class PouchyWorldClient {
                 kind: 'user',
                 text: input.text,
                 ...(input.sourceRoleId ? { sourceRoleId: input.sourceRoleId } : {}),
+                ...(input.focusRoles?.length ? { focusRoles: [...input.focusRoles] } : {}),
                 ...(input.proposedPatches ? { proposedPatches: input.proposedPatches } : {})
             },
             ...(input.traceId ? { traceId: input.traceId } : {})

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pouchy_ai/world-sdk",
-	"version": "0.22.0",
+	"version": "0.23.0",
 	"description": "Server-side TypeScript client for Pouchy World \u2014 story packages, world definitions, world sessions, coordinated turns, trusted events, replay verification and script drafts. Node only: it holds a project Secret Key and a source signing key, which never belong in a browser or a mobile app.",
 	"type": "module",
 	"license": "SEE LICENSE IN LICENSE",