quotacap 0.0.39 → 0.0.41

package/dist/adapters/manual.js

@@ -15,8 +15,8 @@ export function parseManualUsage(provider, text, now = new Date()) {
     return {
         provider,
         plan: "unknown",
-        usedPct,
-        sessionPct,
+        weeklyPct: usedPct,
+        fiveHourPct: sessionPct,
         resetsAt,
         periodStart,
         source: "manual",

package/dist/adapters/muse.js

@@ -115,8 +115,8 @@ export function parseMuseTui(text, now = new Date()) {
     return {
         provider: "muse",
         plan,
-        usedPct,
-        sessionPct,
+        weeklyPct: usedPct,
+        fiveHourPct: sessionPct,
         resetsAt,
         periodStart,
         source: "tui",
@@ -177,7 +177,7 @@ export const museAdapter = {
                 unavailable: e,
                 usagePass: (timeoutMs) => usagePass(timeoutMs),
                 warmTurn: async (timeoutMs) => {
-                    await trackedExecFile("muse", "muse", ["exec", "hi"], {
+                    await trackedExecFile("muse", "muse", ["exec", "1+1"], {
                         cwd: museProbeDir(),
                         env: { ...process.env, MUSE_NO_AUTO_UPDATE: "1" },
                         timeout: timeoutMs,

package/dist/adapters/opencode-go.js

@@ -46,6 +46,32 @@ function readBearerToken(env = process.env) {
     }
     return entry.key;
 }
+// `rate-limited` is the binding state, not a failure: it is exactly the
+// reading issue 109 needed. Anything unreadable fails closed.
+function parseMonthly(usage) {
+    const monthly = usage.monthly;
+    if (typeof monthly !== "object" || monthly === null)
+        return {};
+    const m = monthly;
+    if (m.status !== "ok" && m.status !== "rate-limited") {
+        throw new Error("opencode-go: unknown monthly status");
+    }
+    const percent = m.percent;
+    if (typeof percent !== "number" || !Number.isFinite(percent) || percent < 0) {
+        throw new Error("opencode-go: bad monthly pct");
+    }
+    const resetsMs = Date.parse(String(m.resetsAt ?? ""));
+    if (!Number.isFinite(resetsMs)) {
+        throw new Error("opencode-go: bad monthly reset");
+    }
+    const exhausted = m.status === "rate-limited" || percent > 100;
+    return {
+        monthlyKind: "included",
+        monthlyStatus: exhausted ? "exhausted" : "ok",
+        monthlyPct: exhausted ? 100 : percent,
+        monthlyResetsAt: new Date(resetsMs).toISOString(),
+    };
+}
 export function parseOpencodeGoUsage(body, now = new Date()) {
     const usage = body?.usage;
     if (typeof usage !== "object" || usage === null) {
@@ -77,15 +103,17 @@ export function parseOpencodeGoUsage(body, now = new Date()) {
     if (typeof sessionPct !== "number" || !Number.isFinite(sessionPct) || sessionPct < 0 || sessionPct > 100) {
         throw new Error("opencode-go: bad rolling pct");
     }
+    const monthly = parseMonthly(usage);
     return {
         provider: "opencode-go",
         plan: "unknown",
-        usedPct,
-        sessionPct,
+        weeklyPct: usedPct,
+        fiveHourPct: sessionPct,
         resetsAt: new Date(resetsMs).toISOString(),
         periodStart: new Date(resetsMs - 7 * 86400000).toISOString(),
         source: "api",
         fetchedAt: now.toISOString(),
+        ...monthly,
     };
 }
 export const opencodeGoAdapter = {

package/dist/adapters/pty.d.ts

@@ -29,6 +29,15 @@ export interface PtyRunOptions {
      */
     respondToQueries?: boolean;
     completionRegex?: RegExp;
+    /**
+     * Optional initial prompt responder before readyRegex matches.
+     * If matched against the cleaned transcript during the pre-ready poll loop,
+     * sends `reply` once to dismiss or answer the prompt (e.g. workspace trust in a probe directory).
+     */
+    preReadyResponse?: {
+        match: RegExp;
+        reply: string;
+    };
     /** If matched, abort immediately with a clear error (e.g. trust prompts). */
     abortOn?: RegExp;
     timeoutMs: number;

package/dist/adapters/pty.js

@@ -329,6 +329,7 @@ async function runPtyBun(opts) {
         if (opts.readyRegex) {
             const deadline = Date.now() + readyTimeoutMs;
             let matched = false;
+            let preReadySent = false;
             while (Date.now() < deadline) {
                 checkCap();
                 checkAborted();
@@ -341,6 +342,13 @@ async function runPtyBun(opts) {
                     });
                 }
                 const clean = stripAnsi(transcript);
+                if (opts.preReadyResponse && !preReadySent && regexTest(opts.preReadyResponse.match, clean)) {
+                    preReadySent = true;
+                    try {
+                        proc.terminal.write(opts.preReadyResponse.reply);
+                    }
+                    catch { }
+                }
                 checkAbort(clean);
                 if (regexTest(opts.readyRegex, clean)) {
                     matched = true;
@@ -633,6 +641,7 @@ async function runPtyNode(opts) {
         if (opts.readyRegex) {
             const deadline = Date.now() + readyTimeoutMs;
             let matched = false;
+            let preReadySent = false;
             while (Date.now() < deadline) {
                 checkCap();
                 checkAborted();
@@ -645,6 +654,13 @@ async function runPtyNode(opts) {
                     });
                 }
                 const clean = stripAnsi(transcript);
+                if (opts.preReadyResponse && !preReadySent && regexTest(opts.preReadyResponse.match, clean)) {
+                    preReadySent = true;
+                    try {
+                        ptyProcess.write(opts.preReadyResponse.reply);
+                    }
+                    catch { }
+                }
                 checkAbort(clean);
                 if (regexTest(opts.readyRegex, clean)) {
                     matched = true;

package/dist/adapters/types.d.ts

@@ -1,8 +1,16 @@
 export interface Quota {
     provider: string;
     plan: string;
-    usedPct: number;
-    sessionPct?: number;
+    /** The paced window. 0..100. Named `usedPct` before this release. */
+    weeklyPct: number;
+    /** 5-hour rolling window. 0..100. Display only — never ranks. Was `sessionPct`. */
+    fiveHourPct?: number;
+    /** Included monthly envelope. 0..100. Absent means the provider has no monthly window. */
+    monthlyPct?: number;
+    monthlyResetsAt?: string;
+    monthlyStatus?: "ok" | "exhausted";
+    /** "included" only this slice. A spend cap or PAYG ceiling will carry its own value. */
+    monthlyKind?: "included";
     resetsAt: string;
     periodStart: string;
     source: "cli" | "api" | "scrape" | "manual" | "tui";
@@ -10,6 +18,13 @@ export interface Quota {
     creditsUsd?: number;
     resetsAtEstimated?: boolean;
 }
+/** Store and wire shape: `Quota` plus the one-release aliases. */
+export interface QuotaWire extends Quota {
+    /** @deprecated alias for weeklyPct. Removed the release after next. */
+    usedPct: number;
+    /** @deprecated alias for fiveHourPct. Removed the release after next. */
+    sessionPct?: number;
+}
 export interface ParsedQuota extends Quota {
     raw?: string;
 }

package/dist/advisory/engine.d.ts

@@ -1,9 +1,9 @@
 import type { Quota } from "../adapters/types.js";
-import type { Advisory, RecommendationBasis } from "./types.js";
+import type { Advisory, RecommendationBasis, BindingWindow } from "./types.js";
 /**
  * Pace from a single reading.
  *
- * `usedPct` is a running total since the window opened, and `periodStart` is
+ * `weeklyPct` is a running total since the window opened, and `periodStart` is
  * a required field every adapter sets, so a pace is always computable from
  * one poll. Returns null when `periodStart` is missing or unparseable, or
  * when less than MIN_PACE_SPAN_DAYS has elapsed (annualizing a smaller
@@ -22,6 +22,7 @@ export declare function recommend(quotas: Quota[], _task: string, paceByProvider
     wastePct: number;
     idealRate: number;
     recommendationBasis: RecommendationBasis;
+    bindingWindow: BindingWindow;
     alternatives: Quota[];
     advisories: Advisory[];
 } | {
@@ -30,6 +31,7 @@ export declare function recommend(quotas: Quota[], _task: string, paceByProvider
     wastePct: null;
     idealRate: number;
     recommendationBasis: RecommendationBasis;
+    bindingWindow: BindingWindow;
     alternatives: Quota[];
     advisories: Advisory[];
 };

package/dist/advisory/engine.js

@@ -3,7 +3,7 @@ const DAY_MS = 86400000;
 /**
  * Pace from a single reading.
  *
- * `usedPct` is a running total since the window opened, and `periodStart` is
+ * `weeklyPct` is a running total since the window opened, and `periodStart` is
  * a required field every adapter sets, so a pace is always computable from
  * one poll. Returns null when `periodStart` is missing or unparseable, or
  * when less than MIN_PACE_SPAN_DAYS has elapsed (annualizing a smaller
@@ -18,7 +18,7 @@ export function averagePace(q, now = new Date()) {
     const elapsedDays = (now.getTime() - start) / DAY_MS;
     if (elapsedDays < MIN_PACE_SPAN_DAYS)
         return null;
-    const pace = q.usedPct / elapsedDays;
+    const pace = q.weeklyPct / elapsedDays;
     if (!Number.isFinite(pace))
         return null;
     return Math.max(0, pace);
@@ -60,13 +60,29 @@ function elapsedPctOf(q, now) {
 export function computeAdvisory(q, recent, baseline, now = new Date()) {
     const resets = new Date(q.resetsAt);
     const daysLeft = Math.max(0.1, (resets.getTime() - now.getTime()) / DAY_MS);
-    const remaining = 100 - q.usedPct;
+    const remaining = 100 - q.weeklyPct;
     const idealRate = remaining / daysLeft;
     const avgPace = averagePace(q, now);
     // Nothing left to burn: force the capped verdict even when the recent
     // window is flat (burn 0 at 100% used must not read "on track").
     const exhausted = remaining <= 0;
     const burnRate = blendForecast(recent, baseline);
+    // Above every return: the unknown-pace path below is exactly what pool 2
+    // ranks, so a binding computed later would leave it on weekly numbers.
+    const weeklyHeadroom = remaining / daysLeft;
+    let bindingWindow = "weekly";
+    let bindingRemaining = remaining;
+    let bindingDaysLeft = daysLeft;
+    if (q.monthlyKind === "included" && typeof q.monthlyPct === "number" && q.monthlyResetsAt) {
+        const monthlyRemaining = q.monthlyStatus === "exhausted" ? 0 : Math.max(0, 100 - q.monthlyPct);
+        const monthlyDaysLeft = Math.max(0.1, (new Date(q.monthlyResetsAt).getTime() - now.getTime()) / DAY_MS);
+        const monthlyHeadroom = monthlyRemaining / monthlyDaysLeft;
+        if (monthlyHeadroom < weeklyHeadroom || monthlyRemaining === 0) {
+            bindingWindow = "monthly";
+            bindingRemaining = monthlyRemaining;
+            bindingDaysLeft = monthlyDaysLeft;
+        }
+    }
     // paceSource describes recent availability; the blend's composition is
     // carried by recentRate and baselineRate.
     const paceSource = recent !== null ? "recent" : burnRate !== null ? "window-average" : "unknown";
@@ -88,6 +104,9 @@ export function computeAdvisory(q, recent, baseline, now = new Date()) {
             status: exhausted ? "at risk" : "unknown",
             wastePct: exhausted ? 0 : null,
             urgency: exhausted ? "slow down" : "on track",
+            bindingWindow,
+            bindingRemaining,
+            bindingDaysLeft,
         };
     }
     if (exhausted) {
@@ -107,14 +126,17 @@ export function computeAdvisory(q, recent, baseline, now = new Date()) {
             status: "at risk",
             wastePct: 0,
             urgency: "slow down",
+            bindingWindow,
+            bindingRemaining,
+            bindingDaysLeft,
         };
     }
     // Red needs a deadband margin and a cumulatively-ahead position on a
     // verified clock; a missing or estimated clock caps at Watch.
     const elapsed = elapsedPctOf(q, now);
     const estimated = q.resetsAtEstimated === true;
-    const gate = elapsed !== null && !estimated && q.usedPct >= elapsed * (1 - GATE_TOL);
-    const aheadOfElapsed = elapsed !== null && !estimated && q.usedPct > elapsed * (1 + GATE_TOL);
+    const gate = elapsed !== null && !estimated && q.weeklyPct >= elapsed * (1 - GATE_TOL);
+    const aheadOfElapsed = elapsed !== null && !estimated && q.weeklyPct > elapsed * (1 + GATE_TOL);
     const wastePct = Math.max(0, remaining - burnRate * daysLeft);
     const daysToExhaust = burnRate > 0 ? remaining / burnRate : Infinity;
     const over = daysToExhaust < daysLeft * (1 - RISK_MARGIN);
@@ -137,7 +159,18 @@ export function computeAdvisory(q, recent, baseline, now = new Date()) {
         urgency = "save";
     if (estimated && urgency === "burn now")
         urgency = "use soon";
-    return { provider: q.provider, daysLeft, remaining, idealRate, burnRate, recentRate: recent, baselineRate: baseline, aheadOfElapsed, avgPace, burnMeasured, paceSource, daysToExhaust, status, wastePct, urgency };
+    return { provider: q.provider, daysLeft, remaining, idealRate, burnRate, recentRate: recent, baselineRate: baseline, aheadOfElapsed, avgPace, burnMeasured, paceSource, daysToExhaust, status, wastePct, urgency, bindingWindow, bindingRemaining, bindingDaysLeft };
+}
+/**
+ * Known-waste sort key. `wastePct` is a flow (budget forecast to go unspent
+ * by the weekly deadline); `bindingRemaining` is a stock. The binding window's
+ * headroom per day, priced over the weekly days-left the pool sorts on, caps
+ * the claim at what the account can actually absorb. Weekly-bound providers
+ * are untouched: the ratio is 1 and `wastePct <= remaining` always.
+ */
+function rankWaste(a) {
+    const affordable = a.bindingRemaining * (a.daysLeft / a.bindingDaysLeft);
+    return Math.min(a.wastePct, affordable);
 }
 export function recommend(quotas, _task, paceByProvider = new Map(), now = new Date()) {
     if (!quotas.length) {
@@ -147,6 +180,7 @@ export function recommend(quotas, _task, paceByProvider = new Map(), now = new D
             wastePct: 0,
             idealRate: 0,
             recommendationBasis: "none",
+            bindingWindow: "weekly",
             alternatives: [],
             advisories: [],
         };
@@ -162,32 +196,38 @@ export function recommend(quotas, _task, paceByProvider = new Map(), now = new D
     // are a fallback pool, read from the flags on the quotas already received.
     const estimatedProviders = new Set(quotas.filter(q => q.resetsAtEstimated === true).map(q => q.provider));
     // 1. Prefer measured providers with positive avoidable waste (actionable "Use more" candidates).
-    const positiveWaste = advisories.filter((a) => a.paceSource !== "unknown" && a.wastePct !== null && a.wastePct > 0);
+    const positiveWaste = advisories.filter((a) => a.paceSource !== "unknown" && a.wastePct !== null && a.wastePct > 0 && a.bindingRemaining > 0);
     if (positiveWaste.length > 0) {
         const verified = positiveWaste.filter(a => !estimatedProviders.has(a.provider));
         const pool = verified.length ? verified : positiveWaste.filter(a => estimatedProviders.has(a.provider));
-        const burnNow = pool.filter(a => a.urgency === "burn now");
-        const use = (burnNow.length ? burnNow : pool).sort((a, b) => b.wastePct - a.wastePct)[0];
+        const burnNow = pool.filter(a => a.urgency === "burn now" && a.bindingWindow === "weekly");
+        const use = (burnNow.length ? burnNow : pool).sort((a, b) => rankWaste(b) - rankWaste(a))[0];
         return {
             use: use.provider,
-            reason: `${Math.round(use.wastePct)}% waste in ${use.daysLeft.toFixed(1)}d`,
-            wastePct: use.wastePct,
+            reason: use.bindingWindow === "monthly"
+                ? `${Math.round(use.bindingRemaining)}% of month left in ${use.bindingDaysLeft.toFixed(1)}d`
+                : `${Math.round(use.wastePct)}% waste in ${use.daysLeft.toFixed(1)}d`,
+            wastePct: rankWaste(use),
             idealRate: use.idealRate,
             recommendationBasis: "known-waste",
+            bindingWindow: use.bindingWindow,
             alternatives: quotas,
             advisories,
         };
     }
     // 2. Low-confidence fallback: rank unknown providers by remaining headroom (remaining / daysLeft).
-    const unknownProviders = advisories.filter(a => a.paceSource === "unknown" && a.remaining > 0);
+    const unknownProviders = advisories.filter(a => a.paceSource === "unknown" && a.bindingRemaining > 0);
     if (unknownProviders.length > 0) {
-        const use = unknownProviders.sort((a, b) => (b.remaining / b.daysLeft) - (a.remaining / a.daysLeft))[0];
+        const use = unknownProviders.sort((a, b) => (b.bindingRemaining / b.bindingDaysLeft) - (a.bindingRemaining / a.bindingDaysLeft))[0];
         return {
             use: use.provider,
-            reason: `Measuring pace; ${Math.round(use.remaining)}% remains with ${use.daysLeft.toFixed(1)}d until reset`,
+            reason: use.bindingWindow === "monthly"
+                ? `Measuring pace; ${Math.round(use.bindingRemaining)}% of month left with ${use.bindingDaysLeft.toFixed(1)}d until reset`
+                : `Measuring pace; ${Math.round(use.remaining)}% remains with ${use.daysLeft.toFixed(1)}d until reset`,
             wastePct: null,
             idealRate: use.idealRate,
             recommendationBasis: "unknown-headroom",
+            bindingWindow: use.bindingWindow,
             alternatives: quotas,
             advisories,
         };
@@ -199,6 +239,7 @@ export function recommend(quotas, _task, paceByProvider = new Map(), now = new D
         wastePct: 0,
         idealRate: 0,
         recommendationBasis: "none",
+        bindingWindow: "weekly",
         alternatives: quotas,
         advisories,
     };

package/dist/advisory/snapshot.js

@@ -20,6 +20,13 @@ function normalizeAdvisory(adv) {
         avgPace: adv.avgPace !== null && Number.isFinite(adv.avgPace) ? adv.avgPace : null,
         daysToExhaust: adv.daysToExhaust !== null && Number.isFinite(adv.daysToExhaust) ? adv.daysToExhaust : null,
         wastePct: adv.wastePct !== null && Number.isFinite(adv.wastePct) ? adv.wastePct : null,
+        bindingWindow: adv.bindingWindow === "monthly" ? "monthly" : "weekly",
+        bindingRemaining: Number.isFinite(adv.bindingRemaining)
+            ? adv.bindingRemaining
+            : Number.isFinite(adv.remaining) ? adv.remaining : 0,
+        bindingDaysLeft: Number.isFinite(adv.bindingDaysLeft)
+            ? adv.bindingDaysLeft
+            : Number.isFinite(adv.daysLeft) ? adv.daysLeft : 0,
     };
 }
 export function buildSnapshot(db, opts) {
@@ -67,9 +74,9 @@ export function buildSnapshot(db, opts) {
         if (quota !== null) {
             const resetsMs = new Date(quota.resetsAt).getTime();
             const fetchedMs = new Date(quota.fetchedAt).getTime();
-            if (!Number.isFinite(quota.usedPct) ||
-                quota.usedPct < 0 ||
-                quota.usedPct > 100 ||
+            if (!Number.isFinite(quota.weeklyPct) ||
+                quota.weeklyPct < 0 ||
+                quota.weeklyPct > 100 ||
                 Number.isNaN(resetsMs) ||
                 Number.isNaN(fetchedMs)) {
                 isInvalid = true;
@@ -168,6 +175,7 @@ export function buildSnapshot(db, opts) {
             wastePct: null,
             idealRate: 0,
             recommendationBasis: "none",
+            bindingWindow: "weekly",
             models: [],
             catalogStatus: "unfetched",
             catalogFetchedAt: null,

package/dist/advisory/types.d.ts

@@ -1,4 +1,4 @@
-import type { Quota } from "../adapters/types.js";
+import type { QuotaWire } from "../adapters/types.js";
 import type { AttemptRecord } from "../store/attempts.js";
 import type { CatalogStatus, CatalogView, ListedModel } from "../catalog/types.js";
 /**
@@ -15,6 +15,7 @@ export type Urgency = "burn now" | "use soon" | "slow down" | "save" | "on track
 export type BurnStatus = "at risk" | "watch" | "on track" | "unknown";
 export type PaceSource = "recent" | "window-average" | "unknown";
 export type RecommendationBasis = "known-waste" | "unknown-headroom" | "none";
+export type BindingWindow = "weekly" | "monthly";
 export type ExclusionReason = "not-reporting" | "stale" | "reset-passed" | "invalid" | "provider-failed" | null;
 export type { AttemptRecord };
 export interface Advisory {
@@ -39,6 +40,12 @@ export interface Advisory {
     status: BurnStatus;
     wastePct: number | null;
     urgency: Urgency;
+    /** Which included window is scarcer per day left. "weekly" when there is no included monthly. */
+    bindingWindow: BindingWindow;
+    /** Remaining percent of the binding window. Equals `remaining` when weekly binds. */
+    bindingRemaining: number;
+    /** Days until the binding window resets. Equals `daysLeft` when weekly binds. */
+    bindingDaysLeft: number;
 }
 export interface Recommendation {
     use: string;
@@ -46,10 +53,11 @@ export interface Recommendation {
     wastePct: number | null;
     idealRate: number;
     recommendationBasis: RecommendationBasis;
+    bindingWindow: BindingWindow;
     models: ListedModel[];
     catalogStatus: CatalogStatus;
     catalogFetchedAt: string | null;
-    alternatives: Array<Quota & {
+    alternatives: Array<QuotaWire & {
         catalog: CatalogView;
     }>;
     advisories: Advisory[];
@@ -74,7 +82,7 @@ export interface ProviderSnapshot {
     harness: string | null;
     description: string | null;
     enabled: boolean;
-    quota: Quota | null;
+    quota: QuotaWire | null;
     lastAttempt: AttemptRecord | null;
     lastSuccessAt: string | null;
     reporting: boolean;

package/dist/cli/advise.js

@@ -82,6 +82,7 @@ export function registerAdviseCommand(program, deps) {
                             createClient,
                             execService,
                             ...takeoverOpts,
+                            json: !!o.json || takeoverOpts.json,
                         });
                         console.error(r.message);
                         // The takeover verified the daemon now reports the CLI version;

package/dist/cli/clients.d.ts

@@ -3,6 +3,7 @@ import type { ServiceClient } from "../runtime/client.js";
 import type { CatalogFetcher } from "../catalog/index.js";
 import type { SleepFn } from "./takeover.js";
 import type { UpdateCache } from "../runtime/updates.js";
+import type { PhaseFn } from "./progress.js";
 export interface CreateClientOptions {
     port: number;
     token?: string;
@@ -24,8 +25,11 @@ export interface ClientCommandDeps {
         sleep?: SleepFn;
         timeoutMs?: number;
         readToken?: () => string | undefined;
+        phase?: PhaseFn;
+        json?: boolean;
     };
     checkUpdates?: () => Promise<UpdateCache | null>;
     catalogFetchers?: Record<string, CatalogFetcher>;
+    phase?: PhaseFn;
 }
 export declare function registerClientCommands(program: Command, deps?: ClientCommandDeps): void;

package/dist/cli/models.js

@@ -6,12 +6,13 @@ import { providerIdentity } from "../advisory/provider-names.js";
 import { readToken } from "../runtime/token.js";
 import { createServiceClient } from "../runtime/client.js";
 import { OFFLINE_LABEL } from "./snapshot-source.js";
+import { phase } from "./progress.js";
 function projectModels(catalogs, quotaMap, providerNames) {
     const out = [];
     for (const [id, catalog] of catalogs) {
         const identity = providerIdentity(id, providerNames);
         const quota = quotaMap.get(id);
-        const leftoverPct = quota?.usedPct != null ? Math.round((100 - quota.usedPct) * 10) / 10 : null;
+        const leftoverPct = quota?.weeklyPct != null ? Math.round((100 - quota.weeklyPct) * 10) / 10 : null;
         out.push({
             id,
             displayName: identity.displayName,
@@ -70,6 +71,9 @@ export function registerModelsCommand(program, deps = {}) {
         });
         let body;
         try {
+            if (o.refresh) {
+                (deps.phase ?? phase)("refreshing model catalogs…", { json: !!o.json });
+            }
             const url = o.refresh
                 ? (o.provider ? `/api/models/refresh?provider=${encodeURIComponent(o.provider)}` : "/api/models/refresh")
                 : (o.provider ? `/api/models?provider=${encodeURIComponent(o.provider)}` : "/api/models");

package/dist/cli/progress.d.ts

@@ -0,0 +1,32 @@
+export interface ProgressOptions {
+    /** Suppress output when machine-readable JSON is requested. */
+    json?: boolean;
+    /** Explicitly silence progress (e.g. quiet mode). */
+    quiet?: boolean;
+    /** Whether the output stream is interactive. Defaults to process.stderr.isTTY. */
+    isTTY?: boolean;
+    /** Custom writer for stderr (defaults to console.error). */
+    stderr?: (message: string) => void;
+}
+export type PhaseFn = (message: string, opts?: ProgressOptions) => void;
+/**
+ * Format a progress phase string ensuring consistent trailing ellipsis without duplication.
+ */
+export declare function formatPhase(message: string): string;
+/**
+ * Determine whether progress messages should be printed given the options.
+ */
+export declare function shouldEmitProgress(opts?: ProgressOptions): boolean;
+/**
+ * Emit a progress phase message strictly to stderr if interactive and non-json.
+ */
+export declare function phase(message: string, opts?: ProgressOptions): void;
+/**
+ * Await work, calling emit only if it is still pending after graceMs, so an
+ * already-settled fast path stays silent.
+ */
+export declare function phaseIfSlow<T>(work: Promise<T>, emit: () => void, graceMs?: number): Promise<T>;
+/**
+ * Create a phase reporter with pre-bound default options.
+ */
+export declare function createPhase(baseOpts?: ProgressOptions): (message: string, overrideOpts?: ProgressOptions) => void;

package/dist/cli/progress.js

@@ -0,0 +1,70 @@
+// Shared progress helper for multi-second CLI operations.
+// Strictly writes to stderr with a consistent lowercase phrasing ending in '…'.
+// Automatically suppressed under --json, quiet mode, and non-interactive (non-TTY) runs.
+/**
+ * Format a progress phase string ensuring consistent trailing ellipsis without duplication.
+ */
+export function formatPhase(message) {
+    const trimmed = message.trim();
+    if (!trimmed)
+        return "";
+    if (trimmed.endsWith("...")) {
+        return `${trimmed.slice(0, -3)}…`;
+    }
+    if (trimmed.endsWith("…")) {
+        return trimmed;
+    }
+    return `${trimmed}…`;
+}
+/**
+ * Determine whether progress messages should be printed given the options.
+ */
+export function shouldEmitProgress(opts = {}) {
+    if (opts.json || opts.quiet)
+        return false;
+    if (opts.isTTY !== undefined)
+        return Boolean(opts.isTTY);
+    return Boolean(process.stderr.isTTY);
+}
+/**
+ * Emit a progress phase message strictly to stderr if interactive and non-json.
+ */
+export function phase(message, opts = {}) {
+    const formatted = formatPhase(message);
+    if (!formatted)
+        return;
+    if (!shouldEmitProgress(opts))
+        return;
+    const write = opts.stderr ?? console.error;
+    write(formatted);
+}
+/**
+ * Await work, calling emit only if it is still pending after graceMs, so an
+ * already-settled fast path stays silent.
+ */
+export async function phaseIfSlow(work, emit, graceMs = 250) {
+    let timer;
+    const slow = new Promise((r) => {
+        timer = setTimeout(() => r("slow"), graceMs);
+    });
+    try {
+        const first = await Promise.race([
+            work.then(() => "done", () => "done"),
+            slow,
+        ]);
+        if (first === "slow")
+            emit();
+        return await work;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Create a phase reporter with pre-bound default options.
+ */
+export function createPhase(baseOpts = {}) {
+    return (message, overrideOpts = {}) => {
+        phase(message, { ...baseOpts, ...overrideOpts });
+    };
+}

package/dist/cli/runtime.d.ts

@@ -2,6 +2,7 @@ import type { Command } from "commander";
 import { startService, type StartServiceOptions } from "../runtime/service.js";
 import { type ServiceClient } from "../runtime/client.js";
 import { type SleepFn } from "./takeover.js";
+import { type PhaseFn } from "./progress.js";
 export type StartServiceFn = (opts?: StartServiceOptions) => ReturnType<typeof startService>;
 export type OpenBrowserFn = (url: string) => Promise<void> | void;
 export type ExecServiceFn = (args: string[], opts?: Record<string, any>) => Promise<number>;
@@ -20,10 +21,13 @@ export interface RuntimeCommandDeps {
         sleep?: SleepFn;
         timeoutMs?: number;
         readToken?: () => string | undefined;
+        phase?: PhaseFn;
+        json?: boolean;
     };
     checkUpdates?: () => Promise<unknown>;
     isInstalled?: () => Promise<boolean>;
     serviceSupported?: () => boolean;
+    phase?: PhaseFn;
 }
 export interface WebLaunchOptions {
     port?: string;
@@ -38,5 +42,6 @@ export declare function waitForInitialPoll(port: number, opts?: {
     }) => any;
     sleep?: SleepFn;
     timeoutMs?: number;
+    phase?: PhaseFn;
 }): Promise<void>;
 export declare function registerRuntimeCommands(program: Command, deps?: RuntimeCommandDeps): void;