@ishlabs/cli 0.17.7 → 0.19.0

package/dist/lib/study-events.d.ts

@@ -1,7 +1,7 @@
 /**
  * SSE consumer for the backend's per-study event stream.
  *
- * Used by `study run --wait` to wake up the poll loop as soon as a tester
+ * Used by `study run --wait` to wake up the poll loop as soon as a participant
  * status / interaction event arrives, instead of waiting for the next poll
  * tick. The canonical truth source remains `GET /studies/{id}` — SSE here
  * only shortens the latency between a backend event and the next status
@@ -26,11 +26,11 @@ export interface StudyEvent {
     type: string;
     study_id: string;
     iteration_id?: string | null;
-    tester_id?: string | null;
+    participant_id?: string | null;
     interaction_id?: string | null;
     frame_id?: string | null;
     frame_version_id?: string | null;
-    tester_status?: string | null;
+    participant_status?: string | null;
     ts: string;
     seq: number;
     payload?: unknown;

package/dist/lib/study-events.js

@@ -1,7 +1,7 @@
 /**
  * SSE consumer for the backend's per-study event stream.
  *
- * Used by `study run --wait` to wake up the poll loop as soon as a tester
+ * Used by `study run --wait` to wake up the poll loop as soon as a participant
  * status / interaction event arrives, instead of waiting for the next poll
  * tick. The canonical truth source remains `GET /studies/{id}` — SSE here
  * only shortens the latency between a backend event and the next status

package/dist/lib/study-inputs.d.ts

@@ -3,13 +3,23 @@
  * flags. Mirrors the loose validation style of `src/lib/ask-questions.ts`.
  */
 import type { Assignment, InterviewQuestion } from "./types.js";
+/**
+ * Validate a parsed array of assignment objects. Shared by the
+ * `--assignments-file` and inline `--assignments` paths so both enforce the
+ * same shape: each entry needs a non-empty `name` + `instructions`, and an
+ * optional `steps` checklist (validated against backend bounds). Response-only
+ * keys like `id` / `step_completion` are tolerated and passed through so a
+ * `study get --json` payload round-trips back into a create.
+ */
+export declare function validateAssignmentsArray(parsed: unknown, label: string): Assignment[];
 /**
  * Parse `"Name:Instructions"`. Splits on the first `:`, so colons inside
  * the instructions text are preserved.
  */
 export declare function parseAssignment(value: string): Assignment;
 /**
- * Read a JSON file containing an array of `{name, instructions}` entries.
+ * Read a JSON file containing an array of `{name, instructions, steps?}`
+ * entries. `steps` is an optional checklist of `{name, description?}` actions.
  */
 export declare function loadAssignmentsFile(filePath: string): Assignment[];
 /**

package/dist/lib/study-inputs.js

@@ -4,6 +4,71 @@
  */
 import { readFileSync } from "node:fs";
 import { resolve as resolvePath } from "node:path";
+const STEP_NAME_MAX = 80;
+const STEP_DESC_MAX = 500;
+/**
+ * Validate an optional `steps` checklist on one assignment. Mirrors the
+ * backend bounds (`AssignmentStep`: name 1–80, description ≤500) so authors get
+ * a local error instead of a 422. Returns the cleaned step list.
+ */
+function validateSteps(raw, label) {
+    if (!Array.isArray(raw)) {
+        throw new Error(`${label}.steps must be an array of {name, description?} objects.`);
+    }
+    return raw.map((entry, j) => {
+        const s = entry;
+        if (!s || typeof s !== "object") {
+            throw new Error(`${label}.steps[${j}] must be an object with a name.`);
+        }
+        if (typeof s.name !== "string" || !s.name.trim()) {
+            throw new Error(`${label}.steps[${j}].name must be a non-empty string.`);
+        }
+        if (s.name.length > STEP_NAME_MAX) {
+            throw new Error(`${label}.steps[${j}].name must be ≤${STEP_NAME_MAX} characters.`);
+        }
+        if (s.description !== undefined && s.description !== null) {
+            if (typeof s.description !== "string") {
+                throw new Error(`${label}.steps[${j}].description must be a string.`);
+            }
+            if (s.description.length > STEP_DESC_MAX) {
+                throw new Error(`${label}.steps[${j}].description must be ≤${STEP_DESC_MAX} characters.`);
+            }
+        }
+        const step = { name: s.name };
+        if (typeof s.description === "string")
+            step.description = s.description;
+        return step;
+    });
+}
+/**
+ * Validate a parsed array of assignment objects. Shared by the
+ * `--assignments-file` and inline `--assignments` paths so both enforce the
+ * same shape: each entry needs a non-empty `name` + `instructions`, and an
+ * optional `steps` checklist (validated against backend bounds). Response-only
+ * keys like `id` / `step_completion` are tolerated and passed through so a
+ * `study get --json` payload round-trips back into a create.
+ */
+export function validateAssignmentsArray(parsed, label) {
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        throw new Error(`${label} must be a non-empty JSON array.`);
+    }
+    for (let i = 0; i < parsed.length; i++) {
+        const a = parsed[i];
+        if (!a || typeof a !== "object") {
+            throw new Error(`assignments[${i}] must be an object with name + instructions.`);
+        }
+        if (typeof a.name !== "string" || !a.name.trim()) {
+            throw new Error(`assignments[${i}].name must be a non-empty string.`);
+        }
+        if (typeof a.instructions !== "string" || !a.instructions.trim()) {
+            throw new Error(`assignments[${i}].instructions must be a non-empty string.`);
+        }
+        if (a.steps !== undefined && a.steps !== null) {
+            a.steps = validateSteps(a.steps, `assignments[${i}]`);
+        }
+    }
+    return parsed;
+}
 /**
  * Parse `"Name:Instructions"`. Splits on the first `:`, so colons inside
  * the instructions text are preserved.
@@ -24,7 +89,8 @@ export function parseAssignment(value) {
     return { name, instructions };
 }
 /**
- * Read a JSON file containing an array of `{name, instructions}` entries.
+ * Read a JSON file containing an array of `{name, instructions, steps?}`
+ * entries. `steps` is an optional checklist of `{name, description?}` actions.
  */
 export function loadAssignmentsFile(filePath) {
     let raw;
@@ -41,22 +107,7 @@ export function loadAssignmentsFile(filePath) {
     catch {
         throw new Error(`Invalid JSON in assignments file: ${filePath}`);
     }
-    if (!Array.isArray(parsed) || parsed.length === 0) {
-        throw new Error(`Assignments file must be a non-empty JSON array: ${filePath}`);
-    }
-    for (let i = 0; i < parsed.length; i++) {
-        const a = parsed[i];
-        if (!a || typeof a !== "object") {
-            throw new Error(`assignments[${i}] must be an object with name + instructions.`);
-        }
-        if (typeof a.name !== "string" || !a.name.trim()) {
-            throw new Error(`assignments[${i}].name must be a non-empty string.`);
-        }
-        if (typeof a.instructions !== "string" || !a.instructions.trim()) {
-            throw new Error(`assignments[${i}].instructions must be a non-empty string.`);
-        }
-    }
-    return parsed;
+    return validateAssignmentsArray(parsed, `Assignments file ${filePath}`);
 }
 /**
  * Parse a plain question text into a default text-typed, after-timed

package/dist/lib/study-participants.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Wrapper for the post-split `GET /studies/{id}/participants` endpoint.
+ *
+ * Returns a flat list of participants for one study with an `iteration_id`
+ * discriminator on each row. Each row carries the rich per-participant graph
+ * (person, interactions[], participant_summary, interview_answers, …) that
+ * used to be embedded under `study.iterations[*].participants[*]` on the
+ * legacy `GET /studies/{id}` response.
+ */
+import type { ApiClient } from "./api-client.js";
+import type { Participant } from "./types.js";
+export interface StudyParticipant extends Participant {
+    person?: {
+        id?: string;
+        name?: string;
+    };
+    interactions?: unknown[];
+    participant_summary?: Record<string, unknown> | null;
+    interview_answers?: Array<{
+        question_id?: string;
+        answer?: unknown;
+    }>;
+    participant_files?: unknown[];
+    participant_assignments?: unknown[];
+    conversation_id?: string | null;
+    error_message?: string | null;
+    error_kind?: string | null;
+    [k: string]: unknown;
+}
+export declare function fetchStudyParticipants(client: ApiClient, studyId: string, opts?: {
+    timeout?: number;
+}): Promise<StudyParticipant[]>;

package/dist/lib/study-participants.js

@@ -0,0 +1,12 @@
+/**
+ * Wrapper for the post-split `GET /studies/{id}/participants` endpoint.
+ *
+ * Returns a flat list of participants for one study with an `iteration_id`
+ * discriminator on each row. Each row carries the rich per-participant graph
+ * (person, interactions[], participant_summary, interview_answers, …) that
+ * used to be embedded under `study.iterations[*].participants[*]` on the
+ * legacy `GET /studies/{id}` response.
+ */
+export async function fetchStudyParticipants(client, studyId, opts) {
+    return await client.get(`/studies/${studyId}/participants`, undefined, opts);
+}

package/dist/lib/types.d.ts

@@ -54,10 +54,46 @@ export interface SecretUpdateInput {
 export interface SecretBatchCreateInput {
     secrets: SecretCreateInput[];
 }
+/**
+ * One atomic, author-supplied action inside an assignment's checklist
+ * (e.g. "Add to cart"). Authored via the JSON forms of `study create/update`
+ * (`--assignments-file` / `--assignments`) — only for `interactive` and
+ * `external_chatbot chat` modalities; the backend rejects steps elsewhere.
+ */
+export interface AssignmentStep {
+    /** Response-only server slug (e.g. "add-to-cart"); omitted on write. */
+    id?: string;
+    /** 1–80 chars. */
+    name: string;
+    /** ≤500 chars. */
+    description?: string;
+}
+/** One sampled participant who failed a step, with the verifier's reason. */
+export interface SampleFailure {
+    participant_id: string;
+    reason: string;
+}
+/**
+ * Response-only per-step completion rollup, populated by the backend after a
+ * run grades each step per participant. Ignored on write.
+ */
+export interface StepCompletion {
+    step_id: string;
+    name: string;
+    description?: string;
+    total: number;
+    passed: number;
+    rate?: number | null;
+    sample_failures?: SampleFailure[];
+}
 export interface Assignment {
     id?: string;
     name: string;
     instructions: string;
+    /** Optional checklist authored on write; resolved with `id` on read. */
+    steps?: AssignmentStep[];
+    /** Response-only completion rollup; ignored on write. */
+    step_completion?: StepCompletion[];
 }
 export interface InterviewQuestion {
     id?: string;
@@ -119,7 +155,6 @@ export interface Iteration {
     description?: string;
     label?: string;
     details?: Record<string, unknown>;
-    testers?: Tester[];
     created_at: string;
     updated_at: string;
 }
@@ -134,39 +169,75 @@ export interface IterationUpdateInput {
     details?: Record<string, unknown>;
     label?: string;
 }
-export interface TesterProfile {
+export interface Person {
     id: string;
     name: string;
     [key: string]: unknown;
 }
-export type SourceKind = "text_file" | "audio" | "image";
-export type SourceStatus = "pending_upload" | "uploaded" | "transcribing" | "processed" | "failed";
-export interface AudienceSource {
+export type AttachmentKind = "text_file" | "audio" | "image";
+export type AttachmentStatus = "pending_upload" | "uploaded" | "transcribing" | "processing" | "processed" | "failed";
+/** How a file relates to a participant profile (`identity` is reserved). */
+export type AttachmentRelation = "seed" | "attached";
+/** Single attachment row returned by GET /people/attachments/{id}. */
+export interface Attachment {
     id: string;
     product_id: string;
-    kind: SourceKind;
-    status: SourceStatus;
-    original_filename: string;
+    kind: AttachmentKind;
+    status: AttachmentStatus;
+    file_name: string;
     content_type: string;
+    file_size_bytes?: number | null;
     extracted_text_length?: number | null;
+    description?: string | null;
     error?: string | null;
+    relations: AttachmentRelation[];
     created_at: string;
 }
-export interface InitiateSourceUploadResponse {
-    source_id: string;
+export interface InitiateAttachmentUploadResponse {
+    attachment_id: string;
     signed_url: string;
     upload_token: string;
 }
+export type SourceKind = AttachmentKind;
+export type SourceStatus = AttachmentStatus;
+export type PersonSource = Attachment;
+export type InitiateSourceUploadResponse = InitiateAttachmentUploadResponse;
 export interface ProposeCountResponse {
     proposed_count: number;
     rationale: string;
 }
-export interface GenerateAudienceRequest {
+export interface GeneratePeopleRequest {
     product_id: string;
     description?: string;
     source_upload_ids?: string[];
     count?: number;
 }
+export type GenerationJobStatus = "queued" | "processing" | "completed" | "failed";
+export interface CreateGenerationJobRequest {
+    product_id: string;
+    description?: string;
+    source_upload_ids?: string[];
+    count?: number;
+}
+export interface GenerationJob {
+    id: string;
+    status: GenerationJobStatus;
+    progress_message: string | null;
+    person_ids: string[];
+    error: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** One scenario the job grounded in a real reaction (GET /people/{id}/scenarios). */
+export interface ProfileScenario {
+    source: string;
+    scenario_prompt: string;
+    text: string;
+    raw_response?: {
+        evidence_quote?: string;
+    } & Record<string, unknown>;
+    [key: string]: unknown;
+}
 export interface GeneratedProfile {
     id: string;
     name: string;
@@ -243,30 +314,30 @@ export interface EvidenceTraceResponse {
     raw_response: Record<string, unknown> | null;
     created_at: string;
 }
-export interface Tester {
+export interface Participant {
     id: string;
     iteration_id: string;
-    tester_profile_id: string;
+    person_id: string;
     instance_name?: string;
     instance_number?: number;
     status: string;
     language?: string;
     platform?: string;
-    tester_type?: string;
+    participant_type?: string;
     viewport_width?: number;
     viewport_height?: number;
     created_at: string;
 }
-export interface TesterCreateInput {
-    tester_profile_id: string;
+export interface ParticipantCreateInput {
+    person_id: string;
     instance_name?: string;
     status?: string;
     language?: string;
     platform?: string;
-    tester_type?: string;
+    participant_type?: string;
 }
 export interface SimulationStartResponse {
-    tester_id: string;
+    participant_id: string;
     study_id: string;
     job_id: string | null;
     message: string;
@@ -296,7 +367,6 @@ export interface SimulationConfig {
     id: string;
     name: string;
     model_settings?: Record<string, unknown>;
-    simulation_settings?: Record<string, unknown>;
     prompts?: Record<string, unknown>;
     outputs?: Record<string, unknown>;
     source_type?: string;
@@ -329,14 +399,14 @@ export interface InterviewAnswer {
 /**
  * Pattern B — drill-in subset for a follow-up ask round.
  *
- * Filters the new round's audience to the testers who picked
+ * Filters the new round's participants to those who picked
  * `picked_variant_id` on the 1-indexed prior `round`. Mirrors the
- * backend's `AudienceSubset` model. Only valid on follow-up rounds —
+ * backend's `ParticipantSubset` model. Only valid on follow-up rounds —
  * round 1 has no prior round to filter against. The backend rejects
  * unresolvable subsets with a 422 carrying
- * `error_kind: "audience_subset_invalid"`.
+ * `error_kind: "participant_subset_invalid"`.
  */
-export interface AudienceSubset {
+export interface ParticipantSubset {
     round: number;
     picked_variant_id: string;
 }
@@ -346,13 +416,13 @@ export interface AskRoundInput {
     wants_pick?: boolean;
     wants_ratings?: boolean;
     questions?: InterviewQuestion[];
-    audience_subset?: AudienceSubset;
+    participant_subset?: ParticipantSubset;
 }
 export interface AskCreateInput {
     name: string;
     description?: string;
     language?: string;
-    tester_profile_ids: string[];
+    person_ids: string[];
     first_round: AskRoundInput;
     dispatch?: boolean;
 }
@@ -361,20 +431,20 @@ export interface AskUpdateInput {
     description?: string;
     is_archived?: boolean;
 }
-export interface AddTestersInput {
-    tester_profile_ids: string[];
-    round_id: string;
+export interface AddPeopleInput {
+    person_ids: string[];
+    dispatch_into_round_id: string;
     backfill_prior_rounds?: boolean;
 }
 export interface AddRoundQuestionsInput {
     questions: InterviewQuestion[];
     redispatch_all?: boolean;
 }
-export interface AskAudienceTester {
+export interface AskParticipant {
     id: string;
     ask_id?: string;
-    tester_profile_id?: string;
-    tester_profile?: Record<string, unknown> | null;
+    person_id?: string;
+    person?: Record<string, unknown> | null;
     instance_name?: string;
     status?: string;
     [key: string]: unknown;
@@ -382,7 +452,7 @@ export interface AskAudienceTester {
 export interface AskResponseModel {
     id: string;
     ask_round_id: string;
-    tester_id: string;
+    participant_id: string;
     comment?: string | null;
     variant_pick_id?: string | null;
     pick_confidence?: number | null;
@@ -418,7 +488,7 @@ export interface Ask {
     description?: string | null;
     is_archived: boolean;
     status?: AskStatus;
-    testers: AskAudienceTester[];
+    participants: AskParticipant[];
     rounds: AskRound[];
     created_at: string;
     updated_at: string;
@@ -431,7 +501,7 @@ export interface AskListItem {
     description?: string | null;
     is_archived: boolean;
     status?: AskStatus;
-    audience_count: number;
+    participant_count: number;
     round_count: number;
     last_round_at?: string | null;
     created_at: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ishlabs/cli",
-  "version": "0.17.7",
+  "version": "0.19.0",
   "description": "The command-line interface for ish",
   "type": "module",
   "bin": {

package/dist/commands/profile.d.ts

@@ -1,5 +0,0 @@
-/**
- * ish profile — Manage profiles, audience generation, and source uploads.
- */
-import type { Command } from "commander";
-export declare function registerProfileCommands(program: Command): void;

package/dist/commands/study-tester.d.ts

@@ -1,8 +0,0 @@
-/**
- * ish study tester — Inspect and manage testers (low-level; usually
- * created via `ish study run`).
- *
- * Default action: `ish study tester <id>` shows tester details and results.
- */
-import type { Command } from "commander";
-export declare function attachStudyTesterCommands(study: Command): void;