@ishlabs/cli 0.24.0 → 0.25.0

package/dist/commands/ask.js

@@ -436,15 +436,15 @@ Picks come back with a \`pick_confidence\` (0..1) score per participant when
     // error rather than a transient failure.
     ask
         .command("dispatch")
-        .description("Dispatch a draft ask — bills credits and starts the round")
+        .description("Dispatch a draft ask — draws credits and starts the round")
         .argument("[id]", "Ask alias or UUID (defaults to active ask)")
         .option("--ask <id>", "Ask ID; alternative to positional argument")
         .option("--wait", "Wait until the first round completes (or errors)")
         .option("--timeout <s>", "Wait timeout in seconds (default 300)")
         .addHelpText("after", `
 Use after \`ish ask create --no-dispatch\` to start a draft once the user has
-reviewed it. The dispatch is BILLABLE — credits are charged when responses
-land, the same as a normal create.
+reviewed it. Dispatch draws credits as responses land, the same as a normal
+create. This is the expected way to run an ask — go ahead and dispatch.
 
 Examples:
   # Dispatch the active draft and wait for results:

package/dist/commands/iteration.js

@@ -383,7 +383,7 @@ Concept pages: ish docs get-page concepts/iteration
         // Media image
         .option("--image-urls <urls>", "Comma-separated image URLs or local file paths — image modality")
         // Shared media
-        .option("--title <title>", "Content title — media modalities")
+        .option("--title <title>", "Content title shown to participants (the leading headline they read) — media modalities")
         .option("--mime-type <type>", "MIME type (e.g. video/mp4) — media modalities")
         // Copy/caption
         .option("--copy-text <text>", "Ad copy or social post caption (or @filepath) — ads & social posts")

package/dist/commands/study-analyze.js

@@ -81,7 +81,7 @@ export function attachStudyAnalyzeCommands(study) {
     study
         .command("analyze")
         .description("Trigger an AI summary + key-insights analysis for a study. " +
-        "First analysis per study is free; subsequent runs cost 10 credits.")
+        "First analysis per study is included; subsequent runs draw 10 credits.")
         .argument("[id]", "Study ID (defaults to active study)")
         .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
         .option("--wait", "Poll until the run reaches completed or failed")

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
@@ -33,8 +33,8 @@ function parseMaxInteractions(value) {
 /**
  * Default cap the CLI sends when neither `--max-interactions` nor the
  * iteration carries its own value. Picked to match the frontend's
- * conservative interactive launchers and to prevent runaway spend when an
- * iteration runs against a broken or non-responsive surface — without a
+ * conservative interactive launchers and to prevent runaway credit draw when
+ * an iteration runs against a broken or non-responsive surface — without a
  * cap, a stuck participant can rack up hundreds of steps before the SDK gives
  * up.
  */
@@ -264,6 +264,34 @@ function readIterationDetails(details) {
         ...(typeof details.title === "string" && { title: details.title }),
     };
 }
+/**
+ * Normalize a platform string for matching. "web", "browser", and unset all
+ * mean the default browser path; "android"/"ios" are native. Lets `--platform
+ * web` match a "browser" iteration (and vice-versa) without false mismatches.
+ */
+function normalizePlatform(platform) {
+    const p = (platform ?? "").toLowerCase();
+    if (p === "" || p === "web" || p === "browser")
+        return "browser";
+    return p;
+}
+/**
+ * The local platform the user explicitly requested via flags, before any
+ * iteration is picked: --platform, or inferred from --app's extension
+ * (.apk → android, .app → ios). Undefined when neither is set (no preference →
+ * don't filter iterations by platform). The iteration's stored platform is
+ * deliberately NOT consulted here — it's what we're selecting against.
+ */
+function requestedLocalPlatform(opts) {
+    if (opts.platform)
+        return opts.platform;
+    const app = opts.app?.toLowerCase();
+    if (app?.endsWith(".apk"))
+        return "android";
+    if (app?.endsWith(".app"))
+        return "ios";
+    return undefined;
+}
 export function attachStudyRunCommands(study) {
     // --- Primary: `study run` ---
     const studyRun = study
@@ -294,6 +322,8 @@ export function attachStudyRunCommands(study) {
         .option("--devtools", "Open Chrome DevTools (local mode only)")
         .option("--debug", "Enable detailed debug logging to stderr and ~/.ish/local-sim.log")
         .option("--parallel <n>", "Run N participants in parallel (local mode only, default: all)")
+        .option("--platform <platform>", "Local target platform: 'web' (Playwright), 'android' (adb emulator), or 'ios' (simctl+idb simulator). Defaults to the iteration's platform.")
+        .option("--app <path>", "Native local mode: path to an .apk (android) / .app (ios) to install, or an installed package/bundle id to launch. The extension implies --platform.")
         .addHelpText("after", `
 Note: --workspace and --study are optional if you have set active context
   via \`ish workspace use <alias>\` and \`ish study use <alias>\`.
@@ -326,7 +356,7 @@ Examples:
   $ ish study run --config c-c3c
 
   # Cap interactions per participant (default 20 — pass higher to allow deeper
-  # exploration, lower to cap spend on a known-broken surface):
+  # exploration, lower to cap credit draw on a known-broken surface):
   $ ish study run --max-interactions 30
 
   # Block until all simulations finish (or timeout):
@@ -412,8 +442,13 @@ Examples:
             if (!study.assignments || study.assignments.length === 0) {
                 throw new Error("Study has no assignments. Add tasks with --assignments when creating the study, or use `ish study generate`.");
             }
-            // Step 1: Pick iteration (explicit --iteration, or latest on study)
+            // Step 1: Pick iteration (explicit --iteration, or latest on study).
+            // When --platform / --app requests a local platform, select the
+            // iteration whose details.platform matches — otherwise a multi-platform
+            // study (e.g. an android AND an ios iteration) would silently run the
+            // latest, which may be the wrong platform.
             const iterations = study.iterations || [];
+            const wantPlatform = opts.local ? requestedLocalPlatform(opts) : undefined;
             let iteration;
             if (opts.iteration) {
                 const wantedId = resolveId(opts.iteration);
@@ -421,6 +456,25 @@ Examples:
                 if (!iteration) {
                     throw new Error(`Iteration ${opts.iteration} not found on this study.`);
                 }
+                // An explicit --iteration whose platform contradicts --platform is a
+                // footgun (you'd drive the wrong device); refuse rather than guess.
+                if (wantPlatform) {
+                    const itPlatform = readIterationDetails(iteration.details).platform;
+                    if (normalizePlatform(itPlatform) !== normalizePlatform(wantPlatform)) {
+                        throw new Error(`--platform ${wantPlatform} but iteration ${opts.iteration} is platform ` +
+                            `'${itPlatform ?? "browser"}'. Pass the matching iteration or drop --platform.`);
+                    }
+                }
+            }
+            else if (wantPlatform) {
+                // Latest iteration whose platform matches the requested one.
+                const matching = iterations.filter((it) => normalizePlatform(readIterationDetails(it.details).platform) === normalizePlatform(wantPlatform));
+                if (matching.length === 0) {
+                    const available = [...new Set(iterations.map((it) => normalizePlatform(readIterationDetails(it.details).platform)))].join(", ") || "none";
+                    throw new Error(`No ${wantPlatform} iteration on this study (platforms present: ${available}). ` +
+                        `Create one with \`ish iteration create --study ${resolvedStudy} ...\`, or pass --iteration.`);
+                }
+                iteration = matching[matching.length - 1];
             }
             else if (iterations.length > 0) {
                 iteration = iterations[iterations.length - 1];
@@ -663,7 +717,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}`);
                             }
                         }
@@ -691,6 +745,21 @@ Examples:
             // by reusing the iteration's existing Conversation rows or by
             // calling pair-batch.
             let pairConversationIds = [];
+            // Resolve the local target platform ONCE so participant-create and the
+            // local-sim dispatch agree. Precedence: --platform flag > --app
+            // extension (.apk → android, .app → ios) > iteration's stored platform
+            // > browser. Used to set participant.platform (so the backend's native
+            // trigger is driven primarily by the participant, not just the
+            // empty-tree fallback) and to pick the device in the local loop.
+            const platformFromApp = opts.app?.toLowerCase().endsWith(".apk")
+                ? "android"
+                : opts.app?.toLowerCase().endsWith(".app")
+                    ? "ios"
+                    : undefined;
+            const resolvedPlatform = opts.platform
+                ?? platformFromApp
+                ?? detailsView.platform
+                ?? "browser";
             if (isPair && pairConfig) {
                 // Pair-mode flow mirrors the MCP (`ish-mcp` `_run_pair_mode`):
                 //   1. If the iteration already carries `conversations[]` from a
@@ -782,7 +851,7 @@ Examples:
                     participant_type: "ai",
                     status: "draft",
                     ...(opts.language && { language: opts.language }),
-                    ...(!isMedia && !isChat && { platform: detailsView.platform || "browser" }),
+                    ...(!isMedia && !isChat && { platform: resolvedPlatform }),
                 }));
                 log(`Creating ${participantInputs.length} participant${participantInputs.length > 1 ? "s" : ""}...`);
                 const batchResult = await client.post(`/iterations/${iterationId}/participants/batch`, { participants: participantInputs }, { timeout: dispatchTimeoutMs });
@@ -814,6 +883,8 @@ Examples:
                     devtools: opts.devtools,
                     debug: opts.debug,
                     parallel: opts.parallel ? parseInt(opts.parallel, 10) : undefined,
+                    platform: resolvedPlatform,
+                    ...(opts.app && { appPath: opts.app }),
                     quiet: globals.quiet,
                     json: globals.json,
                 });
@@ -1021,7 +1092,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) {
@@ -1042,14 +1113,11 @@ Examples:
                     }, true);
                 }
                 else {
-                    for (let i = 0; i < simResults.length; i++) {
-                        const participant = createdParticipants[i];
-                        const personName = participant?.person?.name || "Unknown";
-                        log(`  ${personName.padEnd(24)} QUEUED`);
-                    }
+                    const studyAlias = tagAlias(ALIAS_PREFIX.study, resolvedStudy);
+                    const n = createdParticipants.length;
+                    log(`Dispatched ${n} participant${n > 1 ? "s" : ""} — run \`ish study results ${studyAlias}\` for results (or \`ish study poll --study ${studyAlias}\` / --wait to track progress).`);
                     const url = getWebUrl(globals, `/${resolvedWorkspace}/${resolvedStudy}/timeline`);
-                    log(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
-                    log(`Run \`ish study poll --study ${resolvedStudy}\` (or --wait next time) to check progress.`);
+                    log(`  ${terminalLink(url, "Open in browser ↗")}`);
                 }
                 return;
             }

package/dist/commands/study.js

@@ -113,7 +113,7 @@ Concept pages: ish docs get-page concepts/study
         .requiredOption("--name <name>", "Study name")
         .option("--description <description>", "Study description")
         .option("--modality <modality>", "Study modality (interactive, video, audio, text, image, document, chat)")
-        .option("--content-type <type>", "Content type (per-modality enum — see 'Content types by modality' below). Not used for interactive / chat.")
+        .option("--content-type <type>", "Content type (per-modality enum — see 'Content types by modality' below). Changes how --title is presented to participants (e.g. content-type email renders --title as the Subject: line). Not used for interactive / chat.")
         .option("--assignment <name:instructions>", "Assignment as 'Name:Instructions' (repeatable)", collectRepeatable, [])
         .option("--assignments-file <path>", "JSON file with assignments array")
         .option("--assignments <json>", "Inline JSON array of assignments (escape hatch)")
@@ -124,7 +124,7 @@ Concept pages: ish docs get-page concepts/study
         .option("--screen-format <format>", "Screen format for interactive iterations: desktop (default) or mobile_portrait (hyphen/underscore variants accepted)")
         .option("--content-url <url>", "Public URL of the media file. Creates iteration A inline (video, audio, document modalities). For local files, use the 2-step `iteration create` flow.")
         .option("--image-urls <urls>", "Comma-separated public image URLs. Creates iteration A inline (image modality). For local files, use the 2-step `iteration create` flow.")
-        .option("--title <title>", "Content title (text + media modalities — image, video, audio, document; optional). Not used for interactive / chat.")
+        .option("--title <title>", "Participant-facing content title — the headline participants read before the body (text + media modalities — image, video, audio, document; optional). With --content-type email it becomes the email Subject: line. Not an internal label. Not used for interactive / chat.")
         .option("--segmentation-json <json>", "Segmentation JSON for the inline iteration A — time_based {intervals_seconds, labels?}, section_based {sections[{name,label,...}]}, or page_based {} (text + media). section_based sections are SEMANTIC: group related paragraphs into a few coherent sections (a long article is usually 3-6 sections, not one per paragraph). Lets one `study create` build a complete segmented iteration — no separate `iteration create` needed.")
         .option("--content-config-json <json>", "Content-config JSON for the inline iteration A (early_termination, selected_segment_indices) — text + media.")
         .option("--content-html <html>", "HTML version of the text, or @filepath — text modality (email rendering)")
@@ -239,6 +239,9 @@ Examples:
 
 Content types by modality (source: VALID_CONTENT_TYPES in src/lib/types.ts; interactive + chat omitted — they don't take --content-type):
 ${describeContentTypes()}
+  The content type also shapes how --title is rendered to participants: with
+  content-type email, --title becomes the email Subject: line; otherwise it
+  reads as the leading headline of the content.
 
 Tips:
   Use \`--get <path>\` to capture a single value (e.g. \`--get id\`),
@@ -310,11 +313,12 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                 }
                 normalizedScreenFormat = normalized;
             }
-            // Pattern G.2: --title is metadata, not content. The backend
-            // accepts it on text + media modalities (see
-            // `buildIterationDetails` in iteration.ts). Reject it only on
-            // shapes that have no title field — interactive (URL only) and
-            // chat (endpoint config carries its own metadata).
+            // --title is participant-facing content: the backend renders it as a
+            // leading headline participants read before the body (and as the email
+            // Subject: line when content-type is email). It only exists on text +
+            // media modalities (see `buildIterationDetails` in iteration.ts), so
+            // reject it on shapes that have no title field — interactive (URL only)
+            // and chat (endpoint config carries its own configuration).
             if (opts.title !== undefined
                 && opts.contentText === undefined
                 && opts.contentUrl === undefined

package/dist/lib/alias-store.js

@@ -129,7 +129,7 @@ const HYDRATE_HINT = {
     // alias map at ~/.ish/aliases.json carries any sources the CLI has
     // touched in this session.
     ps: "ish source upload <file>  # or `cat ~/.ish/aliases.json | grep ^ps-` to recover prior aliases",
-    pt: "ish participant get <participant-id>",
+    pt: "ish study participant <participant-id>",
     c: "ish config list",
     a: "ish ask list",
     r: "ish ask get <ask-id>",

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

@@ -48,6 +48,8 @@ export declare class ApiClient {
         screenshot_url?: string;
         location_name: string;
         screen_format?: string;
+        full_page_screenshot_base64?: string;
+        platform?: string;
     }): Promise<{
         frame_version_id: string;
     }>;

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",
     };
 }