@ishlabs/cli 0.13.0 → 0.14.1

package/dist/lib/local-sim/types.d.ts

@@ -56,6 +56,13 @@ export interface ForwardEntry {
     type: string;
     content: string;
 }
+export interface LocalTabInfo {
+    id: string;
+    url: string;
+    title: string;
+    active: boolean;
+    opener_id: string | null;
+}
 export interface LocalSimStepRequest {
     tester_id: string;
     product_id: string;
@@ -76,6 +83,7 @@ export interface LocalSimStepRequest {
     dom_model: string | null;
     llm_provider: string | null;
     user_instruction?: string | null;
+    tabs?: LocalTabInfo[];
 }
 export interface LocalStepAction {
     type: string;
@@ -93,6 +101,9 @@ export interface LocalStepAction {
     count: number | null;
     duration_ms: number | null;
     thoughts: string | null;
+    modifiers: string[] | null;
+    key: string | null;
+    tab_id: string | null;
 }
 /** Raw backend step response — output is nested, actions are separate. */
 export interface LocalSimStepResponseRaw {
@@ -121,6 +132,9 @@ export interface LocalSimStepResponseRaw {
                 count?: number;
                 duration_ms?: number;
                 thoughts?: string;
+                modifiers?: string[];
+                key?: string;
+                tab_id?: string;
             }>;
         };
     };
@@ -168,6 +182,7 @@ export interface RecordInteraction {
     actions: ActionData[];
     current_location: string | null;
     assignment_completed: boolean;
+    tabs?: LocalTabInfo[];
 }
 export interface AssignmentStatusUpdate {
     assignment_id: string;

package/dist/lib/modality.d.ts

@@ -21,7 +21,75 @@ export declare function isChatModality(modality: string | undefined): boolean;
  */
 export declare function iterationHasContent(details: unknown, modality: string | undefined): boolean;
 /** The flag fragment a user should pass to populate content for a given modality. */
-export declare function describeRequiredContentFlag(modality: string): string;
+export declare function describeRequiredContentFlag(modality: string, chatMode?: ChatMode): string;
+/**
+ * Chat mode discriminator. Lives inside `iteration.details.mode_details.mode`
+ * once the backend migration has run. CLI code that pre-dates the migration
+ * may still encounter top-level chat keys (`endpoint`, `chatbot_endpoint_id`);
+ * the read helpers below fall back to that legacy shape and treat it as
+ * `external_chatbot`.
+ */
+declare const CHAT_MODES: readonly ["external_chatbot", "tester_pair"];
+export type ChatMode = typeof CHAT_MODES[number];
+/**
+ * Normalise user-supplied `--chat-mode` values. Accepts both `tester_pair`
+ * (canonical) and `tester-pair` (hyphenated — matches CLI flag convention
+ * elsewhere in `ish`); same for `external-chatbot`. Returns `null` for
+ * anything unrecognised so callers can throw a clean ValidationError.
+ */
+export declare function normalizeChatMode(raw: string | undefined): ChatMode | null;
+/** Read the chat mode discriminator, defaulting to `external_chatbot` for legacy payloads. */
+export declare function readChatMode(details: unknown): ChatMode;
+/**
+ * Extract the external-chatbot endpoint reference from chat details.
+ * Reads from `mode_details` first, then falls back to top-level keys for
+ * back-compat with legacy iteration payloads.
+ */
+export declare function readExternalChatbotEndpoint(details: unknown): {
+    endpoint?: Record<string, unknown>;
+    chatbot_endpoint_id?: string;
+};
+/**
+ * Extract the tester-pair payload from chat details. Returns `undefined` if
+ * `mode_details.mode !== "tester_pair"`. Does not validate equal lengths or
+ * non-empty scenarios — that's the caller's job (see `iterationHasContent`
+ * and `validateIterationDetails`).
+ */
+export declare function readTesterPairConfig(details: unknown): {
+    audience_a: string[];
+    audience_b: string[];
+    scenario_a: string;
+    scenario_b: string;
+    initiator_side: "a" | "b";
+    role_criteria_a?: Record<string, unknown>;
+    role_criteria_b?: Record<string, unknown>;
+} | undefined;
+/**
+ * RoleCriteria — persona-first filter that resolves a tester-profile pool
+ * for one side of a tester_pair iteration. Mirrors the backend Pydantic
+ * shape in `app/api/models/iterations.py:RoleCriteria` (swift-charm plan).
+ * All fields optional; an empty object is treated as "no filter".
+ */
+export declare const ROLE_CRITERIA_KEYS: readonly ["occupation", "min_age", "max_age", "gender", "country", "education_level_in", "household_in", "locale_type_in", "income_level_in", "employment_status_in", "requires_captions", "uses_screen_reader", "prefers_reduced_motion", "prefers_high_contrast", "has_any_accessibility_need"];
+export type RoleCriteriaKey = typeof ROLE_CRITERIA_KEYS[number];
+/**
+ * Validate a parsed role-criteria object client-side. Whitelists known
+ * keys (typo guard — catches `occupations` vs `occupation`), type-checks
+ * each field, and returns the cleaned object. Throws a descriptive Error
+ * on the first violation. Returns `undefined` for `undefined` input so
+ * callers can `validateRoleCriteria(opts.roleCriteriaA)` without a guard.
+ *
+ * Mirrors the backend Pydantic check shape-for-shape; surfacing locally
+ * costs less than a round-trip and gives agents the same error contract
+ * they get for other CLI inputs (exit 2, ValidationError).
+ */
+export declare function validateRoleCriteria(raw: unknown, flagName: string): Record<string, unknown> | undefined;
+/**
+ * Pretty-print a role criteria object as a single-line summary for human
+ * output (confirmation block, iteration get renderer). Returns `""` when
+ * the object is empty / undefined so callers can compose safely.
+ */
+export declare function summarizeRoleCriteria(criteria: Record<string, unknown> | undefined): string;
 export type DetailsValidation = {
     ok: true;
 } | {
@@ -40,3 +108,4 @@ export type DetailsValidation = {
  * boundary.
  */
 export declare function validateIterationDetails(modality: string | undefined, details: unknown): DetailsValidation;
+export {};

package/dist/lib/modality.js

@@ -7,6 +7,7 @@
  * and the call sites (`study run`, `iteration update`, ...) pick up the
  * change for free.
  */
+import { normalizeEnumValue } from "./enums.js";
 import { MEDIA_MODALITIES } from "./types.js";
 /** True for the media-bucket modalities that share batch + content semantics. */
 export function isMediaModality(modality) {
@@ -42,18 +43,44 @@ export function iterationHasContent(details, modality) {
         return false;
     }
     if (modality === "chat") {
-        // A chat iteration carries either an inline endpoint config or a
-        // pointer to a saved chatbot_endpoints row.
-        const hasEndpoint = !!d.endpoint && typeof d.endpoint === "object";
-        const hasEndpointId = typeof d.chatbot_endpoint_id === "string"
-            && d.chatbot_endpoint_id.length > 0;
-        return hasEndpoint || hasEndpointId;
+        const mode = readChatMode(details);
+        if (mode === "tester_pair") {
+            const pair = readTesterPairConfig(details);
+            if (!pair)
+                return false;
+            // Each side needs *either* an explicit audience or a role-criteria
+            // filter. Scenarios are always required (they're how the persona
+            // gets a role to inhabit).
+            const sideAHasAudience = pair.audience_a.length > 0 || !!pair.role_criteria_a;
+            const sideBHasAudience = pair.audience_b.length > 0 || !!pair.role_criteria_b;
+            if (!sideAHasAudience || !sideBHasAudience)
+                return false;
+            if (pair.scenario_a.length === 0 || pair.scenario_b.length === 0)
+                return false;
+            // Equal-length pairing is only enforced when *both* sides ship an
+            // explicit audience. Criteria-driven sides are resolved server-side
+            // and persisted back to audience_*; until then the lengths may
+            // legitimately differ (or be zero).
+            const bothAudiencesExplicit = pair.audience_a.length > 0
+                && pair.audience_b.length > 0
+                && !pair.role_criteria_a
+                && !pair.role_criteria_b;
+            if (bothAudiencesExplicit && pair.audience_a.length !== pair.audience_b.length) {
+                return false;
+            }
+            return true;
+        }
+        // external_chatbot: an inline endpoint config or a pointer to a saved
+        // chatbot_endpoints row. Check `mode_details` first; fall back to the
+        // legacy top-level keys for iterations that pre-date the backend migration.
+        const ep = readExternalChatbotEndpoint(details);
+        return !!ep.endpoint || !!ep.chatbot_endpoint_id;
     }
     // interactive (default)
     return typeof d.url === "string" && d.url.length > 0;
 }
 /** The flag fragment a user should pass to populate content for a given modality. */
-export function describeRequiredContentFlag(modality) {
+export function describeRequiredContentFlag(modality, chatMode) {
     if (modality === "text")
         return "--content-text <text-or-@file>";
     if (modality === "video" || modality === "audio" || modality === "document") {
@@ -61,10 +88,226 @@ export function describeRequiredContentFlag(modality) {
     }
     if (modality === "image")
         return "--image-urls <comma-separated>";
-    if (modality === "chat")
+    if (modality === "chat") {
+        if (chatMode === "tester_pair") {
+            return "--chat-mode tester_pair (--audience-a <ids> | --role-criteria-a <json-or-@file>) (--audience-b <ids> | --role-criteria-b <json-or-@file>) --scenario-a <text-or-@file> --scenario-b <text-or-@file>";
+        }
         return "--endpoint <id> | --endpoint-config <file>";
+    }
     return "--url <url>";
 }
+/**
+ * Chat mode discriminator. Lives inside `iteration.details.mode_details.mode`
+ * once the backend migration has run. CLI code that pre-dates the migration
+ * may still encounter top-level chat keys (`endpoint`, `chatbot_endpoint_id`);
+ * the read helpers below fall back to that legacy shape and treat it as
+ * `external_chatbot`.
+ */
+const CHAT_MODES = ["external_chatbot", "tester_pair"];
+/**
+ * Normalise user-supplied `--chat-mode` values. Accepts both `tester_pair`
+ * (canonical) and `tester-pair` (hyphenated — matches CLI flag convention
+ * elsewhere in `ish`); same for `external-chatbot`. Returns `null` for
+ * anything unrecognised so callers can throw a clean ValidationError.
+ */
+export function normalizeChatMode(raw) {
+    return normalizeEnumValue(raw, CHAT_MODES);
+}
+/** Read the chat mode discriminator, defaulting to `external_chatbot` for legacy payloads. */
+export function readChatMode(details) {
+    if (!details || typeof details !== "object")
+        return "external_chatbot";
+    const md = details.mode_details;
+    if (md && typeof md === "object") {
+        const mode = md.mode;
+        if (mode === "tester_pair")
+            return "tester_pair";
+        if (mode === "external_chatbot")
+            return "external_chatbot";
+    }
+    return "external_chatbot";
+}
+/**
+ * Extract the external-chatbot endpoint reference from chat details.
+ * Reads from `mode_details` first, then falls back to top-level keys for
+ * back-compat with legacy iteration payloads.
+ */
+export function readExternalChatbotEndpoint(details) {
+    if (!details || typeof details !== "object")
+        return {};
+    const d = details;
+    const md = d.mode_details && typeof d.mode_details === "object"
+        ? d.mode_details
+        : undefined;
+    const endpoint = (md?.endpoint && typeof md.endpoint === "object")
+        ? md.endpoint
+        : (d.endpoint && typeof d.endpoint === "object")
+            ? d.endpoint
+            : undefined;
+    const idRaw = (typeof md?.chatbot_endpoint_id === "string" && md.chatbot_endpoint_id.length > 0)
+        ? md.chatbot_endpoint_id
+        : (typeof d.chatbot_endpoint_id === "string" && d.chatbot_endpoint_id.length > 0)
+            ? d.chatbot_endpoint_id
+            : undefined;
+    return {
+        ...(endpoint && { endpoint }),
+        ...(idRaw && { chatbot_endpoint_id: idRaw }),
+    };
+}
+/**
+ * Extract the tester-pair payload from chat details. Returns `undefined` if
+ * `mode_details.mode !== "tester_pair"`. Does not validate equal lengths or
+ * non-empty scenarios — that's the caller's job (see `iterationHasContent`
+ * and `validateIterationDetails`).
+ */
+export function readTesterPairConfig(details) {
+    if (!details || typeof details !== "object")
+        return undefined;
+    const md = details.mode_details;
+    if (!md || typeof md !== "object")
+        return undefined;
+    const m = md;
+    if (m.mode !== "tester_pair")
+        return undefined;
+    const audA = Array.isArray(m.audience_a) ? m.audience_a.filter((x) => typeof x === "string") : [];
+    const audB = Array.isArray(m.audience_b) ? m.audience_b.filter((x) => typeof x === "string") : [];
+    const scenA = typeof m.scenario_a === "string" ? m.scenario_a : "";
+    const scenB = typeof m.scenario_b === "string" ? m.scenario_b : "";
+    const init = m.initiator_side === "b" ? "b" : "a";
+    const critA = (m.role_criteria_a && typeof m.role_criteria_a === "object" && !Array.isArray(m.role_criteria_a))
+        ? m.role_criteria_a
+        : undefined;
+    const critB = (m.role_criteria_b && typeof m.role_criteria_b === "object" && !Array.isArray(m.role_criteria_b))
+        ? m.role_criteria_b
+        : undefined;
+    return {
+        audience_a: audA,
+        audience_b: audB,
+        scenario_a: scenA,
+        scenario_b: scenB,
+        initiator_side: init,
+        ...(critA && { role_criteria_a: critA }),
+        ...(critB && { role_criteria_b: critB }),
+    };
+}
+/**
+ * RoleCriteria — persona-first filter that resolves a tester-profile pool
+ * for one side of a tester_pair iteration. Mirrors the backend Pydantic
+ * shape in `app/api/models/iterations.py:RoleCriteria` (swift-charm plan).
+ * All fields optional; an empty object is treated as "no filter".
+ */
+export const ROLE_CRITERIA_KEYS = [
+    "occupation",
+    "min_age",
+    "max_age",
+    "gender",
+    "country",
+    "education_level_in",
+    "household_in",
+    "locale_type_in",
+    "income_level_in",
+    "employment_status_in",
+    "requires_captions",
+    "uses_screen_reader",
+    "prefers_reduced_motion",
+    "prefers_high_contrast",
+    "has_any_accessibility_need",
+];
+const ROLE_CRITERIA_LIST_KEYS = new Set([
+    "occupation",
+    "gender",
+    "country",
+    "education_level_in",
+    "household_in",
+    "locale_type_in",
+    "income_level_in",
+    "employment_status_in",
+]);
+const ROLE_CRITERIA_BOOLEAN_KEYS = new Set([
+    "requires_captions",
+    "uses_screen_reader",
+    "prefers_reduced_motion",
+    "prefers_high_contrast",
+    "has_any_accessibility_need",
+]);
+/**
+ * Validate a parsed role-criteria object client-side. Whitelists known
+ * keys (typo guard — catches `occupations` vs `occupation`), type-checks
+ * each field, and returns the cleaned object. Throws a descriptive Error
+ * on the first violation. Returns `undefined` for `undefined` input so
+ * callers can `validateRoleCriteria(opts.roleCriteriaA)` without a guard.
+ *
+ * Mirrors the backend Pydantic check shape-for-shape; surfacing locally
+ * costs less than a round-trip and gives agents the same error contract
+ * they get for other CLI inputs (exit 2, ValidationError).
+ */
+export function validateRoleCriteria(raw, flagName) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`Invalid ${flagName}: expected a JSON object.`);
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!ROLE_CRITERIA_KEYS.includes(key)) {
+            throw new Error(`Invalid ${flagName}: unknown key "${key}". Allowed keys: ${ROLE_CRITERIA_KEYS.join(", ")}.`);
+        }
+        if (value === null || value === undefined)
+            continue;
+        if (ROLE_CRITERIA_LIST_KEYS.has(key)) {
+            if (!Array.isArray(value) || !value.every((v) => typeof v === "string" && v.length > 0)) {
+                throw new Error(`Invalid ${flagName}: "${key}" must be an array of non-empty strings.`);
+            }
+            if (value.length === 0)
+                continue;
+            out[key] = value;
+            continue;
+        }
+        if (ROLE_CRITERIA_BOOLEAN_KEYS.has(key)) {
+            if (typeof value !== "boolean") {
+                throw new Error(`Invalid ${flagName}: "${key}" must be a boolean.`);
+            }
+            out[key] = value;
+            continue;
+        }
+        // numeric fields: min_age, max_age
+        if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value)) {
+            throw new Error(`Invalid ${flagName}: "${key}" must be an integer.`);
+        }
+        if ((key === "min_age" || key === "max_age") && value < 0) {
+            throw new Error(`Invalid ${flagName}: "${key}" must be non-negative.`);
+        }
+        out[key] = value;
+    }
+    if (typeof out.min_age === "number" && typeof out.max_age === "number" && out.min_age > out.max_age) {
+        throw new Error(`Invalid ${flagName}: min_age (${out.min_age}) must be <= max_age (${out.max_age}).`);
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Pretty-print a role criteria object as a single-line summary for human
+ * output (confirmation block, iteration get renderer). Returns `""` when
+ * the object is empty / undefined so callers can compose safely.
+ */
+export function summarizeRoleCriteria(criteria) {
+    if (!criteria)
+        return "";
+    const parts = [];
+    for (const key of ROLE_CRITERIA_KEYS) {
+        const v = criteria[key];
+        if (v === undefined || v === null)
+            continue;
+        if (Array.isArray(v)) {
+            if (v.length === 0)
+                continue;
+            parts.push(`${key}=[${v.join(", ")}]`);
+        }
+        else {
+            parts.push(`${key}=${String(v)}`);
+        }
+    }
+    return parts.join(", ");
+}
 /**
  * Detect modality/details mismatch on `iteration update --details-json`.
  *
@@ -81,9 +324,11 @@ export function validateIterationDetails(modality, details) {
     }
     const d = details;
     const hasUrl = typeof d.url === "string" && d.url.length > 0;
-    const hasEndpointObj = !!d.endpoint && typeof d.endpoint === "object";
-    const hasEndpointId = typeof d.chatbot_endpoint_id === "string"
-        && d.chatbot_endpoint_id.length > 0;
+    const ep = readExternalChatbotEndpoint(details);
+    const hasEndpointObj = !!ep.endpoint;
+    const hasEndpointId = !!ep.chatbot_endpoint_id;
+    const hasModeDetails = !!d.mode_details && typeof d.mode_details === "object";
+    const isPair = readChatMode(details) === "tester_pair";
     const hasContentText = typeof d.content_text === "string" && d.content_text.length > 0;
     const hasContentUrl = typeof d.content_url === "string" && d.content_url.length > 0;
     const imageUrls = d.image_urls;
@@ -91,20 +336,81 @@ export function validateIterationDetails(modality, details) {
         ? imageUrls.length > 0
         : typeof imageUrls === "string" && imageUrls.length > 0;
     if (modality === "chat") {
+        if (isPair) {
+            const pair = readTesterPairConfig(details);
+            if (!pair) {
+                return {
+                    ok: false,
+                    reason: "missing or malformed mode_details for tester_pair chat iteration",
+                    suggestion: "tester_pair iterations require mode_details: { mode: 'tester_pair', audience_a|role_criteria_a, audience_b|role_criteria_b, scenario_a, scenario_b }",
+                };
+            }
+            // Validate criteria shape if present; surfaces client-side errors
+            // (typo'd key, wrong type) before the round-trip.
+            try {
+                validateRoleCriteria(pair.role_criteria_a, "role_criteria_a");
+                validateRoleCriteria(pair.role_criteria_b, "role_criteria_b");
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    reason: err instanceof Error ? err.message : "invalid role criteria",
+                    suggestion: `allowed keys: ${ROLE_CRITERIA_KEYS.join(", ")}`,
+                };
+            }
+            const sideAHasAudience = pair.audience_a.length > 0 || !!pair.role_criteria_a;
+            const sideBHasAudience = pair.audience_b.length > 0 || !!pair.role_criteria_b;
+            if (!sideAHasAudience || !sideBHasAudience) {
+                return {
+                    ok: false,
+                    reason: "tester_pair iteration is missing audience input on at least one side",
+                    suggestion: "each side needs either an explicit audience (audience_a/audience_b) or a role-criteria filter (role_criteria_a/role_criteria_b)",
+                };
+            }
+            const bothAudiencesExplicit = pair.audience_a.length > 0
+                && pair.audience_b.length > 0
+                && !pair.role_criteria_a
+                && !pair.role_criteria_b;
+            const lenA = pair.audience_a.length;
+            const lenB = pair.audience_b.length;
+            const validPairing = lenA === lenB || lenA === 1 || lenB === 1;
+            if (bothAudiencesExplicit && !validPairing) {
+                return {
+                    ok: false,
+                    reason: `tester_pair audiences cannot be paired (audience_a=${lenA}, audience_b=${lenB})`,
+                    suggestion: "pick the same number on each side (zip 1:1 by index), or exactly 1 on one side to broadcast across the other; or use role_criteria_a/_b to let the backend resolve the pool",
+                };
+            }
+            if (pair.scenario_a.length === 0 || pair.scenario_b.length === 0) {
+                return {
+                    ok: false,
+                    reason: "tester_pair iteration is missing scenario_a or scenario_b",
+                    suggestion: "both scenarios are required and asymmetric; pass --scenario-a and --scenario-b on `iteration create`",
+                };
+            }
+            return { ok: true };
+        }
         if (hasEndpointObj || hasEndpointId)
             return { ok: true };
+        if (hasModeDetails) {
+            return {
+                ok: false,
+                reason: "unrecognised mode_details for chat iteration",
+                suggestion: "mode_details must be either { mode:'external_chatbot', endpoint|chatbot_endpoint_id } or { mode:'tester_pair', audience_a, audience_b, scenario_a, scenario_b }",
+            };
+        }
         if (hasUrl) {
             return {
                 ok: false,
                 reason: "interactive-shape details on a chat iteration",
-                suggestion: "use --details-json with .endpoint or .chatbot_endpoint_id, or use `ish iteration update` with --endpoint <id>",
+                suggestion: "use --details-json with mode_details.endpoint or mode_details.chatbot_endpoint_id, or use `ish iteration update` with --endpoint <id>",
             };
         }
         if (hasContentText || hasContentUrl || hasImageUrls) {
             return {
                 ok: false,
                 reason: "media-shape details on a chat iteration",
-                suggestion: "chat iterations require .endpoint (object) or .chatbot_endpoint_id (string); pass --endpoint <id> or --endpoint-config <file>",
+                suggestion: "chat iterations require mode_details with endpoint/chatbot_endpoint_id (external_chatbot mode) or audience_a/_b + scenario_a/_b (tester_pair mode)",
             };
         }
         // No recognised content keys at all. Don't reject — agent might be
@@ -114,7 +420,7 @@ export function validateIterationDetails(modality, details) {
     if (modality === "interactive") {
         if (hasUrl)
             return { ok: true };
-        if (hasEndpointObj || hasEndpointId) {
+        if (hasEndpointObj || hasEndpointId || hasModeDetails) {
             return {
                 ok: false,
                 reason: "chat-shape details on an interactive iteration",
@@ -140,7 +446,7 @@ export function validateIterationDetails(modality, details) {
                 suggestion: "text iterations require .content_text; pass --content-text <text-or-@file>",
             };
         }
-        if (hasEndpointObj || hasEndpointId) {
+        if (hasEndpointObj || hasEndpointId || hasModeDetails) {
             return {
                 ok: false,
                 reason: "chat-shape details on a text iteration",
@@ -159,7 +465,7 @@ export function validateIterationDetails(modality, details) {
                 suggestion: `${modality} iterations require .content_url; pass --content-url <url-or-file>`,
             };
         }
-        if (hasEndpointObj || hasEndpointId) {
+        if (hasEndpointObj || hasEndpointId || hasModeDetails) {
             return {
                 ok: false,
                 reason: `chat-shape details on a ${modality} iteration`,
@@ -178,7 +484,7 @@ export function validateIterationDetails(modality, details) {
                 suggestion: "image iterations require .image_urls (array or comma-separated string); pass --image-urls <urls>",
             };
         }
-        if (hasEndpointObj || hasEndpointId) {
+        if (hasEndpointObj || hasEndpointId || hasModeDetails) {
             return {
                 ok: false,
                 reason: "chat-shape details on an image iteration",

package/dist/lib/output.js

@@ -127,6 +127,18 @@ const UUID_KEYS_TO_KEEP = new Set([
 const LEAN_PASSTHROUGH_KEYS = new Set([
     // Pattern H: variant_id → [tester_id, ...] for drill-in audience discovery.
     "pick_buckets",
+    // Pattern A: workspace cold-start fields. Agents need these without --verbose
+    // to spot a safe reuse target (has_headroom) and order workspaces by recency.
+    // last_activity_at is a timestamp — would otherwise be stripped.
+    // child_counts is a dict — passthrough preserves the inner counts verbatim.
+    "study_count",
+    "ask_count",
+    "tester_profile_count",
+    "child_counts",
+    "has_headroom",
+    "last_activity_at",
+    // workspace create --ensure: signals whether an existing workspace was reused.
+    "reused",
 ]);
 /**
  * Strip UUID-valued fields, null/undefined values, and timestamps.
@@ -642,8 +654,24 @@ function formatLabel(key) {
 /**
  * Default workspace fields exposed in both TTY tables and JSON output.
  * Anything not in this set (e.g. has_figma_token) is hidden unless --verbose.
+ *
+ * Pattern A fields (study_count, child_counts, has_headroom, last_activity_at,
+ * …) are load-bearing for the cold-start workflow — agents need them to pick
+ * a safe reuse target. `reused` ships on `workspace create --ensure` responses.
  */
-const WORKSPACE_DEFAULT_FIELDS = ["alias", "name", "base_url", "created_at"];
+const WORKSPACE_DEFAULT_FIELDS = [
+    "alias",
+    "name",
+    "base_url",
+    "created_at",
+    "study_count",
+    "ask_count",
+    "tester_profile_count",
+    "child_counts",
+    "has_headroom",
+    "last_activity_at",
+    "reused",
+];
 function projectWorkspace(workspace, options = {}) {
     const result = {};
     if (options.writePath && workspace.id !== null && workspace.id !== undefined) {
@@ -673,13 +701,35 @@ export function formatWorkspaceList(workspaces, json) {
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.workspace);
-    printTable(["#", "NAME", "BASE URL", "CREATED"], workspaces.map((w) => [
+    printTable(["#", "NAME", "ROOM", "STUDIES", "ASKS", "TESTERS", "LAST ACTIVITY"], workspaces.map((w) => [
         aliasMap.get(String(w.id)) || String(w.id || ""),
         String(w.name || ""),
-        String(w.base_url || "-"),
-        formatDate(w.created_at),
+        formatHeadroom(w.has_headroom),
+        formatChildCount(w, "studies", "study_count"),
+        formatChildCount(w, "asks", "ask_count"),
+        formatChildCount(w, "tester_profiles", "tester_profile_count"),
+        formatDate(w.last_activity_at),
     ]));
 }
+function formatHeadroom(v) {
+    if (v === true)
+        return "yes";
+    if (v === false)
+        return "full";
+    return "-";
+}
+function formatChildCount(w, childKey, flatKey) {
+    const child = w.child_counts;
+    if (child !== null && typeof child === "object" && childKey in child) {
+        const v = child[childKey];
+        if (typeof v === "number")
+            return String(v);
+    }
+    const flat = w[flatKey];
+    if (typeof flat === "number")
+        return String(flat);
+    return "-";
+}
 export function formatWorkspaceDetail(workspace, json, options = {}) {
     if (json) {
         if (_verbose) {
@@ -697,7 +747,14 @@ export function formatWorkspaceDetail(workspace, json, options = {}) {
         Description: workspace.description || "-",
         "Base URL": workspace.base_url || "-",
         Created: formatDate(workspace.created_at),
+        "Last activity": formatDate(workspace.last_activity_at),
+        Headroom: formatHeadroom(workspace.has_headroom),
+        Studies: formatChildCount(workspace, "studies", "study_count"),
+        Asks: formatChildCount(workspace, "asks", "ask_count"),
+        Testers: formatChildCount(workspace, "tester_profiles", "tester_profile_count"),
     };
+    if (workspace.reused !== undefined)
+        display.Reused = workspace.reused ? "yes" : "no";
     printKeyValue(display);
 }
 // --- Site-access formatting ---