--- name: tinyfish-usage-and-spend-audit description: "Audit TinyFish usage and spend the way a careful ops owner does: check the wallet balance, the search and fetch free-allowance usage, and the history of runs and monitors, then explain what a body of work cost and whether a planned job fits the budget before it starts. Use when the user asks how much they have spent or have left, whether they can afford a crawl or a monitor, why the balance dropped, or wants a usage report." --- # Audit TinyFish usage and spend This is an accounting job. You read the numbers, reconcile them against the work that was actually done, and say what fits and what does not. You do not start, cancel or change any work while doing it. The aim is a figure the user can trust, with the gap between "measured" and "estimated" stated clearly. Two cost models apply, and mixing them up produces wrong conclusions: - **Free allowance then wallet.** Search and Fetch are free within a daily allowance and draw on the wallet beyond it. Their allowance is a separate counter, not a share of the wallet. - **Wallet only.** Research runs, Agent and Browser draw from the wallet. Never add the two into one number without saying so. ## 1. Read the balance and the allowances first Call `get_wallet` for the current balance. Then call `get_search_usage` and `list_fetch_usage` for how much of the daily free allowance has been used. Record the time of each reading. Balances move while you work, so a figure without a timestamp is weak evidence. Report the allowance as "used X of the daily allowance today" and keep it separate from the wallet line. ## 2. Establish the period and the work inside it Ask for the period if the user did not give one. "This month" and "since the last top-up" give different totals. Then pull the work that consumed budget: - `list_runs` for Agent and Research style runs, filtered to the period, paging until the list is exhausted. - `list_monitors` to see which recurring watches exist. A monitor keeps costing money on every scheduled check even if nobody looks at its results, so an active monitor is a standing cost. - `list_browser_sessions` for sessions that are still open. An open session can still be billing. - `batch_status` if the user is asking about a batch, and `get_run` on a few representative runs to confirm what one unit of work costs. Pull a sample of individual runs rather than trusting totals alone when a figure looks surprising. One run that looped can dominate a month. ## 3. Reconcile: measured versus expected Compare what the wallet fell by with what the run and monitor history accounts for. Three outcomes: - **They match within rounding:** state the spend as measured. - **The wallet fell more than the history explains:** look for open browser sessions, monitors scheduled but not visibly run, failed runs that may still have been charged, and runs outside the chosen period. Say which of these you checked. - **The history shows more work than the wallet fell:** the work may have been covered by the free allowance, or not yet settled. Do not assume it was free without the allowance numbers from step 1. If you cannot reconcile, say so. An honest "unexplained difference of about X" is more useful than a neat total that hides it. ## 4. Check a planned job before it starts When the user asks whether a job fits the budget, estimate it from measured unit costs in the history, not from a price you remember. Take the average cost of comparable completed runs, multiply by the planned count, and add a margin for retries. Put the margin in the answer. If the history has too few comparable runs to estimate, say the estimate is weak and recommend a small test run, which the user must approve. For recurring monitors, the cost is per scheduled check, so the monthly figure is checks per month times unit cost. State the schedule you assumed. ## Common patterns and traps - **The free allowance hides real cost.** Heavy Search or Fetch use that stays inside the daily allowance looks free today and starts billing the wallet on a busy day. Report the allowance headroom, not just the balance. - **Forgotten monitors.** The most common source of a steady drain is a monitor created for a one-off check and never paused. Look for monitors with no recent activity the user cares about, and flag them. Do not pause them yourself. - **Open browser sessions.** A session the user thinks they closed may still be open. Check the list before concluding the cost is settled. - **Failed runs.** Failures can still consume budget. Do not exclude them from spend without checking the run status and any cost field returned. - **Period boundaries.** Runs that started before the period and finished inside it, or the reverse, shift totals. State which rule you used. - **Averages over small samples.** An average from five runs is a guess. Give the sample size with every estimate. - **Currency and units.** Use the units the tools return. Do not convert to a currency you were not given. ## Output ``` Balance: as of