@pouchy_ai/world-sdk 0.22.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @pouchy_ai/world-sdk
 
+## 0.24.0
+
+- **`startNextEpisode` now rides the MACHINE lane** (Secret Key + provider
+  signature, id namespace `epn:`) — the same two proofs as `runTurn` — so an
+  unattended serial backend can advance its own player's worldline. Before
+  this it required the expiring owner token, which made serial UX impossible
+  for an integrator: the backend that drives every beat of the story could
+  not move it to the next episode (#2998).
+- The method signature is unchanged (`startNextEpisode(environmentId,
+  worldInstanceId)`); an optional `{ requestId }` third argument pins the
+  signature id slot for callers that want to supply their own.
+- The server still accepts the owner lane, and still exposes no `/admin`
+  mirror — an admin key proves the project, never the Provider.
+- Idempotence is untouched: the run id stays server-derived from the
+  worldline, the episode and the revision it starts at; `requestId` is a
+  signature slot, not an idempotency key.
+- Server-side this is world API 1.30.0.
+
+## 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

@@ -45,7 +45,10 @@ const world = new PouchyWorldClient({
 **Authoring** — `createStoryPackage`, `publishStoryPackage`, `getStoryPackage`,
 `listStoryPackages`, `createWorld`, `publishWorld`, `getWorld`, `listWorlds`.
 
-**Running** — `createWorldSession`, `runTurn`, `sendEvent`.
+**Running** — `createWorldSession`, `runTurn`, `sendEvent`,
+`startNextEpisode` (machine lane since 0.24.0 — an unattended serial backend
+can advance its own player's worldline to the next episode and receive the
+carryover).
 
 **Deliberating** — `deliberate`, `selectCandidate`. Ask for a couple of public
 directions a beat could take, then commit the one the player picked. Off unless
@@ -115,6 +118,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.24.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. */
@@ -1032,10 +1032,17 @@ export declare class PouchyWorldClient {
      *  revision it starts at, so a retried call lands on the same run and
      *  answers `created: false` rather than forking the story.
      *
-     *  OWNER TOKEN ONLY — no `/admin` mirror, on the same reasoning as
-     *  `preflightWorld`: the mirror carries reads, and this is the write that
-     *  decides a story moves on. */
-    startNextEpisode(environmentId: string, worldInstanceId: string): Promise<WorldNextEpisodeResponse>;
+     *  MACHINE LANE since 0.24.0 (#2998, world API 1.30.0): a Secret Key plus a
+     *  provider signature in the `epn:` namespace — the same two proofs as
+     *  `runTurn`, because the party trusted to author every beat, including the
+     *  one that ends an episode, is the party deciding the story moves on. So
+     *  an unattended serial backend can now advance its own player's worldline.
+     *  (Before 0.24.0 this rode the owner token; the server still accepts that
+     *  lane, and still exposes no `/admin` mirror — an admin key proves the
+     *  project, never the Provider.) */
+    startNextEpisode(environmentId: string, worldInstanceId: string, opts?: {
+        requestId?: string;
+    }): Promise<WorldNextEpisodeResponse>;
     /** Publish the next world revision. Existing world INSTANCES keep the
      *  revision they were created on — a published change reaches new instances
      *  only, which is what keeps a running story from changing runtime or rules
@@ -1320,6 +1327,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.24.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
@@ -356,11 +356,20 @@ export class PouchyWorldClient {
      *  revision it starts at, so a retried call lands on the same run and
      *  answers `created: false` rather than forking the story.
      *
-     *  OWNER TOKEN ONLY — no `/admin` mirror, on the same reasoning as
-     *  `preflightWorld`: the mirror carries reads, and this is the write that
-     *  decides a story moves on. */
-    startNextEpisode(environmentId, worldInstanceId) {
-        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/episodes/next`, {});
+     *  MACHINE LANE since 0.24.0 (#2998, world API 1.30.0): a Secret Key plus a
+     *  provider signature in the `epn:` namespace — the same two proofs as
+     *  `runTurn`, because the party trusted to author every beat, including the
+     *  one that ends an episode, is the party deciding the story moves on. So
+     *  an unattended serial backend can now advance its own player's worldline.
+     *  (Before 0.24.0 this rode the owner token; the server still accepts that
+     *  lane, and still exposes no `/admin` mirror — an admin key proves the
+     *  project, never the Provider.) */
+    startNextEpisode(environmentId, worldInstanceId, opts = {}) {
+        const requestId = opts.requestId ?? newTurnId('epn-req');
+        return this.signed(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/episodes/next`, { requestId }, 
+        // Namespaced id slot: an episode-start signature can never be
+        // replayed onto the turn door, the events ingress or a deliberation.
+        `epn:${requestId}`);
     }
     /** Publish the next world revision. Existing world INSTANCES keep the
      *  revision they were created on — a published change reaches new instances
@@ -700,6 +709,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.24.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",