@ishlabs/cli 0.24.0 → 0.24.1

package/dist/commands/study-run.js

@@ -14,7 +14,7 @@ import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { output, formatSimulationPoll } from "../lib/output.js";
 import { fetchStudyParticipants } from "../lib/study-participants.js";
 import { streamStudyEvents } from "../lib/study-events.js";
-import { isMediaModality, isChatModality, iterationHasContent, describeRequiredContentFlag, readChatMode, readParticipantPairConfig, summarizeRoleCriteria, } from "../lib/modality.js";
+import { isMediaModality, isChatModality, iterationHasContent, describeRequiredContentFlag, readChatMode, readParticipantPairConfig, summarizeRoleCriteria, toModality, } from "../lib/modality.js";
 // NOTE: local-sim modules are loaded via dynamic import at the `--local`
 // branch below, NOT statically here. `local-sim/install.ts` deep-imports
 // `playwright-core/lib/server/registry/index`, which is not exposed by
@@ -663,7 +663,7 @@ Examples:
                                     : `CLI default — pass --max-interactions to override`;
                             log(`    Max steps:      ${stepsForMedia} (${source})`);
                             if (Number.isFinite(stepsForMedia)) {
-                                const est = estimateMediaRun({ participantCount, maxInteractions: stepsForMedia });
+                                const est = estimateMediaRun({ modality: toModality(modality), participantCount, maxInteractions: stepsForMedia });
                                 log(`    Credits (est):  ≈ ${est.upper_bound} credit(s) upper bound — ${est.breakdown}`);
                             }
                         }
@@ -1021,7 +1021,7 @@ Examples:
                 const steps = resolveMaxInteractions(opts.maxInteractions, iteration.details);
                 if (!Number.isFinite(steps))
                     return null;
-                return estimateMediaRun({ participantCount, maxInteractions: steps });
+                return estimateMediaRun({ modality: toModality(modality), participantCount, maxInteractions: steps });
             })();
             if (!opts.wait) {
                 if (globals.json) {

package/dist/lib/billing.d.ts

@@ -2,17 +2,23 @@
  * Credit cost estimators — mirror the backend's billing formulas so the CLI
  * can surface a pre-dispatch estimate without a network round-trip.
  *
- * The numbers here MUST match `ish-backend/app/{media,chat}/billing.py`
- * and `app/billing/service.py`. If the backend formula changes, update
- * this file in the same commit, otherwise the CLI will mislead agents.
+ * Source of truth: `ish-backend/app/billing/rates.py` (`MODALITY_RATES`,
+ * `compute_step_cost`, `compute_chat_cost`, `ASK_PER_RESPONSE_CREDITS`,
+ * `PAIR_CHAT_SIDE_MULTIPLIER`). These numbers MUST match that module — when a
+ * multiplier changes there, update this file in the same commit, otherwise the
+ * CLI will mislead agents. The backend prices through one `price_run` dispatcher
+ * shared by `POST /billing/estimate` and the real preflight reservation, so the
+ * preview here is calibrated to the actual charge as long as the rates agree.
  *
- * Today every modality uses the same shape: `max(1, round(steps / 10))`
- * per principal (per participant for media/interactive, per conversation for
- * chat, ×2 for participant-pair). Asks bill flat 1 credit per successful
- * participant response. These are intentionally per-run estimates; long-term
- * we'll fetch `GET /billing/rates` and parameterise modalities — see
- * `reference/credits` docs page.
+ * Each modality has its own per-step rate (interactive costs the most —
+ * screenshot + vision per step; text-only the least). The per-principal cost is
+ * `max(1, round(steps * per_step_credits))`, per participant for step-based
+ * modalities and per conversation (×2 in pair mode) for chat. Asks bill a flat
+ * credit per successful participant response (an upper bound — refusals/errors
+ * don't bill). Clients that need authoritative live rates can fetch them from
+ * `GET /billing/rates`; this offline mirror is for the pre-dispatch preview.
  */
+import type { Modality } from "./modality.js";
 export interface CreditEstimate {
     /** Upper bound (no early termination). Never claims exactness. */
     upper_bound: number;
@@ -23,16 +29,24 @@ export interface CreditEstimate {
     /** Always "credits" today; reserved for future-proofing (e.g. millicredits). */
     unit: "credits";
 }
-/** Mirror of `app/media/billing.py::media_credit_cost`. */
-export declare function mediaCreditCost(steps: number): number;
-/** Mirror of `app/chat/billing.py::chat_credit_cost`. */
-export declare function chatCreditCost(turns: number): number;
 /**
- * Media/interactive run: 1 credit-cost-per-participant × participant count. Modality
- * doesn't currently affect the rate (interactive == text == video at the
- * billing layer) — kept as a parameter for forward compatibility.
+ * Per-principal step-based cost for one participant running `steps` interactions
+ * on a study of `modality`. Mirror of `app/billing/rates.py::compute_step_cost`.
+ */
+export declare function stepCreditCost(modality: Modality, steps: number): number;
+/**
+ * Per-conversation chat cost. Mirror of `app/billing/rates.py::compute_chat_cost`
+ * — `max(1, round(turns * chat_rate))`, doubled in pair mode (both sides bill
+ * per turn).
+ */
+export declare function chatCreditCost(turns: number, isPair?: boolean): number;
+/**
+ * Step-based run (interactive / text / image / video / audio / document):
+ * per-participant cost × participant count. The per-step rate is modality-
+ * specific (see `PER_STEP_CREDITS`).
  */
 export declare function estimateMediaRun(args: {
+    modality: Modality;
     participantCount: number;
     maxInteractions: number;
 }): CreditEstimate;

package/dist/lib/billing.js

@@ -2,41 +2,90 @@
  * Credit cost estimators — mirror the backend's billing formulas so the CLI
  * can surface a pre-dispatch estimate without a network round-trip.
  *
- * The numbers here MUST match `ish-backend/app/{media,chat}/billing.py`
- * and `app/billing/service.py`. If the backend formula changes, update
- * this file in the same commit, otherwise the CLI will mislead agents.
+ * Source of truth: `ish-backend/app/billing/rates.py` (`MODALITY_RATES`,
+ * `compute_step_cost`, `compute_chat_cost`, `ASK_PER_RESPONSE_CREDITS`,
+ * `PAIR_CHAT_SIDE_MULTIPLIER`). These numbers MUST match that module — when a
+ * multiplier changes there, update this file in the same commit, otherwise the
+ * CLI will mislead agents. The backend prices through one `price_run` dispatcher
+ * shared by `POST /billing/estimate` and the real preflight reservation, so the
+ * preview here is calibrated to the actual charge as long as the rates agree.
  *
- * Today every modality uses the same shape: `max(1, round(steps / 10))`
- * per principal (per participant for media/interactive, per conversation for
- * chat, ×2 for participant-pair). Asks bill flat 1 credit per successful
- * participant response. These are intentionally per-run estimates; long-term
- * we'll fetch `GET /billing/rates` and parameterise modalities — see
- * `reference/credits` docs page.
+ * Each modality has its own per-step rate (interactive costs the most —
+ * screenshot + vision per step; text-only the least). The per-principal cost is
+ * `max(1, round(steps * per_step_credits))`, per participant for step-based
+ * modalities and per conversation (×2 in pair mode) for chat. Asks bill a flat
+ * credit per successful participant response (an upper bound — refusals/errors
+ * don't bill). Clients that need authoritative live rates can fetch them from
+ * `GET /billing/rates`; this offline mirror is for the pre-dispatch preview.
  */
-/** Mirror of `app/media/billing.py::media_credit_cost`. */
-export function mediaCreditCost(steps) {
+/**
+ * Per-step credit multiplier per modality. Mirror of
+ * `app/billing/rates.py::MODALITY_RATES` (the `per_step_credits` field).
+ */
+const PER_STEP_CREDITS = {
+    interactive: 1.0,
+    video: 0.5,
+    audio: 0.3,
+    image: 0.2,
+    text: 0.1,
+    document: 0.3,
+    chat: 0.2,
+};
+/** Mirror of `app/billing/rates.py::ASK_PER_RESPONSE_CREDITS`. */
+const ASK_PER_RESPONSE_CREDITS = 1;
+/** Mirror of `app/billing/rates.py::PAIR_CHAT_SIDE_MULTIPLIER`. */
+const PAIR_CHAT_SIDE_MULTIPLIER = 2;
+/**
+ * Round half-to-even ("banker's rounding") to match Python's built-in
+ * `round()`, which the backend uses. `Math.round` rounds half *up*, so for
+ * costs that land on a .5 boundary (e.g. video at rate 0.5 with an odd step
+ * count: 5 × 0.5 = 2.5) it would over-quote by one credit vs the real charge.
+ * Replicating banker's rounding keeps the preview byte-for-byte with the
+ * backend's `compute_step_cost` / `compute_chat_cost`.
+ */
+function bankersRound(value) {
+    const floor = Math.floor(value);
+    const diff = value - floor;
+    if (diff < 0.5)
+        return floor;
+    if (diff > 0.5)
+        return floor + 1;
+    // Exactly .5 — round to the nearest even integer.
+    return floor % 2 === 0 ? floor : floor + 1;
+}
+/**
+ * Per-principal step-based cost for one participant running `steps` interactions
+ * on a study of `modality`. Mirror of `app/billing/rates.py::compute_step_cost`.
+ */
+export function stepCreditCost(modality, steps) {
     if (!Number.isFinite(steps) || steps <= 0)
         return 1;
-    return Math.max(1, Math.round(steps / 10));
+    return Math.max(1, bankersRound(steps * PER_STEP_CREDITS[modality]));
 }
-/** Mirror of `app/chat/billing.py::chat_credit_cost`. */
-export function chatCreditCost(turns) {
+/**
+ * Per-conversation chat cost. Mirror of `app/billing/rates.py::compute_chat_cost`
+ * — `max(1, round(turns * chat_rate))`, doubled in pair mode (both sides bill
+ * per turn).
+ */
+export function chatCreditCost(turns, isPair = false) {
     if (!Number.isFinite(turns) || turns <= 0)
-        return 1;
-    return Math.max(1, Math.round(turns / 10));
+        return isPair ? PAIR_CHAT_SIDE_MULTIPLIER : 1;
+    const perSide = Math.max(1, bankersRound(turns * PER_STEP_CREDITS.chat));
+    return isPair ? perSide * PAIR_CHAT_SIDE_MULTIPLIER : perSide;
 }
 /**
- * Media/interactive run: 1 credit-cost-per-participant × participant count. Modality
- * doesn't currently affect the rate (interactive == text == video at the
- * billing layer) — kept as a parameter for forward compatibility.
+ * Step-based run (interactive / text / image / video / audio / document):
+ * per-participant cost × participant count. The per-step rate is modality-
+ * specific (see `PER_STEP_CREDITS`).
  */
 export function estimateMediaRun(args) {
-    const perParticipant = mediaCreditCost(args.maxInteractions);
+    const perParticipant = stepCreditCost(args.modality, args.maxInteractions);
     const total = Math.max(0, args.participantCount) * perParticipant;
+    const rate = PER_STEP_CREDITS[args.modality];
     return {
         upper_bound: total,
         formula: "media_per_participant",
-        breakdown: `${args.participantCount} participant(s) × max(1, round(${args.maxInteractions} steps / 10)) = ${args.participantCount} × ${perParticipant} = ${total}`,
+        breakdown: `${args.participantCount} participant(s) × max(1, round(${args.maxInteractions} steps × ${rate})) = ${args.participantCount} × ${perParticipant} = ${total}`,
         unit: "credits",
     };
 }
@@ -47,18 +96,19 @@ export function estimateChatSolo(args) {
     return {
         upper_bound: total,
         formula: "chat_solo",
-        breakdown: `${args.participantCount} participant(s) × max(1, round(${args.maxTurns} turns / 10)) = ${args.participantCount} × ${perParticipant} = ${total}`,
+        breakdown: `${args.participantCount} participant(s) × max(1, round(${args.maxTurns} turns × ${PER_STEP_CREDITS.chat})) = ${args.participantCount} × ${perParticipant} = ${total}`,
         unit: "credits",
     };
 }
 /** Participant-pair chat: each turn bills both sides, so cost doubles. */
 export function estimateChatPair(args) {
-    const perSide = chatCreditCost(args.maxTurns);
-    const total = Math.max(0, args.conversationCount) * perSide * 2;
+    const perConversation = chatCreditCost(args.maxTurns, true);
+    const perSide = perConversation / PAIR_CHAT_SIDE_MULTIPLIER;
+    const total = Math.max(0, args.conversationCount) * perConversation;
     return {
         upper_bound: total,
         formula: "chat_pair",
-        breakdown: `${args.conversationCount} conv × max(1, round(${args.maxTurns} turns / 10)) × 2 sides = ${args.conversationCount} × ${perSide} × 2 = ${total}`,
+        breakdown: `${args.conversationCount} conv × max(1, round(${args.maxTurns} turns × ${PER_STEP_CREDITS.chat})) × ${PAIR_CHAT_SIDE_MULTIPLIER} sides = ${args.conversationCount} × ${perSide} × ${PAIR_CHAT_SIDE_MULTIPLIER} = ${total}`,
         unit: "credits",
     };
 }
@@ -67,11 +117,11 @@ export function estimateChatPair(args) {
  * for completed responses; the upper bound assumes everyone completes).
  */
 export function estimateAskRound(args) {
-    const total = Math.max(0, args.participantCount);
+    const total = Math.max(0, args.participantCount) * ASK_PER_RESPONSE_CREDITS;
     return {
         upper_bound: total,
         formula: "ask_per_response",
-        breakdown: `${args.participantCount} participant(s) × 1 credit/response = ${total} (upper bound; only successful responses bill)`,
+        breakdown: `${args.participantCount} participant(s) × ${ASK_PER_RESPONSE_CREDITS} credit/response = ${total} (upper bound; only successful responses bill)`,
         unit: "credits",
     };
 }

package/dist/lib/modality.d.ts

@@ -7,7 +7,16 @@
  * and the call sites (`study run`, `iteration update`, ...) pick up the
  * change for free.
  */
-export type Modality = "interactive" | "video" | "audio" | "text" | "image" | "document" | "chat";
+/** All study modalities. Matches the backend `Modality` enum value set. */
+export declare const MODALITIES: readonly ["interactive", "video", "audio", "text", "image", "document", "chat"];
+export type Modality = typeof MODALITIES[number];
+/**
+ * Coerce a raw study-modality string to a known `Modality`, defaulting to
+ * `"interactive"` for unknown/empty values — the same default the CLI uses
+ * elsewhere (`study.modality || "interactive"`) and the highest-cost rate, so
+ * an unrecognised modality errs toward over-estimating rather than under.
+ */
+export declare function toModality(raw: string | undefined): Modality;
 /** True for the media-bucket modalities that share batch + content semantics. */
 export declare function isMediaModality(modality: string | undefined): boolean;
 /** True for chat modality. Wrapped as a helper so callers don't sprinkle string literals. */

package/dist/lib/modality.js

@@ -9,6 +9,27 @@
  */
 import { normalizeEnumValue } from "./enums.js";
 import { MEDIA_MODALITIES } from "./types.js";
+/** All study modalities. Matches the backend `Modality` enum value set. */
+export const MODALITIES = [
+    "interactive",
+    "video",
+    "audio",
+    "text",
+    "image",
+    "document",
+    "chat",
+];
+/**
+ * Coerce a raw study-modality string to a known `Modality`, defaulting to
+ * `"interactive"` for unknown/empty values — the same default the CLI uses
+ * elsewhere (`study.modality || "interactive"`) and the highest-cost rate, so
+ * an unrecognised modality errs toward over-estimating rather than under.
+ */
+export function toModality(raw) {
+    return MODALITIES.includes(raw ?? "")
+        ? raw
+        : "interactive";
+}
 /** True for the media-bucket modalities that share batch + content semantics. */
 export function isMediaModality(modality) {
     return !!modality && MEDIA_MODALITIES.includes(modality);

package/package.json

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