@mattstack/rt-client 0.26.0 → 0.27.0

package/dist/commands.d.ts

@@ -108,6 +108,7 @@ export type GateOption = string | {
     value: string;
     label: string;
     recommended?: boolean;
+    description?: string;
 };
 export interface GateOrigin {
     paneId?: string;
@@ -117,11 +118,14 @@ export interface GateOrigin {
     surface?: string;
     presentation?: "form" | "wait";
 }
+/** `context` is per-question material (what this one choice turns on);
+    the gate-level `context` on the open/ask payload is the whole ask's. */
 export interface GateQuestion {
     id: string;
     label: string;
     multi: boolean;
     options: GateOption[];
+    context?: string;
 }
 /** Implementations live in gate-options.ts (the browser-safe ./gate
     subpath); re-exported here so existing commands.ts/index.ts consumers
@@ -1506,9 +1510,10 @@ export interface Commands {
                 worktree?: string;
             };
         };
-        /** `contextOmitted` appears only when the caller's context exceeded the
-            8192-byte cap and was dropped: the gate still opened, but with none of
-            the material the reader needs. */
+        /** `contextOmitted` appears only when the gate context plus every
+            question's `context` exceeded their shared 8192-byte budget: the
+            gate still opened, but question contexts were dropped, and the gate
+            context too when it was over the budget on its own. */
         data: {
             id: string;
             presentation: "form" | "wait";

package/dist/gate-options.d.ts

@@ -5,6 +5,9 @@ import type { GateOption, GateQuestion } from "./commands.ts";
 export interface GateOptionObject {
     value: string;
     label: string;
+    /** Per-option explanation, carried verbatim: never capitalized, never
+        suffixed, never filled in from value/label. */
+    description?: string;
 }
 export declare function gateOptionValue(o: GateOption): string;
 export declare function gateOptionLabel(o: GateOption): string;
@@ -17,8 +20,13 @@ export declare function gateOptionLabel(o: GateOption): string;
     word-like (see isWordLikeLabel), and an object form's `recommended:
     true` lifts into a " (Recommended)" label suffix -- guarded against
     double-appending -- since `recommended` itself does not survive into
-    the returned object; the suffix IS its wire representation. Every
-    returned entry is a full {value,label} pair -- callers may trust the
-    return type without re-checking it. Pure and order-preserving. */
+    the returned object; the suffix IS its wire representation. An object
+    form's non-empty string `description` rides along untouched (no
+    capitalization, no suffix); any other description shape is dropped.
+    Every returned entry is a full {value,label} pair -- callers may trust
+    the return type without re-checking it. Pure and order-preserving. */
 export declare function normalizeGateOptions(options: GateOption[]): GateOptionObject[];
+/** Options normalize per normalizeGateOptions; a question's `context` is
+    kept verbatim when it is a non-blank string and dropped otherwise, so a
+    stored row never carries an empty or non-string context key. */
 export declare function normalizeGateQuestions(questions: GateQuestion[]): GateQuestion[];

package/dist/gate.js

@@ -33,11 +33,18 @@ function normalizeGateOptions(options) {
     label = capitalize(label);
     if (recommended && label && !HAS_RECOMMENDED_SUFFIX.test(label))
       label += RECOMMENDED_SUFFIX;
-    return { value, label };
+    const d = o !== null && typeof o === "object" ? o.description : undefined;
+    return typeof d === "string" && d ? { value, label, description: d } : { value, label };
   });
 }
 function normalizeGateQuestions(questions) {
-  return questions.map((q) => ({ ...q, options: normalizeGateOptions(q.options) }));
+  return questions.map((q) => {
+    const { context, ...rest } = q;
+    const out = { ...rest, options: normalizeGateOptions(q.options) };
+    if (typeof context === "string" && context.trim())
+      out.context = context;
+    return out;
+  });
 }
 
 // src/gate-answers.ts

package/dist/index.js

@@ -493,11 +493,18 @@ function normalizeGateOptions(options) {
     label = capitalize(label);
     if (recommended && label && !HAS_RECOMMENDED_SUFFIX.test(label))
       label += RECOMMENDED_SUFFIX;
-    return { value, label };
+    const d = o !== null && typeof o === "object" ? o.description : undefined;
+    return typeof d === "string" && d ? { value, label, description: d } : { value, label };
   });
 }
 function normalizeGateQuestions(questions) {
-  return questions.map((q) => ({ ...q, options: normalizeGateOptions(q.options) }));
+  return questions.map((q) => {
+    const { context, ...rest } = q;
+    const out = { ...rest, options: normalizeGateOptions(q.options) };
+    if (typeof context === "string" && context.trim())
+      out.context = context;
+    return out;
+  });
 }
 
 // src/commands.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mattstack/rt-client",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "type": "module",
   "exports": {
     ".": {

package/src/commands.ts

@@ -97,7 +97,7 @@ export const GATE_BY_PANE = "pane";
 export type GateStatus = "open" | "answered" | "parked" | "closed";
 /** Reconciler's view of an agent's liveness; also the value `GateRow.executor` is stamped with. */
 export type ExecutorState = "live" | "blocked" | "hidden" | "gone" | "cleared" | "unknown";
-export type GateOption = string | { value: string; label: string; recommended?: boolean };
+export type GateOption = string | { value: string; label: string; recommended?: boolean; description?: string };
 export interface GateOrigin {
   paneId?: string;
   tabId?: string;
@@ -106,7 +106,9 @@ export interface GateOrigin {
   surface?: string;
   presentation?: "form" | "wait";
 }
-export interface GateQuestion { id: string; label: string; multi: boolean; options: GateOption[] }
+/** `context` is per-question material (what this one choice turns on);
+    the gate-level `context` on the open/ask payload is the whole ask's. */
+export interface GateQuestion { id: string; label: string; multi: boolean; options: GateOption[]; context?: string }
 /** Implementations live in gate-options.ts (the browser-safe ./gate
     subpath); re-exported here so existing commands.ts/index.ts consumers
     are unaffected. */
@@ -711,9 +713,10 @@ export interface Commands {
       agent?: string;
       origin?: { surface?: string; tabId?: string; worktree?: string };
     };
-    /** `contextOmitted` appears only when the caller's context exceeded the
-        8192-byte cap and was dropped: the gate still opened, but with none of
-        the material the reader needs. */
+    /** `contextOmitted` appears only when the gate context plus every
+        question's `context` exceeded their shared 8192-byte budget: the
+        gate still opened, but question contexts were dropped, and the gate
+        context too when it was over the budget on its own. */
     data: { id: string; presentation: "form" | "wait"; subject: string; supersededId: string | null; contextOmitted?: true };
   };
   /**

package/src/gate-options.ts

@@ -6,6 +6,9 @@ import type { GateOption, GateQuestion } from "./commands.ts";
 export interface GateOptionObject {
   value: string;
   label: string;
+  /** Per-option explanation, carried verbatim: never capitalized, never
+      suffixed, never filled in from value/label. */
+  description?: string;
 }
 
 export function gateOptionValue(o: GateOption): string {
@@ -45,9 +48,11 @@ function capitalize(label: string): string {
     word-like (see isWordLikeLabel), and an object form's `recommended:
     true` lifts into a " (Recommended)" label suffix -- guarded against
     double-appending -- since `recommended` itself does not survive into
-    the returned object; the suffix IS its wire representation. Every
-    returned entry is a full {value,label} pair -- callers may trust the
-    return type without re-checking it. Pure and order-preserving. */
+    the returned object; the suffix IS its wire representation. An object
+    form's non-empty string `description` rides along untouched (no
+    capitalization, no suffix); any other description shape is dropped.
+    Every returned entry is a full {value,label} pair -- callers may trust
+    the return type without re-checking it. Pure and order-preserving. */
 export function normalizeGateOptions(options: GateOption[]): GateOptionObject[] {
   return options.map((o) => {
     const recommended = o !== null && typeof o === "object" && (o as { recommended?: unknown }).recommended === true;
@@ -70,10 +75,19 @@ export function normalizeGateOptions(options: GateOption[]): GateOptionObject[]
     // downstream `label || value` fallback (gate-kit) must still see label
     // as absent, not as a non-empty "(Recommended)" that hides the value.
     if (recommended && label && !HAS_RECOMMENDED_SUFFIX.test(label)) label += RECOMMENDED_SUFFIX;
-    return { value, label };
+    const d = o !== null && typeof o === "object" ? (o as { description?: unknown }).description : undefined;
+    return typeof d === "string" && d ? { value, label, description: d } : { value, label };
   });
 }
 
+/** Options normalize per normalizeGateOptions; a question's `context` is
+    kept verbatim when it is a non-blank string and dropped otherwise, so a
+    stored row never carries an empty or non-string context key. */
 export function normalizeGateQuestions(questions: GateQuestion[]): GateQuestion[] {
-  return questions.map((q) => ({ ...q, options: normalizeGateOptions(q.options) }));
+  return questions.map((q) => {
+    const { context, ...rest } = q;
+    const out: GateQuestion = { ...rest, options: normalizeGateOptions(q.options) };
+    if (typeof context === "string" && context.trim()) out.context = context;
+    return out;
+  });
 }