PR-B5 (ADR 0008 Phase B): TypeScript SDK — @kakeya/runtime

[FluffyAIcode]

⚠️ Stacked PR

Depends on PR #47 (PR-B4). Diff against main shows both PRs;
once #47 merges, this auto-rebases to a clean PR-B5-only diff.

What

Final PR of ADR 0008 Phase B. Ships sdks/typescript/ —
@kakeya/runtime package matching ADR §3.2 exactly. Public API
mirrors the Python SDK at sdks/python/kakeya/* symbol-for-symbol
(modulo TS naming convention) so cross-language users see one
shape:

import { Client } from "@kakeya/runtime";

const client = new Client("localhost:50051");
try {
  const session = await client.createSession({ eosTokenIds: [151645] });
  try {
    await session.append([10, 20, 30]);
    for await (const tokenId of session.generate({ maxTokens: 64 })) {
      console.log(tokenId);
    }
  } finally {
    await session.close();
  }
} finally {
  client.close();
}

Targets

Runtime	Supported
Node.js 20+	✅ (engines.node enforced)
Electron 30+	✅ (API-compatible with Node)
Bun 1.1+	✅ (API-compatible with Node)
Browser	❌ (gRPC-Web / WebSocket out of scope; ADR §8 OQ-1)

Surface

File	Role
src/index.ts	Public exports
src/client.ts (~110 lines)	Client, DEFAULT_ADDRESS, ClientOptions
src/session.ts (~285 lines)	Session, SessionInfo, GenerateOptions, GenerateResult
src/errors.ts (~130 lines)	KakeyaError base + 7 typed subclasses + wrapGrpcError
src/proto_gen/kakeya/v1/runtime.ts	Generated by protoc-gen-ts_proto; CI's proto-stub-drift extended to enforce

Error mapping (mirrors Python exactly):

gRPC StatusCode	SDK exception
NOT_FOUND	SessionNotFoundError
INVALID_ARGUMENT	InvalidArgumentError
FAILED_PRECONDITION	InvariantViolationError
RESOURCE_EXHAUSTED	ResourceExhaustedError
UNIMPLEMENTED	UnimplementedError
CANCELLED	RpcCancelledError
(other)	KakeyaError (base, with .rpcCode)
(client-side, never on wire)	SessionClosedError

Wire transport

@grpc/grpc-js (Node-native HTTP/2). Generated stubs use
protoc-gen-ts_proto with these options (recorded in
scripts/regenerate_proto_stubs.sh):

esModuleInterop=true        match tsconfig
forceLong=string            uint64 → string (JS Number can't hold full range)
outputServices=grpc-js      generate @grpc/grpc-js style Client + Service
useOptionals=messages       proto3 optional + message fields use TS optional
stringEnums=false           enums emit as integer constants (matches wire)
removeEnumPrefix=true       strip GENERATE_DONE_ prefix from enum members

forceLong=string is the safe default for uint64 fields
(historyLength, kvLiveBytes, droppedTokenCount, seed):
values cross the wire as decimal strings; the SDK converts to
Number at the public-API boundary. seed parameter accepts
number | string and stringifies internally for ergonomics.

Tests (54 vitest cases, 100% coverage)

File	Tests	Focus
test/client.test.ts	14	Construction, properties, idempotent close, all createSession arg paths, end-to-end RESOURCE_EXHAUSTED and NOT_FOUND via real gRPC channel
test/session.test.ts	20	All 5 RPC methods, async iterator for generate, HistoryTruncated capture, sampling param forwarding, error mappings, local-close vs runtime-eviction split, lastResult reset between calls
test/errors.test.ts	20	Every grpc.status → typed subclass, unknown-status fallback, details ?? message ?? "" fallback chain
test/server_fixture.ts	(helper)	In-Node @grpc/grpc-js server with parameterized canned-response handlers. Real wire format, real gRPC channel — no mocks of the SUT

npm test
54 passed | 100 % statements | 100 % branches | 100 % functions | 100 % lines

Tooling additions

scripts/regenerate_proto_stubs.sh (extended)

Single canonical regen command now produces both Python and TS
stubs. Behavior:

• Python stubs → inference_engine/server/proto_gen/ (unchanged)
• TS stubs → sdks/typescript/src/proto_gen/ (new)

Skips TS generation with a clear warning if ts-proto isn't
installed (avoids breaking contributors who only have Python tools).

.github/workflows/ci.yaml (extended)

Two changes:

1. proto-stub-drift job now also drift-checks TS stubs.
   Installs Node 20 + ts-proto before regen; git diff --exit-code covers both inference_engine/server/proto_gen/
   and sdks/typescript/src/proto_gen/.

2. typescript-sdk-tests job (new). Runs:

   • npm install in sdks/typescript/
   • npm run typecheck (strict TS)
   • npm test (vitest with 100% coverage thresholds)

Per ADR 0008 §9

Linux-only-path carve-out: zero MLX runtime code; SDK is pure TS
over @grpc/grpc-js. The Linux CI gate is the binding gate. Mac
M4 reviewers can run npm test in sdks/typescript/ to verify
on Apple Silicon, but no §9 mandatory report applies.

Reviewer checklist

• Public API matches Python SDK symbol-for-symbol (modulo case): Client, Session, SessionInfo, 7 typed errors, DEFAULT_ADDRESS.
• No tokenization in SDK core (grep -ri "applyChatTemplate\|tokenizer" sdks/typescript/src/ returns no production hits).
• Generated stubs reproducible: CI's proto-stub-drift job confirms on every push.
• Real gRPC channel in tests (no mocks of @grpc/grpc-js itself).
• forceLong=string rationale documented in the regen script (uint64 safety).
• engines.node>=20 declared in package.json.
• No browser-runtime assumptions in code (Node-only @grpc/grpc-js).

Phase B is complete after this PR merges

PR-A1 (#40)  proto/runtime.proto + buf lint                  ✅ merged
PR-A2 (#41)  SessionStore + INV-1/2                          ✅ merged
PR-A3 (#42)  remove ADR 0007 dead code                       ✅ merged
PR-A3b(#43)  session-slab ownership + CacheInspector         ✅ merged
PR-B1 (#44)  gRPC Create/Close/GetSessionInfo                ✅ merged
PR-B2 (#45)  AppendTokens + byte-exact prefill-incremental   ✅ merged
PR-B3 (#46)  Generate server-streaming + greedy              ⏳ ready
PR-B4 (#47)  Python SDK (kakeya.Client + Session)            ⏳ ready
PR-B5 (this) TypeScript SDK (@kakeya/runtime)                ⏳ this PR

What's next (post-Phase-B)

• Phase C / PR-D1: Refactor the deprecated HTTP shim onto the new SessionStore (today the HTTP shim still uses PooledVerifier directly).
• Phase E / PR-E1: tests/integration/ directory + the long-promised test_inv3_session_determinism_gate.py running against the real Qwen3 verifier on Mac M4.
• v0.4 deferreds: multi-tenant authentication, speculative-decoding integration into Generate, browser-targeted SDK transport (revisit OQ-1).