@onekeyfe/hd-transport 1.2.0-alpha.3 → 1.2.0-alpha.31

package/__tests__/protocol-v2.test.js

@@ -1,9 +1,18 @@
 const { ProtocolV2 } = require('../src/protocols');
 const { parseConfigure } = require('../src/serialization/protobuf/messages');
-const sessionModule = require('../src/protocols/v2/session');
-
-const { ProtocolV2FrameAssembler, ProtocolV2Session, probeProtocolV2 } = sessionModule;
+const {
+  ProtocolV2FrameAssembler,
+  ProtocolV2LinkError,
+  ProtocolV2SequenceCursor,
+  ProtocolV2Session,
+  hexToBytes,
+  probeProtocolV2,
+} = require('../src/protocols/v2/session');
 const protocolV2 = require('../src/protocols/v2');
+const {
+  PROTOCOL_V2_DEFAULT_RESPONSE_TIMEOUT_MS,
+  PROTOCOL_V2_FRAME_MAX_BYTES,
+} = require('../src/constants');
 
 const protocolV1Messages = parseConfigure({
   nested: {
@@ -55,21 +64,22 @@ const protocolV1Messages = parseConfigure({
 
 const protocolV2Messages = parseConfigure({
   nested: {
-    GetProtoVersion: {
+    ProtocolInfoRequest: {
       fields: {},
     },
-    ProtoVersion: {
+    ProtocolInfo: {
       fields: {
-        major_version: {
+        version: {
           type: 'uint32',
           id: 1,
         },
-        minor_version: {
+        supported_messages: {
           type: 'uint32',
           id: 2,
+          rule: 'repeated',
         },
-        patch_version: {
-          type: 'uint32',
+        protobuf_definition: {
+          type: 'string',
           id: 3,
         },
       },
@@ -90,17 +100,80 @@ const protocolV2Messages = parseConfigure({
         },
       },
     },
-    DevFirmwareUpdate: {
-      fields: {},
+    Failure: {
+      fields: {
+        code: {
+          type: 'uint32',
+          id: 1,
+        },
+        subcode: {
+          type: 'uint32',
+          id: 2,
+        },
+        message: {
+          type: 'string',
+          id: 3,
+        },
+      },
     },
-    DevFirmwareInstallProgress: {
+    DeviceFirmwareTarget: {
       fields: {
         target_id: {
           type: 'uint32',
           id: 1,
         },
-        progress: {
+        path: {
+          type: 'string',
+          id: 2,
+        },
+      },
+    },
+    DeviceFirmwareUpdateRequest: {
+      fields: {
+        targets: {
+          type: 'DeviceFirmwareTarget',
+          id: 1,
+          rule: 'repeated',
+        },
+      },
+    },
+    DeviceFirmwareUpdateRecord: {
+      fields: {
+        target_id: {
           type: 'uint32',
+          id: 1,
+        },
+        status: {
+          type: 'uint32',
+          id: 10,
+        },
+        payload_version: {
+          type: 'uint32',
+          id: 20,
+        },
+        path: {
+          type: 'string',
+          id: 30,
+        },
+      },
+    },
+    DeviceFirmwareUpdateStatus: {
+      fields: {
+        records: {
+          type: 'DeviceFirmwareUpdateRecord',
+          id: 1,
+          rule: 'repeated',
+        },
+      },
+    },
+    DeviceSession: {
+      fields: {
+        session_id: {
+          type: 'bytes',
+          id: 1,
+        },
+        btc_test_address: {
+          type: 'string',
           id: 2,
         },
       },
@@ -130,13 +203,15 @@ const protocolV2Messages = parseConfigure({
     },
     MessageType: {
       values: {
-        MessageType_GetProtoVersion: 60200,
-        MessageType_ProtoVersion: 60201,
+        MessageType_ProtocolInfoRequest: 60200,
+        MessageType_ProtocolInfo: 60201,
         MessageType_Ping: 60206,
         MessageType_Success: 60207,
+        MessageType_Failure: 60208,
         MessageType_FileWrite: 60805,
-        MessageType_DevFirmwareUpdate: 61000,
-        MessageType_DevFirmwareInstallProgress: 61001,
+        MessageType_DeviceFirmwareUpdateRequest: 61000,
+        MessageType_DeviceFirmwareUpdateStatus: 61002,
+        MessageType_DeviceSession: 60607,
         MessageType_PartialNested: 62000,
       },
     },
@@ -150,6 +225,7 @@ const schemas = {
 
 const rewriteSeq = (frame, seq) => {
   const copy = new Uint8Array(frame);
+  copy[4] = 1;
   copy[6] = seq;
   copy[copy.length - 1] = protocolV2.crc8(copy, copy.length - 1);
   return copy;
@@ -157,10 +233,10 @@ const rewriteSeq = (frame, seq) => {
 
 describe('Protocol V2 framing and session', () => {
   test('encodes and decodes Protocol V2 protobuf frames', () => {
-    const frame = ProtocolV2.encodeFrame(schemas, 'ProtoVersion', {
-      major_version: 1,
-      minor_version: 2,
-      patch_version: 3,
+    const frame = ProtocolV2.encodeFrame(schemas, 'ProtocolInfo', {
+      version: 1,
+      supported_messages: [60200, 60201],
+      protobuf_definition: 'proto',
     });
 
     const parsed = protocolV2.decodeFrame(frame);
@@ -168,15 +244,15 @@ describe('Protocol V2 framing and session', () => {
 
     const decoded = ProtocolV2.decodeFrame(schemas, frame);
     expect(decoded).toEqual({
-      type: 'ProtoVersion',
-      messageName: 'ProtoVersion',
+      type: 'ProtocolInfo',
+      messageName: 'ProtocolInfo',
       messageTypeId: 60201,
       pbPayload: parsed.pbPayload,
       seq: parsed.seq,
       message: {
-        major_version: 1,
-        minor_version: 2,
-        patch_version: 3,
+        version: 1,
+        supported_messages: [60200, 60201],
+        protobuf_definition: 'proto',
       },
     });
   });
@@ -201,6 +277,34 @@ describe('Protocol V2 framing and session', () => {
     expect(decoded.message).toEqual({ message: 'ok' });
   });
 
+  test('round-trips a DeviceSession response with a 32-byte session id', () => {
+    const sessionId = '01'.repeat(32);
+    const frame = ProtocolV2.encodeFrame(schemas, 'DeviceSession', {
+      session_id: sessionId,
+      btc_test_address: 'tb1qwallet',
+    });
+
+    const decoded = ProtocolV2.decodeFrame(schemas, frame);
+
+    expect(decoded.type).toBe('DeviceSession');
+    expect(decoded.message).toEqual({
+      session_id: sessionId,
+      btc_test_address: 'tb1qwallet',
+    });
+  });
+
+  test('reports malformed DeviceSession protobuf as a schema-compatible transport error', () => {
+    const malformedPayload = new Uint8Array(32);
+    malformedPayload[0] = 0x0a;
+    malformedPayload[1] = 101;
+    const frame = protocolV2.encodeProtobufFrame(60607, malformedPayload);
+
+    expect(() => ProtocolV2.decodeFrame(schemas, frame)).toThrow(
+      'Protocol V2 protobuf decode failed for "DeviceSession" (60607, 32-byte payload); ' +
+        'the payload is malformed or incompatible with the active SDK schema.'
+    );
+  });
+
   test('decodes missing optional nested messages as null', () => {
     const frame = ProtocolV2.encodeFrame(schemas, 'PartialNested', {
       label: 'only label',
@@ -214,10 +318,9 @@ describe('Protocol V2 framing and session', () => {
   });
 
   test('reassembles split Protocol V2 frames and rejects oversized frames', () => {
-    const frame = ProtocolV2.encodeFrame(schemas, 'ProtoVersion', {
-      major_version: 1,
-      minor_version: 0,
-      patch_version: 0,
+    const frame = ProtocolV2.encodeFrame(schemas, 'ProtocolInfo', {
+      version: 1,
+      supported_messages: [],
     });
     const assembler = new ProtocolV2FrameAssembler();
 
@@ -228,16 +331,35 @@ describe('Protocol V2 framing and session', () => {
     expect(() => assembler.push(oversized)).toThrow('Protocol V2 frame too large');
   });
 
+  test('enforces a transport-specific receive frame boundary', () => {
+    const assembler = new ProtocolV2FrameAssembler(2048);
+    const oversizedHeader = new Uint8Array([0x5a, 0x01, 0x08]);
+
+    expect(() => assembler.push(oversizedHeader)).toThrow('Protocol V2 frame too large: 2049');
+  });
+
+  test('enforces the firmware 4200-byte Protocol V2 frame boundary', () => {
+    const boundaryFrame = ProtocolV2.encodeFrame(schemas, 'Ping', {
+      message: 'x'.repeat(4187),
+    });
+
+    expect(PROTOCOL_V2_FRAME_MAX_BYTES).toBe(4200);
+    expect(boundaryFrame).toHaveLength(PROTOCOL_V2_FRAME_MAX_BYTES);
+    expect(() =>
+      ProtocolV2.encodeFrame(schemas, 'Ping', {
+        message: 'x'.repeat(4188),
+      })
+    ).toThrow('Protocol V2 frame too large: 4201 > 4200');
+  });
+
   test('keeps bytes after the first complete frame for the next read', () => {
-    const first = ProtocolV2.encodeFrame(schemas, 'ProtoVersion', {
-      major_version: 1,
-      minor_version: 0,
-      patch_version: 0,
+    const first = ProtocolV2.encodeFrame(schemas, 'ProtocolInfo', {
+      version: 1,
+      supported_messages: [],
     });
-    const second = ProtocolV2.encodeFrame(schemas, 'ProtoVersion', {
-      major_version: 2,
-      minor_version: 0,
-      patch_version: 0,
+    const second = ProtocolV2.encodeFrame(schemas, 'ProtocolInfo', {
+      version: 2,
+      supported_messages: [],
     });
     const assembler = new ProtocolV2FrameAssembler();
     const combined = new Uint8Array(first.length + second.length);
@@ -250,10 +372,9 @@ describe('Protocol V2 framing and session', () => {
 
   test('session writes one encoded frame and decodes the response frame', async () => {
     const written = [];
-    const response = ProtocolV2.encodeFrame(schemas, 'ProtoVersion', {
-      major_version: 2,
-      minor_version: 0,
-      patch_version: 1,
+    const response = ProtocolV2.encodeFrame(schemas, 'ProtocolInfo', {
+      version: 2,
+      supported_messages: [60206],
     });
     const session = new ProtocolV2Session({
       schemas,
@@ -266,51 +387,251 @@ describe('Protocol V2 framing and session', () => {
         Promise.resolve(rewriteSeq(response, protocolV2.decodeFrame(written[0]).seq)),
     });
 
-    const result = await session.call('GetProtoVersion', {});
+    const result = await session.call('ProtocolInfoRequest', {});
 
     expect(written).toHaveLength(1);
     expect(written[0][4]).toBe(1);
     expect(written[0][5]).toBe(0);
     expect(protocolV2.decodeFrame(written[0]).messageTypeId).toBe(60200);
     expect(result).toEqual({
-      type: 'ProtoVersion',
+      type: 'ProtocolInfo',
+      message: {
+        version: 2,
+        supported_messages: [60206],
+        protobuf_definition: null,
+      },
+    });
+  });
+
+  test('session does not log Protocol V2 TX and RX frames', async () => {
+    const written = [];
+    const logger = { debug: jest.fn() };
+    const response = ProtocolV2.encodeFrame(schemas, 'ProtocolInfo', {
+      version: 2,
+      supported_messages: [60206],
+      protobuf_definition: 'sensitive-schema',
+    });
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      logger,
+      logPrefix: 'ProtocolV2 Test',
+      writeFrame: frame => {
+        written.push(frame);
+        return Promise.resolve();
+      },
+      readFrame: () =>
+        Promise.resolve(rewriteSeq(response, protocolV2.decodeFrame(written[0]).seq)),
+    });
+
+    await session.call('ProtocolInfoRequest', {});
+
+    expect(logger.debug).not.toHaveBeenCalled();
+  });
+
+  test('session does not log RX frame metadata when protobuf payload decoding fails', async () => {
+    const logger = { debug: jest.fn() };
+    const response = protocolV2.encodeProtobufFrame(
+      60208,
+      hexToBytes('0801121648616e646c6572206e6f742072656769737465726564')
+    );
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      logger,
+      logPrefix: 'ProtocolV2 Test',
+      writeFrame: () => Promise.resolve(),
+      readFrame: () => Promise.resolve(rewriteSeq(response, 1)),
+    });
+
+    await expect(session.call('Ping', { message: 'hello' })).rejects.toThrow();
+
+    expect(logger.debug).not.toHaveBeenCalled();
+  });
+
+  test('session skips Proto Link ACK frames before decoding the protobuf response', async () => {
+    const ack = new Uint8Array(8);
+    ack[0] = 0x5a;
+    ack[1] = 8;
+    ack[2] = 0;
+    ack[4] = 1;
+    ack[5] = 1;
+    ack[6] = 1;
+    ack[3] = protocolV2.crc8(ack, 3);
+    ack[7] = protocolV2.crc8(ack, 7);
+
+    const response = ProtocolV2.encodeFrame(schemas, 'Success', {
+      message: 'ok',
+    });
+    const readFrame = jest
+      .fn()
+      .mockResolvedValueOnce(ack)
+      .mockResolvedValueOnce(rewriteSeq(response, 1));
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      writeFrame: () => Promise.resolve(),
+      readFrame,
+    });
+
+    await expect(session.call('Ping', { message: 'hello' })).resolves.toEqual({
+      type: 'Success',
       message: {
-        major_version: 2,
-        minor_version: 0,
-        patch_version: 1,
+        message: 'ok',
       },
     });
+    expect(readFrame).toHaveBeenCalledTimes(2);
   });
 
-  test('session starts response timeout after the frame is written', async () => {
+  test('session accepts a terminal response before an ACK', async () => {
     const response = ProtocolV2.encodeFrame(schemas, 'Success', {
       message: 'ok',
     });
     const session = new ProtocolV2Session({
       schemas,
       router: 1,
-      writeFrame: () =>
-        new Promise(resolve => {
-          setTimeout(resolve, 30);
-        }),
-      readFrame: () => Promise.resolve(response),
+      writeFrame: () => Promise.resolve(),
+      readFrame: () => Promise.resolve(rewriteSeq(response, 1)),
     });
 
     await expect(
-      session.call('Ping', { message: 'hello' }, { timeoutMs: 10, expectedTypes: ['Success'] })
+      session.call('Ping', { message: 'hello' }, { expectedTypes: ['Success'] })
+    ).resolves.toEqual({
+      type: 'Success',
+      message: {
+        message: 'ok',
+      },
+    });
+  });
+
+  test('session uses the unified response timeout before the first ACK', async () => {
+    const response = ProtocolV2.encodeFrame(schemas, 'Success', {
+      message: 'ok',
+    });
+    const readFrame = jest.fn(() => Promise.resolve(rewriteSeq(response, 1)));
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      writeFrame: () => Promise.resolve(),
+      readFrame,
+    });
+
+    await expect(
+      session.call(
+        'Ping',
+        { message: 'hello' },
+        {
+          timeoutMs: 12_345,
+          expectedTypes: ['Success'],
+        }
+      )
     ).resolves.toEqual({
       type: 'Success',
       message: {
         message: 'ok',
       },
     });
+    expect(readFrame).toHaveBeenCalledWith(expect.objectContaining({ timeoutMs: 12_345 }));
+  });
+
+  test('session rejects an ACK that belongs to another request sequence', async () => {
+    const ack = new Uint8Array(8);
+    ack[0] = 0x5a;
+    ack[1] = 8;
+    ack[4] = 1;
+    ack[5] = 1;
+    ack[6] = 2;
+    ack[3] = protocolV2.crc8(ack, 3);
+    ack[7] = protocolV2.crc8(ack, 7);
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      writeFrame: () => Promise.resolve(),
+      readFrame: () => Promise.resolve(ack),
+    });
+
+    await expect(session.call('Ping', { message: 'hello' })).rejects.toEqual(
+      expect.objectContaining({
+        name: 'ProtocolV2LinkError',
+        code: 'ack-sequence',
+        message: 'Protocol V2 ACK sequence mismatch: expected 1, got 2',
+      })
+    );
+  });
+
+  test('session rejects a response from another routing channel', async () => {
+    const response = ProtocolV2.encodeFrame(schemas, 'Success', { message: 'wrong route' });
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      writeFrame: () => Promise.resolve(),
+      readFrame: () => Promise.resolve(response),
+    });
+
+    await expect(session.call('Ping', { message: 'hello' })).rejects.toBeInstanceOf(
+      ProtocolV2LinkError
+    );
   });
 
-  test('session accepts response frames with a device-owned seq', async () => {
-    const response = ProtocolV2.encodeFrame(schemas, 'ProtoVersion', {
-      major_version: 2,
-      minor_version: 0,
-      patch_version: 1,
+  test('session rejects BLE frames above its configured frame limit before writing', async () => {
+    const writeFrame = jest.fn().mockResolvedValue(undefined);
+    const response = ProtocolV2.encodeFrame(schemas, 'Success', {
+      message: 'ok',
+    });
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      maxFrameBytes: 2048,
+      writeFrame,
+      readFrame: () => Promise.resolve(rewriteSeq(response, 1)),
+    });
+
+    await expect(session.call('Ping', { message: 'x'.repeat(2048) })).rejects.toThrow(
+      'Protocol V2 frame too large for transport: 2061 > 2048'
+    );
+    expect(writeFrame).not.toHaveBeenCalled();
+  });
+
+  test('session watchdog covers a write that never settles', async () => {
+    const readFrame = jest.fn();
+    let writeSignal;
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      writeFrame: (_frame, context) => {
+        writeSignal = context.signal;
+        return new Promise(() => {});
+      },
+      readFrame,
+    });
+
+    await expect(
+      session.call('Ping', { message: 'hello' }, { timeoutMs: 10, expectedTypes: ['Success'] })
+    ).rejects.toThrow('Protocol V2 response timeout after 10ms for Ping');
+    expect(writeSignal.aborted).toBe(true);
+    expect(readFrame).not.toHaveBeenCalled();
+  });
+
+  test('session watchdog covers prepareCall before writing', async () => {
+    const writeFrame = jest.fn();
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      prepareCall: () => new Promise(() => {}),
+      writeFrame,
+      readFrame: jest.fn(),
+    });
+
+    await expect(session.call('Ping', { message: 'hello' }, { timeoutMs: 10 })).rejects.toThrow(
+      'Protocol V2 response timeout after 10ms for Ping'
+    );
+    expect(writeFrame).not.toHaveBeenCalled();
+  });
+
+  test('session logs a device-owned response seq without rejecting the frame', async () => {
+    const response = ProtocolV2.encodeFrame(schemas, 'ProtocolInfo', {
+      version: 2,
+      supported_messages: [],
     });
     const logger = {
       debug: jest.fn(),
@@ -323,18 +644,53 @@ describe('Protocol V2 framing and session', () => {
       logger,
     });
 
-    await expect(session.call('GetProtoVersion', {})).resolves.toEqual({
-      type: 'ProtoVersion',
+    await expect(session.call('ProtocolInfoRequest', {})).resolves.toEqual({
+      type: 'ProtocolInfo',
       message: {
-        major_version: 2,
-        minor_version: 0,
-        patch_version: 1,
+        version: 2,
+        supported_messages: [],
+        protobuf_definition: null,
       },
     });
-    expect(logger.debug).toHaveBeenCalledWith(expect.stringContaining('seq differs'));
+    expect(logger.debug).not.toHaveBeenCalled();
+  });
+
+  test('session accepts gaps in the firmware-global response sequence', async () => {
+    const response = ProtocolV2.encodeFrame(schemas, 'Success', { message: 'ok' });
+    const readFrame = jest
+      .fn()
+      .mockResolvedValueOnce(rewriteSeq(response, 1))
+      .mockResolvedValueOnce(rewriteSeq(response, 4));
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      writeFrame: () => Promise.resolve(),
+      readFrame,
+    });
+
+    await session.call('Ping', { message: 'first' });
+    await expect(session.call('Ping', { message: 'second' })).resolves.toMatchObject({
+      type: 'Success',
+    });
+  });
+
+  test('session rejects a duplicate device response sequence', async () => {
+    const response = ProtocolV2.encodeFrame(schemas, 'Success', { message: 'ok' });
+    const readFrame = jest.fn(() => Promise.resolve(rewriteSeq(response, 7)));
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      writeFrame: () => Promise.resolve(),
+      readFrame,
+    });
+
+    await session.call('Ping', { message: 'first' });
+    await expect(session.call('Ping', { message: 'second' })).rejects.toThrow(
+      'Protocol V2 duplicate response sequence: 7'
+    );
   });
 
-  test('session logs decoded transmit and receive payloads', async () => {
+  test('session does not log transmit or receive payload details', async () => {
     const response = ProtocolV2.encodeFrame(schemas, 'Success', {
       message: 'accepted',
     });
@@ -345,7 +701,7 @@ describe('Protocol V2 framing and session', () => {
       schemas,
       router: 1,
       writeFrame: () => Promise.resolve(),
-      readFrame: () => Promise.resolve(response),
+      readFrame: () => Promise.resolve(rewriteSeq(response, 1)),
       logger,
       logPrefix: 'ProtocolV2 Test',
     });
@@ -357,30 +713,7 @@ describe('Protocol V2 framing and session', () => {
       },
     });
 
-    expect(logger.debug).toHaveBeenCalledWith('[ProtocolV2 Test] TX payload name=Ping', {
-      message: 'hello',
-    });
-    expect(logger.debug).toHaveBeenCalledWith(
-      '[ProtocolV2 Test] encode raw frame',
-      expect.objectContaining({
-        context: 'tx:Ping',
-        messageTypeId: 60206,
-        router: 1,
-      })
-    );
-    expect(logger.debug).toHaveBeenCalledWith(
-      '[ProtocolV2 Test] decode raw frame',
-      expect.objectContaining({
-        context: 'rx:Ping',
-        messageTypeId: 60207,
-      })
-    );
-    expect(logger.debug).toHaveBeenCalledWith(
-      '[ProtocolV2 Test] RX payload type=Success messageTypeId=60207',
-      {
-        message: 'accepted',
-      }
-    );
+    expect(logger.debug).not.toHaveBeenCalled();
   });
 
   test('session suppresses debug logs for file transfer calls', async () => {
@@ -394,7 +727,7 @@ describe('Protocol V2 framing and session', () => {
       schemas,
       router: 1,
       writeFrame: () => Promise.resolve(),
-      readFrame: () => Promise.resolve(response),
+      readFrame: () => Promise.resolve(rewriteSeq(response, 1)),
       logger,
     });
 
@@ -412,15 +745,17 @@ describe('Protocol V2 framing and session', () => {
     const stale = ProtocolV2.encodeFrame(schemas, 'Success', {
       message: 'stale response',
     });
-    const response = ProtocolV2.encodeFrame(schemas, 'ProtoVersion', {
-      major_version: 2,
-      minor_version: 0,
-      patch_version: 1,
+    const response = ProtocolV2.encodeFrame(schemas, 'ProtocolInfo', {
+      version: 2,
+      supported_messages: [],
     });
     const logger = {
       debug: jest.fn(),
     };
-    const readFrame = jest.fn().mockResolvedValueOnce(stale).mockResolvedValueOnce(response);
+    const readFrame = jest
+      .fn()
+      .mockResolvedValueOnce(rewriteSeq(stale, 1))
+      .mockResolvedValueOnce(rewriteSeq(response, 2));
     const session = new ProtocolV2Session({
       schemas,
       router: 1,
@@ -430,13 +765,13 @@ describe('Protocol V2 framing and session', () => {
     });
 
     await expect(
-      session.call('GetProtoVersion', {}, { expectedTypes: ['ProtoVersion'] })
+      session.call('ProtocolInfoRequest', {}, { expectedTypes: ['ProtocolInfo'] })
     ).resolves.toEqual({
-      type: 'ProtoVersion',
+      type: 'ProtocolInfo',
       message: {
-        major_version: 2,
-        minor_version: 0,
-        patch_version: 1,
+        version: 2,
+        supported_messages: [],
+        protobuf_definition: null,
       },
     });
 
@@ -446,9 +781,8 @@ describe('Protocol V2 framing and session', () => {
 
   test('session consumes intermediate response frames before returning the final response', async () => {
     const written = [];
-    const progress = ProtocolV2.encodeFrame(schemas, 'DevFirmwareInstallProgress', {
-      target_id: 0,
-      progress: 42,
+    const progress = ProtocolV2.encodeFrame(schemas, 'DeviceFirmwareUpdateStatus', {
+      records: [{ target_id: 4, status: 1 }],
     });
     const success = ProtocolV2.encodeFrame(schemas, 'Success', {
       message: 'ok',
@@ -458,7 +792,9 @@ describe('Protocol V2 framing and session', () => {
       const [writtenFrame] = written;
       const { seq } = protocolV2.decodeFrame(writtenFrame);
       return Promise.resolve(
-        readFrame.mock.calls.length === 1 ? rewriteSeq(progress, seq) : rewriteSeq(success, seq)
+        readFrame.mock.calls.length === 1
+          ? rewriteSeq(progress, seq)
+          : rewriteSeq(success, protocolV2.nextProtoSeq(seq))
       );
     });
     const session = new ProtocolV2Session({
@@ -472,20 +808,19 @@ describe('Protocol V2 framing and session', () => {
     });
 
     const result = await session.call(
-      'DevFirmwareUpdate',
-      {},
+      'DeviceFirmwareUpdateRequest',
+      { targets: [{ target_id: 4, path: 'vol1:firmware.bin' }] },
       {
-        intermediateTypes: ['DevFirmwareInstallProgress'],
+        intermediateTypes: ['DeviceFirmwareUpdateStatus'],
         onIntermediateResponse,
       }
     );
 
     expect(readFrame).toHaveBeenCalledTimes(2);
     expect(onIntermediateResponse).toHaveBeenCalledWith({
-      type: 'DevFirmwareInstallProgress',
+      type: 'DeviceFirmwareUpdateStatus',
       message: {
-        target_id: 0,
-        progress: 42,
+        records: [{ target_id: 4, status: 1, payload_version: null, path: null }],
       },
     });
     expect(result).toEqual({
@@ -575,7 +910,7 @@ describe('Protocol V2 framing and session', () => {
     });
 
     await expect(
-      session.call('GetProtoVersion', {}, { timeoutMs: 10, expectedTypes: ['ProtoVersion'] })
+      session.call('ProtocolInfoRequest', {}, { timeoutMs: 10, expectedTypes: ['ProtocolInfo'] })
     ).rejects.toThrow('Protocol V2 response timeout');
 
     // Without cancellation the loop would skip this unexpected Success frame
@@ -636,7 +971,7 @@ describe('Protocol V2 framing and session', () => {
         }
         return Promise.resolve();
       },
-      readFrame: () => Promise.resolve(response),
+      readFrame: () => Promise.resolve(rewriteSeq(response, 1)),
     });
 
     await expect(session.call('Ping', { message: '1' })).rejects.toThrow('transport write failed');
@@ -674,6 +1009,109 @@ describe('Protocol V2 framing and session', () => {
     expect(written.map(frame => frame[6])).toEqual([1, 2, 1]);
   });
 
+  test('session reuses an injected sequence cursor across recreated sessions', async () => {
+    const written = [];
+    const cursor = new ProtocolV2SequenceCursor();
+    const makeSession = () =>
+      new ProtocolV2Session({
+        schemas,
+        router: 1,
+        sequenceCursor: cursor,
+        writeFrame: frame => {
+          written.push(frame);
+          return Promise.resolve();
+        },
+        readFrame: () => {
+          const [frame] = written.slice(-1);
+          const { seq } = protocolV2.decodeFrame(frame);
+          return Promise.resolve(
+            rewriteSeq(ProtocolV2.encodeFrame(schemas, 'Success', { message: 'ok' }), seq)
+          );
+        },
+      });
+
+    await makeSession().call('Ping', { message: '1' });
+    await makeSession().call('Ping', { message: '2' });
+
+    expect(written.map(frame => frame[6])).toEqual([1, 2]);
+  });
+
+  test('session passes per-call context to frame IO callbacks', async () => {
+    const writeContexts = [];
+    const readContexts = [];
+    const response = ProtocolV2.encodeFrame(schemas, 'Success', { message: 'ok' });
+    let responseSeq = 0;
+    const session = new ProtocolV2Session({
+      schemas,
+      router: 1,
+      generation: 7,
+      writeFrame: (_frame, context) => {
+        writeContexts.push(context);
+        return Promise.resolve();
+      },
+      readFrame: context => {
+        readContexts.push(context);
+        responseSeq = protocolV2.nextProtoSeq(responseSeq);
+        return Promise.resolve(rewriteSeq(response, responseSeq));
+      },
+    });
+
+    await session.call('Ping', { message: 'ping' }, { timeoutMs: 123 });
+    await session.call('FileWrite', {}, { timeoutMs: 456 });
+    await session.call('Ping', { message: 'default-timeout' });
+
+    const normalizeContext = ({ signal, ...context }) => ({
+      ...context,
+      signalAborted: signal.aborted,
+    });
+    expect(writeContexts.map(normalizeContext)).toEqual([
+      {
+        messageName: 'Ping',
+        timeoutMs: 123,
+        highVolume: false,
+        generation: 7,
+        signalAborted: false,
+      },
+      {
+        messageName: 'FileWrite',
+        timeoutMs: 456,
+        highVolume: true,
+        generation: 7,
+        signalAborted: false,
+      },
+      {
+        messageName: 'Ping',
+        timeoutMs: PROTOCOL_V2_DEFAULT_RESPONSE_TIMEOUT_MS,
+        highVolume: false,
+        generation: 7,
+        signalAborted: false,
+      },
+    ]);
+    expect(readContexts.map(normalizeContext)).toEqual([
+      {
+        messageName: 'Ping',
+        timeoutMs: 123,
+        highVolume: false,
+        generation: 7,
+        signalAborted: false,
+      },
+      {
+        messageName: 'FileWrite',
+        timeoutMs: 456,
+        highVolume: true,
+        generation: 7,
+        signalAborted: false,
+      },
+      {
+        messageName: 'Ping',
+        timeoutMs: PROTOCOL_V2_DEFAULT_RESPONSE_TIMEOUT_MS,
+        highVolume: false,
+        generation: 7,
+        signalAborted: false,
+      },
+    ]);
+  });
+
   test('assembler throws and resets on frames with an impossible length field', () => {
     const assembler = new ProtocolV2FrameAssembler();
     // expectedLen = 0 < 8-byte minimum: without the guard this poisons the
@@ -700,10 +1138,9 @@ describe('Protocol V2 framing and session', () => {
   });
 
   test('assembler drain returns every buffered complete frame', () => {
-    const first = ProtocolV2.encodeFrame(schemas, 'ProtoVersion', {
-      major_version: 1,
-      minor_version: 0,
-      patch_version: 0,
+    const first = ProtocolV2.encodeFrame(schemas, 'ProtocolInfo', {
+      version: 1,
+      supported_messages: [],
     });
     const second = ProtocolV2.encodeFrame(schemas, 'Success', { message: 'ok' });
     const third = ProtocolV2.encodeFrame(schemas, 'Success', { message: 'last' });
@@ -754,7 +1191,6 @@ describe('Protocol V2 framing and session', () => {
   });
 
   test('hexToBytes converts valid hex and rejects malformed input', () => {
-    const { hexToBytes } = sessionModule;
     expect(hexToBytes('5a0102')).toEqual(new Uint8Array([0x5a, 0x01, 0x02]));
     expect(hexToBytes('')).toEqual(new Uint8Array(0));
     expect(() => hexToBytes('abc')).toThrow('Invalid hex string: odd length');