Tool calling: модель вызывает ваши функции

mkdir tool-calling
cd tool-calling
npm init -y
npm pkg set type=module
npm pkg set private=true --json
npm pkg delete main scripts.test
npm pkg set scripts.test="node --test" scripts.typecheck="tsc" scripts.demo="node src/demo.ts"
npm install @anthropic-ai/sdk@0.133.0 zod@4.6.6
npm install -D typescript@7.0.2 @types/node@24

{
  "compilerOptions": {
    "target": "es2024",
    "module": "nodenext",
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "types": ["node"],
    "skipLibCheck": true
  },
  "include": ["src", "test"]
}

// In-memory salon schedule: one master, slots every 30 minutes, 10:00–20:00
export const SERVICE_IDS = ["manicure", "pedicure", "haircut"] as const;
export type ServiceId = (typeof SERVICE_IDS)[number];

export const SERVICE_MINUTES: Record<ServiceId, number> = {
  manicure: 60,
  pedicure: 90,
  haircut: 60,
};

export type Booking = {
  id: string;
  service: ServiceId;
  date: string; // YYYY-MM-DD, salon local time
  time: string; // HH:MM
  clientName: string;
  phone: string;
};

export class SlotTakenError extends Error {}

const OPENS = 10 * 60;
const CLOSES = 20 * 60;
const STEP = 30;

const toMinutes = (time: string) => Number(time.slice(0, 2)) * 60 + Number(time.slice(3, 5));
const toTime = (minutes: number) =>
  `${String(Math.floor(minutes / 60)).padStart(2, "0")}:${String(minutes % 60).padStart(2, "0")}`;

export class Salon {
  #bookings: Booking[] = [];
  #nextId = 1;

  get bookings(): readonly Booking[] {
    return [...this.#bookings];
  }

  freeSlots(service: ServiceId, date: string): string[] {
    const length = SERVICE_MINUTES[service];
    const busy = this.#bookings
      .filter((b) => b.date === date)
      .map((b) => [toMinutes(b.time), toMinutes(b.time) + SERVICE_MINUTES[b.service]] as const);
    const slots: string[] = [];
    for (let start = OPENS; start + length <= CLOSES; start += STEP) {
      const overlaps = busy.some(([from, to]) => start < to && from < start + length);
      if (!overlaps) slots.push(toTime(start));
    }
    return slots;
  }

  book(input: Omit<Booking, "id">): Booking {
    // Re-check right before writing: the slot may have been taken since the model saw it
    if (!this.freeSlots(input.service, input.date).includes(input.time)) {
      throw new SlotTakenError(`${input.date} ${input.time} is already taken`);
    }
    const booking = { id: `B-${this.#nextId++}`, ...input };
    this.#bookings.push(booking);
    return booking;
  }
}

import type Anthropic from "@anthropic-ai/sdk";
import { z } from "zod";
import { SERVICE_IDS, SlotTakenError, type Salon } from "./salon.ts";

// 1. What the model sees: name, description and JSON Schema of each tool
export const TOOLS: Anthropic.Tool[] = [
  {
    name: "get_free_slots",
    description:
      "Returns free start times for one salon service on one date. " +
      "Call it before offering times to the client and again before create_booking. " +
      "Times are local salon time (Asia/Almaty), 24-hour HH:MM; the salon works 10:00-20:00. " +
      "An empty list means the day is fully booked. This tool does not book anything.",
    strict: true,
    input_schema: {
      type: "object",
      properties: {
        service: { type: "string", enum: [...SERVICE_IDS], description: "Service id" },
        date: { type: "string", format: "date", description: "YYYY-MM-DD, today or up to 30 days ahead" },
      },
      required: ["service", "date"],
      additionalProperties: false,
    },
  },
  {
    name: "create_booking",
    description:
      "Books one appointment. Call it only for a time that get_free_slots returned and only when " +
      "the client has given service, date, time, name and phone. Never invent a name or a phone number. " +
      "The application shows the client a confirmation button before writing the booking; " +
      "if the client declines, the tool returns an error and nothing is booked.",
    strict: true,
    input_schema: {
      type: "object",
      properties: {
        service: { type: "string", enum: [...SERVICE_IDS] },
        date: { type: "string", format: "date", description: "YYYY-MM-DD" },
        time: { type: "string", pattern: "^([01]\\d|2[0-3]):[0-5]\\d$", description: "HH:MM from get_free_slots" },
        client_name: { type: "string", description: "Client's first name as they wrote it" },
        phone: { type: "string", pattern: "^\\+7\\d{10}$", description: "Phone in +7XXXXXXXXXX format" },
      },
      required: ["service", "date", "time", "client_name", "phone"],
      additionalProperties: false,
    },
  },
];

import type Anthropic from "@anthropic-ai/sdk";
import { READ_ONLY_TOOLS, TOOLS, runTool, type ToolContext } from "./tools.ts";

export type TurnResult = {
  status: "done" | "stopped" | "step_limit";
  text: string;
  stopReason: Anthropic.StopReason | null;
  steps: number;
};

export type ChatOptions = {
  client: Anthropic;
  ctx: ToolContext;
  model?: string;
  maxSteps?: number;
  log?: (event: Record<string, unknown>) => void;
};

const systemPrompt = (today: string) =>
  "You are the booking assistant of a beauty salon in Almaty. Answer in the client's language. " +
  `Today is ${today}. Check free times with get_free_slots before offering them. ` +
  "Before create_booking, make sure you know the service, date, time, name and phone; ask if anything is missing.";

// One tool call failing must not break the whole turn: unexpected errors become is_error results
async function safeRun(call: Anthropic.ToolUseBlock, ctx: ToolContext): Promise<Anthropic.ToolResultBlockParam> {
  try {
    return await runTool(call, ctx);
  } catch (error) {
    console.error(`tool ${call.name} crashed`, error); // details stay in our logs, not in the prompt
    return { type: "tool_result", tool_use_id: call.id, content: "Internal error. Apologize and offer to call the salon.", is_error: true };
  }
}

// Read-only calls run concurrently, calls with side effects run one by one in the model's order
async function runCalls(calls: Anthropic.ToolUseBlock[], ctx: ToolContext, log: ChatOptions["log"]) {
  const results = new Map<string, Anthropic.ToolResultBlockParam>();
  const timed = async (call: Anthropic.ToolUseBlock) => {
    const started = performance.now();
    const result = await safeRun(call, ctx);
    log?.({ tool: call.name, input: call.input, error: result.is_error === true, ms: Math.round(performance.now() - started) });
    results.set(call.id, result);
  };
  await Promise.all(calls.filter((c) => READ_ONLY_TOOLS.has(c.name)).map(timed));
  for (const call of calls.filter((c) => !READ_ONLY_TOOLS.has(c.name))) await timed(call);
  // One tool_result for every tool_use, in the same order, all in a single user message
  return calls.map((call) => results.get(call.id)!);
}

export async function runTurn(messages: Anthropic.MessageParam[], opts: ChatOptions): Promise<TurnResult> {
  const { client, ctx, model = "claude-opus-5-5", maxSteps = 6, log } = opts;
  // The model only sees the tools this conversation is allowed to use
  const tools = TOOLS.filter((tool) => ctx.allowedTools.has(tool.name));

  for (let step = 1; step <= maxSteps; step++) {
    const response = await client.messages.create({
      model,
      max_tokens: 16000,
      system: systemPrompt(ctx.today),
      tools,
      messages,
    });
    // Keep the whole content (text, tool_use, thinking blocks) in history, not just the text
    messages.push({ role: "assistant", content: response.content });

    const text = response.content
      .filter((block): block is Anthropic.TextBlock => block.type === "text")
      .map((block) => block.text)
      .join("\n");
    log?.({ step, stopReason: response.stop_reason });

    if (response.stop_reason === "end_turn") return { status: "done", text, stopReason: response.stop_reason, steps: step };
    if (response.stop_reason !== "tool_use") {
      // max_tokens, refusal and others: no tools to run, the application decides what to show
      return { status: "stopped", text, stopReason: response.stop_reason, steps: step };
    }

    const calls = response.content.filter((block): block is Anthropic.ToolUseBlock => block.type === "tool_use");
    messages.push({ role: "user", content: await runCalls(calls, ctx, log) });
  }

  return { status: "step_limit", text: "", stopReason: null, steps: maxSteps };
}

// 2. What our code accepts: the same shape plus rules JSON Schema in strict mode cannot express
const GetFreeSlotsInput = z.strictObject({
  service: z.enum(SERVICE_IDS),
  date: z.iso.date(),
});

const CreateBookingInput = z.strictObject({
  service: z.enum(SERVICE_IDS),
  date: z.iso.date(),
  time: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/),
  client_name: z.string().trim().min(2).max(60),
  phone: z.string().regex(/^\+7\d{10}$/),
});

export const READ_ONLY_TOOLS: ReadonlySet<string> = new Set(["get_free_slots"]);

export type ToolContext = {
  salon: Salon;
  today: string; // YYYY-MM-DD in the salon's time zone
  allowedTools: ReadonlySet<string>;
  // A human decision outside the model: a button in the chat, not a model's "yes"
  confirm: (summary: string) => Promise<boolean>;
};

type Result = Anthropic.ToolResultBlockParam;

const DAY_MS = 24 * 60 * 60 * 1000;

function checkDate(date: string, today: string): string | null {
  const days = (Date.parse(date) - Date.parse(today)) / DAY_MS;
  if (days < 0) return `Date ${date} is in the past (today is ${today}). Ask the client for another date.`;
  if (days > 30) return `Date ${date} is more than 30 days ahead. Bookings open 30 days in advance.`;
  return null;
}

// 3. Execute one tool call. Every failure becomes an instructive is_error result, never a crash
export async function runTool(call: Anthropic.ToolUseBlock, ctx: ToolContext): Promise<Result> {
  const ok = (data: unknown): Result => ({ type: "tool_result", tool_use_id: call.id, content: JSON.stringify(data) });
  const fail = (message: string): Result => ({ type: "tool_result", tool_use_id: call.id, content: message, is_error: true });

  if (!ctx.allowedTools.has(call.name)) {
    return fail(`Tool ${call.name} is not available in this conversation.`);
  }

  switch (call.name) {
    case "get_free_slots": {
      const parsed = GetFreeSlotsInput.safeParse(call.input);
      if (!parsed.success) return fail(`Invalid arguments:\n${z.prettifyError(parsed.error)}`);
      const { service, date } = parsed.data;
      const dateProblem = checkDate(date, ctx.today);
      if (dateProblem) return fail(dateProblem);
      return ok({ service, date, slots: ctx.salon.freeSlots(service, date) });
    }

    case "create_booking": {
      const parsed = CreateBookingInput.safeParse(call.input);
      if (!parsed.success) return fail(`Invalid arguments:\n${z.prettifyError(parsed.error)}`);
      const { service, date, time, client_name, phone } = parsed.data;
      const dateProblem = checkDate(date, ctx.today);
      if (dateProblem) return fail(dateProblem);
      if (!ctx.salon.freeSlots(service, date).includes(time)) {
        return fail(`${date} ${time} is not free for ${service}. Call get_free_slots and offer one of the returned times.`);
      }

      const approved = await ctx.confirm(`${service}, ${date} ${time}, ${client_name}, ${phone}`);
      if (!approved) return fail("The client did not confirm. Nothing was booked. Ask what to change.");

      try {
        const booking = ctx.salon.book({ service, date, time, clientName: client_name, phone });
        return ok({ booking_id: booking.id, service, date, time });
      } catch (error) {
        if (error instanceof SlotTakenError) {
          return fail(`${date} ${time} was just taken by another client. Call get_free_slots again.`);
        }
        throw error;
      }
    }

    default:
      return fail(`Unknown tool ${call.name}.`);
  }
}

// Local stand-in for POST /v1/messages: replays scripted model turns and records every request.
// It also checks the history rule the real API enforces: each tool_use is answered by a tool_result
// in the very next user message, and tool_result blocks come first.
import { createServer } from "node:http";
import type { AddressInfo } from "node:net";
import type Anthropic from "@anthropic-ai/sdk";

export type MockTurn = {
  content: Array<
    | { type: "text"; text: string }
    | { type: "tool_use"; id: string; name: string; input: Record<string, unknown> }
  >;
  stop_reason: Anthropic.StopReason;
};

type RequestBody = Anthropic.MessageCreateParamsNonStreaming;

function historyProblem(messages: Anthropic.MessageParam[]): string | null {
  for (let i = 0; i < messages.length; i++) {
    const { role, content } = messages[i]!;
    if (role !== "assistant" || typeof content === "string") continue;
    const ids = content.flatMap((b) => (b.type === "tool_use" ? [b.id] : []));
    if (ids.length === 0) continue;
    const next = messages[i + 1];
    if (!next) continue;
    const blocks = typeof next.content === "string" ? [] : next.content;
    const resultIds = blocks.flatMap((b) => (b.type === "tool_result" ? [b.tool_use_id] : []));
    const firstOther = blocks.findIndex((b) => b.type !== "tool_result");
    if (next.role !== "user" || ids.some((id) => !resultIds.includes(id))) {
      return "tool_use ids were found without tool_result blocks immediately after";
    }
    if (firstOther !== -1 && firstOther < resultIds.length) return "tool_result blocks must come first";
  }
  return null;
}

export async function startMockAnthropic(script: MockTurn[]) {
  const requests: RequestBody[] = [];
  let turn = 0;

  const server = createServer(async (req, res) => {
    let raw = "";
    for await (const chunk of req) raw += chunk;
    const send = (status: number, body: unknown) => {
      res.writeHead(status, { "content-type": "application/json" });
      res.end(JSON.stringify(body));
    };
    if (req.method !== "POST" || req.url !== "/v1/messages") return send(404, {});

    const body = JSON.parse(raw) as RequestBody;
    requests.push(structuredClone(body));
    const problem = historyProblem(body.messages);
    if (problem) return send(400, { type: "error", error: { type: "invalid_request_error", message: problem } });

    const next = script[turn++];
    if (!next) return send(500, { type: "error", error: { type: "api_error", message: "mock script exhausted" } });
    send(200, {
      id: `msg_mock_${turn}`,
      type: "message",
      role: "assistant",
      model: body.model,
      content: next.content,
      stop_reason: next.stop_reason,
      stop_sequence: null,
      usage: { input_tokens: 0, output_tokens: 0 },
    });
  });

  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
  const { port } = server.address() as AddressInfo;
  return {
    url: `http://127.0.0.1:${port}`,
    requests,
    close: () => new Promise<void>((resolve) => server.close(() => resolve())),
  };
}

// Full tool-calling cycle against the local mock: no API key, no network
import Anthropic from "@anthropic-ai/sdk";
import { runTurn } from "./chat.ts";
import { startMockAnthropic } from "./mock-anthropic.ts";
import { Salon } from "./salon.ts";

const mock = await startMockAnthropic([
  {
    // The model asks for two dates at once: parallel tool calls
    stop_reason: "tool_use",
    content: [
      { type: "text", text: "Checking Friday and Saturday." },
      { type: "tool_use", id: "toolu_01", name: "get_free_slots", input: { service: "manicure", date: "2026-10-16" } },
      { type: "tool_use", id: "toolu_02", name: "get_free_slots", input: { service: "manicure", date: "2026-10-17" } },
    ],
  },
  {
    stop_reason: "tool_use",
    content: [
      {
        type: "tool_use",
        id: "toolu_03",
        name: "create_booking",
        input: { service: "manicure", date: "2026-10-16", time: "15:00", client_name: "Aigerim", phone: "+77010000000" },
      },
    ],
  },
  { stop_reason: "end_turn", content: [{ type: "text", text: "Done: manicure on Friday, October 16 at 15:00." }] },
]);

const salon = new Salon();
salon.book({ service: "manicure", date: "2026-10-16", time: "16:00", clientName: "Test", phone: "+77000000000" });

const client = new Anthropic({ apiKey: "test-key", baseURL: mock.url, maxRetries: 0 });
const messages: Anthropic.MessageParam[] = [
  { role: "user", content: "Book me for a manicure on Friday after 3 pm. Aigerim, +77010000000" },
];

const result = await runTurn(messages, {
  client,
  ctx: {
    salon,
    today: "2026-10-12",
    allowedTools: new Set(["get_free_slots", "create_booking"]),
    confirm: async (summary) => {
      console.log(`[confirm button] ${summary} -> yes`);
      return true;
    },
  },
  log: (event) => console.log(JSON.stringify(event)),
});

console.log(result);
console.log("bookings:", salon.bookings.map((b) => `${b.id} ${b.date} ${b.time} ${b.clientName}`));
console.log("requests sent:", mock.requests.length);
console.dir(mock.requests[1]!.messages.at(-1), { depth: 3 }); // what we sent back after step 1
await mock.close();

$ node src/demo.ts
{"step":1,"stopReason":"tool_use"}
{"tool":"get_free_slots","input":{"service":"manicure","date":"2026-10-16"},"error":false,"ms":1}
{"tool":"get_free_slots","input":{"service":"manicure","date":"2026-10-17"},"error":false,"ms":0}
{"step":2,"stopReason":"tool_use"}
[confirm button] manicure, 2026-10-16 15:00, Aigerim, +77010000000 -> yes
{"tool":"create_booking","input":{"service":"manicure","date":"2026-10-16","time":"15:00","client_name":"Aigerim","phone":"+77010000000"},"error":false,"ms":1}
{"step":3,"stopReason":"end_turn"}
{
  status: 'done',
  text: 'Done: manicure on Friday, October 16 at 15:00.',
  stopReason: 'end_turn',
  steps: 3
}
bookings: [ 'B-1 2026-10-16 16:00 Test', 'B-2 2026-10-16 15:00 Aigerim' ]
requests sent: 3
{
  role: 'user',
  content: [
    {
      type: 'tool_result',
      tool_use_id: 'toolu_01',
      content: '{"service":"manicure","date":"2026-10-16","slots":["10:00","10:30","11:00","11:30","12:00","12:30","13:00","13:30","14:00","14:30","15:00","17:00","17:30","18:00","18:30","19:00"]}'
    },
    {
      type: 'tool_result',
      tool_use_id: 'toolu_02',
      content: '{"service":"manicure","date":"2026-10-17","slots":["10:00","10:30","11:00","11:30","12:00","12:30","13:00","13:30","14:00","14:30","15:00","15:30","16:00","16:30","17:00","17:30","18:00","18:30","19:00"]}'
    }
  ]
}

import assert from "node:assert/strict";
import { describe, it } from "node:test";
import type Anthropic from "@anthropic-ai/sdk";
import { Salon } from "../src/salon.ts";
import { runTool, type ToolContext } from "../src/tools.ts";

const call = (name: string, input: Record<string, unknown>): Anthropic.ToolUseBlock =>
  ({ type: "tool_use", id: "toolu_test", name, input }) as Anthropic.ToolUseBlock;

const booking = { service: "manicure", date: "2026-10-16", time: "15:00", client_name: "Aigerim", phone: "+77010000000" };

function context(overrides: Partial<ToolContext> = {}): ToolContext {
  return {
    salon: new Salon(),
    today: "2026-10-12",
    allowedTools: new Set(["get_free_slots", "create_booking"]),
    confirm: async () => true,
    ...overrides,
  };
}

describe("argument validation", () => {
  const invalid: Array<[string, string, Record<string, unknown>, RegExp]> = [
    ["missing date", "get_free_slots", { service: "manicure" }, /date/],
    ["date in a wrong format", "get_free_slots", { service: "manicure", date: "16.10.2026" }, /Invalid ISO date/],
    ["unknown service", "get_free_slots", { service: "massage", date: "2026-10-16" }, /service/],
    ["extra property", "create_booking", { ...booking, discount: 50 }, /Unrecognized key: "discount"/],
    ["phone in a wrong format", "create_booking", { ...booking, phone: "8 701 000 00 00" }, /phone/],
    ["time as a number", "create_booking", { ...booking, time: 15 }, /time/],
    ["empty name", "create_booking", { ...booking, client_name: " " }, /client_name/],
  ];

  for (const [title, name, input, message] of invalid) {
    it(`rejects ${title} with is_error`, async () => {
      const ctx = context();
      const result = await runTool(call(name, input), ctx);
      assert.equal(result.is_error, true);
      assert.equal(result.tool_use_id, "toolu_test");
      assert.match(String(result.content), message);
      assert.equal(ctx.salon.bookings.length, 0);
    });
  }

  it("rejects a date in the past with an instruction for the model", async () => {
    const result = await runTool(call("get_free_slots", { service: "manicure", date: "2026-10-01" }), context());
    assert.equal(result.is_error, true);
    assert.match(String(result.content), /in the past \(today is 2026-10-12\)/);
  });
});

describe("business rules and boundaries", () => {
  it("returns free slots without the busy time", async () => {
    const ctx = context();
    ctx.salon.book({ service: "manicure", date: "2026-10-16", time: "16:00", clientName: "T", phone: "+77000000000" });
    const result = await runTool(call("get_free_slots", { service: "manicure", date: "2026-10-16" }), ctx);
    const { slots } = JSON.parse(String(result.content)) as { slots: string[] };
    assert.equal(result.is_error, undefined);
    assert.ok(slots.includes("15:00"));
    assert.ok(!slots.includes("15:30") && !slots.includes("16:00") && !slots.includes("16:30"));
  });

  it("refuses a busy time and does not ask the client", async () => {
    let asked = false;
    const ctx = context({ confirm: async () => (asked = true) });
    ctx.salon.book({ service: "manicure", date: "2026-10-16", time: "15:00", clientName: "T", phone: "+77000000000" });
    const result = await runTool(call("create_booking", booking), ctx);
    assert.equal(result.is_error, true);
    assert.match(String(result.content), /not free.*Call get_free_slots/);
    assert.equal(asked, false);
  });

  it("books nothing when the client declines", async () => {
    const ctx = context({ confirm: async () => false });
    const result = await runTool(call("create_booking", booking), ctx);
    assert.equal(result.is_error, true);
    assert.match(String(result.content), /did not confirm/);
    assert.equal(ctx.salon.bookings.length, 0);
  });

  it("books after confirmation", async () => {
    const ctx = context();
    const result = await runTool(call("create_booking", booking), ctx);
    assert.equal(result.is_error, undefined);
    assert.deepEqual(JSON.parse(String(result.content)), { booking_id: "B-1", service: "manicure", date: "2026-10-16", time: "15:00" });
  });

  it("does not run a tool that is not allowed in this conversation", async () => {
    const ctx = context({ allowedTools: new Set(["get_free_slots"]) });
    const result = await runTool(call("create_booking", booking), ctx);
    assert.equal(result.is_error, true);
    assert.match(String(result.content), /not available/);
    assert.equal(ctx.salon.bookings.length, 0);
  });

  it("answers an unknown tool name with is_error", async () => {
    const result = await runTool(call("cancel_booking", { booking_id: "B-1" }), context({ allowedTools: new Set(["cancel_booking"]) }));
    assert.equal(result.is_error, true);
    assert.match(String(result.content), /Unknown tool cancel_booking/);
  });
});

import assert from "node:assert/strict";
import { describe, it } from "node:test";
import Anthropic from "@anthropic-ai/sdk";
import { runTurn } from "../src/chat.ts";
import { startMockAnthropic, type MockTurn } from "../src/mock-anthropic.ts";
import { Salon } from "../src/salon.ts";
import type { ToolContext } from "../src/tools.ts";

const slots = (id: string, date: string): MockTurn["content"][number] => ({
  type: "tool_use",
  id,
  name: "get_free_slots",
  input: { service: "manicure", date },
});
const book = (id: string, time: string): MockTurn["content"][number] => ({
  type: "tool_use",
  id,
  name: "create_booking",
  input: { service: "manicure", date: "2026-10-16", time, client_name: "Aigerim", phone: "+77010000000" },
});

async function run(script: MockTurn[], ctx: Partial<ToolContext> = {}, maxSteps?: number) {
  const mock = await startMockAnthropic(script);
  const salon = new Salon();
  try {
    const result = await runTurn([{ role: "user", content: "Manicure on Friday after 3 pm" }], {
      client: new Anthropic({ apiKey: "test-key", baseURL: mock.url, maxRetries: 0 }),
      ctx: { salon, today: "2026-10-12", allowedTools: new Set(["get_free_slots", "create_booking"]), confirm: async () => true, ...ctx },
      maxSteps,
    });
    return { result, requests: mock.requests, salon };
  } finally {
    await mock.close();
  }
}

type Sent = Anthropic.ToolResultBlockParam[];
const lastUserBlocks = (request: Anthropic.MessageCreateParamsNonStreaming) => request.messages.at(-1)!.content as Sent;

describe("tool-calling loop against the mock Messages API", () => {
  it("runs the full cycle: parallel lookups, booking, final answer", async () => {
    const { result, requests, salon } = await run([
      { stop_reason: "tool_use", content: [slots("toolu_01", "2026-10-16"), slots("toolu_02", "2026-10-17")] },
      { stop_reason: "tool_use", content: [book("toolu_03", "15:00")] },
      { stop_reason: "end_turn", content: [{ type: "text", text: "Booked for 15:00." }] },
    ]);

    assert.deepEqual(result, { status: "done", text: "Booked for 15:00.", stopReason: "end_turn", steps: 3 });
    assert.equal(requests.length, 3);
    assert.deepEqual(requests[0]!.tools!.map((t) => (t as Anthropic.Tool).name), ["get_free_slots", "create_booking"]);

    // Both parallel results go back in ONE user message, in the order of the calls
    const second = lastUserBlocks(requests[1]!);
    assert.equal(requests[1]!.messages.at(-1)!.role, "user");
    assert.deepEqual(second.map((b) => b.tool_use_id), ["toolu_01", "toolu_02"]);
    assert.ok(second.every((b) => b.type === "tool_result" && b.is_error === undefined));

    assert.deepEqual(lastUserBlocks(requests[2]!).map((b) => b.tool_use_id), ["toolu_03"]);
    assert.equal(salon.bookings.length, 1);
  });

  it("returns invalid arguments as is_error and lets the model correct itself", async () => {
    const { result, requests, salon } = await run([
      { stop_reason: "tool_use", content: [book("toolu_01", "3 pm")] },
      { stop_reason: "tool_use", content: [book("toolu_02", "15:00")] },
      { stop_reason: "end_turn", content: [{ type: "text", text: "Booked." }] },
    ]);
    const first = lastUserBlocks(requests[1]!)[0]!;
    assert.equal(first.is_error, true);
    assert.match(String(first.content), /Invalid arguments[\s\S]*time/);
    assert.equal(result.status, "done");
    assert.equal(salon.bookings.length, 1);
  });

  it("stops at the step limit instead of looping forever", async () => {
    const endless = Array.from({ length: 10 }, (_, i): MockTurn => ({
      stop_reason: "tool_use",
      content: [slots(`toolu_${i}`, "2026-10-16")],
    }));
    const { result, requests } = await run(endless, {}, 3);
    assert.equal(result.status, "step_limit");
    assert.equal(requests.length, 3);
  });

  it("hides and blocks tools that are not allowed", async () => {
    const { requests, salon } = await run(
      [
        { stop_reason: "tool_use", content: [book("toolu_01", "15:00")] },
        { stop_reason: "end_turn", content: [{ type: "text", text: "I can only show free times." }] },
      ],
      { allowedTools: new Set(["get_free_slots"]) },
    );
    assert.deepEqual(requests[0]!.tools!.map((t) => (t as Anthropic.Tool).name), ["get_free_slots"]);
    assert.equal(lastUserBlocks(requests[1]!)[0]!.is_error, true);
    assert.equal(salon.bookings.length, 0);
  });

  it("does not run tools when the answer was cut by max_tokens", async () => {
    const { result, requests } = await run([{ stop_reason: "max_tokens", content: [{ type: "text", text: "Let me che" }] }]);
    assert.deepEqual([result.status, result.stopReason], ["stopped", "max_tokens"]);
    assert.equal(requests.length, 1);
  });
});

> tool-calling@1.0.0 test
> node --test

▶ tool-calling loop against the mock Messages API
  ✔ runs the full cycle: parallel lookups, booking, final answer (52.1838ms)
  ✔ returns invalid arguments as is_error and lets the model correct itself (12.8033ms)
  ✔ stops at the step limit instead of looping forever (9.5571ms)
  ✔ hides and blocks tools that are not allowed (5.2352ms)
  ✔ does not run tools when the answer was cut by max_tokens (3.7351ms)
✔ tool-calling loop against the mock Messages API (84.3836ms)
▶ argument validation
  ✔ rejects missing date with is_error (2.1468ms)
  ✔ rejects date in a wrong format with is_error (0.2898ms)
  ✔ rejects unknown service with is_error (0.2232ms)
  ✔ rejects extra property with is_error (0.6564ms)
  ✔ rejects phone in a wrong format with is_error (0.1848ms)
  ✔ rejects time as a number with is_error (0.1194ms)
  ✔ rejects empty name with is_error (0.1765ms)
  ✔ rejects a date in the past with an instruction for the model (0.1541ms)
✔ argument validation (4.7439ms)
▶ business rules and boundaries
  ✔ returns free slots without the busy time (0.4729ms)
  ✔ refuses a busy time and does not ask the client (0.2533ms)
  ✔ books nothing when the client declines (0.1299ms)
  ✔ books after confirmation (0.5623ms)
  ✔ does not run a tool that is not allowed in this conversation (0.1045ms)
  ✔ answers an unknown tool name with is_error (0.0917ms)
✔ business rules and boundaries (1.808ms)
ℹ tests 19
ℹ suites 3
ℹ pass 19
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 441.0589

$ npm run typecheck
> tool-calling@1.0.0 typecheck
> tsc

// Real run: needs ANTHROPIC_API_KEY in the environment (never in code). Usage:
// node src/main.ts "Book me for a manicure on Friday after 3 pm"
import { createInterface } from "node:readline/promises";
import Anthropic from "@anthropic-ai/sdk";
import { runTurn } from "./chat.ts";
import { Salon } from "./salon.ts";

const rl = createInterface({ input: process.stdin, output: process.stdout });
const messages: Anthropic.MessageParam[] = [{ role: "user", content: process.argv[2] ?? "Hi" }];

const result = await runTurn(messages, {
  client: new Anthropic(), // reads ANTHROPIC_API_KEY
  ctx: {
    salon: new Salon(),
    today: new Date().toLocaleDateString("sv-SE", { timeZone: "Asia/Almaty" }), // YYYY-MM-DD
    allowedTools: new Set(["get_free_slots", "create_booking"]),
    confirm: async (summary) => (await rl.question(`Confirm booking: ${summary}? (y/n) `)).trim() === "y",
  },
  log: (event) => console.error(JSON.stringify(event)),
});

console.log(result.status === "done" ? result.text : `Stopped (${result.status}, ${result.stopReason}). Please call the salon.`);
rl.close();