@ishlabs/cli 0.15.0 → 0.16.0

package/README.md

@@ -308,6 +308,16 @@ ish ask run --new --name "newsletter" \
 
 **Audience flags** (`--profile`, `--sample`, `--all-simulatable`, `--country`, `--gender`, `--min-age`, `--max-age`, `--search`, `--visibility`, `--name`, `--description`, `--workspace`) only apply with `--new` — the audience is fixed at ask creation.
 
+**`--visibility` values** (same set everywhere it's accepted):
+
+| Value | Selects |
+|---|---|
+| `workspace` | Profiles owned by your workspace (default scope). |
+| `shared` | Community-published profiles visible across workspaces. |
+| `platform` | Admin-curated profiles from the platform pool. |
+
+Old values `private` (now `workspace`) and `public` (now `platform`) keep working until the next release; the server logs a deprecation warning and maps them to the new vocabulary.
+
 **Other ask verbs:**
 
 ```bash

package/dist/commands/study-run.js

@@ -11,6 +11,7 @@ import * as readline from "node:readline/promises";
 import { withClient, getWebUrl, terminalLink, resolveWorkspace, resolveStudy, parseWaitTimeout, resolveAudienceProfileIds, addAudienceFilterFlags, hasAudienceFlags, readFileOrStdin, } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { output, formatSimulationPoll } from "../lib/output.js";
+import { streamStudyEvents } from "../lib/study-events.js";
 import { isMediaModality, isChatModality, iterationHasContent, describeRequiredContentFlag, readChatMode, readTesterPairConfig, summarizeRoleCriteria, } from "../lib/modality.js";
 import { runLocalSimulations } from "../lib/local-sim/loop.js";
 import { ensureBrowser } from "../lib/local-sim/install.js";
@@ -93,6 +94,11 @@ function dedupeSimulations(simResults) {
     ];
 }
 const POLL_INTERVAL_MS = 5_000;
+// When the backend SSE stream is connected we drop to a slow backstop —
+// events wake us up promptly, so re-fetching every 5s is wasteful. If the
+// stream dies (older backend, broker offline, token mint failure) the loop
+// transparently reverts to POLL_INTERVAL_MS.
+const SSE_BACKSTOP_INTERVAL_MS = 30_000;
 const TERMINAL_STATUSES = new Set(["completed", "errored", "failed", "cancelled", "canceled"]);
 function flattenTesterStatuses(iterations, only) {
     const rows = [];
@@ -118,38 +124,90 @@ function flattenTesterStatuses(iterations, only) {
 async function pollStudyUntilDone(client, opts) {
     const start = Date.now();
     let lastReported = "";
-    while (true) {
-        const study = await client.get(`/studies/${opts.studyId}`, undefined, { timeout: 60_000 });
-        const isMedia = isMediaModality(study.modality);
-        let iterations = study.iterations;
-        if (opts.iterationId) {
-            iterations = (iterations ?? []).filter((it) => it.id === opts.iterationId);
-        }
-        const rows = flattenTesterStatuses(iterations, opts.testerIds);
-        const total = rows.length;
-        const done = rows.filter((r) => TERMINAL_STATUSES.has(r.status)).length;
-        const errored = rows.filter((r) => r.status === "errored" || r.status === "failed").length;
-        const summary = `${done}/${total} done${errored > 0 ? `, ${errored} errored/failed` : ""}`;
-        if (!opts.quiet && summary !== lastReported) {
-            process.stderr.write(`  ${summary}\n`);
-            lastReported = summary;
-        }
-        if (total > 0 && done === total) {
-            return { rows, isMedia };
-        }
-        if (Date.now() - start > opts.timeoutMs) {
-            throw new WaitTimeoutError(`Timed out after ${Math.round(opts.timeoutMs / 1000)}s waiting for simulations. ` +
-                `${done}/${total} done. Run \`ish study poll --study ${opts.studyId}\` to check status.`, {
-                study_id: opts.studyId,
-                ...(opts.iterationId && { iteration_id: opts.iterationId }),
-                timeout_seconds: Math.round(opts.timeoutMs / 1000),
-                done,
-                total,
-                pending: total - done,
-                rows,
-            });
+    // Open the SSE event stream as a wake source. When the backend supports
+    // it (enable_realtime=true + broker live), tester status changes wake
+    // the loop the moment they happen — no need to wait for the next poll
+    // tick. When it doesn't, the iterator exits silently on the first read
+    // and we fall through to pure polling at POLL_INTERVAL_MS.
+    const ac = new AbortController();
+    const eventIter = streamStudyEvents(client, opts.studyId, ac.signal);
+    // Optimistic: we assume the stream will deliver until the first read
+    // confirms otherwise. The first `await pendingEvent` settles within
+    // milliseconds for an unavailable stream (token mint 503 / endpoint 503)
+    // and is essentially a no-op for the latency budget.
+    let sseAlive = true;
+    let pendingEvent = eventIter.next();
+    try {
+        while (true) {
+            const study = await client.get(`/studies/${opts.studyId}`, undefined, { timeout: 60_000 });
+            const isMedia = isMediaModality(study.modality);
+            let iterations = study.iterations;
+            if (opts.iterationId) {
+                iterations = (iterations ?? []).filter((it) => it.id === opts.iterationId);
+            }
+            const rows = flattenTesterStatuses(iterations, opts.testerIds);
+            const total = rows.length;
+            const done = rows.filter((r) => TERMINAL_STATUSES.has(r.status)).length;
+            const errored = rows.filter((r) => r.status === "errored" || r.status === "failed").length;
+            const summary = `${done}/${total} done${errored > 0 ? `, ${errored} errored/failed` : ""}`;
+            if (!opts.quiet && summary !== lastReported) {
+                process.stderr.write(`  ${summary}\n`);
+                lastReported = summary;
+            }
+            if (total > 0 && done === total) {
+                return { rows, isMedia };
+            }
+            if (Date.now() - start > opts.timeoutMs) {
+                throw new WaitTimeoutError(`Timed out after ${Math.round(opts.timeoutMs / 1000)}s waiting for simulations. ` +
+                    `${done}/${total} done. Run \`ish study poll --study ${opts.studyId}\` to check status.`, {
+                    study_id: opts.studyId,
+                    ...(opts.iterationId && { iteration_id: opts.iterationId }),
+                    timeout_seconds: Math.round(opts.timeoutMs / 1000),
+                    done,
+                    total,
+                    pending: total - done,
+                    rows,
+                });
+            }
+            // Wait for either the next backend event or the next tick. Use the
+            // backstop interval while the stream is delivering (events are the
+            // primary wake source); fall back to POLL_INTERVAL_MS once the
+            // stream is dead (older backend or broker dropped mid-run).
+            const interval = sseAlive ? SSE_BACKSTOP_INTERVAL_MS : POLL_INTERVAL_MS;
+            if (sseAlive && pendingEvent !== null) {
+                let timerHandle;
+                const timer = new Promise((resolve) => {
+                    timerHandle = setTimeout(() => resolve({ kind: "timer" }), interval);
+                });
+                const eventOrEnd = pendingEvent.then((r) => ({ kind: "event", result: r }), () => ({ kind: "event", result: { value: undefined, done: true } }));
+                const winner = await Promise.race([eventOrEnd, timer]);
+                if (timerHandle !== undefined)
+                    clearTimeout(timerHandle);
+                if (winner.kind === "event") {
+                    if (winner.result.done) {
+                        // Stream ended; revert to pure polling for the rest of the run.
+                        sseAlive = false;
+                        pendingEvent = null;
+                    }
+                    else {
+                        // Re-arm for the next event. We deliberately don't act on
+                        // the event payload here — the next loop iteration re-fetches
+                        // status and that's the truth source.
+                        pendingEvent = eventIter.next();
+                    }
+                }
+                // Timer winning doesn't replace pendingEvent — it stays parked
+                // and resolves on whichever event arrives next.
+            }
+            else {
+                await new Promise((resolve) => setTimeout(resolve, interval));
+            }
         }
-        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+    finally {
+        // Stop the SSE fetch + reader so we don't leave a dangling HTTP
+        // connection to the backend after returning / throwing.
+        ac.abort();
     }
 }
 function readIterationDetails(details) {

package/dist/commands/workspace.js

@@ -214,11 +214,12 @@ async function collectWorkspaceUsage(client, workspaceId) {
         .get(`/products/${workspaceId}/studies`)
         .catch(() => []);
     // testers_used: paginated list returns { total, items, ... }. Backend
-    // gates `maxCustomTesterProfiles` on visibility=private.
+    // gates `maxCustomTesterProfiles` on visibility=workspace (rows owned by
+    // this workspace; was `private` before the visibility rename).
     const testersPromise = client
         .get("/tester-profiles", {
         product_id: workspaceId,
-        visibility: "private",
+        visibility: "workspace",
         type: "ai",
         limit: "1",
         offset: "0",

package/dist/lib/api-client.d.ts

@@ -20,6 +20,13 @@ export declare class ApiClient {
         token: string;
     });
     get accessToken(): string;
+    /** Resolved base URL including the ``/api/v1`` prefix.
+     *
+     * Exposed so helpers that bypass the JSON-decoding ``fetch`` wrappers
+     * (e.g. the SSE stream in ``lib/study-events.ts``) can build their own
+     * requests against the same backend.
+     */
+    get apiBase(): string;
     private headers;
     get<T = unknown>(path: string, params?: Record<string, string | string[]>, opts?: RequestOpts): Promise<T>;
     post<T = unknown>(path: string, body?: unknown, opts?: RequestOpts): Promise<T>;

package/dist/lib/api-client.js

@@ -83,6 +83,15 @@ export class ApiClient {
     get accessToken() {
         return this.token;
     }
+    /** Resolved base URL including the ``/api/v1`` prefix.
+     *
+     * Exposed so helpers that bypass the JSON-decoding ``fetch`` wrappers
+     * (e.g. the SSE stream in ``lib/study-events.ts``) can build their own
+     * requests against the same backend.
+     */
+    get apiBase() {
+        return this.baseUrl;
+    }
     headers() {
         return {
             Authorization: `Bearer ${this.token}`,

package/dist/lib/command-helpers.js

@@ -245,7 +245,7 @@ export function addAudienceFilterFlags(cmd, opts = {}) {
         .option("--country <code>", "Filter by 2-letter country code (repeatable)", collectRepeatable, [])
         .option("--min-age <n>", "Minimum age (inclusive)")
         .option("--max-age <n>", "Maximum age (inclusive)")
-        .option("--visibility <v>", "Filter by visibility (private|public)");
+        .option("--visibility <v>", "Filter by visibility: workspace (your workspace), shared (community-published), platform (admin-curated). Old values `private` / `public` still accepted as aliases for `workspace` / `platform` until the next release; server logs a deprecation warning.");
 }
 export function getGlobals(cmd) {
     let globals;

package/dist/lib/docs.js

@@ -1268,7 +1268,12 @@ flags. Two ways to select:
    - \`--min-age 25\`
    - \`--max-age 50\`
    - \`--search "early adopter"\`
-   - \`--visibility shared|private\`
+   - \`--visibility workspace|shared|platform\` (filter by where the
+     profile lives: your workspace, the community-published pool, or
+     the admin-curated platform pool; old values \`private\` /
+     \`public\` still accepted as aliases for \`workspace\` /
+     \`platform\` until the next release with a server-side
+     deprecation warning)
 
 The two modes are **mutually exclusive** — pass either \`--profile\` or
 the filter set, not both.

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

@@ -0,0 +1,46 @@
+/**
+ * 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
+ * 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
+ * fetch; the poll fallback still runs on a slow timer in case events are
+ * missed.
+ *
+ * Best-effort:
+ *  - Mints a short-lived stream token (POST /auth/stream-token).
+ *  - Opens `GET /studies/{id}/events?token=…` via `fetch` and streams the
+ *    response body.
+ *  - Returns (silently exits the iterator) on any failure — token mint
+ *    503 (server not configured), endpoint 503 (broker offline on this
+ *    instance), network error, abort. The caller's polling rhythm is the
+ *    safety net; we never raise.
+ *
+ * Stream-token TTL is 1h on the backend. For runs longer than that the
+ * fetch will end (server closes); the caller falls back to pure polling
+ * for the remainder.
+ */
+import { ApiClient, ApiError } from "./api-client.js";
+export interface StudyEvent {
+    type: string;
+    study_id: string;
+    iteration_id?: string | null;
+    tester_id?: string | null;
+    interaction_id?: string | null;
+    frame_id?: string | null;
+    frame_version_id?: string | null;
+    tester_status?: string | null;
+    ts: string;
+    seq: number;
+    payload?: unknown;
+}
+/**
+ * Async generator that yields parsed StudyEvents from the backend SSE
+ * stream. Exits silently (without throwing) on failure or abort — callers
+ * MUST have a polling fallback that drives correctness.
+ */
+export declare function streamStudyEvents(client: ApiClient, studyId: string, signal: AbortSignal): AsyncGenerator<StudyEvent, void, void>;
+/** Type narrower used by callers to skip the synthetic LAG marker. */
+export declare function isLagEvent(event: StudyEvent): boolean;
+export { ApiError };

package/dist/lib/study-events.js

@@ -0,0 +1,126 @@
+/**
+ * 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
+ * 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
+ * fetch; the poll fallback still runs on a slow timer in case events are
+ * missed.
+ *
+ * Best-effort:
+ *  - Mints a short-lived stream token (POST /auth/stream-token).
+ *  - Opens `GET /studies/{id}/events?token=…` via `fetch` and streams the
+ *    response body.
+ *  - Returns (silently exits the iterator) on any failure — token mint
+ *    503 (server not configured), endpoint 503 (broker offline on this
+ *    instance), network error, abort. The caller's polling rhythm is the
+ *    safety net; we never raise.
+ *
+ * Stream-token TTL is 1h on the backend. For runs longer than that the
+ * fetch will end (server closes); the caller falls back to pure polling
+ * for the remainder.
+ */
+import { ApiError } from "./api-client.js";
+/**
+ * Async generator that yields parsed StudyEvents from the backend SSE
+ * stream. Exits silently (without throwing) on failure or abort — callers
+ * MUST have a polling fallback that drives correctness.
+ */
+export async function* streamStudyEvents(client, studyId, signal) {
+    let token;
+    try {
+        const minted = await client.post("/auth/stream-token", { scope: `study:${studyId}:read` });
+        token = minted.token;
+    }
+    catch (err) {
+        // 503 = server not configured for realtime; anything else = transient.
+        // Either way, fall back silently.
+        void err;
+        return;
+    }
+    const url = `${client.apiBase}/studies/${studyId}/events?token=${encodeURIComponent(token)}`;
+    let response;
+    try {
+        response = await fetch(url, {
+            headers: { Accept: "text/event-stream" },
+            signal,
+        });
+    }
+    catch (err) {
+        void err;
+        return;
+    }
+    if (!response.ok || response.body === null) {
+        // 503 = broker not running on this instance; anything else = unexpected.
+        // Caller's polling rhythm handles it.
+        return;
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder("utf-8");
+    let buffer = "";
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                return;
+            buffer += decoder.decode(value, { stream: true });
+            // SSE framing: events are separated by blank lines. A line beginning
+            // with ":" is a comment (heartbeat) and is ignored.
+            let sep = buffer.indexOf("\n\n");
+            while (sep !== -1) {
+                const block = buffer.slice(0, sep);
+                buffer = buffer.slice(sep + 2);
+                const event = parseEventBlock(block);
+                if (event !== null)
+                    yield event;
+                sep = buffer.indexOf("\n\n");
+            }
+        }
+    }
+    catch (err) {
+        void err;
+        return;
+    }
+    finally {
+        // Best-effort cancel; ignore errors if the connection is already gone.
+        try {
+            await reader.cancel();
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+function parseEventBlock(block) {
+    // Skip comment-only blocks (e.g. `: ping - …`).
+    const lines = block.split(/\r?\n/);
+    let data = null;
+    for (const line of lines) {
+        if (line.startsWith(":") || line.length === 0)
+            continue;
+        if (line.startsWith("data:")) {
+            // Per SSE spec the value starts after the optional single space.
+            const value = line.slice(5).replace(/^ /, "");
+            data = data === null ? value : data + "\n" + value;
+        }
+        // We intentionally ignore `event:` and `id:` here — the type and seq
+        // are also present inside the JSON payload, which is the canonical
+        // form. Reading them from the framing too would just be redundant.
+    }
+    if (data === null)
+        return null;
+    try {
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+/** Type narrower used by callers to skip the synthetic LAG marker. */
+export function isLagEvent(event) {
+    return event.type === "stream.lag";
+}
+// Re-export ApiError so callers don't need a separate import path when
+// branching on whether the stream is available.
+export { ApiError };

package/dist/lib/types.d.ts

@@ -82,7 +82,6 @@ export interface Study {
     source_study_id?: string;
     assignments?: Assignment[];
     interview_questions?: InterviewQuestion[];
-    frames?: unknown[];
     iterations?: Iteration[];
     created_at: string;
     updated_at: string;

package/package.json

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