Claude API の 400/422/529 を“呼ぶ前”に消す5層プリフライト設計 — 月数百件の失敗呼び出しをゼロにした実装

// preflight/schema.ts
import { z } from "zod";
 
const TextBlock = z.object({
  type: z.literal("text"),
  text: z.string().min(1, "text content cannot be empty"),
});
 
const ToolUseBlock = z.object({
  type: z.literal("tool_use"),
  id: z.string().regex(/^toolu_/),
  name: z.string().min(1),
  input: z.record(z.unknown()),
});
 
const ToolResultBlock = z.object({
  type: z.literal("tool_result"),
  tool_use_id: z.string().regex(/^toolu_/),
  content: z.union([z.string(), z.array(TextBlock)]),
  is_error: z.boolean().optional(),
});
 
const ContentBlock = z.discriminatedUnion("type", [
  TextBlock,
  ToolUseBlock,
  ToolResultBlock,
]);
 
const Message = z.object({
  role: z.enum(["user", "assistant"]),
  content: z.union([z.string().min(1), z.array(ContentBlock).min(1)]),
});
 
export const RequestSchema = z.object({
  model: z.string(),
  max_tokens: z.number().int().positive(),
  messages: z.array(Message).min(1).refine(
    (msgs) => alternates(msgs),
    "messages must alternate between user and assistant"
  ),
  system: z.union([z.string(), z.array(TextBlock)]).optional(),
  tools: z.array(z.object({
    name: z.string().regex(/^[a-zA-Z0-9_-]{1,64}$/),
    description: z.string().min(1),
    input_schema: z.object({
      type: z.literal("object"),
      properties: z.record(z.unknown()),
      required: z.array(z.string()).optional(),
    }),
  })).optional(),
});
 
function alternates(msgs: { role: string }[]): boolean {
  for (let i = 1; i < msgs.length; i++) {
    if (msgs[i].role === msgs[i - 1].role) return false;
  }
  return true;
}
// 実行例: const parsed = RequestSchema.safeParse(req); if (!parsed.success) { ... }

// preflight/token-budget.ts
import { encoding_for_model, get_encoding } from "@dqbd/tiktoken";
 
// Claude のトークナイザは Anthropic 独自ですが、cl100k 系で
// 概算しても実用上は ±5% に収まります（自社計測値）。
const enc = get_encoding("cl100k_base");
 
interface TokenBudgetResult {
  estimated: number;
  contextLimit: number;
  maxTokens: number;
  ok: boolean;
  reason?: string;
}
 
const MODEL_LIMITS: Record<string, number> = {
  "claude-opus-4-6": 200_000,
  "claude-sonnet-4-6": 200_000,
  "claude-haiku-4-5-20251001": 200_000,
};
 
export function checkTokenBudget(req: {
  model: string;
  max_tokens: number;
  messages: Array<{ role: string; content: unknown }>;
  system?: string;
  tools?: Array<{ description: string; input_schema: unknown }>;
}): TokenBudgetResult {
  const limit = MODEL_LIMITS[req.model] ?? 200_000;
  const serialized =
    (req.system ?? "") +
    JSON.stringify(req.messages) +
    JSON.stringify(req.tools ?? []);
  const inputTokens = enc.encode(serialized).length;
  const estimated = inputTokens + req.max_tokens;
  const headroom = Math.floor(limit * 0.95); // 5% を安全マージンとして残す
 
  if (estimated > headroom) {
    return {
      estimated,
      contextLimit: limit,
      maxTokens: req.max_tokens,
      ok: false,
      reason: `estimated ${estimated} tokens exceeds 95% of context (${headroom})`,
    };
  }
  return { estimated, contextLimit: limit, maxTokens: req.max_tokens, ok: true };
}
// 期待出力: { estimated: 12345, contextLimit: 200000, ok: true }

// preflight/capability.ts
type Feature = "vision" | "tool_use" | "extended_thinking" | "1m_context";
 
const CAPABILITIES: Record<string, Feature[]> = {
  "claude-opus-4-6": ["vision", "tool_use", "extended_thinking"],
  "claude-sonnet-4-6": ["vision", "tool_use", "extended_thinking"],
  "claude-haiku-4-5-20251001": ["tool_use"],
};
 
export function checkCapabilities(req: {
  model: string;
  hasImage: boolean;
  usesTools: boolean;
  thinking?: { type: string };
}): { ok: boolean; missing: Feature[] } {
  const supported = new Set(CAPABILITIES[req.model] ?? []);
  const required: Feature[] = [];
  if (req.hasImage) required.push("vision");
  if (req.usesTools) required.push("tool_use");
  if (req.thinking?.type === "enabled") required.push("extended_thinking");
  const missing = required.filter((f) => !supported.has(f));
  return { ok: missing.length === 0, missing };
}
// 期待出力: { ok: false, missing: ["vision"] } のように
// 不足機能を列挙して返す

// preflight/content-policy.ts
const SYSTEM_LEAK_MARKERS = [
  /You are a helpful assistant/i,
  /<\|im_start\|>/,
  /BEGIN INTERNAL PROMPT/i,
];
const PII_PATTERNS = [
  /\b\d{3}-\d{4}-\d{4}\b/,         // 日本の電話番号
  /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i, // メール
  /\b\d{4}-\d{4}-\d{4}-\d{4}\b/,    // クレジットカード
];
 
export function checkContentPolicy(req: {
  messages: Array<{ role: string; content: string | unknown[] }>;
}): { ok: boolean; violations: string[] } {
  const v: string[] = [];
  for (const msg of req.messages) {
    const text =
      typeof msg.content === "string"
        ? msg.content
        : msg.content.map((b: any) => b.text ?? "").join("\n");
    for (const re of SYSTEM_LEAK_MARKERS) {
      if (re.test(text)) v.push(`possible system prompt leak: ${re}`);
    }
    for (const re of PII_PATTERNS) {
      if (re.test(text)) v.push(`possible PII: ${re}`);
    }
  }
  return { ok: v.length === 0, violations: v };
}

// preflight/budget-guard.ts
interface SpendCap {
  monthlyJpy: number;
  perRequestJpy: number;
}
 
export async function checkBudget(
  kv: KVNamespace,
  userId: string,
  cap: SpendCap,
  estimatedJpy: number
): Promise<{ ok: boolean; reason?: string }> {
  const monthKey = new Date().toISOString().slice(0, 7);
  const used = parseFloat(
    (await kv.get(`spend:${userId}:${monthKey}`)) ?? "0"
  );
  if (used + estimatedJpy > cap.monthlyJpy) {
    return {
      ok: false,
      reason: `monthly cap exceeded: ${used + estimatedJpy} > ${cap.monthlyJpy}`,
    };
  }
  if (estimatedJpy > cap.perRequestJpy) {
    return {
      ok: false,
      reason: `per-request cap exceeded: ${estimatedJpy} > ${cap.perRequestJpy}`,
    };
  }
  return { ok: true };
}
// 期待出力: { ok: false, reason: "monthly cap exceeded: 6200 > 5000" }

// preflight/index.ts
import { RequestSchema } from "./schema";
import { checkTokenBudget } from "./token-budget";
import { checkCapabilities } from "./capability";
import { checkContentPolicy } from "./content-policy";
import { checkBudget } from "./budget-guard";
 
export type PreflightResult =
  | { kind: "allow"; estimated: { tokens: number; jpy: number } }
  | { kind: "deny"; layer: 1 | 2 | 3 | 4 | 5; reason: string };
 
export async function preflight(
  req: unknown,
  ctx: { kv: KVNamespace; userId: string; cap: SpendCap }
): Promise<PreflightResult> {
  const parsed = RequestSchema.safeParse(req);
  if (!parsed.success) {
    return { kind: "deny", layer: 1, reason: parsed.error.message };
  }
  const r = parsed.data;
 
  const tb = checkTokenBudget(r);
  if (!tb.ok) return { kind: "deny", layer: 2, reason: tb.reason! };
 
  const cap = checkCapabilities({
    model: r.model,
    hasImage: detectImage(r.messages),
    usesTools: !!r.tools?.length,
  });
  if (!cap.ok) {
    return { kind: "deny", layer: 3, reason: `missing: ${cap.missing}` };
  }
 
  const cp = checkContentPolicy(r);
  if (!cp.ok) {
    return { kind: "deny", layer: 4, reason: cp.violations.join("; ") };
  }
 
  const estimatedJpy = estimateJpy(r.model, tb.estimated);
  const bg = await checkBudget(ctx.kv, ctx.userId, ctx.cap, estimatedJpy);
  if (!bg.ok) return { kind: "deny", layer: 5, reason: bg.reason! };
 
  return {
    kind: "allow",
    estimated: { tokens: tb.estimated, jpy: estimatedJpy },
  };
}