feat(ai-gateway): support TypeSafe System One via OpenRouter

[chrarnoldus]

Summary

• Add POST /api/gateway/typesafe/v1/systemone, forwarding to OpenRouter /api/v1/systemone with the platform credential.
• Limit requests to typesafe/jev-1.13 (also accepting the bare jev-1.13 SDK model ID); omitted HTTP models default to that pinned version. No user BYOK, additional providers, or model/metadata endpoint.
• Validate the TypeSafe request/response contract against types from @typesafe-ai/sdk, preserve gateway authentication, rate limits, balance checks and organization policy, and bill upstream usage.cost through the existing microdollar writer.
• Add regression coverage including real TypeSafe SDK transport compatibility and the primary-region usage-record contract. No database migration is required.

SDK usage

import { TypeSafeClient } from "@typesafe-ai/sdk";
const client = new TypeSafeClient({
  apiKey: process.env.KILO_API_KEY,
  baseURL: "https://api.kilo.ai/api/gateway/typesafe",
  defaultModel: "typesafe/jev-1.13",
});
const result = await client.systemOne({
  state: "I was charged twice for my subscription.",
  questions: { refund: { type: "noul", instructions: "Is the customer asking for money back?" } },
});

Validation

This PR was created and assigned to @chrarnoldus before running tests, as requested.

• Passed: 5 focused Jest suites, 156 tests. Includes the TypeSafe route, TypeSafe schemas, usage-record contract, existing usage processing, and gateway audience callsites.
• Passed: web TypeScript checks (pnpm --filter web exec tsgo --noEmit --checkers 1, after the tRPC declaration build), changed-file oxlint, formatting, and git diff --check.
• Passed: live @typesafe-ai/sdk@0.6.0 -> local Next.js gateway -> OpenRouter -> Jev -> local PostgreSQL billing, without mocks. Returned typesafe/jev-1.13-20260917, answer billing, 311 input tokens and 38 output tokens. Upstream cost $0.000013062 persisted as 13 microdollars, with the same generation ID and api_kind=systemone; the local user usage counter increased from 0 to 13.

The local E2E required starting Docker Desktop and a process-only default for the unrelated missing NEXT_PUBLIC_WASTELAND_URL. The repository test:db script currently fails on unsupported pnpm -s; its equivalent infra setup and migrations were run successfully as separate commands. No unrelated tracked tooling or configuration was changed. Temporary Next.js servers were stopped. Full repository validation was not run.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

The incremental commit 688579f09 is a test-only colocation: it moves the System One coverage from the route test into handler.test.ts and leaves a thin re-export assertion in route.test.ts. The move is faithful (call sites were rewritten to handleSystemOneRequest, mocks and fixtures are unchanged) and introduces no new defects.

Files Reviewed (2 files)

• apps/web/src/app/api/gateway/typesafe/v1/systemone/route.test.ts
• apps/web/src/lib/ai-gateway/typesafe/handler.test.ts

Previous Review Summaries (3 snapshots, latest commit cabfd2f)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit cabfd2f)

Status: No Issues Found | Recommendation: Merge

Executive Summary

The review-fix commit cabfd2f08 resolves both prior findings in handler.ts — the upstream 402 body is now cancelled and the invalid authentication_error fallback was removed in favour of the discriminated-union auth contract — and the accompanying test updates introduce no new defects.

Files Reviewed (2 files)

• apps/web/src/lib/ai-gateway/typesafe/handler.ts
• apps/web/src/app/api/gateway/typesafe/v1/systemone/route.test.ts

Previous review (commit eed8fd2)

Status: 2 Issues Found | Recommendation: Address before merge

Executive Summary

The TypeSafe System One handler was extracted into apps/web/src/lib/ai-gateway/typesafe/handler.ts mostly unchanged; the two open defects from the previous review (abandoned 402 upstream body, invalid error_type value) persist in the relocated code, and the refactor introduced no new defects.

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	1

Issue Details (click to expand)

WARNING

File	Line	Issue
apps/web/src/lib/ai-gateway/typesafe/handler.ts	114	Upstream 402 response body abandoned; connection buffer not released

SUGGESTION

File	Line	Issue
apps/web/src/lib/ai-gateway/typesafe/handler.ts	48	authentication_error is not a valid ProxyErrorType (use authentication_required)

Files Reviewed (5 files)

• apps/web/src/app/api/gateway/typesafe/v1/systemone/route.ts - 0 issues (re-export only)
• apps/web/src/lib/ai-gateway/typesafe/handler.ts - 2 issues
• apps/web/src/app/api/gateway/typesafe/v1/systemone/route.test.ts - 0 issues
• apps/web/src/lib/ai-gateway/typesafe/schemas.ts - 0 issues (rename only)
• apps/web/src/lib/ai-gateway/typesafe/schemas.test.ts - 0 issues (rename/import only)

Fix these issues in Kilo Cloud

Previous review (commit 48b9dff)

Status: 2 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	1

Issue Details (click to expand)

WARNING

File	Line	Issue
apps/web/src/app/api/gateway/typesafe/v1/systemone/route.ts	117	Upstream 402 response body abandoned; connection buffer not released

SUGGESTION

File	Line	Issue
apps/web/src/app/api/gateway/typesafe/v1/systemone/route.ts	49	authentication_error is not a valid ProxyErrorType (use authentication_required)

Files Reviewed (8 files)

• apps/web/package.json - 0 issues
• apps/web/src/app/api/gateway/typesafe/v1/systemone/route.ts - 2 issues
• apps/web/src/app/api/gateway/typesafe/v1/systemone/route.test.ts - 0 issues
• apps/web/src/lib/ai-gateway/typesafe.ts - 0 issues
• apps/web/src/lib/ai-gateway/typesafe.test.ts - 0 issues
• apps/web/src/lib/ai-gateway/usage-record-contract.test.ts - 0 issues
• packages/db/src/schema-types.ts - 0 issues
• pnpm-lock.yaml - 0 issues

Fix these issues in Kilo Cloud

---

_{Reviewed by deepseek-v4.1-flash · Input: 0 · Output: 0 · Cached: 0}

_{Review guidance: REVIEW.md from base branch main}