@wireai/activation 0.13.6-next.0 → 0.14.0

package/src/utils/readPlan.ts

@@ -1,10 +1,10 @@
 /**
  * readPlan — lift the backend's onboarding plan off the message thread.
  *
- * WHY IT EXISTS. On the AI path the server appends a SECOND A2A DataPart to the turn it finishes
- * on: `{ kind: "onboarding_plan", plan: {...} }`, alongside the component envelope the renderer
- * already consumes. The kit carries that payload out through `OnboardingResult.plan` and stops
- * there. It does NOT interpret it, does NOT validate its fields, does NOT log it and does NOT
+ * WHY IT EXISTS. When it sends a plan, the server appends a SECOND A2A DataPart to the turn it
+ * finishes on: `{ kind: "onboarding_plan", plan: {...} }`, alongside the component envelope the
+ * renderer already consumes. The kit carries that payload out through `OnboardingResult.plan` and
+ * stops there. It does NOT interpret it, does NOT validate its fields, does NOT log it and does NOT
  * attach it to any event — the plan is user-derived content, and deciding what it MEANS is the
  * host's job (the kit/host boundary in `ai_rules/context_map.md`: the kit ends at the completion
  * CTA).
@@ -19,14 +19,24 @@
  * so a throw here would cost the user the completion of an onboarding they already finished. Every
  * step below is a runtime-guarded read.
  *
- * The static (non-AI) flow carries no plan at all. That path is unchanged and fully supported.
+ * WHICH RUNS CARRY A PLAN IS THE BACKEND'S CONFIGURATION, NOT THE KIT'S. This reader matches the
+ * `kind` MARKER below and never the flow that produced the turn, so it needs no knowledge of how
+ * the tenant is configured. A run that carries no plan yields `undefined`: unchanged, and fully
+ * supported.
  */
 import type { Message } from "wireai-rn";
 
 /**
- * The read-back member the SDK surfaces for every A2A DataPart past the first, in wire order and
- * uninterpreted. Declared HERE, structurally, because the installed `wireai-rn` peer (0.2.4) does
- * not declare it on `Message` yet.
+ * The read-back member the SDK surfaces for every A2A DataPart past the first, uninterpreted.
+ *
+ * NOT in wire order, and nothing here may assume it is. The SDK FLATTENS a task's parts across
+ * agent messages LATEST-FIRST (and then artifacts latest-first) before dropping the first one, so
+ * this array is a cross-message collection, not one turn's parts in the order they arrived. On a
+ * task carrying history, a previous turn's component envelope lands here beside this turn's plan.
+ * `readPlan` is safe from that because it matches the `kind` MARKER below, never a position.
+ *
+ * Declared HERE, structurally, because the installed `wireai-rn` peer (0.2.4) does not declare it
+ * on `Message` yet.
  *
  * TODO(re-pin): delete this local type and read the member straight off `Message` once a
  * `wireai-rn` that declares it is published and the peer range is re-pinned. Until then the two
@@ -58,8 +68,14 @@ const planFromPart = (part: unknown): unknown => {
  *
  * ORDERING, stated so it is not undefined behavior: the thread is scanned NEWEST TURN FIRST, so a
  * thread carrying two plans resolves to the LAST one — the same turn `handleFinish` completes on.
- * Within a single turn, wire order decides: the first well-formed plan part wins. A malformed part
- * is skipped rather than treated as a terminator, so a broken payload can never shadow a good one.
+ *
+ * Inside one message's `dataParts` the first WELL-FORMED plan part wins, and that is a scan order,
+ * NOT a wire-order guarantee. Wire order does not hold even within a single turn: `dataParts` is
+ * the SDK's flattened, cross-agent-message collection (latest-first, see `WithDataParts` above), so
+ * on a task carrying history a previous turn's parts sit in the same array. This is exactly why the
+ * match is on the `onboarding_plan` MARKER and never on a position. A part that is not a
+ * well-formed plan is skipped rather than treated as a terminator, so neither a stale envelope nor
+ * a broken payload can shadow a good plan.
  */
 export const readPlan = (messages: readonly Message[]): unknown => {
   for (let i = messages.length - 1; i >= 0; i--) {

package/src/utils/readProgress.ts

@@ -18,6 +18,8 @@ type PartialProgress = {
   /** The stable per-slot identity, when the backend sends one. See `OnboardingProgress.slot_id`. */
   slot_id?: string;
   skippable?: boolean;
+  /** The experiment arm assigned to this session, when the tenant runs one. See `OnboardingProgress.variant`. */
+  variant?: string;
 };
 
 export const readProgress = (response?: WireAIResponse): PartialProgress => {
@@ -33,5 +35,8 @@ export const readProgress = (response?: WireAIResponse): PartialProgress => {
     // Whitelisted the same way as every other field: an old backend simply omits it.
     slot_id: typeof p.slot_id === "string" ? p.slot_id : undefined,
     skippable: typeof p.skippable === "boolean" ? p.skippable : undefined,
+    // Whitelisted like the rest: a non-string (or absent) arm key reads as "no experiment", never
+    // as an error. The kit does not interpret the value — see `OnboardingProgress.variant`.
+    variant: typeof p.variant === "string" ? p.variant : undefined,
   };
 };