deepdebug-local-agent 1.3.0 → 1.5.0

package/tools/interop/LaV2NodeContentInteropTest.java

@@ -0,0 +1,248 @@
+package io.visionhammer.gateway.cloud.infrastructure.byoc;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaProtocolV2Properties;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2Chunk;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2InboundListener;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2Metrics;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2Session;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2SessionStore;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2TestKit;
+import io.visionhammer.gateway.governance.application.DataPlanePolicy;
+import io.visionhammer.gateway.identity.application.AgentAuthorizationEntity;
+import io.visionhammer.gateway.identity.application.AgentAuthorizationStore;
+import io.visionhammer.gateway.shared.localagent.AgentRequestSigner;
+import io.visionhammer.gateway.workspace.application.WorkspaceRepository;
+import org.junit.jupiter.api.Test;
+import org.springframework.http.server.reactive.HttpHandler;
+import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
+import org.springframework.web.reactive.socket.server.WebSocketService;
+import org.springframework.web.reactive.socket.server.support.HandshakeWebSocketService;
+import org.springframework.web.reactive.socket.server.upgrade.ReactorNettyRequestUpgradeStrategy;
+import org.springframework.web.server.adapter.WebHttpHandlerBuilder;
+import reactor.core.publisher.Mono;
+import reactor.core.scheduler.Schedulers;
+import reactor.netty.DisposableServer;
+import reactor.netty.http.server.HttpServer;
+
+import java.io.BufferedReader;
+import java.io.InputStreamReader;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.time.Clock;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HexFormat;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.BlockingQueue;
+import java.util.concurrent.LinkedBlockingQueue;
+import java.util.concurrent.TimeUnit;
+
+import static io.visionhammer.gateway.cloud.application.byoc.v2.LaV2TestKit.OM;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assumptions.assumeTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * F3-07 interoperability: the REAL Node Local Agent content handlers (opaque ids, path guard, DLP enforce, git diff,
+ * chunking) against the REAL gateway {@link LaV2Session} behind a real Reactor Netty WebSocket on loopback, real
+ * system clock, real Ed25519 signer. Run from the gateway checkout (JDK 21):
+ *
+ *   LA_REPO=/path/to/deepdebug-local-agent mvn -o test -Dtest=LaV2NodeContentInteropTest
+ *
+ * Skipped when LA_REPO is not set. Not proven here: Cloud Run / LB / TLS, Memorystore, two gateway instances, the HTTP
+ * relay endpoint (F3-06) in front of this session.
+ */
+class LaV2NodeContentInteropTest {
+
+    private static final String TENANT = LaV2TestKit.TENANT;
+    private static final String AGENT = LaV2TestKit.AGENT;
+
+    private static Map<String, Object> request(String kind, String ref) {
+        return Map.of("kind", kind, "ref", ref, "actor", Map.of("userId", "usr-42", "role", "member"));
+    }
+
+    @Test
+    void realNodeContentHandlersAgainstTheRealLaV2Session() throws Exception {
+        String laRepo = System.getenv("LA_REPO");
+        assumeTrue(laRepo != null && !laRepo.isBlank(), "LA_REPO not set");
+
+        Clock clock = Clock.systemUTC();
+        LaProtocolV2Properties props = new LaProtocolV2Properties();
+        props.setEnabled(true);
+        List<String> rejected = Collections.synchronizedList(new ArrayList<>());
+        LaV2Metrics metrics = new LaV2Metrics() {
+            @Override public void rejected(String code) { rejected.add(code); }
+        };
+        LaV2InboundListener listener = (t, a, type, rid, payload) -> { };
+        AgentRequestSigner signer = new AgentRequestSigner(LaV2TestKit.PEM, "k1", clock);
+        LaV2Session.Env env = new LaV2Session.Env(LaV2TestKit.CONTRACT, props, signer, OM, clock, metrics, Schedulers.parallel(), List.of(listener));
+
+        AgentAuthorizationStore store = mock(AgentAuthorizationStore.class);
+        WorkspaceRepository workspaces = mock(WorkspaceRepository.class);
+        DataPlanePolicy policy = mock(DataPlanePolicy.class);
+        when(workspaces.findDefaultByTenantId(anyString())).thenReturn(Mono.empty());
+        when(store.save(any())).thenAnswer(i -> Mono.just(i.getArgument(0)));
+        when(store.touchLastSeen(any())).thenReturn(Mono.just(1));
+        when(policy.requiresEnforcedSigning(anyString())).thenReturn(Mono.just(true));
+        AgentAuthorizationEntity auth = new AgentAuthorizationEntity();
+        auth.setId(UUID.fromString(AGENT));
+        auth.setTenantId(UUID.fromString(TENANT));
+        auth.setAuthorizationToken("tok");
+        when(store.findByAuthorizationToken("tok")).thenReturn(Mono.just(auth));
+        AgentWebSocketHandler handler = new AgentWebSocketHandler(OM, workspaces, store, signer, null, null, null,
+                new LaV2SessionStore(env), props, policy);
+
+        WebSocketService wsService = new HandshakeWebSocketService(new ReactorNettyRequestUpgradeStrategy());
+        HttpHandler http = WebHttpHandlerBuilder.webHandler(exchange -> wsService.handleRequest(exchange, handler)).build();
+        DisposableServer server = HttpServer.create().host("127.0.0.1").port(0).handle(new ReactorHttpHandlerAdapter(http)).bindNow();
+
+        ProcessBuilder pb = new ProcessBuilder("node", laRepo + "/tools/interop/la-interop-content-client.mjs");
+        pb.environment().putAll(Map.of(
+                "GW_URL", "ws://127.0.0.1:" + server.port() + "/api/v1/agent/ws", "TOKEN", "tok", "TENANT", TENANT, "AGENT", AGENT,
+                "KEY_ID", "k1", "PUBLIC_KEY", LaV2TestKit.PUB, "MODE", "enforce", "LOCAL_AGENT_DLP_MODE", "enforce"));
+        pb.redirectErrorStream(true);
+        Process proc = pb.start();
+        BlockingQueue<JsonNode> events = new LinkedBlockingQueue<>();
+        List<String> transcript = Collections.synchronizedList(new ArrayList<>());
+        Thread reader = new Thread(() -> {
+            try (BufferedReader r = new BufferedReader(new InputStreamReader(proc.getInputStream(), StandardCharsets.UTF_8))) {
+                String line;
+                while ((line = r.readLine()) != null) {
+                    transcript.add(line);
+                    try {
+                        events.add(OM.readTree(line));
+                    } catch (Exception ignored) {
+                        // node warnings
+                    }
+                }
+            } catch (Exception ignored) {
+                // process ended
+            }
+        });
+        reader.setDaemon(true);
+        reader.start();
+        java.io.Writer stdin = new java.io.OutputStreamWriter(proc.getOutputStream(), StandardCharsets.UTF_8);
+
+        try {
+            JsonNode refsEvt = await(events, "refs", 20);
+            await(events, "ready", 15);
+            assertThat(handler.isAgentConnected(TENANT)).isTrue();
+            JsonNode refs = refsEvt.path("refs");
+            String ghp = refsEvt.path("ghp").asText();
+            assertThat(refs.path("envFile").isNull()).as("no id is minted for .env").isTrue();
+
+            // 1. a file with a token: served, the token masked (DLP enforce), the rest intact
+            List<LaV2Chunk> app = content("file", refs.path("app").asText(), handler);
+            assertThat(app.get(0).status()).isEqualTo("ok");
+            String appText = new String(concat(app), StandardCharsets.UTF_8);
+            assertThat(appText).contains("first line").contains("[REDACTED:github_token]").contains("last line").doesNotContain(ghp);
+
+            // 2. 1 MiB = 32 chunks, byte for byte (no secrets in it)
+            List<LaV2Chunk> big = content("file", refs.path("big").asText(), handler);
+            assertThat(big).hasSize(32);
+            assertThat(big.get(31).last()).isTrue();
+            assertThat(HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(concat(big)))).isEqualTo(refsEvt.path("bigSha256").asText());
+            assertThat(concat(big)).hasSize(refsEvt.path("bigBytes").asInt());
+
+            // 3. a token straddling the 32 KiB chunk boundary of the ORIGINAL file never appears, whole or in part
+            List<LaV2Chunk> mid = content("file", refs.path("mid").asText(), handler);
+            assertThat(mid.get(0).status()).isEqualTo("ok");
+            assertThat(mid.size()).isGreaterThanOrEqualTo(2);
+            for (LaV2Chunk c : mid) {
+                assertThat(new String(c.data(), StandardCharsets.UTF_8)).doesNotContain(ghp.substring(0, 12));
+            }
+            assertThat(new String(concat(mid), StandardCharsets.UTF_8)).contains("[REDACTED:github_token]");
+
+            // 4. an id handed out for an innocent file, later swapped for a link to a file outside the workspace: forbidden, no data
+            List<LaV2Chunk> swapped = content("file", refs.path("swapped").asText(), handler);
+            assertThat(swapped).hasSize(1);
+            assertThat(swapped.get(0).status()).isEqualTo("forbidden");
+            assertThat(swapped.get(0).data()).isEmpty();
+
+            // 5. paths are never ids: traversal, absolute, plain relative -> not_found; nothing else comes back
+            for (String ref : List.of("../../etc/passwd", "/etc/passwd", "src/app.txt", "..%2f..%2fetc%2fpasswd", "cr1_AAAAAAAAAAAAAAAAAAAAAA")) {
+                List<LaV2Chunk> r = content("file", ref, handler);
+                assertThat(r).hasSize(1);
+                assertThat(r.get(0).status()).as(ref).isEqualTo("not_found");
+                assertThat(r.get(0).data()).isEmpty();
+            }
+
+            // 6. a binary file cannot be inspected by the DLP: withheld in enforce
+            assertThat(content("file", refs.path("bin").asText(), handler).get(0).status()).isEqualTo("forbidden");
+
+            // 7. kinds the agent does not serve yet: error + protocol_unsupported (a code of the contract)
+            List<LaV2Chunk> report = content("report", refs.path("app").asText(), handler);
+            assertThat(report.get(0).status()).isEqualTo("error");
+            assertThat(report.get(0).errorCode()).isEqualTo("protocol_unsupported");
+
+            // 8. diff of the work tree (symbolic ref, no client data in it) and of one minted file: masked
+            List<LaV2Chunk> diff = content("diff", "worktree", handler);
+            assertThat(diff.get(0).status()).isEqualTo("ok");
+            assertThat(diff.get(0).contentType()).isEqualTo("text/x-diff");
+            String diffText = new String(concat(diff), StandardCharsets.UTF_8);
+            assertThat(diffText).contains("tracked.js").contains("[REDACTED:github_token]").doesNotContain(ghp).doesNotContain("SECRET-ENV-VALUE").doesNotContain(".env");
+            assertThat(new String(concat(content("diff", refs.path("diffFile").asText(), handler)), StandardCharsets.UTF_8)).contains("tracked.js");
+
+            // 9. the consumer cancels after the first chunk (the relay's client went away): the agent is not left blocked
+            List<LaV2Chunk> first = handler.requestContent(TENANT, null, request("file", refs.path("big").asText()), "ws-1")
+                    .take(1).collectList().block(Duration.ofSeconds(20));
+            assertThat(first).hasSize(1);
+            List<LaV2Chunk> afterCancel = content("file", refs.path("app").asText(), handler);
+            assertThat(afterCancel.get(0).status()).isEqualTo("ok");
+
+            // nothing the Node agent put on the wire was refused by the real gateway session
+            assertThat(rejected).as("frames the real LaV2Session rejected: %s", rejected).isEmpty();
+            // nothing in what the agent printed (events, warnings) carries content or a path
+            String printed = String.join("\n", transcript);
+            assertThat(printed).doesNotContain("OUTSIDE-SECRET").doesNotContain("SECRET-ENV-VALUE").doesNotContain("f307-interop-");
+            System.out.println("CONTENT INTEROP OK: rejected=" + rejected);
+        } finally {
+            try {
+                send(stdin, "quit");
+            } catch (Exception ignored) {
+                // gone
+            }
+            proc.waitFor(5, TimeUnit.SECONDS);
+            proc.destroyForcibly();
+            server.disposeNow();
+        }
+    }
+
+    private static List<LaV2Chunk> content(String kind, String ref, AgentWebSocketHandler handler) {
+        return handler.requestContent(TENANT, null, request(kind, ref), "ws-1").collectList().block(Duration.ofSeconds(30));
+    }
+
+    private static void send(java.io.Writer w, String line) throws Exception {
+        w.write(line + "\n");
+        w.flush();
+    }
+
+    private static JsonNode await(BlockingQueue<JsonNode> q, String evt, int seconds) throws Exception {
+        long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(seconds);
+        List<String> seen = new ArrayList<>();
+        while (System.nanoTime() < deadline) {
+            JsonNode n = q.poll(100, TimeUnit.MILLISECONDS);
+            if (n == null) {
+                continue;
+            }
+            if (evt.equals(n.path("evt").asText())) {
+                return n;
+            }
+            seen.add(n.path("evt").asText() + (n.has("code") ? ":" + n.path("code").asText() : "") + (n.has("m") ? ":" + n.path("m").asText() : ""));
+        }
+        throw new AssertionError("no '" + evt + "' event from the Node LA within " + seconds + " s; saw " + seen);
+    }
+
+    private static byte[] concat(List<LaV2Chunk> chunks) {
+        java.io.ByteArrayOutputStream o = new java.io.ByteArrayOutputStream();
+        chunks.forEach(c -> o.writeBytes(c.data()));
+        return o.toByteArray();
+    }
+}

package/tools/interop/LaV2NodeInteropTest.java

@@ -0,0 +1,266 @@
+package io.visionhammer.gateway.cloud.infrastructure.byoc;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaProtocolV2Properties;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2Chunk;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2Exception;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2InboundListener;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2Metrics;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2Session;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2SessionStore;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2TestKit;
+import io.visionhammer.gateway.governance.application.DataPlanePolicy;
+import io.visionhammer.gateway.identity.application.AgentAuthorizationEntity;
+import io.visionhammer.gateway.identity.application.AgentAuthorizationStore;
+import io.visionhammer.gateway.shared.localagent.AgentRequestSigner;
+import io.visionhammer.gateway.workspace.application.WorkspaceRepository;
+import org.junit.jupiter.api.Test;
+import org.springframework.http.server.reactive.HttpHandler;
+import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
+import org.springframework.web.reactive.socket.server.WebSocketService;
+import org.springframework.web.reactive.socket.server.support.HandshakeWebSocketService;
+import org.springframework.web.reactive.socket.server.upgrade.ReactorNettyRequestUpgradeStrategy;
+import org.springframework.web.server.adapter.WebHttpHandlerBuilder;
+import reactor.core.publisher.Mono;
+import reactor.core.scheduler.Schedulers;
+import reactor.netty.DisposableServer;
+import reactor.netty.http.server.HttpServer;
+
+import java.io.BufferedReader;
+import java.io.InputStreamReader;
+import java.nio.charset.StandardCharsets;
+import java.time.Clock;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.BlockingQueue;
+import java.util.concurrent.LinkedBlockingQueue;
+import java.util.concurrent.TimeUnit;
+
+import static io.visionhammer.gateway.cloud.application.byoc.v2.LaV2TestKit.OM;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assumptions.assumeTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * F3-05b interoperability: the REAL Node Local Agent client (deepdebug-local-agent, protocol v2 link) against
+ * the REAL gateway {@link LaV2Session} behind a real Reactor Netty WebSocket on loopback, real system clock,
+ * real Ed25519 signer. Nothing is mocked on the protocol path (only the authorization store / workspaces /
+ * data-plane policy lookups). Run from the gateway checkout (JDK 21):
+ *
+ *   LA_REPO=/path/to/deepdebug-local-agent mvn -o test -Dtest=LaV2NodeInteropTest
+ *
+ * Skipped when LA_REPO is not set. Not proven here: Cloud Run / LB / TLS, Memorystore, two gateway instances.
+ */
+class LaV2NodeInteropTest {
+
+    private static final String TENANT = LaV2TestKit.TENANT;
+    private static final String AGENT = LaV2TestKit.AGENT;
+
+    private static byte[] pattern(int n) {
+        byte[] b = new byte[n];
+        for (int i = 0; i < n; i++) {
+            b[i] = (byte) ((i * 31 + 7) & 0xff);
+        }
+        return b;
+    }
+
+    private static Map<String, Object> fileRequest(String ref) {
+        return Map.of("kind", "file", "ref", ref, "actor", Map.of("userId", "usr-42", "role", "member"));
+    }
+
+    @Test
+    void realNodeLocalAgentAgainstTheRealLaV2Session() throws Exception {
+        String laRepo = System.getenv("LA_REPO");
+        assumeTrue(laRepo != null && !laRepo.isBlank(), "LA_REPO not set");
+
+        Clock clock = Clock.systemUTC();
+        LaProtocolV2Properties props = new LaProtocolV2Properties();
+        props.setEnabled(true);
+        List<String> rejected = Collections.synchronizedList(new ArrayList<>());
+        int[] retransmits = {0};
+        int[] duplicates = {0};
+        LaV2Metrics metrics = new LaV2Metrics() {
+            @Override public void rejected(String code) { rejected.add(code); }
+            @Override public void retransmit() { retransmits[0]++; }
+            @Override public void duplicate() { duplicates[0]++; }
+        };
+        List<JsonNode> inbound = Collections.synchronizedList(new ArrayList<>());
+        LaV2InboundListener listener = (t, a, type, rid, payload) -> {
+            assertThat(t).isEqualTo(TENANT);
+            assertThat(a).isEqualTo(AGENT);
+            var n = OM.createObjectNode().put("type", type);
+            n.set("payload", payload);
+            inbound.add(n);
+        };
+        AgentRequestSigner signer = new AgentRequestSigner(LaV2TestKit.PEM, "k1", clock);
+        LaV2Session.Env env = new LaV2Session.Env(LaV2TestKit.CONTRACT, props, signer, OM, clock, metrics, Schedulers.parallel(), List.of(listener));
+
+        AgentAuthorizationStore store = mock(AgentAuthorizationStore.class);
+        WorkspaceRepository workspaces = mock(WorkspaceRepository.class);
+        DataPlanePolicy policy = mock(DataPlanePolicy.class);
+        when(workspaces.findDefaultByTenantId(anyString())).thenReturn(Mono.empty());
+        when(store.save(any())).thenAnswer(i -> Mono.just(i.getArgument(0)));
+        when(store.touchLastSeen(any())).thenReturn(Mono.just(1));
+        when(policy.requiresEnforcedSigning(anyString())).thenReturn(Mono.just(true)); // a hybrid/client tenant: enforce required
+        AgentAuthorizationEntity auth = new AgentAuthorizationEntity();
+        auth.setId(UUID.fromString(AGENT));
+        auth.setTenantId(UUID.fromString(TENANT));
+        auth.setAuthorizationToken("tok");
+        when(store.findByAuthorizationToken("tok")).thenReturn(Mono.just(auth));
+        AgentWebSocketHandler handler = new AgentWebSocketHandler(OM, workspaces, store, signer, null, null, null,
+                new LaV2SessionStore(env), props, policy);
+
+        WebSocketService wsService = new HandshakeWebSocketService(new ReactorNettyRequestUpgradeStrategy());
+        HttpHandler http = WebHttpHandlerBuilder.webHandler(exchange -> wsService.handleRequest(exchange, handler)).build();
+        DisposableServer server = HttpServer.create().host("127.0.0.1").port(0).handle(new ReactorHttpHandlerAdapter(http)).bindNow();
+
+        ProcessBuilder pb = new ProcessBuilder("node", laRepo + "/tools/interop/la-interop-client.mjs");
+        pb.environment().putAll(Map.of(
+                "GW_URL", "ws://127.0.0.1:" + server.port() + "/api/v1/agent/ws", "TOKEN", "tok", "TENANT", TENANT, "AGENT", AGENT,
+                "KEY_ID", "k1", "PUBLIC_KEY", LaV2TestKit.PUB, "MODE", "enforce"));
+        pb.redirectErrorStream(true);
+        Process proc = pb.start();
+        BlockingQueue<JsonNode> events = new LinkedBlockingQueue<>();
+        List<String> transcript = Collections.synchronizedList(new ArrayList<>());
+        Thread reader = new Thread(() -> {
+            try (BufferedReader r = new BufferedReader(new InputStreamReader(proc.getInputStream(), StandardCharsets.UTF_8))) {
+                String line;
+                while ((line = r.readLine()) != null) {
+                    transcript.add(line);
+                    try {
+                        events.add(OM.readTree(line));
+                    } catch (Exception ignored) {
+                        // node warnings
+                    }
+                }
+            } catch (Exception ignored) {
+                // process ended
+            }
+        });
+        reader.setDaemon(true);
+        reader.start();
+        java.io.Writer stdin = new java.io.OutputStreamWriter(proc.getOutputStream(), StandardCharsets.UTF_8);
+
+        try {
+            JsonNode ready = await(events, "ready", 15);
+            assertThat(ready.path("resumed").asBoolean()).isFalse();
+            assertThat(handler.isAgentConnected(TENANT)).isTrue();
+
+            // 1. content: 100 KiB (4 chunks), the maximum 2 MiB (64 chunks), a not_found answer
+            List<LaV2Chunk> small = handler.requestContent(TENANT, null, fileRequest("bytes:102400"), "ws-1").collectList().block(Duration.ofSeconds(20));
+            assertThat(small).hasSize(4);
+            assertThat(concat(small)).isEqualTo(pattern(102400));
+            assertThat(small.get(3).last()).isTrue();
+
+            List<LaV2Chunk> max = handler.requestContent(TENANT, null, fileRequest("bytes:2097152"), "ws-1").collectList().block(Duration.ofSeconds(30));
+            assertThat(max).hasSize(64);
+            assertThat(concat(max)).isEqualTo(pattern(2097152));
+
+            List<LaV2Chunk> nf = handler.requestContent(TENANT, null, fileRequest("notfound"), "ws-1").collectList().block(Duration.ofSeconds(20));
+            assertThat(nf).hasSize(1);
+            assertThat(nf.get(0).status()).isEqualTo("not_found");
+
+            // 2. signed CP->LA data frames: the Node LA verifies the Java signature (enforce) and acks
+            Map<String, Object> assign = Map.of("jobId", "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", "kind", "fix",
+                    "repoRef", Map.of("provider", "github", "org", "acme", "repo", "billing", "branch", "main"),
+                    "policy", Map.of("operationMode", "assist", "automationLevel", 2, "ceiling", "autonomous"),
+                    "budget", Map.of("tokens", 200000, "seconds", 900), "llm", Map.of("alias", "vh-coder", "keyRef", "key-la-1"));
+            handler.sendV2(TENANT, null, "job.assign", assign, "ws-1").block(Duration.ofSeconds(10));
+            assertThat(await(events, "job.assign", 5).path("jobId").asText()).isEqualTo("c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f");
+            handler.sendV2(TENANT, null, "job.cancel", Map.of("jobId", "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", "reason", "user"), "ws-1").block(Duration.ofSeconds(10));
+            await(events, "job.cancel", 5);
+
+            // a type the LA has no handler for: rejected ack with protocol_unsupported -> the CP call fails with that code
+            org.assertj.core.api.Assertions.assertThatThrownBy(() -> handler.sendV2(TENANT, null, "config.update", Map.of("retentionDays", 7), "ws-1").block(Duration.ofSeconds(10)))
+                    .isInstanceOf(LaV2Exception.class).extracting(e -> ((LaV2Exception) e).code().wire()).isEqualTo("protocol_unsupported");
+
+            // 3. LA -> CP: 20 events, in order, no duplicates
+            send(stdin, "events 20");
+            await(events, "events-acked", 10);
+            assertThat(iterations(inbound)).containsExactlyElementsOf(range(0, 20));
+
+            // 4. the socket drops; the LA reconnects offering {sessionId,lastRecvSeq}; the gateway resumes the session
+            send(stdin, "drop");
+            JsonNode again = await(events, "ready", 15);
+            assertThat(again.path("resumed").asBoolean()).as("resumed on the same gateway instance").isTrue();
+            assertThat(again.path("sessionId").asText()).isEqualTo(ready.path("sessionId").asText());
+            send(stdin, "events 5");
+            await(events, "events-acked", 10);
+            assertThat(iterations(inbound)).hasSize(25);
+            assertThat(iterations(inbound).subList(20, 25)).containsExactlyElementsOf(range(0, 5));
+
+            // 5. content still works after the resume
+            List<LaV2Chunk> after = handler.requestContent(TENANT, null, fileRequest("bytes:40000"), "ws-1").collectList().block(Duration.ofSeconds(20));
+            assertThat(concat(after)).isEqualTo(pattern(40000));
+
+            // nothing the gateway refused from the Node LA
+            assertThat(rejected).as("frames the real LaV2Session rejected: %s", rejected).isEmpty();
+            System.out.println("INTEROP OK: retransmits=" + retransmits[0] + " duplicates=" + duplicates[0] + " rejected=" + rejected
+                    + " events=" + inbound.size());
+        } finally {
+            try {
+                send(stdin, "quit");
+            } catch (Exception ignored) {
+                // gone
+            }
+            proc.waitFor(5, TimeUnit.SECONDS);
+            proc.destroyForcibly();
+            server.disposeNow();
+            System.out.println("LA transcript (no content): " + transcript.size() + " lines");
+        }
+    }
+
+    private static void send(java.io.Writer w, String line) throws Exception {
+        w.write(line + "\n");
+        w.flush();
+    }
+
+    private static JsonNode await(BlockingQueue<JsonNode> q, String evt, int seconds) throws Exception {
+        long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(seconds);
+        List<String> seen = new ArrayList<>();
+        while (System.nanoTime() < deadline) {
+            JsonNode n = q.poll(100, TimeUnit.MILLISECONDS);
+            if (n == null) {
+                continue;
+            }
+            if (evt.equals(n.path("evt").asText())) {
+                return n;
+            }
+            seen.add(n.path("evt").asText() + (n.has("code") ? ":" + n.path("code").asText() : "") + (n.has("m") ? ":" + n.path("m").asText() : ""));
+        }
+        throw new AssertionError("no '" + evt + "' event from the Node LA within " + seconds + " s; saw " + seen);
+    }
+
+    private static byte[] concat(List<LaV2Chunk> chunks) {
+        java.io.ByteArrayOutputStream o = new java.io.ByteArrayOutputStream();
+        chunks.forEach(c -> o.writeBytes(c.data()));
+        return o.toByteArray();
+    }
+
+    private static List<Integer> iterations(List<JsonNode> inbound) {
+        List<Integer> out = new ArrayList<>();
+        synchronized (inbound) {
+            for (JsonNode n : inbound) {
+                if ("job.event".equals(n.path("type").asText())) {
+                    out.add(n.at("/payload/iteration").asInt());
+                }
+            }
+        }
+        return out;
+    }
+
+    private static List<Integer> range(int from, int to) {
+        List<Integer> l = new ArrayList<>();
+        for (int i = from; i < to; i++) {
+            l.add(i);
+        }
+        return l;
+    }
+}

package/tools/interop/README.md

@@ -0,0 +1,38 @@
+# Interoperability test: this Local Agent against the real gateway `LaV2Session`
+
+`la-interop-client.mjs` is a Local Agent built from this repo's v2 link, with test-only handlers
+(`content.request`, `job.assign`, `job.cancel`) that the product does not have yet. `LaV2NodeInteropTest.java` is a
+JUnit test for the gateway repo: it starts the real `AgentWebSocketHandler` + `LaV2Session` (Reactor Netty,
+loopback, system clock, real Ed25519 signer, `enforce` required), starts the Node client, and drives it.
+
+```bash
+# 1. in a worktree of vh-api-gateway (release/qa, tip >= 7043f75e), JDK 21
+cp /path/to/deepdebug-local-agent/tools/interop/LaV2NodeInteropTest.java \
+   src/test/java/io/visionhammer/gateway/cloud/infrastructure/byoc/
+# 2. run it (needs `node` >= 18 on PATH and `npm ci` done in the LA repo)
+LA_REPO=/path/to/deepdebug-local-agent mvn -o test -Dtest=LaV2NodeInteropTest
+```
+
+It checks: signed `ready` verified by Node; 100 KiB (4 chunks), 2 MiB (64 chunks) and `not_found` content streamed
+LA -> CP and rebuilt byte for byte; signed `job.assign`/`job.cancel` from the Java signer verified by Node and acked;
+a type with no handler -> rejected ack `protocol_unsupported`; 20 `job.event` in order; socket drop -> `resumed:true`
+with the same session id and consecutive seq; content after the resume; zero frames refused by the gateway.
+It is skipped when `LA_REPO` is not set. It does not prove Cloud Run / the load balancer / TLS / Memorystore /
+two gateway instances.
+
+## F3-07: content handlers against the real `LaV2Session`
+
+`la-interop-content-client.mjs` is a Local Agent with the REAL content handlers (opaque ids, path guard, DLP `enforce`,
+git diff, chunking) on a temp workspace; `LaV2NodeContentInteropTest.java` drives it through `AgentWebSocketHandler.requestContent`.
+
+```bash
+cp tools/interop/LaV2NodeContentInteropTest.java <gateway>/src/test/java/io/visionhammer/gateway/cloud/infrastructure/byoc/
+LA_REPO=/path/to/deepdebug-local-agent mvn -o test -Dtest=LaV2NodeContentInteropTest   # JDK 21
+```
+
+It checks: a token masked in a served file; 1 MiB = 32 chunks byte for byte (sha256); a token straddling the 32 KiB
+boundary never appears, whole or in part; an id swapped for a link to a file outside the workspace -> `forbidden`;
+`../../etc/passwd`, `/etc/passwd`, a plain relative path and a made-up id -> `not_found`; binary -> `forbidden` in enforce;
+`report` -> `error` + `protocol_unsupported`; the diff of the work tree masked and without `.env`; the consumer cancels
+after the first chunk and the next request still works; zero frames refused by the gateway; nothing printed by the agent
+carries content or a path. Negative control: with the DLP step disabled in the agent the test fails.

package/tools/interop/la-interop-client.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// A Local Agent for the interoperability test with the REAL gateway session (LaV2Session, Java): the v2 link of
+// this repo around a plain `ws` client, with TEST-ONLY handlers (content.request / job.assign / job.cancel) that
+// the product does not have yet (F3-07). Driven by the Java harness over stdin; reports on stdout, one JSON per line.
+//
+//   env: GW_URL (ws://127.0.0.1:port/api/v1/agent/ws) TOKEN TENANT AGENT KEY_ID PUBLIC_KEY MODE(enforce)
+//   stdin: "events <n>"   send n job.event frames (iteration 0..n-1)
+//          "drop"         terminate the socket and reconnect (resume)
+//          "quit"
+//   content.request ref: "bytes:<n>" -> n deterministic bytes; "notfound" -> a not_found answer
+import readline from "node:readline";
+import WebSocket from "ws";
+import { createV2Link } from "../../src/la-protocol-v2/link.js";
+import { sendContent, sendContentFailure } from "../../src/la-protocol-v2/content.js";
+import { resolveSigningConfig } from "../../src/utils/request-signing.js";
+
+const { GW_URL, TOKEN, TENANT, AGENT, KEY_ID, PUBLIC_KEY, MODE = "enforce" } = process.env;
+const out = (o) => process.stdout.write(JSON.stringify(o) + "\n");
+
+export const patternBytes = (n) => Buffer.from(Array.from({ length: n }, (_, i) => (i * 31 + 7) & 0xff));
+
+const signing = resolveSigningConfig({
+    LOCAL_AGENT_SIGNATURE_MODE: MODE, LOCAL_AGENT_SIGNING_PUBLIC_KEYS: `${KEY_ID}=${PUBLIC_KEY}`, LOCAL_AGENT_TENANT_ID: TENANT,
+}, { defaultFile: null, fileCfg: {} });
+
+const link = createV2Link({
+    log: { info: () => {}, warn: (m) => out({ evt: "warn", m }) },
+    sessionOptions: {
+        tenantId: TENANT, agentId: AGENT, signing, laVersion: "1.3.0", capabilities: ["protocol.v2", "v1.commands", "chunk.base64"],
+        getWorkspaces: () => [{ workspaceId: "ws-1", pathSha256: "ab".repeat(32) }],
+        getHealth: () => ({ diskFreeBytes: 123456789 }),
+        options: { handshakeTimeoutMs: 5000, heartbeatMs: 500 },
+    },
+});
+const session = link.session;
+session.on("ready", (i) => out({ evt: "ready", resumed: i.resumed, sessionId: i.sessionId, limits: i.limits }));
+session.on("refused", (c) => out({ evt: "refused", code: c }));
+session.on("peer-error", (c) => out({ evt: "peer-error", code: c }));
+
+// test-only handlers
+session.setHandler("job.assign", (ctx) => { out({ evt: "job.assign", jobId: ctx.params.jobId, seq: ctx.seq }); return { accept: true }; });
+session.setHandler("job.cancel", (ctx) => { out({ evt: "job.cancel", jobId: ctx.params.jobId, seq: ctx.seq }); return { accept: true }; });
+session.setHandler("content.request", (ctx) => {
+    const { ref } = ctx.params;
+    // ack first (accepted), answer in the background: the CP waits up to 10 s for the first chunk
+    queueMicrotask(async () => {
+        try {
+            if (ref === "notfound") await sendContentFailure(session, { requestId: ctx.requestId, status: "not_found", errorCode: "internal", workspaceId: ctx.workspaceId });
+            else await sendContent(session, { requestId: ctx.requestId, source: patternBytes(Number(ref.split(":")[1])), contentType: "application/octet-stream", workspaceId: ctx.workspaceId });
+            out({ evt: "content.sent", ref });
+        } catch (e) { out({ evt: "content.failed", code: e.code }); }
+    });
+    return { accept: true };
+});
+
+let ws;
+function connect() {
+    ws = new WebSocket(GW_URL, { headers: { Authorization: `Bearer ${TOKEN}` } });
+    const mine = ws;
+    ws.on("open", () => {
+        const legacy = () => { out({ evt: "legacy-register" }); mine.send(JSON.stringify({ type: "register", tenantId: TENANT, port: 5055, workspacePath: null })); };
+        if (!link.begin(mine, legacy)) legacy();
+        const hb = setInterval(() => { if (mine.readyState === 1) mine.send("ping"); else clearInterval(hb); }, 5000);
+    });
+    ws.on("message", (data, isBinary) => {
+        const text = data.toString();
+        if (text === "pong") return;
+        if (link.handleMessage(mine, text, isBinary)) return;
+        out({ evt: "v1-message" });
+    });
+    ws.on("close", (code) => { out({ evt: "closed", code }); link.onClose(mine); if (!quitting) setTimeout(connect, 100); });
+    ws.on("error", () => {});
+}
+let quitting = false;
+connect();
+
+const rl = readline.createInterface({ input: process.stdin });
+rl.on("line", async (line) => {
+    const [cmd, arg] = line.trim().split(/\s+/);
+    if (cmd === "events") {
+        const n = Number(arg);
+        const jobId = "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f";
+        const sends = [];
+        for (let i = 0; i < n; i++) sends.push(session.send("job.event", { jobId, state: "running", iteration: i }).catch((e) => out({ evt: "event-failed", code: e.code })));
+        await Promise.all(sends);
+        out({ evt: "events-acked", n });
+    } else if (cmd === "drop") {
+        out({ evt: "dropping" });
+        ws.terminate();
+    } else if (cmd === "quit") {
+        quitting = true;
+        ws.terminate();
+        link.close();
+        process.exit(0);
+    }
+});
+rl.on("close", () => { quitting = true; try { ws.terminate(); } catch { /* gone */ } process.exit(0); });