# Lab 1 — Your first call, and reading `usage`

**Time:** 20 minutes · **Prerequisites:** Node 20+, an Anthropic API key

## Why this matters

Nothing in this lab looks consequential. One call, four numbers, a truncated
sentence.

But the four numbers in `usage` are the entire reason this project has a budget
at all. Priya has about $4,000 a month against 45,000 tickets in a peak month, and the
policy handbook goes out on every single request. If you cannot read a `usage`
block, you cannot tell the difference between a system that fits that budget and
one that costs ten times more while returning identical answers. That difference
is invisible in the response body. It only shows up in these four fields.

And `stop_reason` is how you find out the model stopped mid-sentence. In a
support context that is a reply to a customer that ends halfway through a
refund amount.

---

## Objectives

By the end you can:

- Make a Messages API call with the TypeScript SDK
- Narrow a `ContentBlock` union correctly (the first thing TypeScript stops you on)
- Read all four `usage` fields and explain what each one costs
- Recognize `stop_reason: "max_tokens"` and know what to do about it

```mermaid
sequenceDiagram
    participant You
    participant SDK as Anthropic SDK
    participant Claude as Claude API

    You->>SDK: messages.create(...)
    SDK->>Claude: POST /v1/messages
    Claude-->>SDK: content + usage
    SDK-->>You: Message object
```

---

## Setup

```bash
npm install && cp .env.example .env
```

Put your key in `.env`, then:

```bash
export $(grep -v '^#' .env | xargs)
```

Verify:

```bash
curl -s localhost:8787/healthz || npm run dev
```

---

## Step 1 — the smallest possible call

Create `scratch/hello.ts`:

```ts
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-opus-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "In one sentence: what is a zipper slider?" }],
});

console.log(response);
```

```bash
npx tsx scratch/hello.ts
```

**Look at the raw response object before you go further.** Note that `content`
is an *array*, that `usage` is present, and that `stop_reason` is `"end_turn"`.

## Step 2 — extract the text (and hit the type error)

Add this and watch TypeScript complain:

```ts
console.log(response.content[0].text);
```

`content` is `ContentBlock[]`, a discriminated union — a block may be `text`,
`thinking`, `tool_use`, and more. You must narrow:

```ts
for (const block of response.content) {
  if (block.type === "text") console.log(block.text);
}
```

> **Why this matters:** on Opus 5, adaptive thinking is on by default, so
> `content[0]` is frequently *not* the text block. Code that indexes position 0
> works in testing and breaks the moment reasoning kicks in.

```quiz
[
  {
    "question": "Why can't you write `response.content[0].text`?",
    "options": [
      "The SDK returns text on a different property",
      "`content` is an array of blocks that may be text, thinking, or tool_use — you have to narrow by `.type`",
      "You need to await it first"
    ],
    "answer": 1,
    "explain": "`content` is a discriminated union. On Opus 5 adaptive thinking is on by default, so index 0 is frequently a `thinking` block — code that indexes position 0 works in testing and breaks the moment reasoning kicks in.",
    "note": "TypeScript will stop you. In JavaScript it fails silently at runtime instead."
  }
]
```

## Step 3 — read the meter

```ts
console.log({
  input: response.usage.input_tokens,
  output: response.usage.output_tokens,
  cache_write: response.usage.cache_creation_input_tokens,
  cache_read: response.usage.cache_read_input_tokens,
});
```

At Opus 5 list price ($5/M input, $25/M output), compute the cost of that call
by hand. Then check yourself against the running service:

```bash
curl -s localhost:8787/v1/estimate -H 'content-type: application/json' \
  -d '{"message":"In one sentence: what is a zipper slider?"}' | jq .cost_usd
```

```receipt
{
  "title": "scratch/hello.ts — representative",
  "note": "Small prompt, no handbook. Your numbers will move; the four fields are the point.",
  "input": 18,
  "output": 42,
  "cacheWrite": 0,
  "cacheRead": 0,
  "cost": "$0.0011",
  "stopReason": "end_turn"
}
```

**Q1.** Why is the estimate's input count so much larger than your script's?

## Step 4 — break it on purpose

Set `max_tokens: 20` and ask for something long:

```ts
const truncated = await client.messages.create({
  model: "claude-opus-5",
  max_tokens: 20,
  messages: [{ role: "user", content: "Explain waterproof-breathable membranes." }],
});
console.log(truncated.stop_reason);
```

You get `"max_tokens"` and a sentence that stops mid-word. **There is no error.**
The request succeeded; the output is just wrong.

**Q2.** A teammate proposes catching this by checking whether the response ends
in a period. Why is that a bad detector, and what's the correct one?

```quiz
[
  {
    "question": "Your response comes back with `stop_reason: \"max_tokens\"`. What happened?",
    "options": [
      "The request failed and you should retry it",
      "The model finished early because it had nothing more to say",
      "The output was cut off mid-generation \u2014 the call succeeded, the answer is just truncated"
    ],
    "answer": 2,
    "explain": "`max_tokens` is an enforced ceiling the model cannot see. Hitting it truncates the output mid-thought. There is no error: HTTP 200, a valid response object, and a sentence that stops halfway.",
    "note": "In a support context that is a reply to a customer that ends partway through a refund amount."
  }
]
```

## Step 5 — handle errors like the service does

Read [`src/lib/errors.ts`](https://github.com/mrlynn/claude-triage-api/blob/main/src/lib/errors.ts). Then reproduce a real
failure:

```bash
ANTHROPIC_API_KEY=sk-ant-nope npx tsx scratch/hello.ts
```

**Q3.** `src/lib/errors.ts` maps `AuthenticationError` to HTTP **500**, not
401. Argue for that choice in one sentence.

## Step 6 — re-run the scoreboard

```bash
npm run eval:quick
```

You changed no prompt in this lab, so the score should not move. Confirm
that it did not. A baseline you have never seen hold steady is not a baseline
you trust yet.

---

## Checkpoint

You should be able to answer, without looking anything up:

- [ ] Why can't you write `response.content[0].text`?
- [ ] What are the four `usage` fields and their relative costs?
- [ ] What is `stop_reason: "max_tokens"` and how do you detect it?
- [ ] Which error classes are retryable?
- [ ] Scoreboard re-run; you can say why it did or did not move

---

## Extension

Wrap your script in a loop that calls the API 3× and prints total cost. Then
add `cache_control` to the system prompt and observe that nothing changes —
your prompt is under Opus 5's 512-token caching minimum, so the breakpoint is
accepted and ignored. That failure is the setup for Lab 5.

```mistake
{
  "id": "content-index-zero",
  "wrong": "console.log(response.content[0].text);",
  "right": "for (const block of response.content) {\n  if (block.type === \"text\") console.log(block.text);\n}",
  "symptom": "TypeScript rejects it: `text` does not exist on every member of the ContentBlock union. In JavaScript it prints undefined whenever the first block is a thinking block.",
  "why": "`content` is an array of blocks of different types. On Opus 5 adaptive thinking is on by default, so index 0 is often not the text block."
}
```

```mistake
{
  "id": "cost-from-output-only",
  "wrong": "const cost = (response.usage.output_tokens * 25) / 1_000_000;",
  "right": "const { usage } = response;\nconst cost = (usage.input_tokens * 5 + usage.output_tokens * 25) / 1_000_000;\n// plus cache_creation_input_tokens and cache_read_input_tokens, each at its own rate",
  "symptom": "The number looks plausible and is always too low. Once the handbook goes out on every request, it is too low by most of the bill.",
  "why": "You pay for input too, and input is usually the larger count. `usage` has four fields because all four are billed, at different rates."
}
```

```mistake
[
  {
    "id": "max-tokens-too-low",
    "wrong": "  max_tokens: 20,",
    "right": "  max_tokens: 1024,",
    "symptom": "HTTP 200 and no error. `stop_reason` is \"max_tokens\", and the text is cut off, or missing entirely because thinking used the whole budget.",
    "why": "`max_tokens` is a hard ceiling on output, and thinking tokens count against it. Too low, and the model is stopped before it finishes, or before it starts writing text."
  },
  {
    "id": "truncation-by-punctuation",
    "wrong": "if (!text.trim().endsWith(\".\")) console.warn(\"reply may be truncated\");",
    "right": "if (response.stop_reason === \"max_tokens\") console.warn(\"reply was truncated\");",
    "symptom": "It warns on complete replies that end in a list, a code block or a question, and it misses truncations that happen to stop at a period.",
    "why": "The API tells you why generation stopped. `stop_reason` is the detector; guessing from the text is not."
  }
]
```

**Answers:** [../solutions/lab-1.md](https://triage.mlynn.dev/docs/solutions/lab-1)

Source: https://triage.mlynn.dev/docs/labs/lab-1-first-call
