@spotpatch/runtime 1.10.0 → 1.11.0

package/dist/external-handoff-panel.cjs

@@ -28,7 +28,359 @@ __export(external_handoff_panel_entry_exports, {
 module.exports = __toCommonJS(external_handoff_panel_entry_exports);
 
 // src/controller/external-handoff-workflow.ts
+var import_external_handoff_browser2 = require("@spotpatch/shared/external-handoff-browser");
+
+// src/controller/browser-api.ts
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function exactKeys(value, keys) {
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+function validTimestamp(value) {
+  if (typeof value !== "string") return false;
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?Z$/u.exec(
+    value
+  );
+  if (match === null) return false;
+  const timestamp = Date.parse(value);
+  if (!Number.isFinite(timestamp)) return false;
+  const date = new Date(timestamp);
+  return date.getUTCFullYear() === Number(match[1]) && date.getUTCMonth() + 1 === Number(match[2]) && date.getUTCDate() === Number(match[3]) && date.getUTCHours() === Number(match[4]) && date.getUTCMinutes() === Number(match[5]) && date.getUTCSeconds() === Number(match[6]);
+}
+async function readBoundedJson(response, maximumBytes) {
+  const declaredLength = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declaredLength) && declaredLength > maximumBytes) {
+    await response.body?.cancel();
+    throw new TypeError("SpotPatch API response exceeds its safety limit.");
+  }
+  if (response.body === null) {
+    throw new TypeError("SpotPatch API response body is unavailable.");
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      total += chunk.value.byteLength;
+      if (total > maximumBytes) {
+        await reader.cancel();
+        throw new TypeError("SpotPatch API response exceeds its safety limit.");
+      }
+      chunks.push(chunk.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const payload = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    payload.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return JSON.parse(
+    new TextDecoder("utf-8", { fatal: true }).decode(payload)
+  );
+}
+function successData(value) {
+  if (!record(value) || !exactKeys(value, ["data", "ok"]) || value.ok !== true) {
+    throw new TypeError("SpotPatch API success envelope is invalid.");
+  }
+  return value.data;
+}
+
+// src/controller/external-agent-control-client.ts
 var import_external_handoff_browser = require("@spotpatch/shared/external-handoff-browser");
+var RESPONSE_OVERHEAD_BYTES = 64 * 1024;
+function member(values, value) {
+  return typeof value === "string" && values.includes(value);
+}
+function integer(value, minimum = 0) {
+  return Number.isSafeInteger(value) && value >= minimum;
+}
+function optionalKeys(value, base, optional) {
+  return exactKeys(value, [
+    ...base,
+    ...optional.filter((key) => value[key] !== void 0)
+  ]);
+}
+function safePath(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 4096 || value.startsWith("/") || value.includes("\\")) {
+    return false;
+  }
+  return value.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}
+function parseFiles(value) {
+  if (!Array.isArray(value) || value.length > import_external_handoff_browser.EXTERNAL_AGENT_CONTROL_LIMITS.maximumChangedFiles) {
+    throw new TypeError("Invalid managed file summaries.");
+  }
+  return value.map((file) => {
+    if (!record(file) || !exactKeys(file, ["additions", "deletions", "path"]) || !safePath(file.path) || !integer(file.additions) || !integer(file.deletions)) {
+      throw new TypeError("Invalid managed file summary.");
+    }
+    return Object.freeze({
+      path: file.path,
+      additions: file.additions,
+      deletions: file.deletions
+    });
+  });
+}
+function parseChecks(value) {
+  if (!Array.isArray(value) || value.length > import_external_handoff_browser.EXTERNAL_AGENT_CONTROL_LIMITS.maximumChecks) {
+    throw new TypeError("Invalid managed check summaries.");
+  }
+  return value.map((check) => {
+    if (!record(check) || !optionalKeys(check, ["durationMs", "id", "outcome"], ["exitCode"]) || typeof check.id !== "string" || !/^[A-Za-z0-9._-]{1,128}$/u.test(check.id) || !member(import_external_handoff_browser.EXTERNAL_AGENT_CHECK_OUTCOMES, check.outcome) || !integer(check.durationMs) || check.exitCode !== void 0 && !Number.isSafeInteger(check.exitCode)) {
+      throw new TypeError("Invalid managed check summary.");
+    }
+    return Object.freeze({
+      id: check.id,
+      outcome: check.outcome,
+      durationMs: check.durationMs,
+      ...check.exitCode === void 0 ? {} : { exitCode: check.exitCode }
+    });
+  });
+}
+function parseTimings(value) {
+  const keys = [
+    "preparing",
+    "agent",
+    "auditing",
+    "validating",
+    "applying",
+    "total"
+  ];
+  if (!record(value) || !optionalKeys(value, [], keys)) {
+    throw new TypeError("Invalid managed timings.");
+  }
+  for (const key of keys) {
+    if (value[key] !== void 0 && !integer(value[key])) {
+      throw new TypeError("Invalid managed timing.");
+    }
+  }
+  return Object.freeze(
+    Object.fromEntries(
+      keys.flatMap((key) => value[key] === void 0 ? [] : [[key, value[key]]])
+    )
+  );
+}
+function parseTask(value) {
+  if (!record(value) || !optionalKeys(
+    value,
+    [
+      "checks",
+      "deliveryStatus",
+      "executionStatus",
+      "files",
+      "managedPhase",
+      "revision",
+      "timings"
+    ],
+    ["resultExpiresAt", "validationOutcome"]
+  ) || !integer(value.revision, 1) || !member(import_external_handoff_browser.EXTERNAL_AGENT_DELIVERY_STATUSES, value.deliveryStatus) || !member(import_external_handoff_browser.EXTERNAL_AGENT_EXECUTION_STATUSES, value.executionStatus) || !member(import_external_handoff_browser.EXTERNAL_AGENT_MANAGED_PHASES, value.managedPhase) || value.validationOutcome !== void 0 && !member(import_external_handoff_browser.EXTERNAL_AGENT_VALIDATION_OUTCOMES, value.validationOutcome) || value.resultExpiresAt !== void 0 && !validTimestamp(value.resultExpiresAt)) {
+    throw new TypeError("Invalid managed task status.");
+  }
+  return Object.freeze({
+    revision: value.revision,
+    deliveryStatus: value.deliveryStatus,
+    executionStatus: value.executionStatus,
+    managedPhase: value.managedPhase,
+    ...value.validationOutcome === void 0 ? {} : { validationOutcome: value.validationOutcome },
+    files: parseFiles(value.files),
+    checks: parseChecks(value.checks),
+    timings: parseTimings(value.timings),
+    ...value.resultExpiresAt === void 0 ? {} : { resultExpiresAt: value.resultExpiresAt }
+  });
+}
+function parseExternalAgentControlStatus(value) {
+  if (!record(value) || !optionalKeys(
+    value,
+    [
+      "adapter",
+      "authReadiness",
+      "connectionState",
+      "grantState",
+      "mode",
+      "schemaVersion",
+      "sequence",
+      "updatedAt"
+    ],
+    ["effectiveModel", "error", "requestedModel", "task"]
+  ) || value.schemaVersion !== 1 || !integer(value.sequence) || !member(import_external_handoff_browser.EXTERNAL_AGENT_MODES, value.mode) || !member(import_external_handoff_browser.EXTERNAL_AGENT_CONNECTION_STATES, value.connectionState) || !member(import_external_handoff_browser.EXTERNAL_AGENT_AUTH_READINESS, value.authReadiness) || !member(import_external_handoff_browser.EXTERNAL_AGENT_GRANT_STATES, value.grantState) || !validTimestamp(value.updatedAt) || value.requestedModel !== void 0 && (typeof value.requestedModel !== "string" || value.requestedModel.length === 0 || value.requestedModel.length > 128) || value.effectiveModel !== void 0 && (typeof value.effectiveModel !== "string" || value.effectiveModel.length === 0 || value.effectiveModel.length > 128) || !record(value.adapter) || !exactKeys(value.adapter, ["availability", "kind", "maturity"]) || value.adapter.kind !== "codex" || value.adapter.maturity !== "experimental" || value.adapter.availability !== "available" && value.adapter.availability !== "unavailable") {
+    throw new TypeError("Invalid external Agent control status.");
+  }
+  let error;
+  if (value.error !== void 0) {
+    if (!record(value.error) || !exactKeys(value.error, ["action", "code", "recoverability", "stage"]) || !member(import_external_handoff_browser.EXTERNAL_AGENT_ERROR_CODES, value.error.code) || !member(import_external_handoff_browser.EXTERNAL_AGENT_ERROR_STAGES, value.error.stage) || !member(import_external_handoff_browser.EXTERNAL_AGENT_ERROR_RECOVERABILITY, value.error.recoverability) || !member(import_external_handoff_browser.EXTERNAL_AGENT_ACTIONS, value.error.action)) {
+      throw new TypeError("Invalid external Agent error.");
+    }
+    error = Object.freeze({
+      code: value.error.code,
+      stage: value.error.stage,
+      recoverability: value.error.recoverability,
+      action: value.error.action
+    });
+  }
+  return Object.freeze({
+    schemaVersion: 1,
+    sequence: value.sequence,
+    mode: value.mode,
+    adapter: Object.freeze({
+      kind: "codex",
+      maturity: "experimental",
+      availability: value.adapter.availability
+    }),
+    connectionState: value.connectionState,
+    authReadiness: value.authReadiness,
+    grantState: value.grantState,
+    ...value.requestedModel === void 0 ? {} : { requestedModel: value.requestedModel },
+    ...value.effectiveModel === void 0 ? {} : { effectiveModel: value.effectiveModel },
+    ...value.task === void 0 ? {} : { task: parseTask(value.task) },
+    ...error === void 0 ? {} : { error },
+    updatedAt: value.updatedAt
+  });
+}
+function parseExternalAgentManagedResult(value) {
+  if (!record(value) || !exactKeys(value, [
+    "checks",
+    "diff",
+    "expiresAt",
+    "files",
+    "revision",
+    "timings",
+    "validationOutcome"
+  ]) || !integer(value.revision, 1) || typeof value.diff !== "string" || value.diff.length > import_external_handoff_browser.EXTERNAL_AGENT_CONTROL_LIMITS.maximumResultDiffBytes || !validTimestamp(value.expiresAt) || !member(import_external_handoff_browser.EXTERNAL_AGENT_VALIDATION_OUTCOMES, value.validationOutcome)) {
+    throw new TypeError("Invalid managed Agent result.");
+  }
+  return Object.freeze({
+    revision: value.revision,
+    diff: value.diff,
+    files: parseFiles(value.files),
+    checks: parseChecks(value.checks),
+    timings: parseTimings(value.timings),
+    validationOutcome: value.validationOutcome,
+    expiresAt: value.expiresAt
+  });
+}
+function parseEvent(value) {
+  if (!record(value) || typeof value.type !== "string") {
+    throw new TypeError("Invalid external Agent event.");
+  }
+  if (value.type === "status" && exactKeys(value, ["data", "type"])) {
+    return Object.freeze({
+      type: "status",
+      data: parseExternalAgentControlStatus(value.data)
+    });
+  }
+  if (value.type === "heartbeat" && exactKeys(value, ["emittedAt", "sequence", "type"]) && integer(value.sequence) && validTimestamp(value.emittedAt)) {
+    return Object.freeze({
+      type: "heartbeat",
+      sequence: value.sequence,
+      emittedAt: value.emittedAt
+    });
+  }
+  throw new TypeError("Invalid external Agent event.");
+}
+function createExternalAgentControlClient(fetch, sessionToken) {
+  const request = async (endpoint, body, maximumBytes = RESPONSE_OVERHEAD_BYTES) => {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        [import_external_handoff_browser.SPOTPATCH_TOKEN_HEADER]: sessionToken
+      },
+      body: JSON.stringify(body)
+    });
+    const envelope = await readBoundedJson(response, maximumBytes);
+    if (!response.ok) throw new TypeError("External Agent control request failed.");
+    return successData(envelope);
+  };
+  return Object.freeze({
+    async status() {
+      return parseExternalAgentControlStatus(
+        await request(import_external_handoff_browser.SPOTPATCH_ENDPOINTS.externalAgentControlStatus, {})
+      );
+    },
+    async connect(value) {
+      return parseExternalAgentControlStatus(
+        await request(import_external_handoff_browser.SPOTPATCH_ENDPOINTS.externalAgentControlConnect, value)
+      );
+    },
+    async disconnect(value) {
+      return parseExternalAgentControlStatus(
+        await request(import_external_handoff_browser.SPOTPATCH_ENDPOINTS.externalAgentControlDisconnect, value)
+      );
+    },
+    async cancel(value) {
+      return parseExternalAgentControlStatus(
+        await request(import_external_handoff_browser.SPOTPATCH_ENDPOINTS.externalAgentControlCancel, value)
+      );
+    },
+    async result(revision) {
+      return parseExternalAgentManagedResult(
+        await request(
+          import_external_handoff_browser.SPOTPATCH_ENDPOINTS.externalAgentResult,
+          { revision },
+          import_external_handoff_browser.EXTERNAL_AGENT_CONTROL_LIMITS.maximumResultDiffBytes + RESPONSE_OVERHEAD_BYTES
+        )
+      );
+    },
+    async events(afterSequence, signal, onEvent) {
+      const response = await fetch(import_external_handoff_browser.SPOTPATCH_ENDPOINTS.externalAgentEvents, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          [import_external_handoff_browser.SPOTPATCH_TOKEN_HEADER]: sessionToken
+        },
+        body: JSON.stringify(afterSequence === void 0 ? {} : { afterSequence }),
+        signal
+      });
+      if (!response.ok || response.body === null) {
+        await response.body?.cancel();
+        throw new TypeError("External Agent event stream is unavailable.");
+      }
+      const reader = response.body.getReader();
+      let pending = new Uint8Array(0);
+      try {
+        for (; ; ) {
+          const chunk = await reader.read();
+          if (chunk.done) break;
+          const combined = new Uint8Array(pending.byteLength + chunk.value.byteLength);
+          combined.set(pending);
+          combined.set(chunk.value, pending.byteLength);
+          pending = combined;
+          for (; ; ) {
+            const newline = pending.indexOf(10);
+            if (newline === -1) break;
+            if (newline === 0 || newline > import_external_handoff_browser.EXTERNAL_AGENT_CONTROL_LIMITS.maximumEventLineBytes) {
+              throw new TypeError("External Agent event line is invalid.");
+            }
+            const line = pending.slice(0, newline);
+            pending = pending.slice(newline + 1);
+            const value = JSON.parse(
+              new TextDecoder("utf-8", { fatal: true }).decode(line)
+            );
+            onEvent(parseEvent(value));
+          }
+          if (pending.byteLength > import_external_handoff_browser.EXTERNAL_AGENT_CONTROL_LIMITS.maximumEventLineBytes) {
+            throw new TypeError("External Agent event line exceeds its limit.");
+          }
+        }
+        if (pending.byteLength !== 0) {
+          throw new TypeError("External Agent event stream ended mid-record.");
+        }
+      } finally {
+        reader.releaseLock();
+      }
+    }
+  });
+}
+
+// src/controller/external-handoff-workflow.ts
 var MAX_SUMMARY_RESPONSE_BYTES = 64 * 1024;
 var OPAQUE_ID_PATTERN = /^[A-Za-z0-9_-]{22,128}$/u;
 var ExternalHandoffApiError = class extends Error {
@@ -39,17 +391,6 @@ var ExternalHandoffApiError = class extends Error {
   }
   code;
 };
-function record(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function exactKeys(value, keys) {
-  const actual = Object.keys(value).sort();
-  const expected = [...keys].sort();
-  return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
-}
-function validTimestamp(value) {
-  return typeof value === "string" && Number.isFinite(Date.parse(value));
-}
 function parseActiveAdapter(value) {
   if (value === null) return null;
   if (!record(value) || !exactKeys(value, ["canDispatch", "connectedAt", "kind", "state", "updatedAt"]) || value.kind !== "claude-channel" && value.kind !== "codex-app-server" || value.state !== "ready" && value.state !== "busy" && value.state !== "blocked" || typeof value.canDispatch !== "boolean" || value.canDispatch !== (value.state === "ready") || !validTimestamp(value.connectedAt) || !validTimestamp(value.updatedAt)) {
@@ -85,7 +426,7 @@ function parseCapability(value) {
     "dispatch",
     "enabled",
     "snapshotSchemaVersion"
-  ]) || value.enabled !== true || typeof value.brokerReady !== "boolean" || !Number.isSafeInteger(value.activeWaitCount) || value.activeWaitCount < 0 || value.activeWaitCount > import_external_handoff_browser.EXTERNAL_HANDOFF_LIMITS.maximumWaiters || value.snapshotSchemaVersion !== import_external_handoff_browser.EXTERNAL_HANDOFF_SNAPSHOT_SCHEMA_VERSION || value.brokerProtocolVersion !== import_external_handoff_browser.EXTERNAL_HANDOFF_BROKER_PROTOCOL_VERSION) {
+  ]) || value.enabled !== true || typeof value.brokerReady !== "boolean" || !Number.isSafeInteger(value.activeWaitCount) || value.activeWaitCount < 0 || value.activeWaitCount > import_external_handoff_browser2.EXTERNAL_HANDOFF_LIMITS.maximumWaiters || value.snapshotSchemaVersion !== import_external_handoff_browser2.EXTERNAL_HANDOFF_SNAPSHOT_SCHEMA_VERSION || value.brokerProtocolVersion !== import_external_handoff_browser2.EXTERNAL_HANDOFF_BROKER_PROTOCOL_VERSION) {
     throw new ExternalHandoffApiError();
   }
   return Object.freeze({
@@ -94,8 +435,8 @@ function parseCapability(value) {
     activeWaitCount: value.activeWaitCount,
     activeAdapter: parseActiveAdapter(value.activeAdapter),
     dispatch: parseDispatch(value.dispatch),
-    snapshotSchemaVersion: import_external_handoff_browser.EXTERNAL_HANDOFF_SNAPSHOT_SCHEMA_VERSION,
-    brokerProtocolVersion: import_external_handoff_browser.EXTERNAL_HANDOFF_BROKER_PROTOCOL_VERSION
+    snapshotSchemaVersion: import_external_handoff_browser2.EXTERNAL_HANDOFF_SNAPSHOT_SCHEMA_VERSION,
+    brokerProtocolVersion: import_external_handoff_browser2.EXTERNAL_HANDOFF_BROKER_PROTOCOL_VERSION
   });
 }
 function parsePublishResult(value) {
@@ -157,7 +498,7 @@ function parseSummary(value) {
     "targetCount",
     ...value.pickedUpAt === void 0 ? [] : ["pickedUpAt"]
   ];
-  if (!exactKeys(value, expectedKeys) || typeof value.sessionId !== "string" || !OPAQUE_ID_PATTERN.test(value.sessionId) || value.framework !== "vite" && value.framework !== "next" || !Number.isSafeInteger(value.revision) || value.revision <= 0 || typeof value.cursor !== "string" || !OPAQUE_ID_PATTERN.test(value.cursor) || !Number.isSafeInteger(value.targetCount) || value.targetCount <= 0 || !record(value.page) || !exactKeys(value.page, ["origin", "pathname"]) || typeof value.page.origin !== "string" || typeof value.page.pathname !== "string" || !validTimestamp(value.publishedAt) || !validTimestamp(value.expiresAt) || value.state !== "available" && value.state !== "expired" && value.state !== "superseded" || !Number.isSafeInteger(value.pickupCount) || value.pickupCount < 0 || value.pickupCount > import_external_handoff_browser.EXTERNAL_HANDOFF_LIMITS.maximumConnectorReceipts || value.pickedUpAt !== void 0 && !validTimestamp(value.pickedUpAt)) {
+  if (!exactKeys(value, expectedKeys) || typeof value.sessionId !== "string" || !OPAQUE_ID_PATTERN.test(value.sessionId) || value.framework !== "vite" && value.framework !== "next" || !Number.isSafeInteger(value.revision) || value.revision <= 0 || typeof value.cursor !== "string" || !OPAQUE_ID_PATTERN.test(value.cursor) || !Number.isSafeInteger(value.targetCount) || value.targetCount <= 0 || !record(value.page) || !exactKeys(value.page, ["origin", "pathname"]) || typeof value.page.origin !== "string" || typeof value.page.pathname !== "string" || !validTimestamp(value.publishedAt) || !validTimestamp(value.expiresAt) || value.state !== "available" && value.state !== "expired" && value.state !== "superseded" || !Number.isSafeInteger(value.pickupCount) || value.pickupCount < 0 || value.pickupCount > import_external_handoff_browser2.EXTERNAL_HANDOFF_LIMITS.maximumConnectorReceipts || value.pickedUpAt !== void 0 && !validTimestamp(value.pickedUpAt)) {
     throw new ExternalHandoffApiError();
   }
   return Object.freeze({
@@ -174,52 +515,8 @@ function parseSummary(value) {
     ...value.pickedUpAt === void 0 ? {} : { pickedUpAt: value.pickedUpAt }
   });
 }
-async function boundedJson(response) {
-  const declaredLength = Number(response.headers.get("content-length"));
-  if (Number.isFinite(declaredLength) && declaredLength > MAX_SUMMARY_RESPONSE_BYTES) {
-    await response.body?.cancel();
-    throw new ExternalHandoffApiError();
-  }
-  if (response.body === null) throw new ExternalHandoffApiError();
-  const reader = response.body.getReader();
-  const chunks = [];
-  let total = 0;
-  try {
-    for (; ; ) {
-      const chunk = await reader.read();
-      if (chunk.done) break;
-      total += chunk.value.byteLength;
-      if (total > MAX_SUMMARY_RESPONSE_BYTES) {
-        await reader.cancel();
-        throw new ExternalHandoffApiError();
-      }
-      chunks.push(chunk.value);
-    }
-  } finally {
-    reader.releaseLock();
-  }
-  const payload = new Uint8Array(total);
-  let offset = 0;
-  for (const chunk of chunks) {
-    payload.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
-  try {
-    return JSON.parse(
-      new TextDecoder("utf-8", { fatal: true }).decode(payload)
-    );
-  } catch {
-    throw new ExternalHandoffApiError();
-  }
-}
 function failureCode(value) {
-  return record(value) && value.ok === false && record(value.error) && (0, import_external_handoff_browser.isErrorCode)(value.error.code) ? value.error.code : void 0;
-}
-function successData(value) {
-  if (!record(value) || !exactKeys(value, ["data", "ok"]) || value.ok !== true) {
-    throw new ExternalHandoffApiError();
-  }
-  return value.data;
+  return record(value) && value.ok === false && record(value.error) && (0, import_external_handoff_browser2.isErrorCode)(value.error.code) ? value.error.code : void 0;
 }
 function omitBrowserCode(annotation) {
   return {
@@ -253,14 +550,23 @@ function api(options) {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          [import_external_handoff_browser.SPOTPATCH_TOKEN_HEADER]: options.sessionToken
+          [import_external_handoff_browser2.SPOTPATCH_TOKEN_HEADER]: options.sessionToken
         },
         body: JSON.stringify(body),
         signal: controller.signal
       });
-      const envelope = await boundedJson(response);
+      let envelope;
+      try {
+        envelope = await readBoundedJson(response, MAX_SUMMARY_RESPONSE_BYTES);
+      } catch {
+        throw new ExternalHandoffApiError();
+      }
       if (!response.ok) throw new ExternalHandoffApiError(failureCode(envelope));
-      return successData(envelope);
+      try {
+        return successData(envelope);
+      } catch {
+        throw new ExternalHandoffApiError();
+      }
     } finally {
       pending.delete(controller);
     }
@@ -272,12 +578,12 @@ function api(options) {
     },
     async capability() {
       return parseCapability(
-        await request(import_external_handoff_browser.SPOTPATCH_ENDPOINTS.externalHandoffCapability, {})
+        await request(import_external_handoff_browser2.SPOTPATCH_ENDPOINTS.externalHandoffCapability, {})
       );
     },
     async publish(requestId, annotation) {
       return parsePublishResult(
-        await request(import_external_handoff_browser.SPOTPATCH_ENDPOINTS.externalHandoffPublish, {
+        await request(import_external_handoff_browser2.SPOTPATCH_ENDPOINTS.externalHandoffPublish, {
           annotation: omitBrowserCode(annotation),
           requestId
         })
@@ -286,14 +592,14 @@ function api(options) {
     async status(cursor) {
       return parseStatusResult(
         await request(
-          import_external_handoff_browser.SPOTPATCH_ENDPOINTS.externalHandoffStatus,
+          import_external_handoff_browser2.SPOTPATCH_ENDPOINTS.externalHandoffStatus,
           cursor === void 0 ? {} : { cursor }
         )
       );
     },
     async resolveDelivery(cursor) {
       return parseStatusResult(
-        await request(import_external_handoff_browser.SPOTPATCH_ENDPOINTS.externalHandoffResolveDelivery, {
+        await request(import_external_handoff_browser2.SPOTPATCH_ENDPOINTS.externalHandoffResolveDelivery, {
           confirmation: "workspace-reviewed",
           cursor
         })
@@ -310,6 +616,7 @@ function createExternalHandoffWorkflow(fetch, panel, selectedAnnotation, session
     window
   };
   const client = api(options);
+  const controlClient = createExternalAgentControlClient(fetch, sessionToken);
   const timers = /* @__PURE__ */ new Set();
   const lifecycle = {
     disposed: false,
@@ -318,12 +625,152 @@ function createExternalHandoffWorkflow(fetch, panel, selectedAnnotation, session
     userActionPending: false
   };
   let capability;
+  let controlStatus;
+  let controlEventController;
+  let controlReconnectDelay = import_external_handoff_browser2.EXTERNAL_AGENT_CONTROL_LIMITS.eventReconnectMinimumMs;
+  let controlReconnectTimer;
+  let controlActionPending = false;
+  let managedResultRevision;
+  let managedResultLoadingRevision;
   let current;
   let retryablePublish;
+  const isDisposed = () => lifecycle.disposed;
   const clearTimers = () => {
     for (const timer of timers) options.window.clearTimeout(timer);
     timers.clear();
   };
+  const clearControlReconnect = () => {
+    if (controlReconnectTimer === void 0) return;
+    options.window.clearTimeout(controlReconnectTimer);
+    controlReconnectTimer = void 0;
+  };
+  const renderManagedResult = async (revision) => {
+    if (lifecycle.disposed || managedResultRevision === revision || managedResultLoadingRevision === revision) {
+      return;
+    }
+    managedResultLoadingRevision = revision;
+    try {
+      const result = await controlClient.result(revision);
+      if (isDisposed() || controlStatus?.task?.revision !== revision) return;
+      managedResultRevision = revision;
+      options.panel.renderManagedResult(result);
+    } catch {
+    } finally {
+      if (managedResultLoadingRevision === revision) {
+        managedResultLoadingRevision = void 0;
+      }
+    }
+  };
+  const applyControlStatus = (value) => {
+    if (controlStatus !== void 0 && value.sequence < controlStatus.sequence) return;
+    controlStatus = value;
+    controlReconnectDelay = import_external_handoff_browser2.EXTERNAL_AGENT_CONTROL_LIMITS.eventReconnectMinimumMs;
+    options.panel.renderControlStatus(value);
+    const resultRevision = value.task?.resultExpiresAt === void 0 ? void 0 : value.task.revision;
+    if (resultRevision !== void 0) void renderManagedResult(resultRevision);
+  };
+  const handleControlEvent = (event) => {
+    if (event.type === "status") {
+      applyControlStatus(event.data);
+      return;
+    }
+    const resultRevision = controlStatus?.task?.resultExpiresAt === void 0 ? void 0 : controlStatus.task.revision;
+    if (resultRevision !== void 0) void renderManagedResult(resultRevision);
+  };
+  const startControlEventStream = () => {
+    if (lifecycle.disposed || !lifecycle.mounted || controlEventController !== void 0) {
+      return;
+    }
+    clearControlReconnect();
+    const controller = new AbortController();
+    controlEventController = controller;
+    void controlClient.events(controlStatus?.sequence, controller.signal, handleControlEvent).catch((error) => {
+      if (lifecycle.disposed || error instanceof DOMException && error.name === "AbortError") {
+        return;
+      }
+      if (controlStatus === void 0) options.panel.renderControlUnavailable();
+    }).finally(() => {
+      if (controlEventController === controller) {
+        controlEventController = void 0;
+      }
+      if (lifecycle.disposed || !lifecycle.mounted) return;
+      const delay = controlReconnectDelay;
+      controlReconnectDelay = Math.min(
+        delay * 2,
+        import_external_handoff_browser2.EXTERNAL_AGENT_CONTROL_LIMITS.eventReconnectMaximumMs
+      );
+      controlReconnectTimer = options.window.setTimeout(() => {
+        controlReconnectTimer = void 0;
+        startControlEventStream();
+      }, delay);
+    });
+  };
+  const refreshControlStatus = async () => {
+    applyControlStatus(await controlClient.status());
+  };
+  const bootstrapControl = async () => {
+    try {
+      await refreshControlStatus();
+    } catch {
+      if (!lifecycle.disposed) options.panel.renderControlUnavailable();
+    } finally {
+      if (!lifecycle.disposed) startControlEventStream();
+    }
+  };
+  const performControlAction = async (action) => {
+    if (lifecycle.disposed || controlActionPending) return;
+    controlActionPending = true;
+    options.panel.setControlBusy(true);
+    try {
+      applyControlStatus(await action());
+    } catch {
+      try {
+        await refreshControlStatus();
+      } catch {
+        if (!isDisposed()) options.panel.renderControlUnavailable();
+      }
+    } finally {
+      controlActionPending = false;
+      if (!isDisposed()) options.panel.setControlBusy(false);
+    }
+  };
+  const handleConnectClick = () => {
+    void performControlAction(
+      () => controlClient.connect({
+        requestId: createRequestId(options.window),
+        adapterKind: "codex",
+        profile: import_external_handoff_browser2.EXTERNAL_AGENT_MANAGED_PROFILE
+      })
+    );
+  };
+  const handleDisconnectClick = () => {
+    void performControlAction(
+      () => controlClient.disconnect({
+        requestId: createRequestId(options.window),
+        adapterKind: "codex",
+        revokeGrant: false
+      })
+    );
+  };
+  const handleRevokeClick = () => {
+    void performControlAction(
+      () => controlClient.disconnect({
+        requestId: createRequestId(options.window),
+        adapterKind: "codex",
+        revokeGrant: true
+      })
+    );
+  };
+  const handleManagedCancelClick = () => {
+    const revision = controlStatus?.task?.revision;
+    if (revision === void 0) return;
+    void performControlAction(
+      () => controlClient.cancel({
+        requestId: createRequestId(options.window),
+        revision
+      })
+    );
+  };
   const errorCode = (error) => error instanceof ExternalHandoffApiError ? error.code : void 0;
   const restorePanel = () => {
     if (current !== void 0) options.panel.renderStatus(current);
@@ -370,7 +817,7 @@ function createExternalHandoffWorkflow(fetch, panel, selectedAnnotation, session
       void refreshStatus(revision).then(() => {
         if (continueWhilePending && !lifecycle.disposed && revision === lifecycle.operation && !lifecycle.userActionPending && current !== void 0 && dispatchIsPending(current.dispatch)) {
           scheduleRefresh(
-            import_external_handoff_browser.EXTERNAL_HANDOFF_LIMITS.activeStatusPollMs,
+            import_external_handoff_browser2.EXTERNAL_HANDOFF_LIMITS.activeStatusPollMs,
             continueWhilePending
           );
         }
@@ -386,7 +833,7 @@ function createExternalHandoffWorkflow(fetch, panel, selectedAnnotation, session
       const annotation = options.selectedAnnotation();
       if (annotation === void 0) {
         lifecycle.userActionPending = false;
-        options.panel.renderError(import_external_handoff_browser.ERROR_CODES.HANDOFF_VALIDATION_FAILED);
+        options.panel.renderError(import_external_handoff_browser2.ERROR_CODES.HANDOFF_VALIDATION_FAILED);
         return;
       }
       const disclosureRevision = lifecycle.operation;
@@ -419,7 +866,7 @@ function createExternalHandoffWorkflow(fetch, panel, selectedAnnotation, session
       });
       options.panel.renderPublishResult(result);
       scheduleRefresh(
-        result.delivery.mode === "active" ? import_external_handoff_browser.EXTERNAL_HANDOFF_LIMITS.activeStatusPollMs : 500,
+        result.delivery.mode === "active" ? import_external_handoff_browser2.EXTERNAL_HANDOFF_LIMITS.activeStatusPollMs : 500,
         result.delivery.mode === "active"
       );
     } catch (error) {
@@ -507,7 +954,15 @@ function createExternalHandoffWorkflow(fetch, panel, selectedAnnotation, session
       options.panel.sendButton.addEventListener("click", handleSendClick);
       options.panel.refreshButton.addEventListener("click", handleRefreshClick);
       options.panel.resolveButton.addEventListener("click", handleResolveClick);
+      options.panel.connectButton.addEventListener("click", handleConnectClick);
+      options.panel.disconnectButton.addEventListener("click", handleDisconnectClick);
+      options.panel.revokeButton.addEventListener("click", handleRevokeClick);
+      options.panel.cancelManagedButton.addEventListener(
+        "click",
+        handleManagedCancelClick
+      );
       void refreshCapability(lifecycle.operation);
+      void bootstrapControl();
     },
     cancelPending,
     dispose() {
@@ -517,10 +972,23 @@ function createExternalHandoffWorkflow(fetch, panel, selectedAnnotation, session
       lifecycle.userActionPending = false;
       retryablePublish = void 0;
       clearTimers();
+      clearControlReconnect();
+      controlEventController?.abort("workflow-disposed");
+      controlEventController = void 0;
       client.cancel();
       options.panel.sendButton.removeEventListener("click", handleSendClick);
       options.panel.refreshButton.removeEventListener("click", handleRefreshClick);
       options.panel.resolveButton.removeEventListener("click", handleResolveClick);
+      options.panel.connectButton.removeEventListener("click", handleConnectClick);
+      options.panel.disconnectButton.removeEventListener(
+        "click",
+        handleDisconnectClick
+      );
+      options.panel.revokeButton.removeEventListener("click", handleRevokeClick);
+      options.panel.cancelManagedButton.removeEventListener(
+        "click",
+        handleManagedCancelClick
+      );
     }
   });
 }
@@ -550,6 +1018,55 @@ function createButton(document, label, className = "") {
 var MESSAGES = Object.freeze({
   "en-US": Object.freeze({
     title: "External Agent connection",
+    agentLabel: "Agent",
+    codexManaged: "Codex \xB7 managed (experimental)",
+    connectManaged: "Connect Codex",
+    disconnectManaged: "Disconnect",
+    revokeManaged: "Revoke grant",
+    cancelManaged: "Cancel managed task",
+    resultTitle: "Managed result",
+    controlConnection: (state, mode) => `Connection: ${state} \xB7 Mode: ${mode}`,
+    controlAuth: (auth, grant) => `Auth: ${auth} \xB7 Grant: ${grant}`,
+    controlModel: (model) => `Model: ${model}`,
+    controlRevision: (task) => `Revision ${String(task.revision)}: ${task.deliveryStatus} / ${task.executionStatus} / ${task.managedPhase}`,
+    controlValidation: (outcome) => `Validation: ${outcome}`,
+    controlFailure: (error, action) => `Error: ${error} \xB7 Next: ${action}`,
+    controlUnavailable: "Page connection management is unavailable; external handoffs still fall back honestly to the Agent inbox.",
+    controlErrorText: Object.freeze({
+      AGENT_BINARY_NOT_FOUND: "Codex is not installed or is not on PATH.",
+      AGENT_BINARY_UNTRUSTED: "The resolved Codex executable is not trusted.",
+      AGENT_VERSION_UNSUPPORTED: "The installed Codex version is unsupported.",
+      APP_SERVER_HANDSHAKE_FAILED: "Codex App Server did not complete startup.",
+      AGENT_AUTH_REQUIRED: "Codex requires an authenticated account.",
+      AGENT_MODEL_UNAVAILABLE: "The configured Codex model is unavailable.",
+      AGENT_PROTOCOL_INCOMPATIBLE: "The Codex App Server protocol is incompatible.",
+      CODEX_CONFIG_ISOLATION_UNSUPPORTED: "This Codex version cannot prove managed configuration isolation.",
+      MANAGED_GRANT_INVALID: "The saved project grant failed validation.",
+      MANAGED_PLATFORM_UNSUPPORTED: "Managed execution is not proven safe on this platform.",
+      MANAGED_GIT_REQUIRED: "Managed execution requires a Git repository.",
+      MANAGED_SNAPSHOT_FAILED: "The independent workspace snapshot could not be created.",
+      MANAGED_SCOPE_VIOLATION: "The candidate change exceeded its authorized paths.",
+      MANAGED_CHANGE_LIMIT_EXCEEDED: "The candidate change exceeded safety limits.",
+      MANAGED_VALIDATION_FAILED: "A required check failed or changed the candidate diff.",
+      MANAGED_WORKSPACE_CONFLICT: "An authorized source file changed during execution.",
+      MANAGED_APPLY_FAILED: "The audited change could not be applied safely.",
+      MANAGED_CLEANUP_INCOMPLETE: "Managed thread or workspace cleanup is incomplete."
+    }),
+    controlActionText: Object.freeze({
+      "install-agent": "Install Codex and retry.",
+      "use-supported-version": "Use a supported Codex version.",
+      "sign-in": "Sign in with Codex, then retry.",
+      "choose-available-model": "Choose an available model in Codex configuration.",
+      "use-inbox": "Continue with the Agent inbox fallback.",
+      "confirm-managed-access": "Revoke the invalid grant and confirm access again.",
+      "review-candidate-diff": "Review the candidate diff and validation output.",
+      "review-workspace-conflict": "Review the workspace changes before retrying.",
+      retry: "Retry the managed connection.",
+      "inspect-cleanup-warning": "Inspect cleanup status before reconnecting."
+    }),
+    resultHeader: (revision, outcome) => `Revision ${String(revision)} \xB7 Validation ${outcome}`,
+    resultDisposition: (outcome) => outcome === "passed" ? "Applied to the project after validation passed." : `Candidate only; it was not applied because validation is ${outcome}.`,
+    resultTiming: (stage, durationMs) => `Timing ${stage}: ${String(durationMs)} ms`,
     description: "Send through a ready active adapter, or publish to the project Agent inbox when no active adapter is connected.",
     ready: "Local Broker ready. No Agent connection is assumed until a connector reads or waits.",
     readyWaiting: (count) => `${String(count)} active connector wait request(s); publishing can wake them immediately.`,
@@ -573,19 +1090,69 @@ var MESSAGES = Object.freeze({
     refresh: "Refresh pickup status",
     resolveUnknown: "Workspace reviewed \u2014 allow a new task",
     settingsTitle: "Project connection setup",
-    settingsHelp: "Setup commands are project-scoped dry runs; append --write only after review. Claude active mode also needs the shown Research Preview launch flag. Codex active mode is zero-setup: run its explicit connector command and keep it open.",
+    settingsHelp: "Codex managed mode is owned by the current development server. The browser never receives vendor credentials or arbitrary command access. Generic and attached adapters remain honest Inbox fallbacks.",
     disclosureTitle: "Confirm external Agent handoff",
     disclosureIntro: (targets, files) => `Publish ${String(targets)} selected target(s) referencing ${String(files)} relative file(s).`,
     disclosureData: "The handoff includes your instructions, component/page context, sanitized DOM/CSS, and bounded source read again by the local Node service.",
     disclosureInbox: "Any SpotPatch connector configured for this project may read it during the 15-minute lifetime.",
     disclosureProvider: "The Agent host may send the content to its cloud provider under that product's data policy.",
     disclosureNoGuarantee: "External edits do not receive SpotPatch's built-in worktree, Apply, or Revert guarantees.",
+    disclosureManagedGuarantee: "Managed Codex edits run in an independent temporary snapshot. SpotPatch audits the diff and only applies it when every trusted required check passes.",
     cancel: "Cancel",
     confirm: "Confirm and send",
     error: (code) => code === "EXTERNAL_AGENT_BUSY" ? "The active Agent is still busy or blocked by an uncertain delivery." : code === "ACTIVE_DISPATCH_INVALID" ? "The active delivery state changed. Refresh before continuing." : code === "HANDOFF_SOURCE_STALE" ? "The selected source changed. Select the current component again." : code === "HANDOFF_RESPONSE_TOO_LARGE" ? "The handoff is too large. Reduce the selected context." : code === "EXTERNAL_HANDOFF_DISABLED" ? "External Agent handoff is disabled in trusted project configuration." : code === "EXTERNAL_HANDOFF_UNAVAILABLE" || code === "SESSION_CLOSED" ? "The local external Agent Broker is unavailable. Restart the development server." : "The external Agent handoff request failed without publishing a partial revision."
   }),
   "zh-CN": Object.freeze({
     title: "\u5916\u90E8 Agent \u8FDE\u63A5",
+    agentLabel: "Agent",
+    codexManaged: "Codex \xB7 \u53D7\u7BA1\u6A21\u5F0F\uFF08\u5B9E\u9A8C\u6027\uFF09",
+    connectManaged: "\u8FDE\u63A5 Codex",
+    disconnectManaged: "\u65AD\u5F00\u8FDE\u63A5",
+    revokeManaged: "\u64A4\u9500\u6388\u6743",
+    cancelManaged: "\u53D6\u6D88\u53D7\u7BA1\u4EFB\u52A1",
+    resultTitle: "\u53D7\u7BA1\u6267\u884C\u7ED3\u679C",
+    controlConnection: (state, mode) => `\u8FDE\u63A5\uFF1A${state} \xB7 \u6A21\u5F0F\uFF1A${mode}`,
+    controlAuth: (auth, grant) => `\u8BA4\u8BC1\uFF1A${auth} \xB7 \u6388\u6743\uFF1A${grant}`,
+    controlModel: (model) => `\u6A21\u578B\uFF1A${model}`,
+    controlRevision: (task) => `revision ${String(task.revision)}\uFF1A${task.deliveryStatus} / ${task.executionStatus} / ${task.managedPhase}`,
+    controlValidation: (outcome) => `\u9A8C\u8BC1\uFF1A${outcome}`,
+    controlFailure: (error, action) => `\u9519\u8BEF\uFF1A${error} \xB7 \u4E0B\u4E00\u6B65\uFF1A${action}`,
+    controlUnavailable: "\u9875\u9762\u8FDE\u63A5\u7BA1\u7406\u4E0D\u53EF\u7528\uFF1B\u5916\u90E8\u4EA4\u63A5\u4ECD\u4F1A\u6309\u771F\u5B9E\u80FD\u529B\u964D\u7EA7\u4E3A Agent \u6536\u4EF6\u7BB1\u3002",
+    controlErrorText: Object.freeze({
+      AGENT_BINARY_NOT_FOUND: "\u672A\u5B89\u88C5 Codex\uFF0C\u6216 Codex \u4E0D\u5728 PATH \u4E2D\u3002",
+      AGENT_BINARY_UNTRUSTED: "\u89E3\u6790\u5230\u7684 Codex \u53EF\u6267\u884C\u6587\u4EF6\u4E0D\u53EF\u4FE1\u3002",
+      AGENT_VERSION_UNSUPPORTED: "\u5DF2\u5B89\u88C5\u7684 Codex \u7248\u672C\u4E0D\u53D7\u652F\u6301\u3002",
+      APP_SERVER_HANDSHAKE_FAILED: "Codex App Server \u672A\u5B8C\u6210\u542F\u52A8\u63E1\u624B\u3002",
+      AGENT_AUTH_REQUIRED: "Codex \u9700\u8981\u5DF2\u767B\u5F55\u7684\u8D26\u6237\u3002",
+      AGENT_MODEL_UNAVAILABLE: "Codex \u914D\u7F6E\u7684\u6A21\u578B\u5F53\u524D\u4E0D\u53EF\u7528\u3002",
+      AGENT_PROTOCOL_INCOMPATIBLE: "Codex App Server \u534F\u8BAE\u4E0D\u517C\u5BB9\u3002",
+      CODEX_CONFIG_ISOLATION_UNSUPPORTED: "\u5F53\u524D Codex \u7248\u672C\u65E0\u6CD5\u8BC1\u660E\u53D7\u7BA1\u914D\u7F6E\u9694\u79BB\u3002",
+      MANAGED_GRANT_INVALID: "\u4FDD\u5B58\u7684\u9879\u76EE\u6388\u6743\u672A\u901A\u8FC7\u6821\u9A8C\u3002",
+      MANAGED_PLATFORM_UNSUPPORTED: "\u5F53\u524D\u5E73\u53F0\u5C1A\u672A\u8BC1\u660E\u53EF\u5B89\u5168\u8FD0\u884C\u53D7\u7BA1\u6267\u884C\u3002",
+      MANAGED_GIT_REQUIRED: "\u53D7\u7BA1\u6267\u884C\u8981\u6C42\u9879\u76EE\u4F4D\u4E8E Git \u4ED3\u5E93\u4E2D\u3002",
+      MANAGED_SNAPSHOT_FAILED: "\u65E0\u6CD5\u521B\u5EFA\u72EC\u7ACB\u5DE5\u4F5C\u533A\u5FEB\u7167\u3002",
+      MANAGED_SCOPE_VIOLATION: "\u5019\u9009\u4FEE\u6539\u8D85\u51FA\u6388\u6743\u8DEF\u5F84\u3002",
+      MANAGED_CHANGE_LIMIT_EXCEEDED: "\u5019\u9009\u4FEE\u6539\u8D85\u8FC7\u5B89\u5168\u4E0A\u9650\u3002",
+      MANAGED_VALIDATION_FAILED: "required check \u5931\u8D25\u6216\u6539\u53D8\u4E86\u5019\u9009 diff\u3002",
+      MANAGED_WORKSPACE_CONFLICT: "\u6267\u884C\u671F\u95F4\u6388\u6743\u6E90\u7801\u53D1\u751F\u4E86\u53D8\u5316\u3002",
+      MANAGED_APPLY_FAILED: "\u5DF2\u5BA1\u8BA1\u4FEE\u6539\u65E0\u6CD5\u5B89\u5168\u5199\u5165\u3002",
+      MANAGED_CLEANUP_INCOMPLETE: "\u53D7\u7BA1 thread \u6216\u5DE5\u4F5C\u533A\u6E05\u7406\u4E0D\u5B8C\u6574\u3002"
+    }),
+    controlActionText: Object.freeze({
+      "install-agent": "\u5B89\u88C5 Codex \u540E\u91CD\u8BD5\u3002",
+      "use-supported-version": "\u6539\u7528\u53D7\u652F\u6301\u7684 Codex \u7248\u672C\u3002",
+      "sign-in": "\u767B\u5F55 Codex \u540E\u91CD\u8BD5\u3002",
+      "choose-available-model": "\u5728 Codex \u914D\u7F6E\u4E2D\u9009\u62E9\u53EF\u7528\u6A21\u578B\u3002",
+      "use-inbox": "\u7EE7\u7EED\u4F7F\u7528 Agent \u6536\u4EF6\u7BB1\u964D\u7EA7\u8DEF\u5F84\u3002",
+      "confirm-managed-access": "\u64A4\u9500\u65E0\u6548\u6388\u6743\u5E76\u91CD\u65B0\u786E\u8BA4\u3002",
+      "review-candidate-diff": "\u68C0\u67E5\u5019\u9009 diff \u548C\u9A8C\u8BC1\u8F93\u51FA\u3002",
+      "review-workspace-conflict": "\u68C0\u67E5\u5DE5\u4F5C\u533A\u53D8\u5316\u540E\u518D\u91CD\u8BD5\u3002",
+      retry: "\u91CD\u8BD5\u53D7\u7BA1\u8FDE\u63A5\u3002",
+      "inspect-cleanup-warning": "\u786E\u8BA4\u6E05\u7406\u72B6\u6001\u540E\u518D\u8FDE\u63A5\u3002"
+    }),
+    resultHeader: (revision, outcome) => `revision ${String(revision)} \xB7 \u9A8C\u8BC1 ${outcome}`,
+    resultDisposition: (outcome) => outcome === "passed" ? "\u9A8C\u8BC1\u901A\u8FC7\uFF0C\u4FEE\u6539\u5DF2\u5199\u5165\u9879\u76EE\u3002" : `\u8FD9\u53EA\u662F\u5019\u9009 diff\uFF1B\u9A8C\u8BC1\u72B6\u6001\u4E3A ${outcome}\uFF0C\u56E0\u6B64\u6CA1\u6709\u5199\u5165\u9879\u76EE\u3002`,
+    resultTiming: (stage, durationMs) => `\u8017\u65F6 ${stage}: ${String(durationMs)} ms`,
     description: "\u6709\u4E3B\u52A8\u9002\u914D\u5668\u5C31\u7ACB\u5373\u6D3E\u53D1\uFF1B\u672A\u8FDE\u63A5\u4E3B\u52A8\u9002\u914D\u5668\u65F6\uFF0C\u8BDA\u5B9E\u964D\u7EA7\u4E3A\u9879\u76EE Agent \u6536\u4EF6\u7BB1\u3002",
     ready: "\u672C\u5730 Broker \u5DF2\u5C31\u7EEA\u3002\u53EA\u6709\u8FDE\u63A5\u5668\u8BFB\u53D6\u6216\u7B49\u5F85\u540E\uFF0C\u624D\u80FD\u8BC1\u660E\u53D1\u751F\u8FC7\u8FDE\u63A5\u3002",
     readyWaiting: (count) => `\u5F53\u524D\u6709 ${String(count)} \u4E2A\u8FDE\u63A5\u5668\u7B49\u5F85\u8BF7\u6C42\uFF0C\u53D1\u5E03\u540E\u53EF\u7ACB\u5373\u5524\u9192\u3002`,
@@ -609,13 +1176,14 @@ var MESSAGES = Object.freeze({
     refresh: "\u5237\u65B0\u53D6\u4EF6\u72B6\u6001",
     resolveUnknown: "\u5DF2\u6838\u5BF9\u5DE5\u4F5C\u533A\uFF0C\u5141\u8BB8\u65B0\u4EFB\u52A1",
     settingsTitle: "\u9879\u76EE\u8FDE\u63A5\u8BBE\u7F6E",
-    settingsHelp: "setup \u547D\u4EE4\u5747\u4E3A\u9879\u76EE\u7EA7 dry-run\uFF0C\u6838\u5BF9\u540E\u624D\u8FFD\u52A0 --write\u3002Claude \u4E3B\u52A8\u6A21\u5F0F\u8FD8\u9700\u4F7F\u7528\u4E0B\u65B9 Research Preview \u542F\u52A8\u53C2\u6570\uFF1BCodex \u4E3B\u52A8\u6A21\u5F0F\u65E0\u9700 setup\uFF0C\u53EA\u9700\u663E\u5F0F\u542F\u52A8\u5E76\u4FDD\u6301 Connector \u547D\u4EE4\u8FD0\u884C\u3002",
+    settingsHelp: "Codex \u53D7\u7BA1\u6A21\u5F0F\u7531\u5F53\u524D\u5F00\u53D1\u670D\u52A1\u6258\u7BA1\uFF0C\u6D4F\u89C8\u5668\u4E0D\u4F1A\u83B7\u5F97\u5382\u5546\u51ED\u8BC1\u6216\u4EFB\u610F\u547D\u4EE4\u6743\u9650\uFF1B\u901A\u7528\u4E0E attached adapter \u4ECD\u6309\u771F\u5B9E\u80FD\u529B\u964D\u7EA7\u4E3A\u6536\u4EF6\u7BB1\u3002",
     disclosureTitle: "\u786E\u8BA4\u53D1\u5E03\u5230\u5916\u90E8 Agent",
     disclosureIntro: (targets, files) => `\u5C06\u53D1\u5E03 ${String(targets)} \u4E2A\u76EE\u6807\uFF0C\u6D89\u53CA ${String(files)} \u4E2A\u9879\u76EE\u76F8\u5BF9\u6587\u4EF6\u3002`,
     disclosureData: "\u4EA4\u63A5\u5305\u542B\u4FEE\u6539\u8BF4\u660E\u3001\u7EC4\u4EF6\u4E0E\u9875\u9762\u4E0A\u4E0B\u6587\u3001\u5DF2\u6E05\u6D17\u7684 DOM/CSS\uFF0C\u4EE5\u53CA\u672C\u5730 Node \u670D\u52A1\u91CD\u65B0\u8BFB\u53D6\u7684\u6709\u754C\u6E90\u7801\u3002",
     disclosureInbox: "15 \u5206\u949F\u6709\u6548\u671F\u5185\uFF0C\u672C\u9879\u76EE\u4E2D\u4EFB\u4F55\u5DF2\u914D\u7F6E\u7684 SpotPatch Connector \u90FD\u53EF\u80FD\u8BFB\u53D6\u3002",
     disclosureProvider: "Agent \u5BBF\u4E3B\u53EF\u80FD\u4F9D\u636E\u5176\u4EA7\u54C1\u6570\u636E\u7B56\u7565\uFF0C\u5C06\u5185\u5BB9\u53D1\u9001\u7ED9\u4E91\u7AEF\u6A21\u578B\u670D\u52A1\u3002",
     disclosureNoGuarantee: "\u5916\u90E8\u4FEE\u6539\u4E0D\u5177\u5907 SpotPatch \u5185\u5EFA Agent \u7684 worktree\u3001Apply \u6216 Revert \u4FDD\u8BC1\u3002",
+    disclosureManagedGuarantee: "\u53D7\u7BA1 Codex \u53EA\u5199\u72EC\u7ACB\u4E34\u65F6\u5FEB\u7167\u3002SpotPatch \u4F1A\u5BA1\u8BA1 diff\uFF0C\u4E14\u4EC5\u5728\u6240\u6709\u53EF\u4FE1 required checks \u901A\u8FC7\u540E\u624D\u5199\u5165\u4E1A\u52A1\u4ED3\u5E93\u3002",
     cancel: "\u53D6\u6D88",
     confirm: "\u786E\u8BA4\u5E76\u53D1\u9001",
     error: (code) => code === "EXTERNAL_AGENT_BUSY" ? "\u4E3B\u52A8 Agent \u4ECD\u5728\u5DE5\u4F5C\uFF0C\u6216\u5B58\u5728\u5C1A\u672A\u6838\u5BF9\u7684\u6295\u9012\u672A\u77E5\u72B6\u6001\u3002" : code === "ACTIVE_DISPATCH_INVALID" ? "\u4E3B\u52A8\u6295\u9012\u72B6\u6001\u5DF2\u7ECF\u53D8\u5316\uFF0C\u8BF7\u5237\u65B0\u540E\u518D\u7EE7\u7EED\u3002" : code === "HANDOFF_SOURCE_STALE" ? "\u9009\u4E2D\u6E90\u7801\u5DF2\u7ECF\u53D8\u5316\uFF0C\u8BF7\u91CD\u65B0\u9009\u62E9\u5F53\u524D\u7EC4\u4EF6\u3002" : code === "HANDOFF_RESPONSE_TOO_LARGE" ? "\u4EA4\u63A5\u5185\u5BB9\u8D85\u8FC7\u4E0A\u9650\uFF0C\u8BF7\u51CF\u5C11\u6240\u9009\u4E0A\u4E0B\u6587\u3002" : code === "EXTERNAL_HANDOFF_DISABLED" ? "\u53EF\u4FE1\u9879\u76EE\u914D\u7F6E\u6CA1\u6709\u542F\u7528\u5916\u90E8 Agent \u4EA4\u63A5\u3002" : code === "EXTERNAL_HANDOFF_UNAVAILABLE" || code === "SESSION_CLOSED" ? "\u672C\u5730\u5916\u90E8 Agent Broker \u4E0D\u53EF\u7528\uFF0C\u8BF7\u91CD\u542F\u5F00\u53D1\u670D\u52A1\u3002" : "\u5916\u90E8 Agent \u4EA4\u63A5\u8BF7\u6C42\u5931\u8D25\uFF0C\u672A\u53D1\u5E03\u4EFB\u4F55\u90E8\u5206 revision\u3002"
@@ -632,9 +1200,17 @@ function createStyles(document) {
     .spotpatch-external-status { padding-left: 10px; border-left: 2px solid var(--spotpatch-accent-cyan); color: #cbd5e1; }
     .spotpatch-external-status[data-state="error"] { border-color: var(--spotpatch-danger); color: #fecdd3; }
     .spotpatch-external-status[data-state="picked-up"] { border-color: var(--spotpatch-success); color: #a7f3d0; }
+    .spotpatch-external-control { margin-top: 9px; padding: 9px; border: 1px solid var(--spotpatch-border); border-radius: 8px; background: rgb(3 7 18 / 28%); }
+    .spotpatch-external-control label { display: grid; gap: 4px; color: var(--spotpatch-text-secondary); font-size: 10px; }
+    .spotpatch-external-control select { width: 100%; padding: 6px 8px; border: 1px solid var(--spotpatch-border); border-radius: 6px; background: var(--spotpatch-bg-input); color: var(--spotpatch-text); font: inherit; }
+    .spotpatch-external-control-status { margin: 7px 0 0; color: #cbd5e1; font-size: 10.5px; line-height: 1.5; white-space: pre-wrap; }
+    .spotpatch-external-control-actions { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 8px; }
+    .spotpatch-external-control-actions button { padding: 5px 8px; border: 1px solid var(--spotpatch-border); border-radius: 6px; background: var(--spotpatch-bg-active); color: var(--spotpatch-text); font: inherit; font-size: 10px; cursor: pointer; }
+    .spotpatch-external-control-actions button:disabled { cursor: default; opacity: .45; }
+    .spotpatch-external-result { margin-top: 8px; color: var(--spotpatch-text-secondary); font-size: 10px; }
+    .spotpatch-external-result pre { max-height: 180px; overflow: auto; margin: 6px 0 0; padding: 7px; border-radius: 6px; background: var(--spotpatch-bg-input); color: #d8d6ff; font: 9px/1.45 ui-monospace, SFMono-Regular, Menlo, monospace; white-space: pre; }
     .spotpatch-external-settings { margin-top: 9px; }
     .spotpatch-external-settings summary { cursor: pointer; color: #c4b5fd; font-size: 11px; }
-    .spotpatch-external-command { display: block; margin-top: 6px; padding: 6px 8px; overflow: auto; border-radius: 6px; background: var(--spotpatch-bg-input); color: #d8d6ff; font: 10px/1.45 ui-monospace, SFMono-Regular, Menlo, monospace; white-space: nowrap; }
     .spotpatch-external-refresh { padding: 3px 7px; border: 1px solid var(--spotpatch-border); border-radius: 6px; background: transparent; color: var(--spotpatch-text-secondary); font: inherit; font-size: 10px; cursor: pointer; }
     .spotpatch-external-refresh:disabled { cursor: default; opacity: .45; }
     .spotpatch-external-resolve { margin-top: 8px; padding: 6px 8px; border: 1px solid #f59e0b; border-radius: 6px; background: rgb(245 158 11 / 10%); color: #fde68a; font: inherit; font-size: 10px; cursor: pointer; }
@@ -695,6 +1271,44 @@ function disclosurePaths(annotation) {
     )
   ]);
 }
+function controlStatusText(value, messages) {
+  const model = value.effectiveModel ?? value.requestedModel;
+  const task = value.task;
+  const parts = [
+    messages.controlConnection(value.connectionState, value.mode),
+    messages.controlAuth(value.authReadiness, value.grantState),
+    ...model === void 0 ? [] : [messages.controlModel(model)],
+    ...task === void 0 ? [] : [
+      messages.controlRevision(task),
+      ...task.validationOutcome === void 0 ? [] : [messages.controlValidation(task.validationOutcome)]
+    ],
+    ...value.error === void 0 ? [] : [
+      messages.controlFailure(
+        messages.controlErrorText[value.error.code],
+        messages.controlActionText[value.error.action]
+      )
+    ]
+  ];
+  return parts.join("\n");
+}
+function managedResultText(result, messages) {
+  const files = result.files.map(
+    (file) => `${file.path} +${String(file.additions)} -${String(file.deletions)}`
+  );
+  const checks = result.checks.map(
+    (check) => `${check.id}: ${check.outcome} (${String(check.durationMs)} ms${check.exitCode === void 0 ? "" : `, exit ${String(check.exitCode)}`})`
+  );
+  const timings = Object.entries(result.timings).flatMap(
+    ([stage, durationMs]) => durationMs === void 0 ? [] : [messages.resultTiming(stage, durationMs)]
+  );
+  return [
+    messages.resultHeader(result.revision, result.validationOutcome),
+    messages.resultDisposition(result.validationOutcome),
+    ...files,
+    ...checks,
+    ...timings
+  ].join("\n");
+}
 function createExternalHandoffPanel(document, framework, locale, sessionId, subscribeLocale, onViewChange) {
   const options = {
     document,
@@ -712,7 +1326,10 @@ function createExternalHandoffPanel(document, framework, locale, sessionId, subs
   let retryable = false;
   let unknownDelivery = false;
   let contextReady = false;
+  let controlOperationBusy = false;
   let visible = false;
+  let control;
+  let managedResultValue;
   let pendingDisclosure;
   let previousFocus;
   const consentKey = `spotpatch:external-handoff-consent:${options.sessionId}`;
@@ -730,27 +1347,46 @@ function createExternalHandoffPanel(document, framework, locale, sessionId, subs
   status.className = "spotpatch-external-status";
   status.setAttribute("role", "status");
   status.setAttribute("aria-live", "polite");
+  const controlRoot = createMarkedElement(document, "div");
+  controlRoot.className = "spotpatch-external-control";
+  const agentLabel = createMarkedElement(document, "label");
+  const agentLabelText = createMarkedElement(document, "span");
+  const agentSelect = createMarkedElement(document, "select");
+  const codexOption = createMarkedElement(document, "option");
+  codexOption.value = "codex";
+  agentSelect.append(codexOption);
+  agentLabel.append(agentLabelText, agentSelect);
+  const controlStatus = createMarkedElement(document, "p");
+  controlStatus.className = "spotpatch-external-control-status";
+  controlStatus.setAttribute("role", "status");
+  const controlActions = createMarkedElement(document, "div");
+  controlActions.className = "spotpatch-external-control-actions";
+  const connectButton = createButton(document, "");
+  const disconnectButton = createButton(document, "");
+  const revokeButton = createButton(document, "");
+  const cancelManagedButton = createButton(document, "");
+  controlActions.append(
+    connectButton,
+    disconnectButton,
+    revokeButton,
+    cancelManagedButton
+  );
+  const managedResult = createMarkedElement(document, "details");
+  managedResult.className = "spotpatch-external-result";
+  managedResult.hidden = true;
+  const managedResultTitle = createMarkedElement(document, "summary");
+  const managedResultSummary = createMarkedElement(document, "p");
+  const managedResultDiff = createMarkedElement(document, "pre");
+  managedResult.append(managedResultTitle, managedResultSummary, managedResultDiff);
+  controlRoot.append(agentLabel, controlStatus, controlActions, managedResult);
   const resolveButton = createButton(document, "", "spotpatch-external-resolve");
   resolveButton.hidden = true;
   const settings = createMarkedElement(document, "details");
   settings.className = "spotpatch-external-settings";
   const settingsTitle = createMarkedElement(document, "summary");
   const settingsHelp = createMarkedElement(document, "p");
-  const cliPrefix = `node ./node_modules/@spotpatch/${options.framework}/dist/cli.js`;
-  const bridgePrefix = `${cliPrefix} bridge`;
-  const commands = [
-    `${bridgePrefix} setup --client claude --scope project --mode active`,
-    "MCP_PROTOCOL_NEGOTIATION=legacy claude --dangerously-load-development-channels server:spotpatch",
-    `${cliPrefix} connect codex --allow-workspace-write`,
-    `${bridgePrefix} setup --client cursor --scope project`
-  ].map((value) => {
-    const command = createMarkedElement(document, "code");
-    command.className = "spotpatch-external-command";
-    command.textContent = value;
-    return command;
-  });
-  settings.append(settingsTitle, settingsHelp, ...commands);
-  root.append(heading, description, status, resolveButton, settings);
+  settings.append(settingsTitle, settingsHelp);
+  root.append(heading, description, controlRoot, status, resolveButton, settings);
   const sendButton = createButton(document, "", "spotpatch-primary");
   sendButton.hidden = true;
   const disclosure = createMarkedElement(document, "div");
@@ -807,6 +1443,23 @@ function createExternalHandoffPanel(document, framework, locale, sessionId, subs
     resolveButton.hidden = !unknownDelivery;
     resolveButton.disabled = !visible || operationBusy || !unknownDelivery;
   };
+  const refreshControlActions = () => {
+    if (control === void 0) {
+      connectButton.disabled = true;
+      disconnectButton.disabled = true;
+      revokeButton.disabled = true;
+      cancelManagedButton.hidden = true;
+      return;
+    }
+    const state = control.connectionState;
+    const operationPending = controlOperationBusy || state === "diagnosing" || state === "connecting" || state === "disconnecting";
+    connectButton.disabled = operationPending || state === "ready" || state === "busy";
+    disconnectButton.disabled = operationPending || state === "disconnected";
+    revokeButton.disabled = operationPending || control.grantState !== "valid";
+    const phase = control.task?.managedPhase;
+    cancelManagedButton.hidden = phase === void 0 || phase === "completed" || phase === "review-required" || phase === "failed" || phase === "cancelled" || phase === "cleanup-warning";
+    cancelManagedButton.disabled = operationPending;
+  };
   const settleDisclosure = (confirmed) => {
     if (pendingDisclosure === void 0) return;
     const resolve = pendingDisclosure;
@@ -850,10 +1503,28 @@ function createExternalHandoffPanel(document, framework, locale, sessionId, subs
     disclosureInbox.textContent = messages.disclosureInbox;
     disclosureProvider.textContent = messages.disclosureProvider;
     disclosureNoGuarantee.textContent = messages.disclosureNoGuarantee;
+    agentLabelText.textContent = messages.agentLabel;
+    codexOption.textContent = messages.codexManaged;
+    connectButton.textContent = messages.connectManaged;
+    disconnectButton.textContent = messages.disconnectManaged;
+    revokeButton.textContent = messages.revokeManaged;
+    cancelManagedButton.textContent = messages.cancelManaged;
+    managedResultTitle.textContent = messages.resultTitle;
+    if (control !== void 0) {
+      controlStatus.textContent = controlStatusText(control, messages);
+      disclosureNoGuarantee.textContent = control.mode === "managed" ? messages.disclosureManagedGuarantee : messages.disclosureNoGuarantee;
+    }
+    if (managedResultValue !== void 0) {
+      managedResultSummary.textContent = managedResultText(
+        managedResultValue,
+        messages
+      );
+    }
     cancelButton.textContent = messages.cancel;
     confirmButton.textContent = messages.confirm;
     resolveButton.textContent = messages.resolveUnknown;
     refreshActions();
+    refreshControlActions();
   };
   cancelButton.addEventListener("click", () => {
     settleDisclosure(false);
@@ -863,10 +1534,13 @@ function createExternalHandoffPanel(document, framework, locale, sessionId, subs
   });
   disclosure.addEventListener("keydown", handleDisclosureKeydown);
   settings.addEventListener("toggle", options.onViewChange);
+  managedResult.addEventListener("toggle", options.onViewChange);
   const unsubscribeLocale = options.subscribeLocale(applyMessages);
   applyMessages();
   status.textContent = messages.ready;
+  controlStatus.textContent = options.locale() === "zh-CN" ? "\u6B63\u5728\u8BFB\u53D6\u672C\u5730\u8FDE\u63A5\u72B6\u6001\u2026\u2026" : "Reading local connection status\u2026";
   refreshActions();
+  refreshControlActions();
   const summaryMessage = (summary) => summary.state === "expired" ? messages.expired(summary.revision) : summary.state === "superseded" ? messages.superseded(summary.revision) : summary.pickupCount > 0 ? messages.pickedUp(
     summary.revision,
     summary.pickupCount,
@@ -900,6 +1574,10 @@ function createExternalHandoffPanel(document, framework, locale, sessionId, subs
     sendButton,
     refreshButton,
     resolveButton,
+    cancelManagedButton,
+    connectButton,
+    disconnectButton,
+    revokeButton,
     confirmDisclosure(annotation) {
       if (hasConsent()) return Promise.resolve(true);
       if (pendingDisclosure !== void 0) return Promise.resolve(false);
@@ -951,6 +1629,30 @@ function createExternalHandoffPanel(document, framework, locale, sessionId, subs
     renderStatus(result) {
       applyStatus(result);
     },
+    renderControlStatus(value) {
+      control = value;
+      controlStatus.textContent = controlStatusText(value, messages);
+      controlStatus.dataset.state = value.connectionState;
+      disclosureNoGuarantee.textContent = value.mode === "managed" ? messages.disclosureManagedGuarantee : messages.disclosureNoGuarantee;
+      refreshControlActions();
+      options.onViewChange();
+    },
+    renderControlUnavailable() {
+      control = void 0;
+      controlStatus.dataset.state = "unavailable";
+      controlStatus.textContent = messages.controlUnavailable;
+      disclosureNoGuarantee.textContent = messages.disclosureNoGuarantee;
+      refreshControlActions();
+      options.onViewChange();
+    },
+    renderManagedResult(result) {
+      managedResultValue = result;
+      managedResult.hidden = false;
+      managedResult.open = true;
+      managedResultSummary.textContent = managedResultText(result, messages);
+      managedResultDiff.textContent = result.diff;
+      options.onViewChange();
+    },
     renderError(code, canRetry = false) {
       operationBusy = false;
       retryable = canRetry;
@@ -964,6 +1666,10 @@ function createExternalHandoffPanel(document, framework, locale, sessionId, subs
       operationBusy = nextBusy;
       refreshActions();
     },
+    setControlBusy(nextBusy) {
+      controlOperationBusy = nextBusy;
+      refreshControlActions();
+    },
     setContextReady(ready) {
       contextReady = ready;
       refreshActions();
@@ -979,6 +1685,7 @@ function createExternalHandoffPanel(document, framework, locale, sessionId, subs
       settleDisclosure(false);
       disclosure.removeEventListener("keydown", handleDisclosureKeydown);
       settings.removeEventListener("toggle", options.onViewChange);
+      managedResult.removeEventListener("toggle", options.onViewChange);
       unsubscribeLocale();
     }
   });