Debug gRPC Connection

Overview

The Bindu core (Python) runs a gRPC server on port 3774 that SDKs connect to via RegisterAgent and Heartbeat. After registration, the core calls back into the SDK's own gRPC server (ephemeral port) via HandleMessages. Most connection bugs are in that handshake.

See docs/grpc/overview.md for the full message flow and docs/grpc/limitations.md for known unimplemented behaviors.

Inputs

• Which end is reporting the failure: core logs vs. SDK logs.
• The exact error message and/or symptom.
• Recent commits touching proto/, bindu/grpc/, or sdks/typescript/src/.

Safety

• Do not modify files under bindu/grpc/generated/ or sdks/typescript/src/generated/ to "make the error go away". Proto drift is the underlying problem, fix it with the regenerate-grpc-stubs skill.
• Do not bypass the heartbeat mechanism. The core relies on heartbeats to clean up dead-agent registrations.
• Do not assume the SDK is at fault before inspecting core logs, the core is the ground truth for registration state.

Execution Contract

1. Confirm both processes are alive and bound to expected ports.
2. Inspect core logs for the registration handshake.
3. Probe the core directly with grpcurl.
4. Check for proto drift.
5. Verify SDK heartbeat timing.
6. Consult limitations doc before filing a bug.

Steps

1. Confirm both processes and ports

lsof -ti:3773 -ti:3774
ps aux | grep -E '(bindu|node.*agent|python.*bindu)' | grep -v grep

• 3773 missing → HTTP/A2A server never started. Check for port clash (lsof -i:3773).
• 3774 missing → core started without --grpc. Restart with bindu serve --grpc.
• SDK process missing → it crashed. Check its own logs for a stacktrace.

2. Inspect core logs

Filter for the [bindu-core] prefix. Meaningful signals: