Expose SDK bridge connectivity check (#25)

## Summary
- add `isConnected()` to `@agent-cdp/sdk` so app code can cheaply detect
whether the agent-cdp runtime bridge is attached before starting a
profiling or capture workflow
- reuse a shared binding lookup inside `AgentRuntimeClient` and cover
the new connectivity check with SDK tests
- document the new SDK call in `docs/SDK.md`

## Backward-compatibility analysis
- existing SDK APIs remain unchanged; this only adds a new optional
helper
- daemon commands, CLI commands, output formats, saved artifacts, and
daemon lifecycle behavior are unchanged
- the change does not alter defaults or bridge timing; it only exposes
the current bridge-installed state as a boolean

## Risks
- `isConnected()` reports bridge presence, so it reflects whether the
runtime bridge is installed in the app context rather than proving a
future command cannot race with a disconnect
- consumers may treat the boolean as a stronger guarantee than it is if
they do not account for target reconnects between the check and a later
SDK call
- documentation now needs to keep the distinction clear between bridge
presence and successful execution of a later profiling command

## Manual testing
- in an app wired with `@agent-cdp/sdk`, start the daemon and select the
target with `agent-cdp target select <target-id>`
- call `isConnected()` before target selection and verify it returns
`false`
- select the target, call `isConnected()` again, and verify it returns
`true`
- run `pnpm --filter @agent-cdp/protocol build`, `pnpm --filter
@agent-cdp/sdk test`, and `pnpm --filter @agent-cdp/sdk typecheck`

Author: V3RON

docs/SDK.md

@@ -37,13 +37,16 @@ Available calls:
 - `cpuProfile.start({ name?, samplingIntervalUs? })`
 - `cpuProfile.status()`
 - `cpuProfile.stop()`
+- `isConnected()`
 
 `cpuProfile.status()` returns whether a profile is active plus the active name, elapsed time, and retained session count. `cpuProfile.stop()` returns the recorded session ID.
 
+`isConnected()` returns `true` when the runtime bridge has been injected into the app, which means `agent-cdp` is currently attached to the selected target. Use it when you want a cheap connectivity check before attempting a profiling or capture command.
+
 ## Workflow
 
 1. Connect `agent-cdp` to the app target.
 2. Trigger `cpuProfile.start()` from app code just before the work you want.
 3. Run the target flow.
 4. Call `cpuProfile.stop()` and keep the returned session ID.
-5. Analyze that same session with the CLI.
+5. Analyze that same session with the CLI.

packages/sdk/src/index.test.ts

@@ -32,6 +32,22 @@ describe("AgentRuntimeClient", () => {
     expect(request.command).toEqual({ type: "js-profile-stop" });
   });
 
+  it("reports whether the runtime bridge is installed", async () => {
+    const client = new AgentRuntimeClient();
+    expect(client.isConnected()).toBe(false);
+
+    agentCdpGlobals()[AGENT_CDP_BINDING_NAME] = () => undefined;
+    expect(client.isConnected()).toBe(true);
+
+    vi.resetModules();
+    const sdk = await import("./index.js");
+    expect(sdk.isConnected()).toBe(true);
+
+    delete agentCdpGlobals()[AGENT_CDP_BINDING_NAME];
+    expect(client.isConnected()).toBe(false);
+    expect(sdk.isConnected()).toBe(false);
+  });
+
   it("sends trace commands and resolves typed bridge responses", async () => {
     const sent: string[] = [];
     agentCdpGlobals()[AGENT_CDP_BINDING_NAME] = (payload: string) => {

packages/sdk/src/index.ts

@@ -63,6 +63,10 @@ export class AgentRuntimeClient {
     this.installReceiver();
   }
 
+  isConnected(): boolean {
+    return this.getBinding() !== null;
+  }
+
   startCpuProfile(options: { name?: string; samplingIntervalUs?: number } = {}): Promise<string> {
     return this.send({
       type: "js-profile-start",
@@ -186,9 +190,9 @@ export class AgentRuntimeClient {
     const startedAt = Date.now();
 
     while (Date.now() - startedAt <= this.timeoutMs) {
-      const binding = agentCdpGlobals()[this.bindingName];
-      if (typeof binding === "function") {
-        return binding as (payload: string) => void;
+      const binding = this.getBinding();
+      if (binding) {
+        return binding;
       }
 
       await sleep(BINDING_POLL_INTERVAL_MS);
@@ -203,6 +207,11 @@ export class AgentRuntimeClient {
     };
   }
 
+  private getBinding(): ((payload: string) => void) | null {
+    const binding = agentCdpGlobals()[this.bindingName];
+    return typeof binding === "function" ? (binding as (payload: string) => void) : null;
+  }
+
   private receive(payload: string): void {
     let response: AgentRuntimeBridgeResponse;
     try {
@@ -228,6 +237,10 @@ export class AgentRuntimeClient {
 
 const defaultClient = new AgentRuntimeClient();
 
+export function isConnected(): boolean {
+  return defaultClient.isConnected();
+}
+
 export const cpuProfile = {
   start: (options?: { name?: string; samplingIntervalUs?: number }) => defaultClient.startCpuProfile(options),
   status: () => defaultClient.getCpuProfileStatus(),