Merge pull request #48 from FluffyAIcode/AgentMemory/v030-pr-b5-typescript-sdk-8e7f

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

Author: FluffyAIcode

.github/workflows/ci.yaml

@@ -258,13 +258,55 @@ jobs:
           # bytes, this job catches it as a drift before merge.
           pip install 'grpcio>=1.65,<2.0' 'grpcio-tools>=1.65,<2.0'
 
-      - name: Regenerate stubs
+      - name: Set up Node.js (for ts-proto plugin)
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: sdks/typescript/package-lock.json
+
+      - name: Install ts-proto in sdks/typescript
+        run: |
+          cd sdks/typescript
+          npm install --no-audit --no-fund
+
+      - name: Regenerate stubs (Python + TypeScript)
         run: bash scripts/regenerate_proto_stubs.sh
 
       - name: Fail if regenerated stubs differ from committed stubs
         run: |
-          if ! git diff --exit-code -- inference_engine/server/proto_gen/; then
+          if ! git diff --exit-code -- inference_engine/server/proto_gen/ sdks/typescript/src/proto_gen/; then
             echo "::error::Committed stubs are out of date with proto/."
             echo "Run scripts/regenerate_proto_stubs.sh locally and commit."
             exit 1
           fi
+
+  typescript-sdk-tests:
+    name: TypeScript SDK tests
+    runs-on: ubuntu-latest
+    # ADR 0008 PR-B5: vitest under Node 20+. The TypeScript SDK is
+    # Linux-runnable end-to-end (no MLX dependency); the in-Node
+    # gRPC server fixture lets us test the SDK against a real
+    # @grpc/grpc-js channel without needing the Python runtime.
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: sdks/typescript/package-lock.json
+
+      - name: Install dependencies
+        working-directory: sdks/typescript
+        run: npm install --no-audit --no-fund
+
+      - name: Type-check
+        working-directory: sdks/typescript
+        run: npm run typecheck
+
+      - name: Run vitest with 100% coverage
+        working-directory: sdks/typescript
+        run: npm test

scripts/regenerate_proto_stubs.sh

@@ -1,21 +1,30 @@
 #!/usr/bin/env bash
-# Regenerate Python gRPC stubs from proto/kakeya/v1/*.proto.
+# Regenerate gRPC stubs from proto/kakeya/v1/*.proto for every SDK.
 #
-# Generated files land in inference_engine/server/proto_gen/ and are
-# committed to the repo. Re-run this script whenever a .proto file
-# changes; CI's `proto-stub-drift` check verifies that the committed
-# stubs are up-to-date by re-running the script and `git diff
-# --exit-code`.
+# Targets:
+#   * Python  -> inference_engine/server/proto_gen/   (PR-A1)
+#   * TypeScript -> sdks/typescript/src/proto_gen/    (PR-B5)
+#
+# Generated files are committed to the repo. Re-run this script
+# whenever a .proto file changes; CI's `proto-stub-drift` check
+# verifies that the committed stubs are byte-identical to what
+# this script produces.
 #
 # This is the canonical regeneration command. Do NOT invoke
-# `python -m grpc_tools.protoc` ad-hoc — keep all flags here so they
-# are reproducible across contributor machines and CI.
+# `protoc` ad-hoc — keep all flags here so they are reproducible
+# across contributor machines and CI.
+#
+# Prerequisites:
+#   * Python: grpcio-tools (provides grpc_tools.protoc)
+#   * TypeScript: ts-proto (installed in sdks/typescript/node_modules)
 
 set -euo pipefail
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 PROTO_ROOT="$ROOT/proto"
 OUT_ROOT="$ROOT/inference_engine/server/proto_gen"
+TS_OUT_ROOT="$ROOT/sdks/typescript/src/proto_gen"
+TS_PROTO_PLUGIN="$ROOT/sdks/typescript/node_modules/.bin/protoc-gen-ts_proto"
 
 # Clean only generated files (preserve hand-written package __init__.py).
 find "$OUT_ROOT" -type f \( -name '*_pb2.py' -o -name '*_pb2_grpc.py' -o -name '*_pb2.pyi' \) -delete 2>/dev/null || true
@@ -57,4 +66,36 @@ if [ -f "$GRPC_FILE" ]; then
     rm -f "$GRPC_FILE.bak"
 fi
 
-echo "Regenerated stubs into $OUT_ROOT"
+echo "Regenerated Python stubs into $OUT_ROOT"
+
+# -----------------------------------------------------------------------------
+# TypeScript stubs (PR-B5)
+# -----------------------------------------------------------------------------
+
+if [ -x "$TS_PROTO_PLUGIN" ]; then
+    # Clean only generated TS files (preserve hand-written package
+    # entry points — none today, but defensive).
+    find "$TS_OUT_ROOT" -type f -name '*.ts' -delete 2>/dev/null || true
+    mkdir -p "$TS_OUT_ROOT"
+
+    # ts-proto generation flags worth pinning here:
+    #   esModuleInterop=true      tsconfig has it; matching keeps imports clean.
+    #   forceLong=string          uint64 / int64 -> string (JS number can't hold them).
+    #   useExactTypes=false       ts-proto's stricter typing for oneof; we keep
+    #                             the more ergonomic discriminated-union shape.
+    #   outputServices=grpc-js    generate @grpc/grpc-js style client + server.
+    #   useOptionals=messages     proto3 optional + message fields use TS optional.
+    #   stringEnums=false         enums emit as integer constants (matches wire).
+    #   removeEnumPrefix=true     strip the GenerateDone_ prefix from enum members.
+    python3 -m grpc_tools.protoc \
+        --plugin="protoc-gen-ts_proto=$TS_PROTO_PLUGIN" \
+        --proto_path="$PROTO_ROOT" \
+        --ts_proto_out="$TS_OUT_ROOT" \
+        --ts_proto_opt=esModuleInterop=true,forceLong=string,outputServices=grpc-js,useOptionals=messages,stringEnums=false,removeEnumPrefix=true \
+        $(find "$PROTO_ROOT" -name '*.proto')
+
+    echo "Regenerated TypeScript stubs into $TS_OUT_ROOT"
+else
+    echo "WARN: ts-proto plugin not found at $TS_PROTO_PLUGIN; skipping TypeScript stub regen." >&2
+    echo "      Run 'npm install' in sdks/typescript/ first." >&2
+fi

sdks/typescript/.gitignore

@@ -0,0 +1,13 @@
+# TypeScript build output
+dist/
+*.tsbuildinfo
+
+# vitest / coverage
+coverage/
+
+# npm
+node_modules/
+
+# IDE
+.vscode/
+.idea/