regenerate-grpc-stubs

name	regenerate-grpc-stubs
description	Regenerate Python + TypeScript gRPC stubs after editing proto files. Use when proto/*.proto changes, imports from bindu.grpc.generated fail, CI reports generated-code drift, or HandleMessages calls fail with proto mismatch.

Regenerate gRPC Stubs

Overview

Bindu's cross-language agents share one proto file: proto/agent_handler.proto. Two generated stub trees must stay in sync with it:

• bindu/grpc/generated/ — Python stubs for the core
• sdks/typescript/src/generated/ — TypeScript stubs for the SDK

Both languages must be regenerated together and committed in the same PR as the proto change. A proto change without matching stubs leaves main broken for anyone who pulls.

Inputs

• <proto_file>: usually proto/agent_handler.proto, or whatever file was modified under proto/.

Safety

• Do not edit files under bindu/grpc/generated/ or sdks/typescript/src/generated/. Changes will be overwritten by the next regeneration.
• Do not split the proto change and the stub regeneration across PRs. They must land atomically.
• If the proto change is breaking (removed fields, renamed RPCs, changed message types), flag it in the PR description — existing clients will break.

Execution Contract

1. Confirm the proto change is intentional and minimal.
2. Regenerate both Python and TypeScript stubs via the project's script.
3. Verify both stub trees compile.
4. Run the gRPC integration tests.
5. Commit proto + both generated trees together.

Steps

1. Review the proto diff

git diff proto/agent_handler.proto

For each change, classify:

• Additive (new RPC, new field with a new tag) — safe, backward-compatible.
• Breaking (removed field, renumbered tag, renamed RPC) — needs a coordination note and a version bump plan.

2. Regenerate all stubs

bash scripts/generate_protos.sh all

The script handles both languages and fixes Python import paths. It is the single source of truth — do not run grpc_tools.protoc or grpc_tools_node_protoc by hand.

3. Verify Python stubs

uv run python -c "from bindu.grpc.generated import agent_handler_pb2, agent_handler_pb2_grpc"
uv run mypy bindu/grpc/

4. Verify TypeScript stubs

cd sdks/typescript && npm run build

5. Run gRPC integration tests

uv run pytest tests/integration/grpc/ -v

6. Update docs if the API surface changed

Touch docs/grpc/api-reference.md for added/removed/modified RPCs. Skip if purely additive internal fields.

7. Commit atomically

One commit containing: the proto change, both generated trees, any doc updates. Commit message:

refactor(grpc): <describe the proto change>

- proto: <summary>
- regenerated Python + TypeScript stubs

Never do

• Never edit bindu/grpc/generated/ or sdks/typescript/src/generated/ directly. The diff will be lost the next time anyone regenerates.
• Never regenerate only one language. Cross-language drift is the #1 source of confusing gRPC bugs.
• Never renumber or reuse proto field tags. That's the one thing protobuf cannot recover from.