@ishlabs/cli 0.21.0 → 0.23.0

package/dist/lib/study-results-filters.js

@@ -79,10 +79,16 @@ function normaliseIterations(rawIterations) {
     }
     return out;
 }
-/** Throw a ValidationError-tagged Error (the wrapper maps it to exit 2). */
-function validationError(message) {
+/** Throw a ValidationError-tagged Error (the wrapper maps it to exit 2).
+ *  Optional `availableValues` rides along as a structured field in the
+ *  emitted JSON envelope so agents can parse the recovery set without
+ *  string-extracting it from the message (Pattern V from round 3). */
+function validationError(message, availableValues) {
     const err = new Error(message);
     err.name = "ValidationError";
+    if (availableValues && availableValues.length > 0) {
+        err.available_values = availableValues;
+    }
     return err;
 }
 /** Resolve `--frame <ref>` into a set of frame_version_ids.
@@ -143,19 +149,21 @@ function resolveFrameRef(ref, frames) {
     const needle = ref.toLowerCase();
     const candidates = frames.filter((f) => f.name && f.name.toLowerCase().includes(needle));
     if (candidates.length === 0) {
-        const available = frames
+        // Pattern V: dedupe + cap the frame list so duplicates (workspace-side
+        // data hazards) don't double-list in the error prose. Carry the
+        // deduped list as a structured `available_values` field for agents.
+        const dedupedNames = Array.from(new Set(frames
             .map((f) => f.name)
-            .filter((n) => typeof n === "string")
-            .slice(0, 10);
-        const hint = available.length > 0
-            ? ` Available frames: ${available.join(", ")}.`
+            .filter((n) => typeof n === "string"))).slice(0, 10);
+        const hint = dedupedNames.length > 0
+            ? ` Available frames: ${dedupedNames.join(", ")}.`
             : " This study has no named frames yet.";
-        throw validationError(`--frame "${ref}" matched no frames on this study.${hint}`);
+        throw validationError(`--frame "${ref}" matched no frames on this study.${hint}`, dedupedNames);
     }
     if (candidates.length > 1) {
-        const names = candidates.map((c) => c.name).filter((n) => !!n);
+        const names = Array.from(new Set(candidates.map((c) => c.name).filter((n) => !!n)));
         throw validationError(`--frame "${ref}" is ambiguous — matched ${candidates.length} frames: ${names.join(", ")}. ` +
-            `Use a more specific substring, a full Frame UUID, or an \`f-…\` alias.`);
+            `Use a more specific substring, a full Frame UUID, or an \`f-…\` alias.`, names);
     }
     indexFrame(candidates[0]);
     return { matchedFrameVersionIds: matched, frameVersionLookup: lookup };
@@ -192,10 +200,23 @@ function resolveAssignmentRef(ref, assignments) {
     return out;
 }
 /** Resolve `--iteration <ref>` to a single iteration_id, or null if no
- *  match (caller errors). UUID-exact or label-exact. */
+ *  match (caller errors). Accepts UUID, iteration alias (`i-…`), or label. */
 function resolveIterationRef(ref, iterations) {
-    if (UUID_RE.test(ref)) {
-        const m = iterations.find((i) => i.id === ref);
+    // Pattern M: iteration aliases (`i-…`) are the canonical short ID
+    // everywhere else in the CLI; accept them here too. Try alias resolution
+    // first, then fall through to UUID-direct, then label match.
+    let candidate = ref;
+    if (ref.startsWith("i-")) {
+        try {
+            candidate = resolveId(ref);
+        }
+        catch {
+            // Unknown alias — let the downstream "matched no iterations" branch
+            // emit the labels hint; the resolveId error doesn't add value here.
+        }
+    }
+    if (UUID_RE.test(candidate)) {
+        const m = iterations.find((i) => i.id === candidate);
         if (!m) {
             throw validationError(`No iteration matches "${ref}" on this study.`);
         }
@@ -383,7 +404,7 @@ export function applyResultsFilters(study, participants, rawFrames, filters) {
         warnings.push(`--turn is only meaningful on chat studies; ignored on modality "${modality}".`);
     }
     if (filters.side !== undefined && !isParticipantPair(study)) {
-        warnings.push(`--side is only meaningful on participant_pair chat studies; ignored.`);
+        warnings.push(`--side is only meaningful on participant_pair chat studies; ignored on modality "${modality}".`);
     }
     // Normalise sentiment labels to lowercase up-front (case-insensitive).
     const sentimentFilter = filters.sentiment

package/dist/lib/study-results-projections.d.ts

@@ -3,14 +3,10 @@
  *
  * Each `buildStudyResultsPer<Kind>` consumes a `FilteredResults` (the output
  * of `applyResultsFilters` in `study-results-filters.ts`) and returns a
- * plain JSON-serialisable value. The surface (T5) hands the result to
- * `output(..., json, { preProjected: true })` for JSON, or to
- * `formatStudyResultsGroupBy` (T6) for human mode.
- *
- * Per-iteration is the only projection that wraps a `{study, slices, ...}`
- * envelope; the others return plain arrays of slice objects. The surface
- * attaches `totals_unfiltered` and `warnings` from the same `FilteredResults`
- * for the array projections.
+ * bare array of slice objects. The surface (`commands/study.ts`) wraps the
+ * array uniformly in a `SliceResponse` envelope alongside `totals_unfiltered`,
+ * `modality_warnings`, `study_id`, and `modality` before handing it off to
+ * `formatStudyResultsGroupBy` for JSON or human rendering.
  *
  * Conventions mirror `buildStudyResultsEnvelope` (`output.ts:1081`) and
  * `buildStudyResultsSummary` (`output.ts:1292`):
@@ -23,18 +19,52 @@
  * Has no IO and no console side-effects.
  */
 import type { FilteredResults } from "./study-results-filters.js";
+import type { StudyResultsGroupByKind } from "./output.js";
 export type { FilteredResults } from "./study-results-filters.js";
 /**
- * `--group-by iteration` — one slice per iteration that has any surviving
- * participants. Slices are ordered by the iteration order on the study
- * (so callers see them in the same order as `ish study get`).
- *
- * Unlike the array-returning projections, this one wraps a stable envelope
- * with `totals_unfiltered` + `warnings` because per-iteration is the
- * "default agent slice" — the one most likely to be piped directly without
- * the surface re-wrapping.
+ * Uniform envelope emitted for every `ish study results --group-by <axis>`
+ * call, mirroring the MCP backend's `SliceResponse[T]`. Six top-level keys,
+ * stable across all six axes — `rows` carries the bare slice array returned
+ * by the matching `buildStudyResultsPer<Kind>` builder.
+ */
+export interface SliceResponse<T> {
+    axis: StudyResultsGroupByKind;
+    rows: T[];
+    totals_unfiltered: {
+        participant_count: number;
+        interaction_count: number;
+    };
+    modality_warnings: string[];
+    study_id: string;
+    modality: string;
+}
+/**
+ * Wrap a bare projection array in the uniform `SliceResponse` envelope.
+ * The surface calls this once after dispatching to one of the six
+ * `buildStudyResultsPer<Kind>` builders, then hands the envelope to
+ * `formatStudyResultsGroupBy`.
+ */
+export declare function wrapSliceProjection<T>(filtered: FilteredResults, axis: StudyResultsGroupByKind, rows: T[], studyId: string, modality: string): SliceResponse<T>;
+interface IterationSlice {
+    iteration_id: string;
+    iteration_label: string | null;
+    participant_count: number;
+    interaction_count: number;
+    sentiment: Record<string, number>;
+    sample_comments: string[];
+    top_actions: Array<{
+        action_type: string;
+        count: number;
+    }>;
+}
+/**
+ * `--group-by iteration` — one slice per declared iteration, in the same
+ * order as `ish study get`. Iterations with zero surviving participants
+ * still appear with `participant_count: 0` so the consumer sees the full
+ * matrix at stable size. Returns a bare array; the surface wraps it in
+ * the uniform `SliceResponse` envelope.
  */
-export declare function buildStudyResultsPerIteration(filtered: FilteredResults): Record<string, unknown>;
+export declare function buildStudyResultsPerIteration(filtered: FilteredResults): IterationSlice[];
 interface FrameSlice {
     frame_id: string;
     frame_label: string | null;

package/dist/lib/study-results-projections.js

@@ -3,14 +3,10 @@
  *
  * Each `buildStudyResultsPer<Kind>` consumes a `FilteredResults` (the output
  * of `applyResultsFilters` in `study-results-filters.ts`) and returns a
- * plain JSON-serialisable value. The surface (T5) hands the result to
- * `output(..., json, { preProjected: true })` for JSON, or to
- * `formatStudyResultsGroupBy` (T6) for human mode.
- *
- * Per-iteration is the only projection that wraps a `{study, slices, ...}`
- * envelope; the others return plain arrays of slice objects. The surface
- * attaches `totals_unfiltered` and `warnings` from the same `FilteredResults`
- * for the array projections.
+ * bare array of slice objects. The surface (`commands/study.ts`) wraps the
+ * array uniformly in a `SliceResponse` envelope alongside `totals_unfiltered`,
+ * `modality_warnings`, `study_id`, and `modality` before handing it off to
+ * `formatStudyResultsGroupBy` for JSON or human rendering.
  *
  * Conventions mirror `buildStudyResultsEnvelope` (`output.ts:1081`) and
  * `buildStudyResultsSummary` (`output.ts:1292`):
@@ -23,6 +19,22 @@
  * Has no IO and no console side-effects.
  */
 import { deterministicAlias, ALIAS_PREFIX } from "./alias-store.js";
+/**
+ * Wrap a bare projection array in the uniform `SliceResponse` envelope.
+ * The surface calls this once after dispatching to one of the six
+ * `buildStudyResultsPer<Kind>` builders, then hands the envelope to
+ * `formatStudyResultsGroupBy`.
+ */
+export function wrapSliceProjection(filtered, axis, rows, studyId, modality) {
+    return {
+        axis,
+        rows,
+        totals_unfiltered: filtered.totals_unfiltered,
+        modality_warnings: filtered.warnings,
+        study_id: deterministicAlias(ALIAS_PREFIX.study, studyId),
+        modality,
+    };
+}
 const SAMPLE_COMMENT_CAP = 5;
 const SAMPLE_COMMENT_MAX_LEN = 200;
 const PARTICIPANT_ALIAS_CAP = 10;
@@ -44,21 +56,24 @@ function asString(v) {
 function truncate(str, maxLen) {
     if (str.length <= maxLen)
         return str;
-    return str.slice(0, maxLen - 3) + "...";
+    // Pattern H: trim at the last word boundary before the cap so quoted
+    // `sample_comments` / `sample_replies` don't end mid-word ("…koncentrera").
+    // Prefer the last sentence terminator if one exists in the kept range;
+    // otherwise fall back to the last whitespace. If neither is found
+    // (a single long unbroken token), hard-cut at the cap.
+    const head = str.slice(0, maxLen - 3);
+    const sentenceBreak = Math.max(head.lastIndexOf(". "), head.lastIndexOf("! "), head.lastIndexOf("? "));
+    if (sentenceBreak >= maxLen / 2)
+        return head.slice(0, sentenceBreak + 1) + "…";
+    const spaceBreak = head.lastIndexOf(" ");
+    if (spaceBreak >= maxLen / 2)
+        return head.slice(0, spaceBreak) + " …";
+    return head + "…";
 }
 function participantAlias(participant) {
     const id = asString(participant.id);
     return id ? deterministicAlias(ALIAS_PREFIX.participant, id) : null;
 }
-function studyHeader(filtered) {
-    const study = filtered.study;
-    const id = asString(study.id);
-    return {
-        alias: id ? deterministicAlias(ALIAS_PREFIX.study, id) : null,
-        name: asString(study.name) ?? null,
-        modality: asString(study.modality) ?? null,
-    };
-}
 function readSentimentLabel(interaction) {
     const s = asRecord(interaction.sentiment);
     return s ? asString(s.label) : null;
@@ -111,14 +126,11 @@ function collectParticipantAlias(bucket, seen, participant) {
     bucket.push(alias);
 }
 /**
- * `--group-by iteration` — one slice per iteration that has any surviving
- * participants. Slices are ordered by the iteration order on the study
- * (so callers see them in the same order as `ish study get`).
- *
- * Unlike the array-returning projections, this one wraps a stable envelope
- * with `totals_unfiltered` + `warnings` because per-iteration is the
- * "default agent slice" — the one most likely to be piped directly without
- * the surface re-wrapping.
+ * `--group-by iteration` — one slice per declared iteration, in the same
+ * order as `ish study get`. Iterations with zero surviving participants
+ * still appear with `participant_count: 0` so the consumer sees the full
+ * matrix at stable size. Returns a bare array; the surface wraps it in
+ * the uniform `SliceResponse` envelope.
  */
 export function buildStudyResultsPerIteration(filtered) {
     const iterations = asArray(filtered.study.iterations);
@@ -176,16 +188,7 @@ export function buildStudyResultsPerIteration(filtered) {
             .map(([action_type, count]) => ({ action_type, count }));
         byIteration.get(iterId).top_actions = rows;
     }
-    // Keep every declared iteration as a slice so the consumer sees the full
-    // matrix at stable size. Iterations with zero surviving rows still appear
-    // with `participant_count: 0` — useful for "matched X / Y" framing.
-    const slices = order.map((o) => byIteration.get(o.id));
-    return {
-        study: studyHeader(filtered),
-        slices,
-        totals_unfiltered: filtered.totals_unfiltered,
-        warnings: filtered.warnings,
-    };
+    return order.map((o) => byIteration.get(o.id));
 }
 /**
  * `--group-by frame` — one slice per Frame that had a surviving interaction.

package/dist/lib/types.d.ts

@@ -357,6 +357,10 @@ export interface SimulationStatus {
     create_time?: string;
     completion_time?: string;
     error?: string;
+    error_kind?: string | null;
+    started_at?: string | null;
+    last_heartbeat_at?: string | null;
+    age_seconds?: number | null;
 }
 export interface SimulationCancelResponse {
     job_id: string;

package/package.json

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