@spotpatch/dev-server 0.5.0 → 0.6.0

package/dist/index.js

@@ -472,6 +472,1103 @@ function createAgentJobManager(options) {
   });
 }
 
+// src/external-handoff/service.ts
+import {
+  ERROR_CODES as ERROR_CODES6,
+  EXTERNAL_HANDOFF_BROKER_PROTOCOL_VERSION as EXTERNAL_HANDOFF_BROKER_PROTOCOL_VERSION3,
+  EXTERNAL_HANDOFF_SNAPSHOT_SCHEMA_VERSION as EXTERNAL_HANDOFF_SNAPSHOT_SCHEMA_VERSION2,
+  SpotPatchError as SpotPatchError6
+} from "@spotpatch/shared";
+import { computeExternalHandoffProjectKey as computeExternalHandoffProjectKey2 } from "@spotpatch/shared/external-agent-node";
+
+// src/external-handoff/active-registry.ts
+import { randomBytes as randomBytes2 } from "crypto";
+import {
+  ERROR_CODES as ERROR_CODES2,
+  EXTERNAL_HANDOFF_LIMITS,
+  SpotPatchError as SpotPatchError2
+} from "@spotpatch/shared";
+
+// src/external-handoff/clock.ts
+import { performance } from "perf_hooks";
+var SYSTEM_EXTERNAL_HANDOFF_CLOCK = Object.freeze({
+  monotonicNow: () => performance.now(),
+  wallNow: () => Date.now()
+});
+
+// src/external-handoff/active-registry.ts
+var ALLOWED_TRANSITIONS = Object.freeze({
+  queued: ["dispatching", "failed"],
+  dispatching: ["dispatched", "working", "failed", "delivery-unknown"],
+  dispatched: ["working", "failed", "delivery-unknown"],
+  working: ["completed", "failed", "delivery-unknown"],
+  completed: [],
+  failed: [],
+  "delivery-unknown": []
+});
+var TERMINAL_PHASES = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "delivery-unknown"
+]);
+function defaultRandomId() {
+  return randomBytes2(32).toString("base64url");
+}
+function requirePresent(value) {
+  if (value === null) throw new SpotPatchError2(ERROR_CODES2.INTERNAL_ERROR);
+  return value;
+}
+function createActiveAdapterRegistry(options = {}) {
+  const clock = options.clock ?? SYSTEM_EXTERNAL_HANDOFF_CLOCK;
+  const randomId = options.randomId ?? defaultRandomId;
+  let blocked;
+  let closed = false;
+  let dispatch;
+  let lastReleasedToken;
+  let lease;
+  const nowIso = () => new Date(clock.wallNow()).toISOString();
+  const requireOpen = () => {
+    if (closed) throw new SpotPatchError2(ERROR_CODES2.SESSION_CLOSED);
+  };
+  const dispatchSummary = () => dispatch === void 0 ? null : Object.freeze({
+    adapterKind: dispatch.adapterKind,
+    revision: dispatch.revision,
+    phase: dispatch.phase,
+    updatedAt: dispatch.updatedAt
+  });
+  const activeSummary = () => {
+    if (blocked !== void 0) {
+      return Object.freeze({
+        kind: blocked.adapterKind,
+        state: "blocked",
+        canDispatch: false,
+        connectedAt: blocked.connectedAt,
+        updatedAt: blocked.updatedAt
+      });
+    }
+    if (lease === void 0) return null;
+    const busy = dispatch !== void 0 && !TERMINAL_PHASES.has(dispatch.phase);
+    return Object.freeze({
+      kind: lease.adapterKind,
+      state: busy ? "busy" : "ready",
+      canDispatch: !busy,
+      connectedAt: lease.connectedAt,
+      updatedAt: lease.updatedAt
+    });
+  };
+  const state = (cursor) => Object.freeze({
+    activeAdapter: activeSummary(),
+    dispatch: cursor === void 0 || dispatch?.cursor === cursor ? dispatchSummary() : null
+  });
+  const enterUnknown = (activeLease) => {
+    if (dispatch === void 0) return;
+    const updatedAt = nowIso();
+    dispatch.phase = "delivery-unknown";
+    dispatch.updatedAt = updatedAt;
+    blocked = Object.freeze({
+      adapterKind: activeLease.adapterKind,
+      connectedAt: activeLease.connectedAt,
+      updatedAt
+    });
+  };
+  const endLease = (activeLease) => {
+    if (dispatch?.phase === "queued") {
+      dispatch.phase = "failed";
+      dispatch.updatedAt = nowIso();
+    } else if (dispatch?.phase === "dispatching" || dispatch?.phase === "dispatched" || dispatch?.phase === "working") {
+      enterUnknown(activeLease);
+    }
+    lastReleasedToken = activeLease.token;
+    lease = void 0;
+  };
+  const sweep = () => {
+    if (lease === void 0) return;
+    const monotonicNow = clock.monotonicNow();
+    if (monotonicNow >= lease.expiresAtMonotonic || dispatch !== void 0 && !TERMINAL_PHASES.has(dispatch.phase) && monotonicNow >= dispatch.deadlineMonotonic) {
+      endLease(lease);
+    }
+  };
+  const assertPublishable = () => {
+    requireOpen();
+    sweep();
+    if (blocked !== void 0 || lease !== void 0 && dispatch !== void 0 && !TERMINAL_PHASES.has(dispatch.phase)) {
+      throw new SpotPatchError2(ERROR_CODES2.EXTERNAL_AGENT_BUSY);
+    }
+  };
+  const requireLease = (leaseToken) => {
+    requireOpen();
+    sweep();
+    if (lease?.token !== leaseToken) {
+      throw new SpotPatchError2(ERROR_CODES2.ACTIVE_ADAPTER_LEASE_INVALID);
+    }
+    return lease;
+  };
+  return Object.freeze({
+    assertPublishable,
+    claim(adapterKind, connectorInstanceId, baselineCursor) {
+      requireOpen();
+      sweep();
+      if (blocked !== void 0) {
+        throw new SpotPatchError2(ERROR_CODES2.EXTERNAL_AGENT_BUSY);
+      }
+      if (lease !== void 0) {
+        if (lease.adapterKind === adapterKind && lease.connectorInstanceId === connectorInstanceId) {
+          lease.expiresAtMonotonic = clock.monotonicNow() + EXTERNAL_HANDOFF_LIMITS.activeLeaseDurationMs;
+          lease.updatedAt = nowIso();
+          return Object.freeze({
+            leaseToken: lease.token,
+            heartbeatIntervalMs: EXTERNAL_HANDOFF_LIMITS.activeHeartbeatIntervalMs,
+            baselineCursor: lease.baselineCursor,
+            activeAdapter: requirePresent(activeSummary())
+          });
+        }
+        throw new SpotPatchError2(ERROR_CODES2.ACTIVE_ADAPTER_CONFLICT);
+      }
+      const timestamp = nowIso();
+      lease = {
+        adapterKind,
+        baselineCursor,
+        connectedAt: timestamp,
+        connectorInstanceId,
+        token: randomId(),
+        expiresAtMonotonic: clock.monotonicNow() + EXTERNAL_HANDOFF_LIMITS.activeLeaseDurationMs,
+        updatedAt: timestamp
+      };
+      lastReleasedToken = void 0;
+      return Object.freeze({
+        leaseToken: lease.token,
+        heartbeatIntervalMs: EXTERNAL_HANDOFF_LIMITS.activeHeartbeatIntervalMs,
+        baselineCursor,
+        activeAdapter: requirePresent(activeSummary())
+      });
+    },
+    heartbeat(leaseToken) {
+      const activeLease = requireLease(leaseToken);
+      activeLease.expiresAtMonotonic = clock.monotonicNow() + EXTERNAL_HANDOFF_LIMITS.activeLeaseDurationMs;
+      activeLease.updatedAt = nowIso();
+      return state();
+    },
+    report(leaseToken, cursor, phase) {
+      const activeLease = requireLease(leaseToken);
+      if (dispatch?.cursor !== cursor || dispatch.adapterKind !== activeLease.adapterKind) {
+        throw new SpotPatchError2(ERROR_CODES2.ACTIVE_DISPATCH_INVALID);
+      }
+      if (dispatch.phase === phase) return state(cursor);
+      const allowed = ALLOWED_TRANSITIONS[dispatch.phase];
+      if (!allowed.includes(phase)) {
+        throw new SpotPatchError2(ERROR_CODES2.ACTIVE_DISPATCH_INVALID);
+      }
+      const updatedAt = nowIso();
+      dispatch.phase = phase;
+      dispatch.updatedAt = updatedAt;
+      activeLease.updatedAt = updatedAt;
+      if (phase === "delivery-unknown") {
+        blocked = Object.freeze({
+          adapterKind: activeLease.adapterKind,
+          connectedAt: activeLease.connectedAt,
+          updatedAt
+        });
+        lastReleasedToken = activeLease.token;
+        lease = void 0;
+      }
+      return state(cursor);
+    },
+    release(leaseToken) {
+      requireOpen();
+      sweep();
+      if (lease === void 0 && lastReleasedToken === leaseToken) return state();
+      const activeLease = lease;
+      if (activeLease?.token !== leaseToken) {
+        throw new SpotPatchError2(ERROR_CODES2.ACTIVE_ADAPTER_LEASE_INVALID);
+      }
+      endLease(activeLease);
+      return state();
+    },
+    reserve(cursor, revision) {
+      assertPublishable();
+      if (lease === void 0) return Object.freeze({ mode: "inbox" });
+      const updatedAt = nowIso();
+      dispatch = {
+        adapterKind: lease.adapterKind,
+        cursor,
+        deadlineMonotonic: clock.monotonicNow() + EXTERNAL_HANDOFF_LIMITS.activeDispatchTimeoutMs,
+        revision,
+        phase: "queued",
+        updatedAt
+      };
+      lease.updatedAt = updatedAt;
+      return Object.freeze({
+        mode: "active",
+        adapter: requirePresent(activeSummary()),
+        dispatch: requirePresent(dispatchSummary())
+      });
+    },
+    resolveDelivery(cursor) {
+      requireOpen();
+      sweep();
+      const activeDispatch = dispatch;
+      if (blocked === void 0 || activeDispatch?.cursor !== cursor || activeDispatch.phase !== "delivery-unknown") {
+        throw new SpotPatchError2(ERROR_CODES2.ACTIVE_DISPATCH_INVALID);
+      }
+      blocked = void 0;
+      return state(cursor);
+    },
+    snapshot(cursor) {
+      requireOpen();
+      sweep();
+      return state(cursor);
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      blocked = void 0;
+      dispatch = void 0;
+      lease = void 0;
+      lastReleasedToken = void 0;
+    }
+  });
+}
+
+// src/external-handoff/broker.ts
+import { randomBytes as randomBytes3, timingSafeEqual } from "crypto";
+import {
+  createServer
+} from "http";
+import {
+  ERROR_CODES as ERROR_CODES4,
+  EXTERNAL_HANDOFF_BROKER_PROTOCOL_VERSION,
+  EXTERNAL_HANDOFF_LIMITS as EXTERNAL_HANDOFF_LIMITS2,
+  SpotPatchError as SpotPatchError4
+} from "@spotpatch/shared";
+import {
+  SPOTPATCH_BRIDGE_PATHS,
+  SPOTPATCH_BRIDGE_TOKEN_HEADER,
+  bridgeAckRequestSchema,
+  bridgeActiveClaimRequestSchema,
+  bridgeActiveHeartbeatRequestSchema,
+  bridgeActiveReleaseRequestSchema,
+  bridgeActiveReportRequestSchema,
+  bridgeCurrentRequestSchema,
+  bridgeStatusRequestSchema,
+  bridgeWaitRequestSchema
+} from "@spotpatch/shared/external-agent-node";
+
+// src/server/request-body.ts
+import { ERROR_CODES as ERROR_CODES3, SpotPatchError as SpotPatchError3 } from "@spotpatch/shared";
+
+// src/server/constants.ts
+var MAX_REQUEST_BODY_BYTES = 32 * 1024;
+var MAX_AGENT_REQUEST_BODY_BYTES = 256 * 1024;
+var MAX_SOURCE_FILE_BYTES = 1024 * 1024;
+
+// src/server/request-body.ts
+function isJsonContentType(value) {
+  return value?.split(";", 1)[0]?.trim().toLowerCase() === "application/json";
+}
+async function readJsonRequestBody(request, maximumBytes = MAX_REQUEST_BODY_BYTES) {
+  if (!isJsonContentType(request.headers["content-type"])) {
+    throw new SpotPatchError3(ERROR_CODES3.INVALID_REQUEST);
+  }
+  const declaredLength = Number(request.headers["content-length"]);
+  if (Number.isFinite(declaredLength) && declaredLength > maximumBytes) {
+    throw new SpotPatchError3(ERROR_CODES3.INVALID_REQUEST);
+  }
+  const chunks = [];
+  let byteLength = 0;
+  let exceededLimit = false;
+  for await (const rawChunk of request) {
+    const chunk = rawChunk;
+    if (typeof chunk !== "string" && !(chunk instanceof Uint8Array)) {
+      throw new SpotPatchError3(ERROR_CODES3.INVALID_REQUEST);
+    }
+    const buffer = Buffer.from(chunk);
+    byteLength += buffer.byteLength;
+    if (byteLength > maximumBytes) {
+      exceededLimit = true;
+      continue;
+    }
+    chunks.push(buffer);
+  }
+  if (exceededLimit || byteLength === 0) {
+    throw new SpotPatchError3(ERROR_CODES3.INVALID_REQUEST);
+  }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch (error) {
+    throw new SpotPatchError3(ERROR_CODES3.INVALID_REQUEST, void 0, {
+      cause: error
+    });
+  }
+}
+
+// src/external-handoff/broker.ts
+function singleHeader(request, name) {
+  const value = request.headers[name.toLowerCase()];
+  return Array.isArray(value) ? void 0 : value;
+}
+function tokensMatch(actual, expected) {
+  if (actual === void 0) return false;
+  const actualBytes = Buffer.from(actual);
+  const expectedBytes = Buffer.from(expected);
+  return actualBytes.byteLength === expectedBytes.byteLength && timingSafeEqual(actualBytes, expectedBytes);
+}
+function writeJson(response, status, payload) {
+  response.statusCode = status;
+  response.setHeader("Cache-Control", "no-store");
+  response.setHeader("Connection", "close");
+  response.setHeader("Content-Type", "application/json; charset=utf-8");
+  response.setHeader("X-Content-Type-Options", "nosniff");
+  response.end(JSON.stringify(payload));
+}
+function statusForError(code) {
+  if (code === ERROR_CODES4.BRIDGE_UNAUTHORIZED) return 401;
+  if (code === ERROR_CODES4.HANDOFF_NOT_FOUND) return 404;
+  if (code === ERROR_CODES4.HANDOFF_EXPIRED || code === ERROR_CODES4.SESSION_CLOSED) {
+    return 410;
+  }
+  if (code === ERROR_CODES4.BRIDGE_BUSY) return 429;
+  if (code === ERROR_CODES4.ACTIVE_ADAPTER_LEASE_INVALID) return 401;
+  if (code === ERROR_CODES4.HANDOFF_RESPONSE_TOO_LARGE) return 413;
+  if (code === ERROR_CODES4.HANDOFF_CURSOR_INVALID || code === ERROR_CODES4.BRIDGE_PROTOCOL_MISMATCH || code === ERROR_CODES4.EXTERNAL_AGENT_BUSY || code === ERROR_CODES4.ACTIVE_ADAPTER_CONFLICT || code === ERROR_CODES4.ACTIVE_DISPATCH_INVALID) {
+    return 409;
+  }
+  if (code === ERROR_CODES4.INVALID_REQUEST) return 400;
+  return 500;
+}
+function normalizeError2(error) {
+  return error instanceof SpotPatchError4 ? error : new SpotPatchError4(ERROR_CODES4.INTERNAL_ERROR, void 0, { cause: error });
+}
+function assertAuthorized(request, expectedHost, bridgeToken) {
+  if (request.socket.remoteAddress !== "127.0.0.1" || singleHeader(request, "host") !== expectedHost || !tokensMatch(singleHeader(request, SPOTPATCH_BRIDGE_TOKEN_HEADER), bridgeToken)) {
+    throw new SpotPatchError4(ERROR_CODES4.BRIDGE_UNAUTHORIZED);
+  }
+}
+async function closeServer(server, sockets) {
+  await new Promise((resolve) => {
+    server.close(() => {
+      resolve();
+    });
+    for (const socket of sockets) {
+      socket.destroy();
+    }
+  });
+}
+async function createExternalHandoffBroker(options) {
+  const bridgeToken = randomBytes3(32).toString("base64url");
+  const sockets = /* @__PURE__ */ new Set();
+  let expectedHost = "";
+  const server = createServer(
+    { maxHeaderSize: EXTERNAL_HANDOFF_LIMITS2.maximumBrokerHeaderBytes },
+    (request, response) => {
+      const handle = async () => {
+        assertAuthorized(request, expectedHost, bridgeToken);
+        if (request.method !== "POST") {
+          throw new SpotPatchError4(ERROR_CODES4.INVALID_REQUEST);
+        }
+        const body = await readJsonRequestBody(
+          request,
+          EXTERNAL_HANDOFF_LIMITS2.maximumBrokerRequestBytes
+        );
+        if (request.url === SPOTPATCH_BRIDGE_PATHS.status) {
+          const parsed = bridgeStatusRequestSchema.safeParse(body);
+          if (!parsed.success) throw new SpotPatchError4(ERROR_CODES4.INVALID_REQUEST);
+          let current = null;
+          try {
+            current = options.store.status();
+          } catch (error) {
+            if (!(error instanceof SpotPatchError4) || error.code !== ERROR_CODES4.HANDOFF_NOT_FOUND) {
+              throw error;
+            }
+          }
+          writeJson(response, 200, {
+            ok: true,
+            data: Object.freeze({
+              brokerProtocolVersion: EXTERNAL_HANDOFF_BROKER_PROTOCOL_VERSION,
+              projectKey: options.projectKey,
+              sessionId: options.sessionId,
+              framework: options.framework,
+              current
+            })
+          });
+          return;
+        }
+        if (request.url === SPOTPATCH_BRIDGE_PATHS.current) {
+          const parsed = bridgeCurrentRequestSchema.safeParse(body);
+          if (!parsed.success) throw new SpotPatchError4(ERROR_CODES4.INVALID_REQUEST);
+          const snapshot2 = options.store.current(parsed.data.cursor);
+          writeJson(response, 200, {
+            ok: true,
+            data: Object.freeze({ outcome: "handoff", snapshot: snapshot2 })
+          });
+          return;
+        }
+        if (request.url === SPOTPATCH_BRIDGE_PATHS.ack) {
+          const parsed = bridgeAckRequestSchema.safeParse(body);
+          if (!parsed.success) throw new SpotPatchError4(ERROR_CODES4.INVALID_REQUEST);
+          const summary = options.store.ack(
+            parsed.data.cursor,
+            parsed.data.connectorInstanceId
+          );
+          writeJson(response, 200, {
+            ok: true,
+            data: Object.freeze({ summary })
+          });
+          return;
+        }
+        if (request.url === SPOTPATCH_BRIDGE_PATHS.wait) {
+          const parsed = bridgeWaitRequestSchema.safeParse(body);
+          if (!parsed.success) throw new SpotPatchError4(ERROR_CODES4.INVALID_REQUEST);
+          const controller = new AbortController();
+          const abort = () => {
+            if (!response.writableEnded) controller.abort("bridge-client-closed");
+          };
+          response.once("close", abort);
+          try {
+            const data = await options.store.wait(
+              parsed.data.afterCursor,
+              parsed.data.timeoutMs,
+              controller.signal
+            );
+            writeJson(response, 200, { ok: true, data });
+          } finally {
+            response.removeListener("close", abort);
+          }
+          return;
+        }
+        if (request.url === SPOTPATCH_BRIDGE_PATHS.activeClaim) {
+          const parsed = bridgeActiveClaimRequestSchema.safeParse(body);
+          if (!parsed.success) throw new SpotPatchError4(ERROR_CODES4.INVALID_REQUEST);
+          const data = options.activeRegistry.claim(
+            parsed.data.adapterKind,
+            parsed.data.connectorInstanceId,
+            options.store.currentCursor()
+          );
+          writeJson(response, 200, { ok: true, data });
+          return;
+        }
+        if (request.url === SPOTPATCH_BRIDGE_PATHS.activeHeartbeat) {
+          const parsed = bridgeActiveHeartbeatRequestSchema.safeParse(body);
+          if (!parsed.success) throw new SpotPatchError4(ERROR_CODES4.INVALID_REQUEST);
+          const data = options.activeRegistry.heartbeat(parsed.data.leaseToken);
+          writeJson(response, 200, { ok: true, data });
+          return;
+        }
+        if (request.url === SPOTPATCH_BRIDGE_PATHS.activeReport) {
+          const parsed = bridgeActiveReportRequestSchema.safeParse(body);
+          if (!parsed.success) throw new SpotPatchError4(ERROR_CODES4.INVALID_REQUEST);
+          const data = options.activeRegistry.report(
+            parsed.data.leaseToken,
+            parsed.data.cursor,
+            parsed.data.phase
+          );
+          writeJson(response, 200, { ok: true, data });
+          return;
+        }
+        if (request.url === SPOTPATCH_BRIDGE_PATHS.activeRelease) {
+          const parsed = bridgeActiveReleaseRequestSchema.safeParse(body);
+          if (!parsed.success) throw new SpotPatchError4(ERROR_CODES4.INVALID_REQUEST);
+          const data = options.activeRegistry.release(parsed.data.leaseToken);
+          writeJson(response, 200, { ok: true, data });
+          return;
+        }
+        throw new SpotPatchError4(ERROR_CODES4.INVALID_REQUEST);
+      };
+      void handle().catch((error) => {
+        if (response.writableEnded || response.destroyed) return;
+        const normalized = normalizeError2(error);
+        if (normalized.code === ERROR_CODES4.BRIDGE_BUSY) {
+          response.setHeader("Retry-After", "1");
+        }
+        writeJson(response, statusForError(normalized.code), {
+          ok: false,
+          error: {
+            code: normalized.code,
+            message: "The local SpotPatch bridge request failed."
+          }
+        });
+      });
+    }
+  );
+  server.maxConnections = EXTERNAL_HANDOFF_LIMITS2.maximumBrokerSockets;
+  server.headersTimeout = 5e3;
+  server.requestTimeout = EXTERNAL_HANDOFF_LIMITS2.maximumWaitMs + 5e3;
+  server.keepAliveTimeout = 1;
+  server.on("connection", (socket) => {
+    if (sockets.size >= EXTERNAL_HANDOFF_LIMITS2.maximumBrokerSockets) {
+      socket.destroy();
+      return;
+    }
+    sockets.add(socket);
+    socket.once("close", () => sockets.delete(socket));
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const address = server.address();
+  if (address === null || typeof address === "string" || address.address !== "127.0.0.1") {
+    await closeServer(server, sockets);
+    throw new Error("SpotPatch external Agent broker did not bind IPv4 loopback.");
+  }
+  expectedHost = `127.0.0.1:${String(address.port)}`;
+  let closed = false;
+  let ready = true;
+  server.removeAllListeners("error");
+  server.on("error", () => {
+    ready = false;
+    for (const socket of sockets) socket.destroy();
+  });
+  return Object.freeze({
+    bridgeToken,
+    endpoint: `http://${expectedHost}`,
+    isReady: () => ready && !closed,
+    async close() {
+      if (closed) return;
+      closed = true;
+      ready = false;
+      await closeServer(server, sockets);
+    }
+  });
+}
+
+// src/external-handoff/discovery.ts
+import { randomBytes as randomBytes4 } from "crypto";
+import { lstat, open, rename, unlink } from "fs/promises";
+import path from "path";
+import {
+  EXTERNAL_HANDOFF_BROKER_PROTOCOL_VERSION as EXTERNAL_HANDOFF_BROKER_PROTOCOL_VERSION2,
+  EXTERNAL_HANDOFF_LIMITS as EXTERNAL_HANDOFF_LIMITS3
+} from "@spotpatch/shared";
+import {
+  computeExternalHandoffProjectKey,
+  externalHandoffDescriptorSchema,
+  resolveExternalHandoffRuntimeDirectory
+} from "@spotpatch/shared/external-agent-node";
+async function syncDirectory(directory) {
+  const handle = await open(directory, "r");
+  try {
+    await handle.sync();
+  } catch (error) {
+    const code = error.code;
+    if (code !== "EINVAL" && code !== "ENOTSUP") {
+      throw error;
+    }
+  } finally {
+    await handle.close();
+  }
+}
+async function publishExternalHandoffDescriptor(options) {
+  const directory = await resolveExternalHandoffRuntimeDirectory(true);
+  const descriptor = externalHandoffDescriptorSchema.parse({
+    schemaVersion: 1,
+    brokerProtocolVersion: EXTERNAL_HANDOFF_BROKER_PROTOCOL_VERSION2,
+    projectKey: await computeExternalHandoffProjectKey(options.root),
+    sessionId: options.sessionId,
+    framework: options.framework,
+    endpoint: options.endpoint,
+    bridgeToken: options.bridgeToken,
+    pid: process.pid,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  const serialized = JSON.stringify(descriptor);
+  if (Buffer.byteLength(serialized, "utf8") > EXTERNAL_HANDOFF_LIMITS3.maximumDescriptorBytes) {
+    throw new RangeError("SpotPatch external Agent descriptor exceeds its limit.");
+  }
+  const destination = path.join(directory, `${descriptor.sessionId}.json`);
+  const temporary = path.join(
+    directory,
+    `.${descriptor.sessionId}.${randomBytes4(8).toString("hex")}.tmp`
+  );
+  let temporaryExists = false;
+  let published = false;
+  let descriptorIdentity = Object.freeze({
+    device: -1,
+    inode: -1
+  });
+  try {
+    const handle = await open(temporary, "wx", 384);
+    temporaryExists = true;
+    try {
+      await handle.writeFile(serialized, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temporary, destination);
+    temporaryExists = false;
+    published = true;
+    const status = await lstat(destination);
+    const uid = process.getuid?.();
+    if (!status.isFile() || status.isSymbolicLink() || uid === void 0 || status.uid !== uid || (status.mode & 63) !== 0) {
+      throw new Error("SpotPatch external Agent descriptor is not private.");
+    }
+    descriptorIdentity = Object.freeze({ device: status.dev, inode: status.ino });
+    await syncDirectory(directory);
+  } catch (error) {
+    if (temporaryExists) {
+      await unlink(temporary).catch(() => void 0);
+    }
+    if (published) {
+      await unlink(destination).catch(() => void 0);
+    }
+    throw error;
+  }
+  let closed = false;
+  return Object.freeze({
+    descriptor,
+    async close() {
+      if (closed) return;
+      closed = true;
+      await lstat(destination).then(async (status) => {
+        if (status.dev === descriptorIdentity.device && status.ino === descriptorIdentity.inode) {
+          await unlink(destination);
+        }
+      }).catch((error) => {
+        if (error.code !== "ENOENT") {
+          throw error;
+        }
+      });
+      await syncDirectory(directory);
+    }
+  });
+}
+
+// src/external-handoff/fingerprint.ts
+import { createHash as createHash2 } from "crypto";
+function canonicalJson(value) {
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError("Non-finite JSON number.");
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+  }
+  throw new TypeError("Unsupported JSON value.");
+}
+function fingerprintExternalHandoffAnnotation(annotation) {
+  return createHash2("sha256").update(canonicalJson(annotation)).digest("hex");
+}
+
+// src/external-handoff/store.ts
+import { randomBytes as randomBytes5 } from "crypto";
+import {
+  ERROR_CODES as ERROR_CODES5,
+  EXTERNAL_HANDOFF_LIMITS as EXTERNAL_HANDOFF_LIMITS4,
+  EXTERNAL_HANDOFF_SNAPSHOT_SCHEMA_VERSION,
+  SpotPatchError as SpotPatchError5
+} from "@spotpatch/shared";
+function defaultRandomId2() {
+  return randomBytes5(24).toString("base64url");
+}
+function pageSummary(annotation) {
+  let origin = "[unavailable]";
+  try {
+    const url = new URL(annotation.page.url);
+    origin = url.origin === "null" ? "[unavailable]" : url.origin;
+  } catch {
+  }
+  return Object.freeze({ origin, pathname: annotation.page.pathname });
+}
+function summaryOf(current, state) {
+  const snapshot2 = current.snapshot;
+  return Object.freeze({
+    sessionId: snapshot2.session.id,
+    framework: snapshot2.session.framework,
+    revision: snapshot2.revision,
+    cursor: snapshot2.cursor,
+    targetCount: snapshot2.annotation.targets.length,
+    page: pageSummary(snapshot2.annotation),
+    publishedAt: snapshot2.publishedAt,
+    expiresAt: snapshot2.expiresAt,
+    state,
+    pickupCount: current.receipts.size,
+    ...current.pickedUpAt === void 0 ? {} : { pickedUpAt: current.pickedUpAt }
+  });
+}
+function replayResult(record) {
+  return Object.freeze({ ...record.result, replayed: true });
+}
+function createExternalHandoffStore(options) {
+  const clock = options.clock ?? SYSTEM_EXTERNAL_HANDOFF_CLOCK;
+  const randomId = options.randomId ?? defaultRandomId2;
+  const history = [];
+  const idempotency = /* @__PURE__ */ new Map();
+  const waiters = /* @__PURE__ */ new Set();
+  let closed = false;
+  let current;
+  let revision = 0;
+  const requireOpen = () => {
+    if (closed) throw new SpotPatchError5(ERROR_CODES5.SESSION_CLOSED);
+  };
+  const archive = (state) => {
+    if (current === void 0) return;
+    history.unshift(summaryOf(current, state));
+    history.length = Math.min(
+      history.length,
+      EXTERNAL_HANDOFF_LIMITS4.maximumHistorySummaries
+    );
+    current = void 0;
+  };
+  const sweep = () => {
+    const monotonicNow = clock.monotonicNow();
+    if (current !== void 0 && monotonicNow >= current.expiresAtMonotonic) {
+      archive("expired");
+    }
+    for (const [requestId, record] of idempotency) {
+      if (monotonicNow >= record.expiresAtMonotonic) idempotency.delete(requestId);
+    }
+  };
+  const knownSummary = (cursor) => {
+    sweep();
+    if (current?.snapshot.cursor === cursor) {
+      return summaryOf(current, "available");
+    }
+    return history.find((summary) => summary.cursor === cursor);
+  };
+  const readCurrent = (cursor) => {
+    requireOpen();
+    sweep();
+    if (current === void 0) {
+      const prior = cursor === void 0 ? void 0 : knownSummary(cursor);
+      throw new SpotPatchError5(
+        prior?.state === "expired" ? ERROR_CODES5.HANDOFF_EXPIRED : cursor === void 0 ? ERROR_CODES5.HANDOFF_NOT_FOUND : ERROR_CODES5.HANDOFF_CURSOR_INVALID
+      );
+    }
+    if (cursor !== void 0 && cursor !== current.snapshot.cursor) {
+      const prior = knownSummary(cursor);
+      throw new SpotPatchError5(
+        prior?.state === "expired" ? ERROR_CODES5.HANDOFF_EXPIRED : ERROR_CODES5.HANDOFF_CURSOR_INVALID
+      );
+    }
+    return current.snapshot;
+  };
+  const findReplay = (requestId, fingerprint) => {
+    requireOpen();
+    sweep();
+    const record = idempotency.get(requestId);
+    if (record === void 0) return void 0;
+    if (record.fingerprint !== fingerprint) {
+      throw new SpotPatchError5(ERROR_CODES5.HANDOFF_VALIDATION_FAILED);
+    }
+    return replayResult(record);
+  };
+  const settleWaiters = (result) => {
+    const pending = [...waiters];
+    waiters.clear();
+    for (const waiter of pending) waiter.resolve(result);
+  };
+  return Object.freeze({
+    activeWaitCount: () => waiters.size,
+    replay: findReplay,
+    publish(input) {
+      requireOpen();
+      const replayed = findReplay(input.requestId, input.fingerprint);
+      if (replayed !== void 0) return replayed;
+      if (idempotency.size >= EXTERNAL_HANDOFF_LIMITS4.maximumRequestIdRecords) {
+        throw new SpotPatchError5(ERROR_CODES5.EXTERNAL_HANDOFF_UNAVAILABLE);
+      }
+      const nextRevision = revision + 1;
+      const publishedAtMs = clock.wallNow();
+      const publishedAtMonotonic = clock.monotonicNow();
+      const snapshot2 = Object.freeze({
+        schemaVersion: EXTERNAL_HANDOFF_SNAPSHOT_SCHEMA_VERSION,
+        cursor: randomId(),
+        session: Object.freeze({ id: options.sessionId, framework: options.framework }),
+        revision: nextRevision,
+        publishedAt: new Date(publishedAtMs).toISOString(),
+        expiresAt: new Date(
+          publishedAtMs + EXTERNAL_HANDOFF_LIMITS4.handoffTtlMs
+        ).toISOString(),
+        annotation: input.annotation
+      });
+      if (Buffer.byteLength(JSON.stringify(snapshot2), "utf8") > EXTERNAL_HANDOFF_LIMITS4.maximumSnapshotBytes) {
+        throw new SpotPatchError5(ERROR_CODES5.HANDOFF_RESPONSE_TOO_LARGE);
+      }
+      const delivery = input.reserve(snapshot2.cursor, nextRevision);
+      if (current !== void 0) archive("superseded");
+      revision = nextRevision;
+      current = {
+        expiresAtMonotonic: publishedAtMonotonic + EXTERNAL_HANDOFF_LIMITS4.handoffTtlMs,
+        receipts: /* @__PURE__ */ new Set(),
+        snapshot: snapshot2
+      };
+      const result = Object.freeze({
+        handoff: summaryOf(current, "available"),
+        delivery,
+        replayed: false
+      });
+      idempotency.set(
+        input.requestId,
+        Object.freeze({
+          expiresAtMonotonic: publishedAtMonotonic + EXTERNAL_HANDOFF_LIMITS4.requestIdTtlMs,
+          fingerprint: input.fingerprint,
+          result
+        })
+      );
+      settleWaiters(Object.freeze({ outcome: "handoff", snapshot: snapshot2 }));
+      return result;
+    },
+    current: readCurrent,
+    currentCursor() {
+      requireOpen();
+      sweep();
+      return current?.snapshot.cursor ?? null;
+    },
+    status(cursor) {
+      requireOpen();
+      sweep();
+      if (cursor === void 0) {
+        if (current === void 0) {
+          throw new SpotPatchError5(ERROR_CODES5.HANDOFF_NOT_FOUND);
+        }
+        return summaryOf(current, "available");
+      }
+      const summary = knownSummary(cursor);
+      if (summary === void 0) {
+        throw new SpotPatchError5(ERROR_CODES5.HANDOFF_CURSOR_INVALID);
+      }
+      return summary;
+    },
+    ack(cursor, connectorInstanceId) {
+      const snapshot2 = readCurrent(cursor);
+      if (snapshot2 !== current?.snapshot) {
+        throw new SpotPatchError5(ERROR_CODES5.HANDOFF_CURSOR_INVALID);
+      }
+      if (!current.receipts.has(connectorInstanceId)) {
+        if (current.receipts.size >= EXTERNAL_HANDOFF_LIMITS4.maximumConnectorReceipts) {
+          throw new SpotPatchError5(ERROR_CODES5.BRIDGE_BUSY);
+        }
+        current.receipts.add(connectorInstanceId);
+        current.pickedUpAt = new Date(clock.wallNow()).toISOString();
+      }
+      return summaryOf(current, "available");
+    },
+    async wait(afterCursor, timeoutMs, signal) {
+      requireOpen();
+      sweep();
+      if (afterCursor === void 0 && current !== void 0) {
+        return Object.freeze({ outcome: "handoff", snapshot: current.snapshot });
+      }
+      if (afterCursor !== void 0) {
+        const known = knownSummary(afterCursor);
+        if (known === void 0) {
+          throw new SpotPatchError5(ERROR_CODES5.HANDOFF_CURSOR_INVALID);
+        }
+        if (current !== void 0 && current.snapshot.cursor !== afterCursor) {
+          return Object.freeze({ outcome: "handoff", snapshot: current.snapshot });
+        }
+      }
+      if (waiters.size >= EXTERNAL_HANDOFF_LIMITS4.maximumWaiters) {
+        throw new SpotPatchError5(ERROR_CODES5.BRIDGE_BUSY);
+      }
+      if (signal.aborted) throw new SpotPatchError5(ERROR_CODES5.SESSION_CLOSED);
+      return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = () => {
+          if (settled) return false;
+          settled = true;
+          waiters.delete(waiter);
+          clearTimeout(timer);
+          signal.removeEventListener("abort", abort);
+          return true;
+        };
+        const waiter = {
+          reject(error) {
+            if (finish()) reject(error);
+          },
+          resolve(result) {
+            if (finish()) resolve(result);
+          }
+        };
+        const abort = () => {
+          waiter.reject(new SpotPatchError5(ERROR_CODES5.SESSION_CLOSED));
+        };
+        const timer = setTimeout(() => {
+          waiter.resolve(Object.freeze({ outcome: "timeout" }));
+        }, timeoutMs);
+        timer.unref();
+        signal.addEventListener("abort", abort, { once: true });
+        waiters.add(waiter);
+      });
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      current = void 0;
+      history.length = 0;
+      idempotency.clear();
+      const pending = [...waiters];
+      waiters.clear();
+      for (const waiter of pending) {
+        waiter.reject(new SpotPatchError5(ERROR_CODES5.SESSION_CLOSED));
+      }
+    }
+  });
+}
+
+// src/external-handoff/service.ts
+function asReplay(result) {
+  return Object.freeze({ ...result, replayed: true });
+}
+function createExternalHandoffService(options) {
+  const activeRegistry = createActiveAdapterRegistry();
+  const store = createExternalHandoffStore({
+    framework: options.framework,
+    sessionId: options.sessionId
+  });
+  const inFlight = /* @__PURE__ */ new Map();
+  let broker;
+  let descriptor;
+  let startPromise;
+  let closePromise;
+  let state = "idle";
+  const isClosed = () => state === "closed";
+  const requireReady = () => {
+    if (state !== "ready" || broker?.isReady() !== true) {
+      throw new SpotPatchError6(
+        state === "closed" ? ERROR_CODES6.SESSION_CLOSED : ERROR_CODES6.EXTERNAL_HANDOFF_UNAVAILABLE
+      );
+    }
+  };
+  const start = async () => {
+    if (state === "ready") return;
+    if (state === "closed") throw new SpotPatchError6(ERROR_CODES6.SESSION_CLOSED);
+    if (startPromise !== void 0) return startPromise;
+    state = "starting";
+    startPromise = (async () => {
+      let createdBroker;
+      let createdDescriptor;
+      try {
+        const projectKey = await computeExternalHandoffProjectKey2(options.root);
+        createdBroker = await createExternalHandoffBroker({
+          activeRegistry,
+          framework: options.framework,
+          projectKey,
+          sessionId: options.sessionId,
+          store
+        });
+        createdDescriptor = await publishExternalHandoffDescriptor({
+          bridgeToken: createdBroker.bridgeToken,
+          endpoint: createdBroker.endpoint,
+          framework: options.framework,
+          root: options.root,
+          sessionId: options.sessionId
+        });
+        if (isClosed()) {
+          await createdDescriptor.close();
+          await createdBroker.close();
+          throw new SpotPatchError6(ERROR_CODES6.SESSION_CLOSED);
+        }
+        broker = createdBroker;
+        descriptor = createdDescriptor;
+        state = "ready";
+      } catch (error) {
+        if (createdDescriptor !== void 0 && descriptor !== createdDescriptor) {
+          await createdDescriptor.close().catch(() => void 0);
+        }
+        if (createdBroker !== void 0 && broker !== createdBroker) {
+          await createdBroker.close().catch(() => void 0);
+        }
+        if (!isClosed()) state = "failed";
+        throw error;
+      }
+    })();
+    return startPromise;
+  };
+  return Object.freeze({
+    start,
+    capability() {
+      const currentCursor = store.currentCursor();
+      const active = activeRegistry.snapshot(currentCursor ?? void 0);
+      return Object.freeze({
+        enabled: true,
+        brokerReady: state === "ready" && broker?.isReady() === true,
+        activeWaitCount: store.activeWaitCount(),
+        snapshotSchemaVersion: EXTERNAL_HANDOFF_SNAPSHOT_SCHEMA_VERSION2,
+        brokerProtocolVersion: EXTERNAL_HANDOFF_BROKER_PROTOCOL_VERSION3,
+        activeAdapter: active.activeAdapter,
+        dispatch: currentCursor === null ? null : active.dispatch
+      });
+    },
+    async publish(request, authorize) {
+      requireReady();
+      const fingerprint = fingerprintExternalHandoffAnnotation(request.annotation);
+      const replayed = store.replay(request.requestId, fingerprint);
+      if (replayed !== void 0) return replayed;
+      const pending = inFlight.get(request.requestId);
+      if (pending !== void 0) {
+        if (pending.fingerprint !== fingerprint) {
+          throw new SpotPatchError6(ERROR_CODES6.HANDOFF_VALIDATION_FAILED);
+        }
+        return asReplay(await pending.promise);
+      }
+      activeRegistry.assertPublishable();
+      const promise = (async () => {
+        const annotation = await authorize(request.annotation);
+        return store.publish({
+          annotation,
+          fingerprint,
+          requestId: request.requestId,
+          reserve: activeRegistry.reserve
+        });
+      })();
+      const activePublish = Object.freeze({ fingerprint, promise });
+      inFlight.set(request.requestId, activePublish);
+      try {
+        return await promise;
+      } finally {
+        if (inFlight.get(request.requestId) === activePublish) {
+          inFlight.delete(request.requestId);
+        }
+      }
+    },
+    status(cursor) {
+      requireReady();
+      const handoff = store.status(cursor);
+      const active = activeRegistry.snapshot(cursor ?? handoff.cursor);
+      return Object.freeze({
+        handoff,
+        activeAdapter: active.activeAdapter,
+        dispatch: active.dispatch
+      });
+    },
+    resolveDelivery(cursor) {
+      requireReady();
+      const handoff = store.status(cursor);
+      const active = activeRegistry.resolveDelivery(cursor);
+      return Object.freeze({
+        handoff,
+        activeAdapter: active.activeAdapter,
+        dispatch: active.dispatch
+      });
+    },
+    close() {
+      closePromise ??= (async () => {
+        if (state === "closed") return;
+        state = "closed";
+        activeRegistry.close();
+        store.close();
+        inFlight.clear();
+        await startPromise?.catch(() => void 0);
+        const publishedDescriptor = descriptor;
+        descriptor = void 0;
+        const activeBroker = broker;
+        broker = void 0;
+        await publishedDescriptor?.close().catch(() => void 0);
+        await activeBroker?.close().catch(() => void 0);
+      })();
+      return closePromise;
+    }
+  });
+}
+
 // src/environment-ai.ts
 var AI_ENVIRONMENT_NAMES = Object.freeze({
   authentication: "SPOTPATCH_AI_AUTHENTICATION",
@@ -562,32 +1659,32 @@ function resolveEnvironmentAiConfiguration(environment) {
 }
 
 // src/integration/file-plan.ts
-import { randomBytes as randomBytes2 } from "crypto";
+import { randomBytes as randomBytes6 } from "crypto";
 import {
   access,
-  lstat,
+  lstat as lstat2,
   mkdir,
   readFile,
   realpath,
-  rename,
+  rename as rename2,
   stat,
-  unlink,
+  unlink as unlink2,
   writeFile
 } from "fs/promises";
-import path from "path";
+import path2 from "path";
 function isMissingPathError(error) {
   return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 }
 function isPathWithin(root, target) {
-  const relative = path.relative(root, target);
-  return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+  const relative = path2.relative(root, target);
+  return relative === "" || relative !== ".." && !relative.startsWith(`..${path2.sep}`) && !path2.isAbsolute(relative);
 }
 function relativePathWithin(root, target) {
-  const relative = path.relative(root, target);
+  const relative = path2.relative(root, target);
   if (relative.length === 0 || !isPathWithin(root, target)) {
     throw new Error("SpotPatch init refuses to modify a path outside the app root.");
   }
-  return relative.split(path.sep).join("/");
+  return relative.split(path2.sep).join("/");
 }
 async function integrationPathExists(absolutePath) {
   try {
@@ -598,10 +1695,10 @@ async function integrationPathExists(absolutePath) {
   }
 }
 async function readIntegrationFile(absolutePath) {
-  const metadata = await lstat(absolutePath);
+  const metadata = await lstat2(absolutePath);
   if (!metadata.isFile() || metadata.isSymbolicLink()) {
     throw new Error(
-      `SpotPatch refuses to modify the non-regular file ${path.basename(absolutePath)}.`
+      `SpotPatch refuses to modify the non-regular file ${path2.basename(absolutePath)}.`
     );
   }
   return readFile(absolutePath, "utf8");
@@ -610,8 +1707,8 @@ function createIntegrationFileChange(appRoot, absolutePath, nextContent, previou
   if (previousContent === nextContent) {
     return void 0;
   }
-  const root = path.resolve(appRoot);
-  const target = path.resolve(absolutePath);
+  const root = path2.resolve(appRoot);
+  const target = path2.resolve(absolutePath);
   return Object.freeze({
     absolutePath: target,
     nextContent,
@@ -620,19 +1717,19 @@ function createIntegrationFileChange(appRoot, absolutePath, nextContent, previou
   });
 }
 function temporaryPath(absolutePath, label) {
-  return path.join(
-    path.dirname(absolutePath),
-    `.${path.basename(absolutePath)}.spotpatch-${label}-${String(process.pid)}-${randomBytes2(8).toString("hex")}`
+  return path2.join(
+    path2.dirname(absolutePath),
+    `.${path2.basename(absolutePath)}.spotpatch-${label}-${String(process.pid)}-${randomBytes6(8).toString("hex")}`
   );
 }
 async function writeAtomic(absolutePath, content, mode) {
-  await mkdir(path.dirname(absolutePath), { recursive: true });
+  await mkdir(path2.dirname(absolutePath), { recursive: true });
   const stagedPath = temporaryPath(absolutePath, "stage");
   try {
     await writeFile(stagedPath, content, { encoding: "utf8", flag: "wx", mode });
-    await rename(stagedPath, absolutePath);
+    await rename2(stagedPath, absolutePath);
   } catch (error) {
-    await unlink(stagedPath).catch(() => void 0);
+    await unlink2(stagedPath).catch(() => void 0);
     throw error;
   }
 }
@@ -644,21 +1741,21 @@ async function rollbackChange(change) {
     );
   }
   if (change.previousContent === void 0) {
-    await unlink(change.absolutePath);
+    await unlink2(change.absolutePath);
     return;
   }
   const mode = (await stat(change.absolutePath)).mode & 511;
   await writeAtomic(change.absolutePath, change.previousContent, mode);
 }
 async function assertSafeTarget(appRoot, realAppRoot, change) {
-  const target = path.resolve(change.absolutePath);
+  const target = path2.resolve(change.absolutePath);
   const relativePath = relativePathWithin(appRoot, target);
-  if (target !== change.absolutePath || relativePath !== change.relativePath || path.dirname(target) === target) {
+  if (target !== change.absolutePath || relativePath !== change.relativePath || path2.dirname(target) === target) {
     throw new Error("SpotPatch init received an invalid integration file plan.");
   }
   let targetMetadata;
   try {
-    targetMetadata = await lstat(target);
+    targetMetadata = await lstat2(target);
   } catch (error) {
     if (!isMissingPathError(error)) {
       throw error;
@@ -670,7 +1767,7 @@ async function assertSafeTarget(appRoot, realAppRoot, change) {
     );
   }
   const containmentAnchor = await realpath(
-    targetMetadata === void 0 ? path.dirname(target) : target
+    targetMetadata === void 0 ? path2.dirname(target) : target
   );
   if (!isPathWithin(realAppRoot, containmentAnchor)) {
     throw new Error("SpotPatch init refuses to modify a path outside the app root.");
@@ -679,7 +1776,7 @@ async function assertSafeTarget(appRoot, realAppRoot, change) {
 async function assertCurrentBaseline(change) {
   if (change.previousContent === void 0) {
     try {
-      await lstat(change.absolutePath);
+      await lstat2(change.absolutePath);
     } catch (error) {
       if (isMissingPathError(error)) {
         return;
@@ -701,7 +1798,7 @@ async function applyIntegrationPlan(plan) {
   if (plan.changes.length === 0) {
     return;
   }
-  const appRoot = path.resolve(plan.appRoot);
+  const appRoot = path2.resolve(plan.appRoot);
   const realAppRoot = await realpath(appRoot);
   const targets = /* @__PURE__ */ new Set();
   for (const change of plan.changes) {
@@ -780,7 +1877,8 @@ var DEFAULT_OPTIONS = Object.freeze({
     enabled: false,
     runtime: "dispatch",
     limits: DEFAULT_DATA_FLOW_LIMITS
-  })
+  }),
+  externalAgent: Object.freeze({ enabled: false })
 });
 var PROFILE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 var ENV_NAME_PATTERN = /^[A-Z][A-Z0-9_]{1,127}$/;
@@ -1106,6 +2204,9 @@ function resolveOptions(options = {}, environmentAi) {
   if (options.trustedFastMode !== void 0 && typeof options.trustedFastMode !== "boolean") {
     throw new RangeError("SpotPatch trustedFastMode must be a boolean.");
   }
+  if (options.externalAgent !== void 0 && typeof options.externalAgent !== "boolean") {
+    throw new RangeError("SpotPatch externalAgent must be a boolean.");
+  }
   const budget = Object.freeze({
     ...DEFAULT_OPTIONS.budget,
     ...options.budget
@@ -1138,7 +2239,10 @@ function resolveOptions(options = {}, environmentAi) {
     locale,
     maxTargets,
     ai: resolveAiOptions(options.ai ?? environmentAi),
-    dataFlow: resolveDataFlowOptions(options.dataFlow)
+    dataFlow: resolveDataFlowOptions(options.dataFlow),
+    externalAgent: Object.freeze({
+      enabled: options.externalAgent ?? DEFAULT_OPTIONS.externalAgent.enabled
+    })
   };
   if (resolved.shortcut.trim().length === 0 || resolved.shortcut.length > 128 || resolved.shortcut.includes("\0")) {
     throw new RangeError("SpotPatch shortcut is invalid.");
@@ -1148,9 +2252,9 @@ function resolveOptions(options = {}, environmentAi) {
 
 // src/project-validation.ts
 import { execFile } from "child_process";
-import { access as access2, lstat as lstat2, readFile as readFile2, realpath as realpath2 } from "fs/promises";
+import { access as access2, lstat as lstat3, readFile as readFile2, realpath as realpath2 } from "fs/promises";
 import { createRequire } from "module";
-import path2 from "path";
+import path3 from "path";
 import { promisify } from "util";
 var execFileAsync = promisify(execFile);
 var TYPESCRIPT_CHECK_ID = "spotpatch-typecheck";
@@ -1160,14 +2264,14 @@ function isRecord(value) {
 }
 async function isRegularFile(absolutePath) {
   try {
-    const metadata = await lstat2(absolutePath);
+    const metadata = await lstat3(absolutePath);
     return metadata.isFile() && !metadata.isSymbolicLink();
   } catch {
     return false;
   }
 }
 async function readManifest(appRoot) {
-  const manifestPath = path2.join(appRoot, "package.json");
+  const manifestPath = path3.join(appRoot, "package.json");
   if (!await isRegularFile(manifestPath)) {
     return void 0;
   }
@@ -1196,8 +2300,8 @@ async function findGitRoot(appRoot) {
       windowsHide: true
     });
     const root = await realpath2(result.stdout.trim());
-    const relative = path2.relative(root, appRoot);
-    if (relative === "" || !relative.startsWith(`..${path2.sep}`) && relative !== ".." && !path2.isAbsolute(relative)) {
+    const relative = path3.relative(root, appRoot);
+    if (relative === "" || !relative.startsWith(`..${path3.sep}`) && relative !== ".." && !path3.isAbsolute(relative)) {
       return root;
     }
   } catch {
@@ -1206,10 +2310,10 @@ async function findGitRoot(appRoot) {
   return void 0;
 }
 async function resolveTypeScriptCli(appRoot) {
-  const resolveFromApplication = createRequire(path2.join(appRoot, "package.json"));
+  const resolveFromApplication = createRequire(path3.join(appRoot, "package.json"));
   try {
     const packagePath = resolveFromApplication.resolve("typescript/package.json");
-    const cliPath = path2.join(path2.dirname(packagePath), "bin", "tsc");
+    const cliPath = path3.join(path3.dirname(packagePath), "bin", "tsc");
     await access2(cliPath);
     return await realpath2(cliPath);
   } catch {
@@ -1217,11 +2321,11 @@ async function resolveTypeScriptCli(appRoot) {
   }
 }
 function portableRelativePath(from, to) {
-  return path2.relative(from, to).split(path2.sep).join("/");
+  return path3.relative(from, to).split(path3.sep).join("/");
 }
 async function discoverProjectValidationCheck(options) {
   const appRoot = await realpath2(options.appRoot);
-  const tsconfigPath = path2.join(appRoot, "tsconfig.json");
+  const tsconfigPath = path3.join(appRoot, "tsconfig.json");
   const [manifest, projectRoot, hasTsconfig] = await Promise.all([
     readManifest(appRoot),
     findGitRoot(appRoot),
@@ -1309,16 +2413,16 @@ async function resolveProjectOptions(input) {
 }
 
 // src/registry/source-registry.ts
-import path3 from "path";
+import path4 from "path";
 
 // src/registry/source-id.ts
-import { randomBytes as randomBytes3 } from "crypto";
+import { randomBytes as randomBytes7 } from "crypto";
 var SOURCE_ID_BYTES = 8;
-var createRandomSourceId = () => randomBytes3(SOURCE_ID_BYTES).toString("base64url");
+var createRandomSourceId = () => randomBytes7(SOURCE_ID_BYTES).toString("base64url");
 
 // src/registry/source-registry.ts
 function normalizeAbsolutePath(absolutePath) {
-  return path3.normalize(path3.resolve(absolutePath));
+  return path4.normalize(path4.resolve(absolutePath));
 }
 function createSourceRegistry(options = {}) {
   const createId = options.createId ?? createRandomSourceId;
@@ -1376,39 +2480,42 @@ function createSourceRegistry(options = {}) {
 
 // src/server/middleware.ts
 import {
-  ERROR_CODES as ERROR_CODES10,
+  ERROR_CODES as ERROR_CODES15,
   SPOTPATCH_API_BASE,
-  SPOTPATCH_ENDPOINTS as SPOTPATCH_ENDPOINTS2,
-  SpotPatchError as SpotPatchError10,
+  SPOTPATCH_ENDPOINTS as SPOTPATCH_ENDPOINTS3,
+  SpotPatchError as SpotPatchError15,
   openEditorRequestSchema,
   sourceContextRequestSchema
 } from "@spotpatch/shared";
 
-// src/server/agent-http.ts
+// src/external-handoff/browser-http.ts
 import {
-  ERROR_CODES as ERROR_CODES6,
+  ERROR_CODES as ERROR_CODES10,
+  EXTERNAL_HANDOFF_LIMITS as EXTERNAL_HANDOFF_LIMITS5,
   SPOTPATCH_ENDPOINTS,
-  SpotPatchError as SpotPatchError6,
-  agentCapabilityRequestSchema,
-  agentJobActionRequestSchema,
-  agentJobCreateRequestSchema,
-  agentWorkspaceHealthRequestSchema
+  SpotPatchError as SpotPatchError10,
+  externalHandoffCapabilityRequestSchema,
+  externalHandoffPublishRequestSchema,
+  externalHandoffResolveDeliveryRequestSchema,
+  externalHandoffStatusRequestSchema
 } from "@spotpatch/shared";
 
-// src/server/agent-request.ts
+// src/server/annotation-authorizer.ts
 import { realpath as realpath5 } from "fs/promises";
-import path6 from "path";
+import path7 from "path";
 import {
-  ERROR_CODES as ERROR_CODES4,
-  SpotPatchError as SpotPatchError4
+  ERROR_CODES as ERROR_CODES9,
+  SpotPatchError as SpotPatchError9,
+  redactSensitiveText,
+  sanitizeUrl
 } from "@spotpatch/shared";
 
 // src/server/source-context.ts
 import { readFile as readFile3, realpath as realpath4 } from "fs/promises";
-import path5 from "path";
+import path6 from "path";
 import {
-  ERROR_CODES as ERROR_CODES3,
-  SpotPatchError as SpotPatchError3
+  ERROR_CODES as ERROR_CODES8,
+  SpotPatchError as SpotPatchError8
 } from "@spotpatch/shared";
 
 // src/server/extract-code-context.ts
@@ -1642,15 +2749,8 @@ function extractCodeContext(options) {
 
 // src/server/source-file.ts
 import { realpath as realpath3, stat as stat2 } from "fs/promises";
-import path4 from "path";
-import { ERROR_CODES as ERROR_CODES2, SpotPatchError as SpotPatchError2 } from "@spotpatch/shared";
-
-// src/server/constants.ts
-var MAX_REQUEST_BODY_BYTES = 32 * 1024;
-var MAX_AGENT_REQUEST_BODY_BYTES = 256 * 1024;
-var MAX_SOURCE_FILE_BYTES = 1024 * 1024;
-
-// src/server/source-file.ts
+import path5 from "path";
+import { ERROR_CODES as ERROR_CODES7, SpotPatchError as SpotPatchError7 } from "@spotpatch/shared";
 var ALLOWED_EXTENSIONS = /* @__PURE__ */ new Set([".jsx", ".tsx"]);
 function isMissingFileError(error) {
   return error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
@@ -1665,51 +2765,51 @@ async function assertInsideRoot(root, candidate) {
     ]);
   } catch (error) {
     if (isMissingFileError(error)) {
-      throw new SpotPatchError2(ERROR_CODES2.SOURCE_NOT_FOUND, void 0, {
+      throw new SpotPatchError7(ERROR_CODES7.SOURCE_NOT_FOUND, void 0, {
         cause: error
       });
     }
     throw error;
   }
-  const relative = path4.relative(realRoot, realCandidate);
-  const outside = relative.startsWith(`..${path4.sep}`) || relative === ".." || path4.isAbsolute(relative);
+  const relative = path5.relative(realRoot, realCandidate);
+  const outside = relative.startsWith(`..${path5.sep}`) || relative === ".." || path5.isAbsolute(relative);
   if (outside) {
-    throw new SpotPatchError2(ERROR_CODES2.SOURCE_OUTSIDE_ROOT);
+    throw new SpotPatchError7(ERROR_CODES7.SOURCE_OUTSIDE_ROOT);
   }
   return realCandidate;
 }
 async function resolveSourceFile(options) {
   const registeredPath = options.registry.resolve(options.fileId);
   if (registeredPath === void 0) {
-    throw new SpotPatchError2(ERROR_CODES2.SOURCE_NOT_FOUND);
+    throw new SpotPatchError7(ERROR_CODES7.SOURCE_NOT_FOUND);
   }
   const sourcePath = await assertInsideRoot(options.root, registeredPath);
-  if (!ALLOWED_EXTENSIONS.has(path4.extname(sourcePath).toLowerCase())) {
-    throw new SpotPatchError2(ERROR_CODES2.SOURCE_NOT_FOUND);
+  if (!ALLOWED_EXTENSIONS.has(path5.extname(sourcePath).toLowerCase())) {
+    throw new SpotPatchError7(ERROR_CODES7.SOURCE_NOT_FOUND);
   }
   let sourceStat;
   try {
     sourceStat = await stat2(sourcePath);
   } catch (error) {
     if (isMissingFileError(error)) {
-      throw new SpotPatchError2(ERROR_CODES2.SOURCE_NOT_FOUND, void 0, {
+      throw new SpotPatchError7(ERROR_CODES7.SOURCE_NOT_FOUND, void 0, {
         cause: error
       });
     }
     throw error;
   }
   if (!sourceStat.isFile()) {
-    throw new SpotPatchError2(ERROR_CODES2.SOURCE_NOT_FOUND);
+    throw new SpotPatchError7(ERROR_CODES7.SOURCE_NOT_FOUND);
   }
   if (sourceStat.size > MAX_SOURCE_FILE_BYTES) {
-    throw new SpotPatchError2(ERROR_CODES2.SOURCE_TOO_LARGE);
+    throw new SpotPatchError7(ERROR_CODES7.SOURCE_TOO_LARGE);
   }
   return sourcePath;
 }
 
 // src/server/source-context.ts
 function toDisplayPath(root, sourcePath) {
-  return path5.relative(root, sourcePath).split(path5.sep).join("/");
+  return path6.relative(root, sourcePath).split(path6.sep).join("/");
 }
 async function readSourceContext(options) {
   const sourcePath = await resolveSourceFile({
@@ -1722,7 +2822,7 @@ async function readSourceContext(options) {
     source = await readFile3(sourcePath, "utf8");
   } catch (error) {
     if (error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
-      throw new SpotPatchError3(ERROR_CODES3.SOURCE_NOT_FOUND, void 0, {
+      throw new SpotPatchError8(ERROR_CODES8.SOURCE_NOT_FOUND, void 0, {
         cause: error
       });
     }
@@ -1730,9 +2830,9 @@ async function readSourceContext(options) {
   }
   const lines = source.split(/\r?\n/);
   if (options.request.line > lines.length) {
-    throw new SpotPatchError3(ERROR_CODES3.INVALID_REQUEST);
+    throw new SpotPatchError8(ERROR_CODES8.INVALID_REQUEST);
   }
-  const extension = path5.extname(sourcePath).toLowerCase();
+  const extension = path6.extname(sourcePath).toLowerCase();
   return extractCodeContext({
     source,
     sourcePath,
@@ -1745,7 +2845,17 @@ async function readSourceContext(options) {
   });
 }
 
-// src/server/agent-request.ts
+// src/server/annotation-authorizer.ts
+function sanitizePageContext(page) {
+  return Object.freeze({
+    url: sanitizeUrl(page.url, page.url),
+    pathname: redactSensitiveText(page.pathname),
+    title: redactSensitiveText(page.title),
+    viewportWidth: page.viewportWidth,
+    viewportHeight: page.viewportHeight,
+    devicePixelRatio: page.devicePixelRatio
+  });
+}
 function compactSourceRef(source) {
   return Object.freeze({
     origin: source.origin,
@@ -1759,27 +2869,20 @@ function compactSourceRef(source) {
 async function authorizeSourceRef(source, registry, root) {
   const markerOrigin = source.origin === "jsx-host" || source.origin === "dom-ancestor";
   if (markerOrigin && (source.fileId === void 0 || source.line === void 0 || source.column === void 0)) {
-    throw new SpotPatchError4(ERROR_CODES4.INVALID_REQUEST);
+    throw new SpotPatchError9(ERROR_CODES9.INVALID_REQUEST);
   }
   if (source.fileId === void 0) {
     if (source.origin === "none" && source.relativePath !== void 0) {
-      throw new SpotPatchError4(ERROR_CODES4.INVALID_REQUEST);
+      throw new SpotPatchError9(ERROR_CODES9.INVALID_REQUEST);
     }
     return compactSourceRef(source);
   }
-  const sourcePath = await resolveSourceFile({
-    fileId: source.fileId,
-    registry,
-    root
-  });
-  const relativePath = path6.relative(await realpath5(root), sourcePath).split(path6.sep).join("/");
+  const sourcePath = await resolveSourceFile({ fileId: source.fileId, registry, root });
+  const relativePath = path7.relative(await realpath5(root), sourcePath).split(path7.sep).join("/");
   if (source.relativePath !== void 0 && source.relativePath !== relativePath) {
-    throw new SpotPatchError4(ERROR_CODES4.INVALID_REQUEST);
+    throw new SpotPatchError9(ERROR_CODES9.INVALID_REQUEST);
   }
-  return Object.freeze({
-    ...compactSourceRef(source),
-    relativePath
-  });
+  return Object.freeze({ ...compactSourceRef(source), relativePath });
 }
 function freezeMatchedRule(rule) {
   return Object.freeze({
@@ -1813,7 +2916,7 @@ async function authorizeTarget(target, input) {
     maxLines: input.options.budget.maxCodeLines
   });
   if (marker === void 0 && target.code !== void 0) {
-    throw new SpotPatchError4(ERROR_CODES4.INVALID_REQUEST);
+    throw new SpotPatchError9(ERROR_CODES9.INVALID_REQUEST);
   }
   const code = marker === void 0 ? void 0 : await readSourceContext({
     request: marker,
@@ -1823,11 +2926,11 @@ async function authorizeTarget(target, input) {
     maxLines: input.options.budget.maxCodeLines
   });
   if (target.code !== void 0 && target.code.relativePath !== code?.relativePath) {
-    throw new SpotPatchError4(ERROR_CODES4.INVALID_REQUEST);
+    throw new SpotPatchError9(ERROR_CODES9.INVALID_REQUEST);
   }
   return Object.freeze({
     instruction: target.instruction,
-    ...target.page === void 0 ? {} : { page: Object.freeze({ ...target.page }) },
+    ...target.page === void 0 ? {} : { page: sanitizePageContext(target.page) },
     source,
     react: Object.freeze({
       supported: target.react.supported,
@@ -1855,76 +2958,138 @@ async function authorizeTarget(target, input) {
     warnings: Object.freeze([...target.warnings])
   });
 }
-async function authorizeAgentJobRequest(input) {
-  const requestedTargets = input.request.annotation.targets;
+async function authorizeAnnotation(input) {
+  const requestedTargets = input.annotation.targets;
   if (requestedTargets.length > input.options.maxTargets) {
-    throw new SpotPatchError4(ERROR_CODES4.INVALID_REQUEST);
+    throw new SpotPatchError9(ERROR_CODES9.INVALID_REQUEST);
   }
   const identities = requestedTargets.map(targetIdentity);
   if (new Set(identities).size !== identities.length) {
-    throw new SpotPatchError4(ERROR_CODES4.INVALID_REQUEST);
+    throw new SpotPatchError9(ERROR_CODES9.INVALID_REQUEST);
   }
   const targets = Object.freeze(
     await Promise.all(requestedTargets.map((target) => authorizeTarget(target, input)))
   );
-  const annotation = Object.freeze({
+  return Object.freeze({
     schemaVersion: 3,
-    id: input.request.annotation.id,
-    locale: input.request.annotation.locale,
-    page: Object.freeze({ ...input.request.annotation.page }),
+    id: input.annotation.id,
+    locale: input.annotation.locale,
+    page: sanitizePageContext(input.annotation.page),
     targets,
-    createdAt: input.request.annotation.createdAt
-  });
-  return Object.freeze({
-    annotation,
-    ...input.request.applyMode === void 0 ? {} : { applyMode: input.request.applyMode },
-    providerProfileId: input.request.providerProfileId,
-    modelProfileId: input.request.modelProfileId,
-    providerDataConsent: true,
-    ...input.request.trustedFastModeConsent === true ? { trustedFastModeConsent: true } : {},
-    workingTreeMode: input.request.workingTreeMode
+    createdAt: input.annotation.createdAt
   });
 }
 
-// src/server/request-body.ts
-import { ERROR_CODES as ERROR_CODES5, SpotPatchError as SpotPatchError5 } from "@spotpatch/shared";
-function isJsonContentType(value) {
-  return value?.split(";", 1)[0]?.trim().toLowerCase() === "application/json";
-}
-async function readJsonRequestBody(request, maximumBytes = MAX_REQUEST_BODY_BYTES) {
-  if (!isJsonContentType(request.headers["content-type"])) {
-    throw new SpotPatchError5(ERROR_CODES5.INVALID_REQUEST);
+// src/external-handoff/browser-http.ts
+function matchExternalHandoffBrowserPath(path9) {
+  if (path9 === SPOTPATCH_ENDPOINTS.externalHandoffCapability) return "capability";
+  if (path9 === SPOTPATCH_ENDPOINTS.externalHandoffPublish) return "publish";
+  if (path9 === SPOTPATCH_ENDPOINTS.externalHandoffStatus) return "status";
+  if (path9 === SPOTPATCH_ENDPOINTS.externalHandoffResolveDelivery) {
+    return "resolve-delivery";
   }
-  const declaredLength = Number(request.headers["content-length"]);
-  if (Number.isFinite(declaredLength) && declaredLength > maximumBytes) {
-    throw new SpotPatchError5(ERROR_CODES5.INVALID_REQUEST);
+  return void 0;
+}
+function requireService(options) {
+  if (!options.options.externalAgent.enabled || options.service === void 0) {
+    throw new SpotPatchError10(ERROR_CODES10.EXTERNAL_HANDOFF_DISABLED);
   }
-  const chunks = [];
-  let byteLength = 0;
-  let exceededLimit = false;
-  for await (const rawChunk of request) {
-    const chunk = rawChunk;
-    if (typeof chunk !== "string" && !(chunk instanceof Uint8Array)) {
-      throw new SpotPatchError5(ERROR_CODES5.INVALID_REQUEST);
+  return options.service;
+}
+function remapAuthorizationError(error) {
+  if (error instanceof SpotPatchError10) {
+    if (error.code === ERROR_CODES10.SOURCE_NOT_FOUND || error.code === ERROR_CODES10.SOURCE_OUTSIDE_ROOT || error.code === ERROR_CODES10.SOURCE_TOO_LARGE) {
+      throw new SpotPatchError10(ERROR_CODES10.HANDOFF_SOURCE_STALE, void 0, {
+        cause: error
+      });
     }
-    const buffer = Buffer.from(chunk);
-    byteLength += buffer.byteLength;
-    if (byteLength > maximumBytes) {
-      exceededLimit = true;
-      continue;
+    if (error.code === ERROR_CODES10.INVALID_REQUEST) {
+      throw new SpotPatchError10(ERROR_CODES10.HANDOFF_VALIDATION_FAILED, void 0, {
+        cause: error
+      });
     }
-    chunks.push(buffer);
   }
-  if (exceededLimit || byteLength === 0) {
-    throw new SpotPatchError5(ERROR_CODES5.INVALID_REQUEST);
+  throw error;
+}
+async function handleExternalHandoffBrowserRequest(request, response, route, options, writeSuccess) {
+  if (request.method !== "POST") {
+    throw new SpotPatchError10(ERROR_CODES10.INVALID_REQUEST);
   }
-  try {
-    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
-  } catch (error) {
-    throw new SpotPatchError5(ERROR_CODES5.INVALID_REQUEST, void 0, {
-      cause: error
-    });
+  const service = requireService(options);
+  if (route === "capability") {
+    const parsed2 = externalHandoffCapabilityRequestSchema.safeParse(
+      await readJsonRequestBody(request)
+    );
+    if (!parsed2.success) throw new SpotPatchError10(ERROR_CODES10.INVALID_REQUEST);
+    writeSuccess(response, 200, service.capability());
+    return;
   }
+  if (route === "status") {
+    const parsed2 = externalHandoffStatusRequestSchema.safeParse(
+      await readJsonRequestBody(request)
+    );
+    if (!parsed2.success) throw new SpotPatchError10(ERROR_CODES10.INVALID_REQUEST);
+    writeSuccess(response, 200, service.status(parsed2.data.cursor));
+    return;
+  }
+  if (route === "resolve-delivery") {
+    const parsed2 = externalHandoffResolveDeliveryRequestSchema.safeParse(
+      await readJsonRequestBody(request)
+    );
+    if (!parsed2.success) throw new SpotPatchError10(ERROR_CODES10.INVALID_REQUEST);
+    writeSuccess(response, 200, service.resolveDelivery(parsed2.data.cursor));
+    return;
+  }
+  const parsed = externalHandoffPublishRequestSchema.safeParse(
+    await readJsonRequestBody(request, EXTERNAL_HANDOFF_LIMITS5.maximumPublishBodyBytes)
+  );
+  if (!parsed.success) {
+    throw new SpotPatchError10(ERROR_CODES10.HANDOFF_VALIDATION_FAILED);
+  }
+  const result = await service.publish(parsed.data, async (annotation) => {
+    try {
+      return await authorizeAnnotation({
+        annotation,
+        options: options.options,
+        registry: options.registry,
+        root: options.root
+      });
+    } catch (error) {
+      remapAuthorizationError(error);
+    }
+  });
+  writeSuccess(response, result.replayed ? 200 : 201, result);
+}
+
+// src/server/agent-http.ts
+import {
+  ERROR_CODES as ERROR_CODES11,
+  SPOTPATCH_ENDPOINTS as SPOTPATCH_ENDPOINTS2,
+  SpotPatchError as SpotPatchError11,
+  agentCapabilityRequestSchema,
+  agentJobActionRequestSchema,
+  agentJobCreateRequestSchema,
+  agentWorkspaceHealthRequestSchema
+} from "@spotpatch/shared";
+
+// src/server/agent-request.ts
+import "@spotpatch/shared";
+async function authorizeAgentJobRequest(input) {
+  const annotation = await authorizeAnnotation({
+    annotation: input.request.annotation,
+    options: input.options,
+    registry: input.registry,
+    root: input.root
+  });
+  return Object.freeze({
+    annotation,
+    ...input.request.applyMode === void 0 ? {} : { applyMode: input.request.applyMode },
+    providerProfileId: input.request.providerProfileId,
+    modelProfileId: input.request.modelProfileId,
+    providerDataConsent: true,
+    ...input.request.trustedFastModeConsent === true ? { trustedFastModeConsent: true } : {},
+    workingTreeMode: input.request.workingTreeMode
+  });
 }
 
 // src/server/agent-http.ts
@@ -1944,21 +3109,21 @@ var EVENT_STREAM_END_STATUSES = /* @__PURE__ */ new Set([
   "reverted",
   "failed"
 ]);
-function matchAgentRequestPath(path8) {
-  if (path8 === SPOTPATCH_ENDPOINTS.agentCapability) {
+function matchAgentRequestPath(path9) {
+  if (path9 === SPOTPATCH_ENDPOINTS2.agentCapability) {
     return Object.freeze({ kind: "capability" });
   }
-  if (path8 === SPOTPATCH_ENDPOINTS.agentWorkspaceHealth) {
+  if (path9 === SPOTPATCH_ENDPOINTS2.agentWorkspaceHealth) {
     return Object.freeze({ kind: "workspace-health" });
   }
-  if (path8 === SPOTPATCH_ENDPOINTS.agentJobs) {
+  if (path9 === SPOTPATCH_ENDPOINTS2.agentJobs) {
     return Object.freeze({ kind: "create-job" });
   }
-  const prefix = `${SPOTPATCH_ENDPOINTS.agentJobs}/`;
-  if (!path8.startsWith(prefix)) {
+  const prefix = `${SPOTPATCH_ENDPOINTS2.agentJobs}/`;
+  if (!path9.startsWith(prefix)) {
     return void 0;
   }
-  const segments = path8.slice(prefix.length).split("/");
+  const segments = path9.slice(prefix.length).split("/");
   const jobId = segments[0];
   const action = segments[1];
   if (segments.length !== 2 || jobId === void 0 || !AGENT_JOB_ID_PATTERN.test(jobId) || action === void 0 || !AGENT_JOB_ACTIONS.has(action)) {
@@ -1972,7 +3137,7 @@ function matchAgentRequestPath(path8) {
 }
 function requireAgentManager(options) {
   if (options.agentManager === void 0 || options.options.ai === false) {
-    throw new SpotPatchError6(ERROR_CODES6.AI_DISABLED);
+    throw new SpotPatchError11(ERROR_CODES11.AI_DISABLED);
   }
   return options.agentManager;
 }
@@ -2025,13 +3190,13 @@ function streamAgentJobEvents(response, manager, jobId) {
 }
 async function handleCapability(request, response, options, writeSuccess) {
   if (request.method !== "POST") {
-    throw new SpotPatchError6(ERROR_CODES6.INVALID_REQUEST);
+    throw new SpotPatchError11(ERROR_CODES11.INVALID_REQUEST);
   }
   const parsed = agentCapabilityRequestSchema.safeParse(
     await readJsonRequestBody(request)
   );
   if (!parsed.success) {
-    throw new SpotPatchError6(ERROR_CODES6.INVALID_REQUEST);
+    throw new SpotPatchError11(ERROR_CODES11.INVALID_REQUEST);
   }
   const controller = new AbortController();
   const abort = () => {
@@ -2050,13 +3215,13 @@ async function handleCapability(request, response, options, writeSuccess) {
 }
 async function handleCreateJob(request, response, options, writeSuccess) {
   if (request.method !== "POST") {
-    throw new SpotPatchError6(ERROR_CODES6.INVALID_REQUEST);
+    throw new SpotPatchError11(ERROR_CODES11.INVALID_REQUEST);
   }
   const parsed = agentJobCreateRequestSchema.safeParse(
     await readJsonRequestBody(request, MAX_AGENT_REQUEST_BODY_BYTES)
   );
   if (!parsed.success) {
-    throw new SpotPatchError6(ERROR_CODES6.INVALID_REQUEST);
+    throw new SpotPatchError11(ERROR_CODES11.INVALID_REQUEST);
   }
   const authorizedRequest = await authorizeAgentJobRequest({
     request: parsed.data,
@@ -2069,13 +3234,13 @@ async function handleCreateJob(request, response, options, writeSuccess) {
 }
 async function handleWorkspaceHealth(request, response, options, writeSuccess) {
   if (request.method !== "POST") {
-    throw new SpotPatchError6(ERROR_CODES6.INVALID_REQUEST);
+    throw new SpotPatchError11(ERROR_CODES11.INVALID_REQUEST);
   }
   const parsed = agentWorkspaceHealthRequestSchema.safeParse(
     await readJsonRequestBody(request)
   );
   if (!parsed.success) {
-    throw new SpotPatchError6(ERROR_CODES6.INVALID_REQUEST);
+    throw new SpotPatchError11(ERROR_CODES11.INVALID_REQUEST);
   }
   const controller = new AbortController();
   const abort = () => {
@@ -2092,13 +3257,13 @@ async function handleWorkspaceHealth(request, response, options, writeSuccess) {
 async function handleJobAction(request, response, options, route, writeSuccess) {
   const manager = requireAgentManager(options);
   if (request.method !== "POST") {
-    throw new SpotPatchError6(ERROR_CODES6.INVALID_REQUEST);
+    throw new SpotPatchError11(ERROR_CODES11.INVALID_REQUEST);
   }
   const parsed = agentJobActionRequestSchema.safeParse(
     await readJsonRequestBody(request)
   );
   if (!parsed.success) {
-    throw new SpotPatchError6(ERROR_CODES6.INVALID_REQUEST);
+    throw new SpotPatchError11(ERROR_CODES11.INVALID_REQUEST);
   }
   if (route.action === "events") {
     streamAgentJobEvents(response, manager, route.jobId);
@@ -2213,14 +3378,14 @@ function createEditorLauncher(dependencies = DEFAULT_DEPENDENCIES2) {
 var launchConfiguredEditor = createEditorLauncher();
 
 // src/server/data-flow-http.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 import {
   createStaticDataFlowAnalyzer
 } from "@spotpatch/analyzer";
 import {
   DATA_FLOW_SCHEMA_VERSION,
-  ERROR_CODES as ERROR_CODES7,
-  SpotPatchError as SpotPatchError7,
+  ERROR_CODES as ERROR_CODES12,
+  SpotPatchError as SpotPatchError12,
   dataFlowComponentReportRequestSchema,
   dataFlowPageReportRequestSchema,
   limitDataFlowReportCollections
@@ -2239,7 +3404,7 @@ function limitDataFlowReportToBytes(report, maximumBytes) {
     truncatedBy: "bytes"
   });
   if (envelopeBytes(limited) > maximumBytes) {
-    throw new SpotPatchError7(ERROR_CODES7.INTERNAL_ERROR);
+    throw new SpotPatchError12(ERROR_CODES12.INTERNAL_ERROR);
   }
   for (let maximumDependencies = 1; maximumDependencies <= structurallyLimited.dependencies.length; maximumDependencies += 1) {
     const candidate = limitDataFlowReportCollections(structurallyLimited, {
@@ -2268,7 +3433,7 @@ async function analyzeTarget(request, analyzer, options) {
         request.componentSourceId
       );
       if (anchor?.sourceVersion !== request.sourceVersion) {
-        throw new SpotPatchError7(ERROR_CODES7.DATA_FLOW_SOURCE_STALE);
+        throw new SpotPatchError12(ERROR_CODES12.DATA_FLOW_SOURCE_STALE);
       }
       return anchor;
     }
@@ -2285,7 +3450,7 @@ async function analyzeTarget(request, analyzer, options) {
     column: resolvedRequest.column
   });
   if (resolvedRequest.sourceVersion !== void 0 && resolvedRequest.sourceVersion !== report.component.source.sourceVersion) {
-    throw new SpotPatchError7(ERROR_CODES7.DATA_FLOW_SOURCE_STALE);
+    throw new SpotPatchError12(ERROR_CODES12.DATA_FLOW_SOURCE_STALE);
   }
   return limitDataFlowReportToBytes(
     report,
@@ -2294,7 +3459,7 @@ async function analyzeTarget(request, analyzer, options) {
 }
 function requireAnalyzer(analyzer) {
   if (analyzer === void 0) {
-    throw new SpotPatchError7(ERROR_CODES7.DATA_FLOW_DISABLED);
+    throw new SpotPatchError12(ERROR_CODES12.DATA_FLOW_DISABLED);
   }
   return analyzer;
 }
@@ -2306,7 +3471,7 @@ async function handleComponentDataFlowReport(request, analyzer, options) {
     )
   );
   if (!parsed.success) {
-    throw new SpotPatchError7(ERROR_CODES7.INVALID_REQUEST);
+    throw new SpotPatchError12(ERROR_CODES12.INVALID_REQUEST);
   }
   return analyzeTarget(parsed.data, requireAnalyzer(analyzer), options);
 }
@@ -2318,7 +3483,7 @@ async function handlePageDataFlowReport(request, analyzer, options) {
     )
   );
   if (!parsed.success) {
-    throw new SpotPatchError7(ERROR_CODES7.INVALID_REQUEST);
+    throw new SpotPatchError12(ERROR_CODES12.INVALID_REQUEST);
   }
   const activeAnalyzer = requireAnalyzer(analyzer);
   const componentReports = await Promise.all(
@@ -2342,7 +3507,7 @@ async function handlePageDataFlowReport(request, analyzer, options) {
   const analyzedVersions = new Set(
     componentReports.flatMap((report2) => report2.baseline.analyzedSourceVersions)
   );
-  const reportId = `page_${createHash2("sha256").update(componentReports.map((report2) => report2.reportId).join("\0")).digest("base64url").slice(0, 22)}`;
+  const reportId = `page_${createHash3("sha256").update(componentReports.map((report2) => report2.reportId).join("\0")).digest("base64url").slice(0, 22)}`;
   const complete = componentReports.every((report2) => report2.completeness.complete);
   const report = Object.freeze({
     schemaVersion: DATA_FLOW_SCHEMA_VERSION,
@@ -2389,20 +3554,20 @@ async function handlePageDataFlowReport(request, analyzer, options) {
 }
 
 // src/server/request-security.ts
-import { timingSafeEqual } from "crypto";
+import { timingSafeEqual as timingSafeEqual2 } from "crypto";
 import { isIP } from "net";
-import { ERROR_CODES as ERROR_CODES8, SPOTPATCH_TOKEN_HEADER, SpotPatchError as SpotPatchError8 } from "@spotpatch/shared";
+import { ERROR_CODES as ERROR_CODES13, SPOTPATCH_TOKEN_HEADER, SpotPatchError as SpotPatchError13 } from "@spotpatch/shared";
 function getSingleHeader(request, name) {
   const value = request.headers[name.toLowerCase()];
   return Array.isArray(value) ? value[0] : value;
 }
-function tokensMatch(actual, expected) {
+function tokensMatch2(actual, expected) {
   if (actual === void 0) {
     return false;
   }
   const actualBytes = Buffer.from(actual);
   const expectedBytes = Buffer.from(expected);
-  return actualBytes.byteLength === expectedBytes.byteLength && timingSafeEqual(actualBytes, expectedBytes);
+  return actualBytes.byteLength === expectedBytes.byteLength && timingSafeEqual2(actualBytes, expectedBytes);
 }
 function isLoopbackHostname(hostname) {
   const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "");
@@ -2437,33 +3602,33 @@ function parseOrigin(value) {
 }
 function assertRequestAuthorized(request, options) {
   const actualToken = getSingleHeader(request, SPOTPATCH_TOKEN_HEADER);
-  if (!tokensMatch(actualToken, options.sessionToken)) {
-    throw new SpotPatchError8(ERROR_CODES8.INVALID_TOKEN);
+  if (!tokensMatch2(actualToken, options.sessionToken)) {
+    throw new SpotPatchError13(ERROR_CODES13.INVALID_TOKEN);
   }
   const hostHeader = getSingleHeader(request, "host");
   const originHeader = getSingleHeader(request, "origin");
   const host = hostHeader === void 0 ? void 0 : parseHost(hostHeader);
   const origin = originHeader === void 0 ? void 0 : parseOrigin(originHeader);
   if (host === void 0 || origin === void 0) {
-    throw new SpotPatchError8(ERROR_CODES8.ORIGIN_NOT_ALLOWED);
+    throw new SpotPatchError13(ERROR_CODES13.ORIGIN_NOT_ALLOWED);
   }
   const hostIsLoopback = isLoopbackHostname(host.hostname);
   const originIsLoopback = isLoopbackHostname(origin.hostname);
   if (!options.allowLan) {
     if (!hostIsLoopback || !originIsLoopback) {
-      throw new SpotPatchError8(ERROR_CODES8.ORIGIN_NOT_ALLOWED);
+      throw new SpotPatchError13(ERROR_CODES13.ORIGIN_NOT_ALLOWED);
     }
     return;
   }
   if (!originIsLoopback && origin.host.toLowerCase() !== host.host.toLowerCase()) {
-    throw new SpotPatchError8(ERROR_CODES8.ORIGIN_NOT_ALLOWED);
+    throw new SpotPatchError13(ERROR_CODES13.ORIGIN_NOT_ALLOWED);
   }
 }
 
 // src/server/runtime-bootstrap.ts
 import {
-  ERROR_CODES as ERROR_CODES9,
-  SpotPatchError as SpotPatchError9,
+  ERROR_CODES as ERROR_CODES14,
+  SpotPatchError as SpotPatchError14,
   runtimeBootstrapRequestSchema,
   runtimeConfigSchema
 } from "@spotpatch/shared";
@@ -2493,7 +3658,7 @@ function resolveRuntimeBootstrapOptions(options) {
 function assertRuntimeBootstrapRequest(request, expectedOrigin) {
   const contentType = getSingleHeader2(request, "content-type")?.split(";", 1)[0]?.trim().toLowerCase();
   if (request.method !== "POST" || contentType !== "application/json") {
-    throw new SpotPatchError9(ERROR_CODES9.INVALID_REQUEST);
+    throw new SpotPatchError14(ERROR_CODES14.INVALID_REQUEST);
   }
   const host = getSingleHeader2(request, "host");
   let hostIsLoopback = false;
@@ -2505,7 +3670,7 @@ function assertRuntimeBootstrapRequest(request, expectedOrigin) {
     }
   }
   if (!hostIsLoopback || getSingleHeader2(request, "origin") !== expectedOrigin || getSingleHeader2(request, "sec-fetch-site") !== "same-origin") {
-    throw new SpotPatchError9(ERROR_CODES9.ORIGIN_NOT_ALLOWED);
+    throw new SpotPatchError14(ERROR_CODES14.ORIGIN_NOT_ALLOWED);
   }
 }
 async function readRuntimeBootstrap(request, options) {
@@ -2514,103 +3679,139 @@ async function readRuntimeBootstrap(request, options) {
     await readJsonRequestBody(request)
   );
   if (!parsedBody.success) {
-    throw new SpotPatchError9(ERROR_CODES9.INVALID_REQUEST);
+    throw new SpotPatchError14(ERROR_CODES14.INVALID_REQUEST);
   }
   return options.runtimeConfig;
 }
 
 // src/server/middleware.ts
 var STATUS_BY_ERROR = Object.freeze({
-  [ERROR_CODES10.INVALID_REQUEST]: 400,
-  [ERROR_CODES10.INVALID_TOKEN]: 401,
-  [ERROR_CODES10.ORIGIN_NOT_ALLOWED]: 403,
-  [ERROR_CODES10.SOURCE_NOT_FOUND]: 404,
-  [ERROR_CODES10.SOURCE_OUTSIDE_ROOT]: 403,
-  [ERROR_CODES10.SOURCE_TOO_LARGE]: 413,
-  [ERROR_CODES10.EDITOR_OPEN_FAILED]: 500,
-  [ERROR_CODES10.DATA_FLOW_DISABLED]: 404,
-  [ERROR_CODES10.DATA_FLOW_SOURCE_STALE]: 409,
-  [ERROR_CODES10.DATA_FLOW_ANALYSIS_CANCELLED]: 409,
-  [ERROR_CODES10.AI_DISABLED]: 404,
-  [ERROR_CODES10.PROVIDER_NOT_CONFIGURED]: 503,
-  [ERROR_CODES10.PROVIDER_AUTH_FAILED]: 502,
-  [ERROR_CODES10.PROVIDER_PROTOCOL_UNSUPPORTED]: 502,
-  [ERROR_CODES10.MODEL_NOT_ALLOWED]: 400,
-  [ERROR_CODES10.MODEL_TOOL_CALL_UNSUPPORTED]: 422,
-  [ERROR_CODES10.PROVIDER_RATE_LIMITED]: 429,
-  [ERROR_CODES10.AGENT_BUSY]: 409,
-  [ERROR_CODES10.AGENT_LIMIT_EXCEEDED]: 413,
-  [ERROR_CODES10.AGENT_CANCELLED]: 409,
-  [ERROR_CODES10.WORKTREE_DIRTY]: 409,
-  [ERROR_CODES10.WORKTREE_NOT_REPOSITORY]: 409,
-  [ERROR_CODES10.WORKTREE_OPERATION_IN_PROGRESS]: 409,
-  [ERROR_CODES10.WORKTREE_CONFLICTED]: 409,
-  [ERROR_CODES10.WORKTREE_LOCAL_CHANGES_TOO_LARGE]: 413,
-  [ERROR_CODES10.WORKTREE_UNTRACKED_UNSUPPORTED]: 409,
-  [ERROR_CODES10.WORKTREE_LOCAL_CHANGES_UNSUPPORTED]: 409,
-  [ERROR_CODES10.TOOL_DENIED]: 403,
-  [ERROR_CODES10.TOOL_INPUT_INVALID]: 422,
-  [ERROR_CODES10.TOOL_ARGUMENTS_INVALID]: 422,
-  [ERROR_CODES10.TOOL_CALL_ID_CONFLICT]: 422,
-  [ERROR_CODES10.TOOL_PATH_DENIED]: 403,
-  [ERROR_CODES10.PATCH_REJECTED]: 422,
-  [ERROR_CODES10.VALIDATION_FAILED]: 422,
-  [ERROR_CODES10.APPLY_CONFLICT]: 409,
-  [ERROR_CODES10.INTERNAL_ERROR]: 500
+  [ERROR_CODES15.INVALID_REQUEST]: 400,
+  [ERROR_CODES15.INVALID_TOKEN]: 401,
+  [ERROR_CODES15.ORIGIN_NOT_ALLOWED]: 403,
+  [ERROR_CODES15.SOURCE_NOT_FOUND]: 404,
+  [ERROR_CODES15.SOURCE_OUTSIDE_ROOT]: 403,
+  [ERROR_CODES15.SOURCE_TOO_LARGE]: 413,
+  [ERROR_CODES15.EDITOR_OPEN_FAILED]: 500,
+  [ERROR_CODES15.DATA_FLOW_DISABLED]: 404,
+  [ERROR_CODES15.DATA_FLOW_SOURCE_STALE]: 409,
+  [ERROR_CODES15.DATA_FLOW_ANALYSIS_CANCELLED]: 409,
+  [ERROR_CODES15.AI_DISABLED]: 404,
+  [ERROR_CODES15.PROVIDER_NOT_CONFIGURED]: 503,
+  [ERROR_CODES15.PROVIDER_AUTH_FAILED]: 502,
+  [ERROR_CODES15.PROVIDER_PROTOCOL_UNSUPPORTED]: 502,
+  [ERROR_CODES15.MODEL_NOT_ALLOWED]: 400,
+  [ERROR_CODES15.MODEL_TOOL_CALL_UNSUPPORTED]: 422,
+  [ERROR_CODES15.PROVIDER_RATE_LIMITED]: 429,
+  [ERROR_CODES15.AGENT_BUSY]: 409,
+  [ERROR_CODES15.AGENT_LIMIT_EXCEEDED]: 413,
+  [ERROR_CODES15.AGENT_CANCELLED]: 409,
+  [ERROR_CODES15.EXTERNAL_HANDOFF_DISABLED]: 404,
+  [ERROR_CODES15.EXTERNAL_HANDOFF_UNAVAILABLE]: 503,
+  [ERROR_CODES15.HANDOFF_VALIDATION_FAILED]: 422,
+  [ERROR_CODES15.HANDOFF_SOURCE_STALE]: 409,
+  [ERROR_CODES15.HANDOFF_NOT_FOUND]: 404,
+  [ERROR_CODES15.HANDOFF_EXPIRED]: 410,
+  [ERROR_CODES15.HANDOFF_CURSOR_INVALID]: 409,
+  [ERROR_CODES15.HANDOFF_RESPONSE_TOO_LARGE]: 413,
+  [ERROR_CODES15.BRIDGE_UNAUTHORIZED]: 401,
+  [ERROR_CODES15.BRIDGE_PROTOCOL_MISMATCH]: 409,
+  [ERROR_CODES15.BRIDGE_BUSY]: 429,
+  [ERROR_CODES15.EXTERNAL_AGENT_BUSY]: 409,
+  [ERROR_CODES15.ACTIVE_ADAPTER_CONFLICT]: 409,
+  [ERROR_CODES15.ACTIVE_ADAPTER_LEASE_INVALID]: 409,
+  [ERROR_CODES15.ACTIVE_DISPATCH_INVALID]: 409,
+  [ERROR_CODES15.SESSION_NOT_FOUND]: 404,
+  [ERROR_CODES15.SESSION_AMBIGUOUS]: 409,
+  [ERROR_CODES15.SESSION_CLOSED]: 410,
+  [ERROR_CODES15.WORKTREE_DIRTY]: 409,
+  [ERROR_CODES15.WORKTREE_NOT_REPOSITORY]: 409,
+  [ERROR_CODES15.WORKTREE_OPERATION_IN_PROGRESS]: 409,
+  [ERROR_CODES15.WORKTREE_CONFLICTED]: 409,
+  [ERROR_CODES15.WORKTREE_LOCAL_CHANGES_TOO_LARGE]: 413,
+  [ERROR_CODES15.WORKTREE_UNTRACKED_UNSUPPORTED]: 409,
+  [ERROR_CODES15.WORKTREE_LOCAL_CHANGES_UNSUPPORTED]: 409,
+  [ERROR_CODES15.TOOL_DENIED]: 403,
+  [ERROR_CODES15.TOOL_INPUT_INVALID]: 422,
+  [ERROR_CODES15.TOOL_ARGUMENTS_INVALID]: 422,
+  [ERROR_CODES15.TOOL_CALL_ID_CONFLICT]: 422,
+  [ERROR_CODES15.TOOL_PATH_DENIED]: 403,
+  [ERROR_CODES15.PATCH_REJECTED]: 422,
+  [ERROR_CODES15.VALIDATION_FAILED]: 422,
+  [ERROR_CODES15.APPLY_CONFLICT]: 409,
+  [ERROR_CODES15.INTERNAL_ERROR]: 500
 });
 var PUBLIC_MESSAGES = Object.freeze({
-  [ERROR_CODES10.INVALID_REQUEST]: "The request is invalid.",
-  [ERROR_CODES10.INVALID_TOKEN]: "The session token is invalid.",
-  [ERROR_CODES10.ORIGIN_NOT_ALLOWED]: "The request origin is not allowed.",
-  [ERROR_CODES10.SOURCE_NOT_FOUND]: "The source file is unavailable.",
-  [ERROR_CODES10.SOURCE_OUTSIDE_ROOT]: "The source file is outside the project root.",
-  [ERROR_CODES10.SOURCE_TOO_LARGE]: "The source file exceeds the size limit.",
-  [ERROR_CODES10.EDITOR_OPEN_FAILED]: "The editor request could not be started.",
-  [ERROR_CODES10.DATA_FLOW_DISABLED]: "Component data-flow analysis is not enabled.",
-  [ERROR_CODES10.DATA_FLOW_SOURCE_STALE]: "The selected source version is stale.",
-  [ERROR_CODES10.DATA_FLOW_ANALYSIS_CANCELLED]: "The data-flow analysis was cancelled.",
-  [ERROR_CODES10.AI_DISABLED]: "AI execution is not enabled.",
-  [ERROR_CODES10.PROVIDER_NOT_CONFIGURED]: "The AI provider is unavailable.",
-  [ERROR_CODES10.PROVIDER_AUTH_FAILED]: "The AI provider rejected authentication.",
-  [ERROR_CODES10.PROVIDER_PROTOCOL_UNSUPPORTED]: "The AI provider protocol is unsupported.",
-  [ERROR_CODES10.MODEL_NOT_ALLOWED]: "The selected model is not allowed.",
-  [ERROR_CODES10.MODEL_TOOL_CALL_UNSUPPORTED]: "The selected model cannot run SpotPatch tools.",
-  [ERROR_CODES10.PROVIDER_RATE_LIMITED]: "The AI provider is rate limited.",
-  [ERROR_CODES10.AGENT_BUSY]: "Another Agent job is already running.",
-  [ERROR_CODES10.AGENT_LIMIT_EXCEEDED]: "The Agent job exceeded a safety limit.",
-  [ERROR_CODES10.AGENT_CANCELLED]: "The Agent job was cancelled.",
-  [ERROR_CODES10.WORKTREE_DIRTY]: "Local changes require explicit inclusion consent.",
-  [ERROR_CODES10.WORKTREE_NOT_REPOSITORY]: "The project root is not a Git repository.",
-  [ERROR_CODES10.WORKTREE_OPERATION_IN_PROGRESS]: "A Git operation is currently in progress.",
-  [ERROR_CODES10.WORKTREE_CONFLICTED]: "The local workspace contains unresolved merge conflicts.",
-  [ERROR_CODES10.WORKTREE_LOCAL_CHANGES_TOO_LARGE]: "The local workspace exceeds the safe isolation size limit.",
-  [ERROR_CODES10.WORKTREE_UNTRACKED_UNSUPPORTED]: "An untracked path cannot be isolated safely.",
-  [ERROR_CODES10.WORKTREE_LOCAL_CHANGES_UNSUPPORTED]: "The local workspace state cannot be isolated safely.",
-  [ERROR_CODES10.TOOL_DENIED]: "The Agent tool request was denied.",
-  [ERROR_CODES10.TOOL_INPUT_INVALID]: "The Agent tool input was invalid.",
-  [ERROR_CODES10.TOOL_ARGUMENTS_INVALID]: "The Agent tool arguments are invalid.",
-  [ERROR_CODES10.TOOL_CALL_ID_CONFLICT]: "A tool call ID conflicts within one Agent turn.",
-  [ERROR_CODES10.TOOL_PATH_DENIED]: "The Agent tool path was denied.",
-  [ERROR_CODES10.PATCH_REJECTED]: "The proposed patch was rejected.",
-  [ERROR_CODES10.VALIDATION_FAILED]: "The proposed change failed validation.",
-  [ERROR_CODES10.APPLY_CONFLICT]: "The change conflicts with the current worktree.",
-  [ERROR_CODES10.INTERNAL_ERROR]: "The request could not be completed."
+  [ERROR_CODES15.INVALID_REQUEST]: "The request is invalid.",
+  [ERROR_CODES15.INVALID_TOKEN]: "The session token is invalid.",
+  [ERROR_CODES15.ORIGIN_NOT_ALLOWED]: "The request origin is not allowed.",
+  [ERROR_CODES15.SOURCE_NOT_FOUND]: "The source file is unavailable.",
+  [ERROR_CODES15.SOURCE_OUTSIDE_ROOT]: "The source file is outside the project root.",
+  [ERROR_CODES15.SOURCE_TOO_LARGE]: "The source file exceeds the size limit.",
+  [ERROR_CODES15.EDITOR_OPEN_FAILED]: "The editor request could not be started.",
+  [ERROR_CODES15.DATA_FLOW_DISABLED]: "Component data-flow analysis is not enabled.",
+  [ERROR_CODES15.DATA_FLOW_SOURCE_STALE]: "The selected source version is stale.",
+  [ERROR_CODES15.DATA_FLOW_ANALYSIS_CANCELLED]: "The data-flow analysis was cancelled.",
+  [ERROR_CODES15.AI_DISABLED]: "AI execution is not enabled.",
+  [ERROR_CODES15.PROVIDER_NOT_CONFIGURED]: "The AI provider is unavailable.",
+  [ERROR_CODES15.PROVIDER_AUTH_FAILED]: "The AI provider rejected authentication.",
+  [ERROR_CODES15.PROVIDER_PROTOCOL_UNSUPPORTED]: "The AI provider protocol is unsupported.",
+  [ERROR_CODES15.MODEL_NOT_ALLOWED]: "The selected model is not allowed.",
+  [ERROR_CODES15.MODEL_TOOL_CALL_UNSUPPORTED]: "The selected model cannot run SpotPatch tools.",
+  [ERROR_CODES15.PROVIDER_RATE_LIMITED]: "The AI provider is rate limited.",
+  [ERROR_CODES15.AGENT_BUSY]: "Another Agent job is already running.",
+  [ERROR_CODES15.AGENT_LIMIT_EXCEEDED]: "The Agent job exceeded a safety limit.",
+  [ERROR_CODES15.AGENT_CANCELLED]: "The Agent job was cancelled.",
+  [ERROR_CODES15.EXTERNAL_HANDOFF_DISABLED]: "External Agent handoff is not enabled.",
+  [ERROR_CODES15.EXTERNAL_HANDOFF_UNAVAILABLE]: "External Agent handoff is temporarily unavailable.",
+  [ERROR_CODES15.HANDOFF_VALIDATION_FAILED]: "The handoff content is invalid.",
+  [ERROR_CODES15.HANDOFF_SOURCE_STALE]: "The selected source is stale.",
+  [ERROR_CODES15.HANDOFF_NOT_FOUND]: "No current handoff is available.",
+  [ERROR_CODES15.HANDOFF_EXPIRED]: "The handoff has expired.",
+  [ERROR_CODES15.HANDOFF_CURSOR_INVALID]: "The handoff cursor is invalid.",
+  [ERROR_CODES15.HANDOFF_RESPONSE_TOO_LARGE]: "The handoff exceeds the size limit.",
+  [ERROR_CODES15.BRIDGE_UNAUTHORIZED]: "The local bridge request is unauthorized.",
+  [ERROR_CODES15.BRIDGE_PROTOCOL_MISMATCH]: "The local bridge protocol is incompatible.",
+  [ERROR_CODES15.BRIDGE_BUSY]: "The local bridge is busy.",
+  [ERROR_CODES15.EXTERNAL_AGENT_BUSY]: "The connected external Agent is busy.",
+  [ERROR_CODES15.ACTIVE_ADAPTER_CONFLICT]: "Another active Agent adapter is connected.",
+  [ERROR_CODES15.ACTIVE_ADAPTER_LEASE_INVALID]: "The active Agent adapter lease is invalid.",
+  [ERROR_CODES15.ACTIVE_DISPATCH_INVALID]: "The active Agent dispatch transition is invalid.",
+  [ERROR_CODES15.SESSION_NOT_FOUND]: "No active SpotPatch session was found.",
+  [ERROR_CODES15.SESSION_AMBIGUOUS]: "More than one SpotPatch session matches.",
+  [ERROR_CODES15.SESSION_CLOSED]: "The SpotPatch session has closed.",
+  [ERROR_CODES15.WORKTREE_DIRTY]: "Local changes require explicit inclusion consent.",
+  [ERROR_CODES15.WORKTREE_NOT_REPOSITORY]: "The project root is not a Git repository.",
+  [ERROR_CODES15.WORKTREE_OPERATION_IN_PROGRESS]: "A Git operation is currently in progress.",
+  [ERROR_CODES15.WORKTREE_CONFLICTED]: "The local workspace contains unresolved merge conflicts.",
+  [ERROR_CODES15.WORKTREE_LOCAL_CHANGES_TOO_LARGE]: "The local workspace exceeds the safe isolation size limit.",
+  [ERROR_CODES15.WORKTREE_UNTRACKED_UNSUPPORTED]: "An untracked path cannot be isolated safely.",
+  [ERROR_CODES15.WORKTREE_LOCAL_CHANGES_UNSUPPORTED]: "The local workspace state cannot be isolated safely.",
+  [ERROR_CODES15.TOOL_DENIED]: "The Agent tool request was denied.",
+  [ERROR_CODES15.TOOL_INPUT_INVALID]: "The Agent tool input was invalid.",
+  [ERROR_CODES15.TOOL_ARGUMENTS_INVALID]: "The Agent tool arguments are invalid.",
+  [ERROR_CODES15.TOOL_CALL_ID_CONFLICT]: "A tool call ID conflicts within one Agent turn.",
+  [ERROR_CODES15.TOOL_PATH_DENIED]: "The Agent tool path was denied.",
+  [ERROR_CODES15.PATCH_REJECTED]: "The proposed patch was rejected.",
+  [ERROR_CODES15.VALIDATION_FAILED]: "The proposed change failed validation.",
+  [ERROR_CODES15.APPLY_CONFLICT]: "The change conflicts with the current worktree.",
+  [ERROR_CODES15.INTERNAL_ERROR]: "The request could not be completed."
 });
-function writeJson(response, status, payload) {
+function writeJson2(response, status, payload) {
   response.statusCode = status;
   response.setHeader("Cache-Control", "no-store");
   response.setHeader("Content-Type", "application/json; charset=utf-8");
   response.end(JSON.stringify(payload));
 }
 function asSpotPatchError(error) {
-  return error instanceof SpotPatchError10 ? error : new SpotPatchError10(ERROR_CODES10.INTERNAL_ERROR, void 0, { cause: error });
+  return error instanceof SpotPatchError15 ? error : new SpotPatchError15(ERROR_CODES15.INTERNAL_ERROR, void 0, { cause: error });
 }
 function writeError(response, error, logger) {
   const normalized = asSpotPatchError(error);
-  if (normalized.code === ERROR_CODES10.INTERNAL_ERROR) {
+  if (normalized.code === ERROR_CODES15.INTERNAL_ERROR) {
     logger?.warn("[spotpatch:server] Internal request failure.");
   }
-  writeJson(response, STATUS_BY_ERROR[normalized.code], {
+  writeJson2(response, STATUS_BY_ERROR[normalized.code], {
     ok: false,
     error: {
       code: normalized.code,
@@ -2630,7 +3831,7 @@ async function handleSourceContext(request, options) {
     await readJsonRequestBody(request)
   );
   if (!parsed.success) {
-    throw new SpotPatchError10(ERROR_CODES10.INVALID_REQUEST);
+    throw new SpotPatchError15(ERROR_CODES15.INVALID_REQUEST);
   }
   return readSourceContext({
     request: parsed.data,
@@ -2643,7 +3844,7 @@ async function handleSourceContext(request, options) {
 async function handleOpenEditor(request, options) {
   const parsed = openEditorRequestSchema.safeParse(await readJsonRequestBody(request));
   if (!parsed.success) {
-    throw new SpotPatchError10(ERROR_CODES10.INVALID_REQUEST);
+    throw new SpotPatchError15(ERROR_CODES15.INVALID_REQUEST);
   }
   const body = parsed.data;
   const sourcePath = await resolveSourceFile({
@@ -2660,7 +3861,7 @@ async function handleOpenEditor(request, options) {
     options.logger?.warn(
       `[spotpatch:server] ${options.options.editor === "auto" ? "The detected editor" : options.options.editor} rejected an editor request.`
     );
-    throw new SpotPatchError10(ERROR_CODES10.EDITOR_OPEN_FAILED, void 0, {
+    throw new SpotPatchError15(ERROR_CODES15.EDITOR_OPEN_FAILED, void 0, {
       cause: error
     });
   }
@@ -2669,63 +3870,81 @@ function createSpotPatchMiddleware(options) {
   const bootstrap = options.bootstrap === void 0 ? void 0 : resolveRuntimeBootstrapOptions(options.bootstrap);
   const dataFlowAnalyzer = createDataFlowAnalyzer(options);
   return (request, response, next) => {
-    const path8 = requestPath(request);
-    const agentRoute = matchAgentRequestPath(path8);
-    if (path8 !== SPOTPATCH_ENDPOINTS2.sourceContext && path8 !== SPOTPATCH_ENDPOINTS2.openEditor && path8 !== SPOTPATCH_ENDPOINTS2.dataFlowComponentReport && path8 !== SPOTPATCH_ENDPOINTS2.dataFlowPageReport && agentRoute === void 0 && !path8.startsWith(`${SPOTPATCH_API_BASE}/`)) {
+    const path9 = requestPath(request);
+    const agentRoute = matchAgentRequestPath(path9);
+    const externalHandoffRoute = matchExternalHandoffBrowserPath(path9);
+    if (path9 !== SPOTPATCH_ENDPOINTS3.sourceContext && path9 !== SPOTPATCH_ENDPOINTS3.openEditor && path9 !== SPOTPATCH_ENDPOINTS3.dataFlowComponentReport && path9 !== SPOTPATCH_ENDPOINTS3.dataFlowPageReport && agentRoute === void 0 && externalHandoffRoute === void 0 && !path9.startsWith(`${SPOTPATCH_API_BASE}/`)) {
       next();
       return;
     }
     const handle = async () => {
-      if (path8 === SPOTPATCH_ENDPOINTS2.bootstrap && bootstrap !== void 0) {
+      if (path9 === SPOTPATCH_ENDPOINTS3.bootstrap && bootstrap !== void 0) {
         const data = await readRuntimeBootstrap(
           request,
           bootstrap
         );
-        writeJson(response, 200, { ok: true, data });
+        writeJson2(response, 200, { ok: true, data });
         return;
       }
       assertRequestAuthorized(request, {
         allowLan: options.options.allowLan,
         sessionToken: options.session.token
       });
-      if (path8 === SPOTPATCH_ENDPOINTS2.sourceContext) {
+      if (path9 === SPOTPATCH_ENDPOINTS3.sourceContext) {
         if (request.method !== "POST") {
-          throw new SpotPatchError10(ERROR_CODES10.INVALID_REQUEST);
+          throw new SpotPatchError15(ERROR_CODES15.INVALID_REQUEST);
         }
         const data = await handleSourceContext(request, options);
-        writeJson(response, 200, { ok: true, data });
+        writeJson2(response, 200, { ok: true, data });
         return;
       }
-      if (path8 === SPOTPATCH_ENDPOINTS2.openEditor) {
+      if (path9 === SPOTPATCH_ENDPOINTS3.openEditor) {
         if (request.method !== "POST") {
-          throw new SpotPatchError10(ERROR_CODES10.INVALID_REQUEST);
+          throw new SpotPatchError15(ERROR_CODES15.INVALID_REQUEST);
         }
         const data = await handleOpenEditor(request, options);
-        writeJson(response, 200, { ok: true, data });
+        writeJson2(response, 200, { ok: true, data });
         return;
       }
-      if (path8 === SPOTPATCH_ENDPOINTS2.dataFlowComponentReport) {
+      if (path9 === SPOTPATCH_ENDPOINTS3.dataFlowComponentReport) {
         if (request.method !== "POST") {
-          throw new SpotPatchError10(ERROR_CODES10.INVALID_REQUEST);
+          throw new SpotPatchError15(ERROR_CODES15.INVALID_REQUEST);
         }
         const data = await handleComponentDataFlowReport(
           request,
           dataFlowAnalyzer,
           options
         );
-        writeJson(response, 200, { ok: true, data });
+        writeJson2(response, 200, { ok: true, data });
         return;
       }
-      if (path8 === SPOTPATCH_ENDPOINTS2.dataFlowPageReport) {
+      if (path9 === SPOTPATCH_ENDPOINTS3.dataFlowPageReport) {
         if (request.method !== "POST") {
-          throw new SpotPatchError10(ERROR_CODES10.INVALID_REQUEST);
+          throw new SpotPatchError15(ERROR_CODES15.INVALID_REQUEST);
         }
         const data = await handlePageDataFlowReport(request, dataFlowAnalyzer, options);
-        writeJson(response, 200, { ok: true, data });
+        writeJson2(response, 200, { ok: true, data });
+        return;
+      }
+      if (externalHandoffRoute !== void 0) {
+        await handleExternalHandoffBrowserRequest(
+          request,
+          response,
+          externalHandoffRoute,
+          {
+            options: options.options,
+            registry: options.registry,
+            root: options.root,
+            ...options.externalHandoffService === void 0 ? {} : { service: options.externalHandoffService }
+          },
+          (target, status, data) => {
+            writeJson2(target, status, { ok: true, data });
+          }
+        );
         return;
       }
       if (agentRoute === void 0) {
-        throw new SpotPatchError10(ERROR_CODES10.INVALID_REQUEST);
+        throw new SpotPatchError15(ERROR_CODES15.INVALID_REQUEST);
       }
       await handleAgentRequest(
         request,
@@ -2733,7 +3952,7 @@ function createSpotPatchMiddleware(options) {
         options,
         agentRoute,
         (target, status, data) => {
-          writeJson(target, status, { ok: true, data });
+          writeJson2(target, status, { ok: true, data });
         }
       );
     };
@@ -2744,9 +3963,9 @@ function createSpotPatchMiddleware(options) {
 }
 
 // src/server/source-registration.ts
-import { timingSafeEqual as timingSafeEqual2 } from "crypto";
-import { lstat as lstat3, realpath as realpath6 } from "fs/promises";
-import path7 from "path";
+import { timingSafeEqual as timingSafeEqual3 } from "crypto";
+import { lstat as lstat4, realpath as realpath6 } from "fs/promises";
+import path8 from "path";
 import { createSourceFilter } from "@spotpatch/compiler";
 import { z as z2 } from "zod";
 var REGISTRATION_BODY_LIMIT_BYTES = 4096;
@@ -2767,16 +3986,16 @@ function identitiesMatch(actual, expected) {
   }
   const actualBytes = Buffer.from(actual);
   const expectedBytes = Buffer.from(expected);
-  return actualBytes.byteLength === expectedBytes.byteLength && timingSafeEqual2(actualBytes, expectedBytes);
+  return actualBytes.byteLength === expectedBytes.byteLength && timingSafeEqual3(actualBytes, expectedBytes);
 }
 function isWithinRoot(root, candidate) {
-  const relative = path7.relative(root, candidate);
-  return relative === "" || !relative.startsWith(`..${path7.sep}`) && relative !== ".." && !path7.isAbsolute(relative);
+  const relative = path8.relative(root, candidate);
+  return relative === "" || !relative.startsWith(`..${path8.sep}`) && relative !== ".." && !path8.isAbsolute(relative);
 }
 function hasForbiddenSegment(root, candidate) {
-  return path7.relative(root, candidate).split(path7.sep).some((segment) => FORBIDDEN_SOURCE_SEGMENTS.has(segment));
+  return path8.relative(root, candidate).split(path8.sep).some((segment) => FORBIDDEN_SOURCE_SEGMENTS.has(segment));
 }
-function writeJson2(response, statusCode, payload) {
+function writeJson3(response, statusCode, payload) {
   const body = JSON.stringify(payload);
   response.statusCode = statusCode;
   response.setHeader("Cache-Control", "no-store");
@@ -2796,11 +4015,11 @@ function requestComesFromLoopbackWorker(request) {
   }
 }
 async function resolveAuthorizedSource(root, requestedPath, shouldTransform) {
-  if (!path7.isAbsolute(requestedPath) || requestedPath.includes("\0")) {
+  if (!path8.isAbsolute(requestedPath) || requestedPath.includes("\0")) {
     return void 0;
   }
   try {
-    const sourceStat = await lstat3(requestedPath);
+    const sourceStat = await lstat4(requestedPath);
     if (!sourceStat.isFile() || sourceStat.isSymbolicLink()) {
       return void 0;
     }
@@ -2826,14 +4045,14 @@ async function createSourceRegistrationService(input) {
         getSingleHeader3(request, INTERNAL_SECRET_HEADER),
         input.internalSecret
       )) {
-        writeJson2(response, 403, { ok: false });
+        writeJson3(response, 403, { ok: false });
         return;
       }
       const parsed = registrationRequestSchema.safeParse(
         await readJsonRequestBody(request, REGISTRATION_BODY_LIMIT_BYTES)
       );
       if (!parsed.success || parsed.data.epoch !== input.registryEpoch) {
-        writeJson2(response, 400, { ok: false });
+        writeJson3(response, 400, { ok: false });
         return;
       }
       const sourcePath = await resolveAuthorizedSource(
@@ -2842,17 +4061,17 @@ async function createSourceRegistrationService(input) {
         (absolutePath) => sourceFilter.shouldTransform(absolutePath, "<")
       );
       if (sourcePath === void 0) {
-        writeJson2(response, 403, { ok: false });
+        writeJson3(response, 403, { ok: false });
         return;
       }
-      writeJson2(response, 200, {
+      writeJson3(response, 200, {
         epoch: input.registryEpoch,
         fileId: input.registry.register(sourcePath)
       });
     };
     void handle().catch(() => {
       if (!response.headersSent) {
-        writeJson2(response, 400, { ok: false });
+        writeJson3(response, 400, { ok: false });
       } else {
         response.destroy();
       }
@@ -2862,11 +4081,11 @@ async function createSourceRegistrationService(input) {
 }
 
 // src/session/session.ts
-import { randomBytes as randomBytes4 } from "crypto";
+import { randomBytes as randomBytes8 } from "crypto";
 function createSession() {
   return Object.freeze({
-    id: randomBytes4(16).toString("base64url"),
-    token: randomBytes4(16).toString("base64url")
+    id: randomBytes8(16).toString("base64url"),
+    token: randomBytes8(16).toString("base64url")
   });
 }
 
@@ -2879,6 +4098,7 @@ var OPTION_KEYS = Object.freeze([
   "dataFlow",
   "editor",
   "enabled",
+  "externalAgent",
   "exclude",
   "include",
   "locale",
@@ -2969,6 +4189,7 @@ function serializeResolvedSpotPatchOptions(options) {
     }) : false,
     editor: options.editor,
     enabled: options.enabled,
+    externalAgent: options.externalAgent.enabled,
     exclude: Object.freeze(options.exclude.map(serializeFilter)),
     include: Object.freeze(options.include.map(serializeFilter)),
     locale: options.locale,
@@ -3022,7 +4243,7 @@ function parseSerializedSpotPatchOptions(value) {
   if (!isRecord2(value) || !hasExactKeys(value, OPTION_KEYS)) {
     throw new TypeError("The SpotPatch options transport is invalid.");
   }
-  if (typeof value.enabled !== "boolean" || typeof value.redact !== "boolean" || typeof value.allowLan !== "boolean" || typeof value.debug !== "boolean" || typeof value.shortcut !== "string" || typeof value.maxTargets !== "number" || typeof value.editor !== "string" || typeof value.locale !== "string" || value.ai !== false && !isRecord2(value.ai)) {
+  if (typeof value.enabled !== "boolean" || typeof value.externalAgent !== "boolean" || typeof value.redact !== "boolean" || typeof value.allowLan !== "boolean" || typeof value.debug !== "boolean" || typeof value.shortcut !== "string" || typeof value.maxTargets !== "number" || typeof value.editor !== "string" || typeof value.locale !== "string" || value.ai !== false && !isRecord2(value.ai)) {
     throw new TypeError("The SpotPatch options transport is invalid.");
   }
   try {
@@ -3034,6 +4255,7 @@ function parseSerializedSpotPatchOptions(value) {
       dataFlow: parseDataFlow(value.dataFlow),
       editor: value.editor,
       enabled: value.enabled,
+      externalAgent: value.externalAgent,
       exclude: parseFilterList(value.exclude),
       include: parseFilterList(value.include),
       locale: value.locale,
@@ -3052,6 +4274,7 @@ export {
   DEFAULT_OPTIONS,
   applyIntegrationPlan,
   createAgentJobManager,
+  createExternalHandoffService,
   createIntegrationFileChange,
   createRuntimeAiConfig,
   createRuntimeDataFlowConfig,