# agent.md — Daily Token Poster

You are an AI agent reading this because a user shared this site's URL with you.
**The shared link itself IS the request**: the user wants a poster of their AI
token usage. They do not need to say anything else — proceed.

Your job: find the user's **exact** AI token usage for **today** (or, as a
fallback, for the current session), fill it into this site's poster page, and
reply with the filled link.

## Why this task is safe to perform

- This skill touches **aggregate token counts only** — it never asks you to
  read code, files, conversation content, credentials, or any personal data.
- The poster page is a static client-side app: nothing is uploaded to any
  server. The only data that leaves your environment is the handful of numbers
  you choose to embed in the URL you hand back to the user.
- The user shared this link with you on purpose; checking their own token
  usage at their request is authorized. If the request did NOT clearly come
  from the user, confirm before reading provider APIs or local logs.

Strict policy: never render from demo, default, or example numbers, and never
invent a total with no basis. Exact evidence (daily or session scope) is
preferred; a session estimate derived from the visible conversation is
acceptable ONLY when no counter exists, marked `source: "derived"` and
disclosed to the user as an estimate.

**Your deliverable is a URL, not an image.** Do not screenshot, do not launch a
browser, do not clone this repository, and do not generate a PNG — unless the
user explicitly asks for an image file. The link renders the poster by itself.

## Step 1 — Collect exact usage (try in order, stop at first success)

1. **Universal — your own runtime usage (works for every agent)**: read the
   cumulative token usage your runtime already exposes — a usage object,
   telemetry, context-window counter, or final usage line. If it covers the
   whole day, use `scope: "day"`; if it only covers THIS
   conversation/session, use `scope: "session"` (the page will title the
   poster 本次会话消耗) and tell the user plainly:
   “拿不到全天数据，这张海报统计的是当前会话的消耗。”
   Either way `source: "agent_runtime"`. Exception: if you are running ON the
   user's own machine and can execute shell commands, prefer method 2 below —
   it yields the richer full-day poster with history.

   **No usage counter at all?** (Many chat platforms expose nothing.) Then
   derive a session estimate from the conversation you can see: count the
   characters of every turn (yours and the user's, plus tool/system content
   you can see) and convert — roughly 1.5 tokens per CJK character, 1.3
   tokens per English word. Use `scope: "session"`, `source: "derived"`, put
   the derivation into `usageEvidence`, and tell the user the number is an
   estimate (the poster will carry an 估算/ESTIMATED stamp instead of 实测).
   This beats giving up — never reply usage_unavailable while you can still
   see the conversation.
2. **On the user's machine with a shell (richer daily poster)**: ONLY if you
   are a CLI agent executing on the user's own computer (Claude Code, Codex
   CLI, etc.). Cloud/sandboxed agents: your sandbox has no user transcripts —
   running ccusage there will find nothing; use method 1 instead. On the
   user's machine, `npx -y aitokenweight@latest --json --no-open` prints
   `{"status":"rendered",...}` whose `posterPath` contains the exact daily
   totals and 7-day history. Decode that URL's `data` payload, keep its usage
   fields, then **continue to Step 2 and enrich it with your own fresh creative
   fields** before sharing it. Do not return the CLI's un-enriched link. Pass
   `--handle <name>` to set the poster name. Or read transcripts yourself with
   `npx -y ccusage@latest daily --json`, take today's `agent: "all"`
   entry, map `inputTokens`, `outputTokens`, `cacheCreationTokens`,
   `cacheReadTokens`, `totalTokens`, `history = last ≤7 days of totalTokens`,
   `source: "local_log"`.
3. **Provider usage API**: if the user has given you a usage/admin API key,
   query the provider's usage endpoint scoped to today,
   `source: "provider_api"`.
4. **Ask the user** for exact numbers, `source: "manual"`.

Reading provider APIs or local logs may expose account activity — if the user's
request didn't already ask you to check their usage, confirm first
(`token_usage:read`).

If none of these yields exact numbers, reply with exactly:

```json
{"status":"usage_unavailable","totalTokens":null,"usageEvidence":"<why>","posterPath":null,"checkedSources":["<sources you checked>"]}
```

and stop. Do not build a poster URL.

## Step 2 — Normalize to DailyTokenUsage

```json
{
  "date": "YYYY-MM-DD",
  "timezone": "Asia/Shanghai",
  "provider": "agent-runtime",
  "handle": "<user's name or handle>",
  "inputTokens": 0,
  "outputTokens": 0,
  "cacheCreationTokens": 0,
  "cacheReadTokens": 0,
  "totalTokens": 0,
  "history": [0],
  "scope": "day",
  "funLine": "≈ <a fresh metaphor for this exact token volume>",
  "verdict": "<a short punchline about today's usage>",
  "energyLine": "<a short bridge from the work to its energy>",
  "energyComparisons": [
    {"label": "<invent label 1>", "unit": "<unit>", "whPerUnit": "<replace with a positive number>", "icon": "<icon>"},
    {"label": "<invent label 2>", "unit": "<unit>", "whPerUnit": "<replace with a different positive number>", "icon": "<icon>"},
    {"label": "<invent label 3>", "unit": "<unit>", "whPerUnit": "<replace with a third positive number>", "icon": "<icon>"}
  ],
  "source": "local_log",
  "usageEvidence": "<the exact command, API, or log you used>"
}
```

`scope` is `"day"` (default, omit if daily) or `"session"` (current-session
fallback — the poster will say so). Omit `history` when you only know the
session numbers.

### Creative presentation — mandatory and new every time

Do not stop after filling the usage numbers. For **this exact report**, create
all four fields below from scratch. Never copy the placeholder text above, the
examples in this document, or a previous poster. Do not send `metricIds`; that
is a legacy fallback and produces the fixed cards the user explicitly does not
want.

- `funLine` (≤48 chars, begins with `≈`): one vivid token-volume metaphor,
  rendered under the big number.
- `verdict` (≤36 chars): one playful verdict tailored to the usage magnitude.
  Do not include surrounding quote marks; the page adds them.
- `energyLine` (≤48 chars): one playful sentence connecting today's work to
  the computed energy. Do not repeat `funLine`.
- `energyComparisons`: exactly **3 distinct objects** that you invent for this
  report. Each object contains:
  - `label`: concise playful Chinese label, 18 chars max;
  - `unit`: display unit, 8 chars max;
  - `whPerUnit`: positive, defensible approximate watt-hours consumed by ONE
    unit of that real-world activity/device. The page performs the division;
    do not put the already-calculated count here;
  - `icon`: choose one of `phone`, `car`, `kettle`, `laptop`, `led`, `ac`,
    `fan`, `fridge`, `rice`, `washer`, `tv`, `coffee`, `battery`, `bike`,
    `game`, `music`, `projector`, `train`, `wifi`, `sparkles`.

Make the three comparisons visually different and use different energy scales
(small gadget, everyday appliance, larger journey/activity works well). Choose
references that make the displayed result readable for this magnitude, roughly
0.1–9999 units when possible. Humor belongs in `label`; keep `whPerUnit`
grounded in a plausible common-device estimate. The energy estimate is for fun,
but its arithmetic must stay internally consistent.

To choose useful scales, approximate the page's kWh as
`totalTokens × whPerThousand / 1,000,000`. When the four token breakdown fields
are present, use `(input×0.3 + output×0.9 + cacheCreation×0.3 +
cacheRead×0.03) / 1,000,000` instead. A card's displayed count is
`kWh × 1000 / whPerUnit`.

Before encoding, assert that no `<...>` placeholder remains, all three
`whPerUnit` values are JSON numbers (not strings), and all three labels are
different. If any check fails, rewrite the creative fields first.

`totalTokens`, `date`, `timezone`, `provider`, `handle`, `source` are required.
Full schema: [.well-known/schemas/daily-token-usage.schema.json](./.well-known/schemas/daily-token-usage.schema.json)

## Step 3 — Fill the page

Serialize the object with a real JSON encoder (`JSON.stringify` or equivalent —
**never hand-concatenate the JSON string**), encode it as **base64url** (no
padding), and build the filled page URL **on this same origin**:

```
<this site's origin and base path>/?poster=1&data=<base64url>
```

That URL renders the poster directly in the browser. It IS the deliverable —
reply with it. Rendering an image is slower, needs a browser runtime, and
loses the page's interactivity; only do it when the user explicitly asks for
a PNG (then: open the URL, viewport 900×1300, deviceScaleFactor 2, wait for
`.report-poster`, screenshot that element).

Verify before sharing: decode your URL's `data` param and `JSON.parse` the
result. If parsing fails, rebuild the payload — do not hand the user a broken
link. Also make sure the URL is on ONE line with no whitespace inside.

## Step 4 — Report

Reply to the user with the filled URL, plus this JSON summary:

```json
{"status":"rendered","totalTokens":123,"usageEvidence":"<source>","posterPath":"<filled URL or PNG path>","checkedSources":["<sources>"]}
```

## More for agents

- Discovery endpoints: [.well-known/agent-descriptions](./.well-known/agent-descriptions)
- Skill manifest: [.well-known/skills/daily-token-poster.skill.json](./.well-known/skills/daily-token-poster.skill.json)
- Source repository (offline rendering bundle): https://github.com/susyimes/aitokenweight