@ishlabs/cli 0.23.1 → 0.24.1

package/dist/connect.js

@@ -4,10 +4,12 @@
 import { spawn, execSync } from "node:child_process";
 import { existsSync, mkdirSync, chmodSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
+import net from "node:net";
 import { loadConfig, saveConfig } from "./config.js";
 import { refreshTokens, isTokenExpired, decodeJwtExp, AuthRefreshPermanentError } from "./auth.js";
 import { binDir, cloudflaredBin, simulationsDir, connectLockPath, ishDir } from "./lib/paths.js";
 import { c } from "./lib/colors.js";
+import { startReverseProxy } from "./lib/reverse-proxy.js";
 const TUNNEL_URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
 const HEARTBEAT_INTERVAL = 10_000;
 const MAX_HEARTBEAT_FAILURES = 3;
@@ -641,8 +643,63 @@ function scheduleProactiveRefresh(token, doRefresh, onTokenRefreshed, onAuthPerm
     }, delay);
     return { stop: () => clearTimeout(timer) };
 }
+// 500ms TCP probe. We label the primary service "frontend" by convention
+// (most devs run a UI on the primary port and APIs behind --proxy /api=…)
+// but it's purely cosmetic — the proxy itself routes by path, not label.
+async function probeService(port, timeoutMs = 500) {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        let settled = false;
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(ok);
+        };
+        socket.setTimeout(timeoutMs);
+        socket.once("connect", () => finish(true));
+        socket.once("timeout", () => finish(false));
+        socket.once("error", () => finish(false));
+        socket.connect(port, "127.0.0.1");
+    });
+}
+async function probeServices(primaryPort, routes) {
+    const targets = [
+        { label: "frontend", port: primaryPort, reachable: false },
+    ];
+    for (const route of routes) {
+        // Pull the port back out of `http://host:port` for the probe; if the user
+        // pointed a route at a non-localhost target we skip the probe (we can't
+        // assume what's reachable from here) — they'll find out on first request.
+        try {
+            const url = new URL(route.target);
+            const port = parseInt(url.port, 10);
+            if (!isNaN(port)) {
+                targets.push({ label: route.prefix, port, reachable: false });
+            }
+        }
+        catch {
+            // Malformed target shouldn't happen — collectProxy validates upstream.
+        }
+    }
+    await Promise.all(targets.map(async (t) => {
+        t.reachable = await probeService(t.port);
+    }));
+    return targets;
+}
+function printProbeResults(probes) {
+    for (const p of probes) {
+        if (p.reachable) {
+            console.error(`${c.green}✓${c.reset} ${p.label} ready on :${p.port}`);
+        }
+        else {
+            console.error(`${c.dim}·${c.reset} ${p.label} not responding on :${p.port} (will retry on first request)`);
+        }
+    }
+}
 // --- Main ---
-export async function runTunnel(port, tokenArg, apiUrlArg, tokenFileArg, outputOpts = {}) {
+export async function runTunnel(port, tokenArg, apiUrlArg, tokenFileArg, outputOpts = {}, routes = []) {
     const json = outputOpts.json ?? false;
     const quiet = outputOpts.quiet ?? false;
     const apiUrl = resolveApiUrl(apiUrlArg);
@@ -665,28 +722,68 @@ export async function runTunnel(port, tokenArg, apiUrlArg, tokenFileArg, outputO
         }
         : null;
     const cloudflaredPath = await resolveCloudflaredBin();
+    // Multi-service mode: spin up a local reverse proxy on an OS-assigned port
+    // and tunnel THAT port. Bare `ish connect <port>` (no --proxy) keeps the
+    // legacy single-port behaviour — no proxy, no health checks.
+    let reverseProxy = null;
+    let tunneledPort = port;
+    if (routes.length > 0) {
+        if (!json && !quiet) {
+            const probes = await probeServices(port, routes);
+            printProbeResults(probes);
+        }
+        try {
+            reverseProxy = await startReverseProxy({ primaryPort: port, routes });
+            tunneledPort = reverseProxy.port;
+        }
+        catch (e) {
+            throw new Error(`Failed to start reverse proxy: ${e instanceof Error ? e.message : e}`);
+        }
+        if (!json && !quiet) {
+            const summary = routes.map((r) => `${r.prefix} → ${r.target}`).join(", ");
+            console.error(`Reverse proxy ready on :${tunneledPort} (default → :${port}, ${summary})`);
+        }
+    }
     let cfResult;
     try {
-        cfResult = await startCloudflared(port, cloudflaredPath, json);
+        cfResult = await startCloudflared(tunneledPort, cloudflaredPath, json);
     }
     catch (e) {
+        if (reverseProxy)
+            await reverseProxy.close().catch(() => { });
         throw new Error(`Failed to start cloudflared: ${e instanceof Error ? e.message : e}`);
     }
     const { process: cfProcess, tunnelUrl } = cfResult;
-    const registered = await registerTunnel(apiUrl, currentToken, tunnelUrl, port);
+    const registered = await registerTunnel(apiUrl, currentToken, tunnelUrl, tunneledPort);
     // Announce the tunnel URL — this is the load-bearing output of `ish connect`.
     if (json) {
-        console.log(JSON.stringify({
+        const connectedPayload = {
             status: "connected",
             tunnel_url: tunnelUrl,
+            // `local_port` keeps reporting the user-supplied primary port so
+            // single-port consumers don't see the proxy's ephemeral port slip in.
             local_port: port,
             registered,
-        }));
+        };
+        if (routes.length > 0) {
+            connectedPayload.proxy_port = tunneledPort;
+            connectedPayload.routes = routes;
+        }
+        console.log(JSON.stringify(connectedPayload));
     }
     else {
         if (!quiet)
             printBanner();
         console.log(`Tunnel URL: ${tunnelUrl} → http://localhost:${port}\n`);
+        if (routes.length > 0) {
+            console.log("Routes:");
+            console.log(`  /          → localhost:${port}`);
+            for (const r of routes) {
+                const padded = r.prefix.padEnd(10, " ");
+                console.log(`  ${padded} → ${r.target.replace(/^http:\/\//, "")}`);
+            }
+            console.log("");
+        }
     }
     let shuttingDown = false;
     // Holders for forward references — `onAuthPermanent` needs to stop these
@@ -720,16 +817,20 @@ export async function runTunnel(port, tokenArg, apiUrlArg, tokenFileArg, outputO
             console.error(`Cause: ${cause.message}`);
         }
         await deregisterTunnel(apiUrl, currentToken, json, true);
+        if (reverseProxy)
+            await reverseProxy.close().catch(() => { });
         cfProcess.kill();
         clearLock();
         process.exit(3);
     };
     heartbeat = startHeartbeat(apiUrl, () => currentToken, serializedRefresh, onTokenRefreshed, async () => {
         await deregisterTunnel(apiUrl, currentToken, json);
+        if (reverseProxy)
+            await reverseProxy.close().catch(() => { });
         cfProcess.kill();
         clearLock();
         process.exit(1);
-    }, onAuthPermanent, json, () => registerTunnel(apiUrl, currentToken, tunnelUrl, port));
+    }, onAuthPermanent, json, () => registerTunnel(apiUrl, currentToken, tunnelUrl, tunneledPort));
     proactiveRefresh = scheduleProactiveRefresh(currentToken, serializedRefresh, onTokenRefreshed, onAuthPermanent, json);
     const shutdown = async () => {
         if (shuttingDown)
@@ -739,6 +840,10 @@ export async function runTunnel(port, tokenArg, apiUrlArg, tokenFileArg, outputO
             console.error("\nShutting down...");
         heartbeat?.stop();
         proactiveRefresh?.stop();
+        // Close the reverse proxy BEFORE killing cloudflared: stop accepting new
+        // inbound requests at the local hop, then tear down the tunnel.
+        if (reverseProxy)
+            await reverseProxy.close().catch(() => { });
         cfProcess.kill();
         await deregisterTunnel(apiUrl, currentToken, json);
         clearLock();
@@ -753,6 +858,8 @@ export async function runTunnel(port, tokenArg, apiUrlArg, tokenFileArg, outputO
         if (!shuttingDown) {
             heartbeat?.stop();
             proactiveRefresh?.stop();
+            if (reverseProxy)
+                await reverseProxy.close().catch(() => { });
             await deregisterTunnel(apiUrl, currentToken, json);
             clearLock();
             process.exit(0);
@@ -766,9 +873,13 @@ export async function runTunnel(port, tokenArg, apiUrlArg, tokenFileArg, outputO
         writeLock({
             pid: process.pid,
             tunnel_url: tunnelUrl,
+            // `local_port` is what the user typed (the primary). When multi-service
+            // is active, `proxy_port` records the OS-assigned port we actually
+            // tunneled, alongside the route table.
             local_port: port,
             registered_at: new Date().toISOString(),
             api_url: apiUrl,
+            ...(routes.length > 0 ? { proxy_port: tunneledPort, routes } : {}),
         });
     }
 }
@@ -785,6 +896,8 @@ function readLock() {
         const parsed = JSON.parse(raw);
         if (typeof parsed.pid !== "number")
             return null;
+        if (!Array.isArray(parsed.routes))
+            parsed.routes = [];
         return parsed;
     }
     catch {
@@ -815,7 +928,7 @@ function pidIsAlive(pid) {
 // stdout, then exit the parent. The child writes the lock file on its
 // own once detached (see ISH_CONNECT_DETACHED branch in runTunnel).
 // ---------------------------------------------------------------------------
-export async function runDetached(port, apiUrlArg, tokenArg, tokenFileArg) {
+export async function runDetached(port, apiUrlArg, tokenArg, tokenFileArg, routes = []) {
     const existing = readLock();
     if (existing && pidIsAlive(existing.pid)) {
         throw new Error(`An active tunnel is already running (pid ${existing.pid}, ${existing.tunnel_url}). Run \`ish disconnect\` first.`);
@@ -839,6 +952,14 @@ export async function runDetached(port, apiUrlArg, tokenArg, tokenFileArg) {
     if (tokenFileArg)
         childArgs.push("--token-file", tokenFileArg);
     childArgs.push("--json", "connect", String(port));
+    // Re-serialise routes into `--proxy /prefix=host:port` form for the child.
+    // Targets coming through here are always `http://host:port` (collectProxy
+    // shape-validates and parseProxyValues builds the URL), so stripping the
+    // scheme back off round-trips cleanly.
+    for (const route of routes) {
+        const stripped = route.target.replace(/^https?:\/\//, "");
+        childArgs.push("--proxy", `${route.prefix}=${stripped}`);
+    }
     const child = spawn(exe, [script, ...childArgs], {
         detached: true,
         stdio: ["ignore", "pipe", "pipe"],
@@ -916,11 +1037,14 @@ export async function runDetached(port, apiUrlArg, tokenArg, tokenFileArg) {
     // don't unref stdio — the child's own SIGTERM handler does graceful
     // shutdown via deregister.
     child.unref();
-    console.log(JSON.stringify({
+    const detachOutput = {
         pid: child.pid,
         tunnel_url: connected.tunnel_url,
         registered: connected.registered,
-    }));
+    };
+    if (routes.length > 0)
+        detachOutput.routes = routes;
+    console.log(JSON.stringify(detachOutput));
 }
 // ---------------------------------------------------------------------------
 // Status — read-only check of the active tunnel.
@@ -938,21 +1062,37 @@ export function connectStatus(json) {
         }
         return;
     }
+    const lockRoutes = lock.routes ?? [];
     if (json) {
-        console.log(JSON.stringify({
+        const payload = {
             active: true,
             pid: lock.pid,
             tunnel_url: lock.tunnel_url,
             local_port: lock.local_port,
             registered_at: lock.registered_at,
             api_url: lock.api_url,
-        }));
+        };
+        if (lockRoutes.length > 0) {
+            payload.proxy_port = lock.proxy_port;
+            payload.routes = lockRoutes;
+        }
+        console.log(JSON.stringify(payload));
     }
     else {
         console.log(`Active tunnel: ${lock.tunnel_url} → http://localhost:${lock.local_port}`);
         console.log(`  pid:           ${lock.pid}`);
         console.log(`  registered_at: ${lock.registered_at}`);
         console.log(`  api:           ${lock.api_url}`);
+        if (lockRoutes.length > 0) {
+            if (lock.proxy_port)
+                console.log(`  proxy_port:    ${lock.proxy_port}`);
+            console.log("Routes:");
+            console.log(`  /          → localhost:${lock.local_port}`);
+            for (const r of lockRoutes) {
+                const padded = r.prefix.padEnd(10, " ");
+                console.log(`  ${padded} → ${r.target.replace(/^http:\/\//, "")}`);
+            }
+        }
     }
 }
 // ---------------------------------------------------------------------------

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { program, Option } from "commander";
+import { program, Option, InvalidArgumentError } from "commander";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
@@ -21,7 +21,7 @@ import { registerMcpCommands } from "./commands/mcp.js";
 import { registerSecretCommands } from "./commands/secret.js";
 import { AGENT_HELP_FOOTER } from "./lib/docs.js";
 import { runInline, EXIT_USAGE, injectGlobalWorkspaceOption } from "./lib/command-helpers.js";
-import { resolveApiUrl, resolveToken } from "./lib/auth.js";
+import { resolveApiUrl, resolveToken, verifyToken } from "./lib/auth.js";
 import { ApiClient } from "./lib/api-client.js";
 import { tagAlias, ALIAS_PREFIX } from "./lib/alias-store.js";
 import { output } from "./lib/output.js";
@@ -155,7 +155,18 @@ Examples:
         if (!opts.force) {
             const existing = loadConfig();
             const existingToken = existing.access_token;
-            if (existingToken && !isTokenExpired(existingToken)) {
+            // Local expiry alone isn't enough to claim "Already logged in": a token
+            // can be unexpired yet rejected by the API — a revoked session, a rotated
+            // signing key, or the classic footgun of a token minted against the dev
+            // Supabase project while we're calling the prod api. Confirm the server
+            // actually accepts it before short-circuiting; otherwise fall through to
+            // the browser flow and re-auth. verifyToken() returns true on a network
+            // blip (best-effort probe), so an offline user with an otherwise-good
+            // token still short-circuits rather than being forced online.
+            const apiUrl = resolveApiUrl(globals.apiUrl, globals.dev);
+            if (existingToken &&
+                !isTokenExpired(existingToken) &&
+                (await verifyToken(existingToken, apiUrl))) {
                 const claims = decodeJwtClaims(existingToken);
                 const email = typeof claims?.email === "string" ? claims.email : "(no email in token)";
                 const exp = typeof claims?.exp === "number" ? claims.exp : 0;
@@ -388,11 +399,45 @@ program
         }
     });
 });
+// Validator for --proxy values. Accepts /prefix=port or /prefix=host:port; we
+// keep the host charset narrow (alphanum, dot, dash) so a malformed value
+// fails fast with a clear message instead of hitting cloudflared.
+const PROXY_VALUE_PATTERN = /^\/[a-zA-Z0-9/_-]+=([a-zA-Z0-9.-]+:)?[0-9]+$/;
+function collectProxy(value, previous) {
+    if (!PROXY_VALUE_PATTERN.test(value)) {
+        // InvalidArgumentError routes through Commander's error-handling path,
+        // which our exitOverride converts to the standard JSON envelope. A
+        // plain Error here would crash with a raw stack trace.
+        throw new InvalidArgumentError(`--proxy expected /prefix=port, got "${value}"`);
+    }
+    return [...previous, value];
+}
+// Convert raw --proxy values (already shape-validated by collectProxy) into
+// `{prefix, target}` records the connect flow can pass straight to
+// startReverseProxy. Rejects duplicate prefixes — the route table would
+// otherwise have a silent winner depending on declaration order.
+function parseProxyValues(values) {
+    const routes = [];
+    const seen = new Set();
+    for (const raw of values) {
+        const eq = raw.indexOf("=");
+        const prefix = raw.slice(0, eq);
+        const rhs = raw.slice(eq + 1);
+        if (seen.has(prefix)) {
+            throw new Error(`--proxy prefix "${prefix}" specified more than once`);
+        }
+        seen.add(prefix);
+        const target = rhs.includes(":") ? `http://${rhs}` : `http://127.0.0.1:${rhs}`;
+        routes.push({ prefix, target });
+    }
+    return routes;
+}
 const connectCmd = program
     .command("connect")
     .description("Expose your localhost to Ish via a Cloudflare tunnel")
     .argument("[port]", "Local port to connect (e.g. 3000)")
     .option("--detach", "Fork after first heartbeat success; print {pid, tunnel_url, registered} JSON and exit")
+    .option("--proxy <route>", "<prefix>=<port>, repeatable (e.g. --proxy /api=8000). Routes incoming requests under <prefix> to localhost:<port>; preserves the full request path.", collectProxy, [])
     .addHelpText("after", `
 Subcommands:
   ish connect status         Read-only check of the active detached tunnel
@@ -403,7 +448,18 @@ Note: --json emits structured one-line JSON for connected/disconnected events.
 
 Detach mode tracks the active tunnel in ~/.ish/connect.lock so \`ish connect
 status\` and \`ish disconnect\` can find it. Foreground (non-detached)
-connects do not write a lock — Ctrl+C is the shutdown verb in that mode.`)
+connects do not write a lock — Ctrl+C is the shutdown verb in that mode.
+
+Multi-service tunneling: pass --proxy /<prefix>=<port> (repeatable) to fan
+one tunnel across several local services. The CLI runs a tiny local reverse
+proxy on an OS-assigned port, tunnels that port, and routes requests by
+longest-prefix match (default → <port>). One origin in the cloud browser →
+no CORS, no cookie crossover.
+
+Examples:
+  $ ish connect 3000                              # frontend only
+  $ ish connect 3000 --proxy /api=8000            # frontend + backend
+  $ ish connect 3000 --proxy /api=8000 --proxy /ws=9000`)
     .action(async (port, opts, cmd) => {
     await runInline(cmd, async (globals) => {
         if (!port) {
@@ -413,15 +469,16 @@ connects do not write a lock — Ctrl+C is the shutdown verb in that mode.`)
         if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
             throw new Error(`Invalid port: ${port}`);
         }
+        const routes = parseProxyValues(opts.proxy ?? []);
         const apiUrl = globals.dev ? "http://localhost:8000" : globals.apiUrl;
         if (opts.detach) {
-            await runDetached(portNum, apiUrl, globals.token, globals.tokenFile);
+            await runDetached(portNum, apiUrl, globals.token, globals.tokenFile, routes);
             return;
         }
         await runTunnel(portNum, globals.token, apiUrl, globals.tokenFile, {
             json: globals.json,
             quiet: globals.quiet,
-        });
+        }, routes);
     });
 });
 connectCmd

package/dist/lib/ask-questions.d.ts

@@ -1,9 +1,19 @@
 /**
- * Loader/validator for `--questions <file.json>`.
+ * Loader/validator for the questionnaire input (`ish study create/update
+ * --questionnaire`, `ish ask … --questions`).
  *
- * Accepts a JSON array of InterviewQuestion entries. Mirrors the loose validation
- * used by `ish study create --questions`: requires `question: string` on every entry,
- * passes the rest through. The backend is the source of truth for the full schema.
+ * Accepts THREE input forms so agents never have to drop a temp file just to
+ * use a rich question type — mirroring how `--assignments` takes inline JSON
+ * and `--assignments-file` takes a path:
+ *   - **inline JSON array**: `'[{"question":"…","type":"slider","min":0,"max":10}]'`
+ *     (value, after trimming, starts with `[`)
+ *   - **@file**:             `@/path/to/questions.json`
+ *   - **bare file path**:    `./questions.json`
+ *
+ * In every form the payload is a JSON array of InterviewQuestion entries.
+ * Validation is loose — requires `question: string` on every entry and folds
+ * the `type` enum to its canonical hyphenated form; the rest passes through, so
+ * the backend stays the source of truth for the full schema.
  */
 import type { InterviewQuestion } from "./types.js";
-export declare function loadQuestionsManifest(filePath: string): InterviewQuestion[];
+export declare function loadQuestionsManifest(input: string): InterviewQuestion[];

package/dist/lib/ask-questions.js

@@ -1,30 +1,53 @@
 /**
- * Loader/validator for `--questions <file.json>`.
+ * Loader/validator for the questionnaire input (`ish study create/update
+ * --questionnaire`, `ish ask … --questions`).
  *
- * Accepts a JSON array of InterviewQuestion entries. Mirrors the loose validation
- * used by `ish study create --questions`: requires `question: string` on every entry,
- * passes the rest through. The backend is the source of truth for the full schema.
+ * Accepts THREE input forms so agents never have to drop a temp file just to
+ * use a rich question type — mirroring how `--assignments` takes inline JSON
+ * and `--assignments-file` takes a path:
+ *   - **inline JSON array**: `'[{"question":"…","type":"slider","min":0,"max":10}]'`
+ *     (value, after trimming, starts with `[`)
+ *   - **@file**:             `@/path/to/questions.json`
+ *   - **bare file path**:    `./questions.json`
+ *
+ * In every form the payload is a JSON array of InterviewQuestion entries.
+ * Validation is loose — requires `question: string` on every entry and folds
+ * the `type` enum to its canonical hyphenated form; the rest passes through, so
+ * the backend stays the source of truth for the full schema.
  */
 import { readFileSync } from "node:fs";
 import { resolve as resolvePath } from "node:path";
 import { normalizeEnumValue, QUESTION_TYPES } from "./enums.js";
-export function loadQuestionsManifest(filePath) {
+export function loadQuestionsManifest(input) {
+    const trimmed = input.trim();
+    // Inline JSON vs file path (bare or `@`-prefixed). Inline JSON starts with
+    // `[` (the expected array) or `{` (a bare object — caught below with a clear
+    // "must be an array" message rather than a confusing "cannot read file");
+    // a real path never starts with either, so the leading char disambiguates.
+    const isInline = trimmed.startsWith("[") || trimmed.startsWith("{");
+    const filePath = trimmed.startsWith("@") ? trimmed.slice(1).trim() : trimmed;
+    const source = isInline ? "inline questionnaire JSON" : `questions file: ${filePath}`;
     let raw;
-    try {
-        raw = readFileSync(resolvePath(filePath), "utf-8");
+    if (isInline) {
+        raw = trimmed;
     }
-    catch {
-        throw new Error(`Cannot read questions file: ${filePath}`);
+    else {
+        try {
+            raw = readFileSync(resolvePath(filePath), "utf-8");
+        }
+        catch {
+            throw new Error(`Cannot read questions file: ${filePath}`);
+        }
     }
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch {
-        throw new Error(`Invalid JSON in questions file: ${filePath}`);
+        throw new Error(`Invalid JSON in ${source}.`);
     }
     if (!Array.isArray(parsed) || parsed.length === 0) {
-        throw new Error(`Questions file must be a non-empty JSON array: ${filePath}`);
+        throw new Error(`Questionnaire must be a non-empty JSON array (${source}).`);
     }
     for (let i = 0; i < parsed.length; i++) {
         const q = parsed[i];

package/dist/lib/auth.d.ts

@@ -5,4 +5,5 @@
 export declare const DEFAULT_API_URL = "https://api.ishlabs.io";
 export declare const API_BASE = "/api/v1";
 export declare function resolveApiUrl(apiUrlArg?: string, dev?: boolean): string;
+export declare function verifyToken(token: string, apiUrl: string): Promise<boolean>;
 export declare function resolveToken(tokenArg: string | undefined, apiUrl: string, tokenFileArg?: string): Promise<string>;

package/dist/lib/auth.js

@@ -15,7 +15,13 @@ export function resolveApiUrl(apiUrlArg, dev) {
         return apiUrlArg;
     return process.env.ISH_API_URL ?? DEFAULT_API_URL;
 }
-async function verifyToken(token, apiUrl) {
+// Exported so the `ish login` idempotency guard can confirm the API actually
+// accepts a saved token before claiming "Already logged in" — a locally
+// unexpired JWT can still be rejected server-side (revoked session, rotated
+// signing key, or a token minted against the dev Supabase project while we call
+// the prod api). Both callers treat a network blip as "assume valid" (returns
+// true below) so an offline user is never forced through a needless re-login.
+export async function verifyToken(token, apiUrl) {
     try {
         const resp = await fetch(`${apiUrl}${API_BASE}/connect/active`, {
             headers: withBaggage({ Authorization: `Bearer ${token}` }),

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;