feat: add gateway protocol attachment support

Extends the gateway wire protocol with GatewayAttachment type and
attachment event. agent.send handler now accepts optional attachments
parameter and converts them for the agent pipeline. Includes 5 new
tests for protocol and handler layers.

src/gateway/handlers/handlers.test.ts

@@ -206,13 +206,51 @@ describe('agent handlers', () => {
 
     await handlers['agent.send'](req, send);
 
-    expect(mockAgent.process).toHaveBeenCalledWith('hello');
+    expect(mockAgent.process).toHaveBeenCalledWith('hello', undefined);
     expect(sent).toHaveLength(1);
     const doneEvent = sent[0] as GatewayEvent;
     expect(doneEvent.event).toBe('done');
     expect((doneEvent.data as any).content).toBe('response text');
   });
 
+  it('agent.send passes attachments to agent.process', async () => {
+    const attachments = [
+      { mimeType: 'image/png', data: 'iVBOR...', filename: 'screenshot.png' },
+      { mimeType: 'application/pdf', url: 'https://example.com/doc.pdf' },
+    ];
+    const req: GatewayRequest = {
+      id: 10,
+      method: 'agent.send',
+      params: { message: 'describe this', connectionId: 'conn-1', attachments },
+    };
+    const sent: OutboundMessage[] = [];
+    const send = vi.fn((msg: OutboundMessage) => sent.push(msg));
+
+    await handlers['agent.send'](req, send);
+
+    expect(mockAgent.process).toHaveBeenCalledWith('describe this', [
+      { mimeType: 'image/png', data: 'iVBOR...', url: undefined, filename: 'screenshot.png' },
+      { mimeType: 'application/pdf', data: undefined, url: 'https://example.com/doc.pdf', filename: undefined },
+    ]);
+    const doneEvent = sent[0] as GatewayEvent;
+    expect(doneEvent.event).toBe('done');
+  });
+
+  it('agent.send works with empty attachments array', async () => {
+    const req: GatewayRequest = {
+      id: 11,
+      method: 'agent.send',
+      params: { message: 'hi', connectionId: 'conn-1', attachments: [] },
+    };
+    const sent: OutboundMessage[] = [];
+    const send = vi.fn((msg: OutboundMessage) => sent.push(msg));
+
+    await handlers['agent.send'](req, send);
+
+    expect(mockAgent.process).toHaveBeenCalledWith('hi', []);
+    expect(sent).toHaveLength(1);
+  });
+
   it('agent.send requires message', async () => {
     const req: GatewayRequest = { id: 2, method: 'agent.send', params: { connectionId: 'conn-1' } };
     const send = vi.fn();