fix(sessions): gate ACP runtime overlay on session metadata

Galin Iliev · Galin Iliev · commit 4ebbf1d7e924 · 2026-05-14T01:46:45.000Z
diff --git a/src/agents/acp-runtime-overlay.ts b/src/agents/acp-runtime-overlay.ts
@@ -13,17 +13,18 @@ export type AgentRuntimeMetadata = {
 };
 
 /**
- * When a session key unambiguously identifies an ACP session (contains the `:acp:`
- * segment), override the resolved runtime metadata to report the ACP runtime id
- * with a "session-key" source — regardless of what the agent-config policy
- * resolved to.  Without this overlay, callers that only have agent-config context
- * (no model/provider) fall back to `id: "pi"` even though the session key makes
- * the actual runtime unambiguous.
+ * When a session key and persisted session metadata identify an ACP
+ * control-plane session, override the resolved runtime metadata to report the
+ * ACP runtime id with a "session-key" source — regardless of what the
+ * agent-config policy resolved to.
  *
  * Callers that already have model/provider context (resolveModelAgentRuntimeMetadata)
  * still benefit here because the model-runtime policy chain does not inspect session
  * keys for the ACP indicator.
  *
+ * Key shape alone is not sufficient: ACP bridge sessions may use ACP-shaped
+ * keys without persisted SessionAcpMeta and still run the configured model.
+ *
  * When `acpBackend` is provided and non-empty, it is used as the runtime id so that
  * sessions backed by a configured non-default ACP backend (e.g. a custom registered
  * backend) are reported faithfully instead of always being labelled "acpx".
@@ -32,9 +33,10 @@ export type AgentRuntimeMetadata = {
 export function applyAcpRuntimeOverlay(
   meta: AgentRuntimeMetadata,
   sessionKey: string | undefined | null,
+  acpRuntime: boolean | undefined,
   acpBackend?: string,
 ): AgentRuntimeMetadata {
-  if (isAcpSessionKey(sessionKey)) {
+  if (acpRuntime === true && isAcpSessionKey(sessionKey)) {
     const id = acpBackend && acpBackend.length > 0 ? acpBackend : "acpx";
     return { id, source: "session-key" };
   }
diff --git a/src/agents/agent-runtime-metadata.ts b/src/agents/agent-runtime-metadata.ts
@@ -22,6 +22,12 @@ export function resolveModelAgentRuntimeMetadata(params: {
   provider?: string;
   model?: string;
   sessionKey?: string;
+  /**
+   * True when the loaded session entry has persisted ACP metadata. ACP-shaped
+   * keys without this marker can be bridge sessions that use the configured
+   * model/runtime.
+   */
+  acpRuntime?: boolean;
   /**
    * The ACP backend identifier stored on the session entry (`entry.acp.backend`).
    * When provided for an ACP-keyed session, the overlay reports this value as the
@@ -45,5 +51,5 @@ export function resolveModelAgentRuntimeMetadata(params: {
     id: policy.runtime,
     source: policy.runtimeSource ?? "implicit",
   };
-  return applyAcpRuntimeOverlay(meta, params.sessionKey, params.acpBackend);
+  return applyAcpRuntimeOverlay(meta, params.sessionKey, params.acpRuntime, params.acpBackend);
 }
diff --git a/src/commands/sessions.acp-runtime-metadata.test.ts b/src/commands/sessions.acp-runtime-metadata.test.ts
@@ -86,6 +86,8 @@ function computeSessionAgentRuntime(params: {
   cfg: OpenClawConfig;
   sessionKey: string;
   fallbackAgentId: string;
+  /** Mirrors `entry?.acp != null` passed from loaded session rows. */
+  acpRuntime?: boolean;
   /** Mirrors `entry?.acp?.backend` passed from the session store entry. */
   acpBackend?: string;
 }): ReturnType<typeof resolveModelAgentRuntimeMetadata> {
@@ -94,6 +96,7 @@ function computeSessionAgentRuntime(params: {
     cfg: params.cfg,
     agentId,
     sessionKey: params.sessionKey,
+    acpRuntime: params.acpRuntime,
     acpBackend: params.acpBackend,
   });
 }
@@ -105,6 +108,7 @@ describe("sessions --json agentRuntime classifier (catalog #18)", () => {
       cfg,
       sessionKey: ACP_SESSION_KEY,
       fallbackAgentId: "copilot",
+      acpRuntime: true,
     });
 
     // The bug was: the session key plainly contains `:acp:` and yet the
@@ -158,6 +162,7 @@ describe("sessions --json agentRuntime classifier (catalog #18)", () => {
       cfg,
       sessionKey: ACP_SESSION_KEY,
       fallbackAgentId: "copilot",
+      acpRuntime: true,
     });
 
     expect(
@@ -178,26 +183,40 @@ describe("sessions --json agentRuntime classifier (catalog #18)", () => {
       cfg,
       sessionKey: ACP_SESSION_KEY,
       fallbackAgentId: "copilot",
+      acpRuntime: true,
       acpBackend: "custom-backend",
     });
 
     expect(agentRuntime.id).toBe("custom-backend");
     expect(agentRuntime.source).toBe("session-key");
   });
 
-  it("backend fallback: ACP session with no entry.acp.backend falls back to 'acpx'", () => {
-    // When the session entry has no acp.backend (entry.acp is absent or backend
-    // is not set), the overlay must fall back to the canonical "acpx" id so
-    // existing behaviour is preserved.
+  it("backend fallback: ACP session with entry.acp but no backend falls back to 'acpx'", () => {
+    // When the session entry has ACP metadata but no acp.backend, the overlay
+    // must fall back to the canonical "acpx" id.
     const cfg = buildConfigWithoutAgentRuntimePolicy();
     const agentRuntime = computeSessionAgentRuntime({
       cfg,
       sessionKey: ACP_SESSION_KEY,
       fallbackAgentId: "copilot",
+      acpRuntime: true,
       // acpBackend intentionally omitted — mirrors entry with no acp.backend
     });
 
     expect(agentRuntime.id).toBe("acpx");
     expect(agentRuntime.source).toBe("session-key");
   });
+
+  it("GREEN control: ACP-shaped bridge session without entry.acp is NOT overridden", () => {
+    const cfg = buildConfigWithoutAgentRuntimePolicy();
+    const agentRuntime = computeSessionAgentRuntime({
+      cfg,
+      sessionKey: ACP_SESSION_KEY,
+      fallbackAgentId: "copilot",
+      acpRuntime: false,
+    });
+
+    expect(agentRuntime.id).not.toBe("acpx");
+    expect(agentRuntime.source).not.toBe("session-key");
+  });
 });
diff --git a/src/commands/sessions.ts b/src/commands/sessions.ts
@@ -295,6 +295,7 @@ export async function sessionsCommand(
           provider: modelRef.provider,
           model: modelRef.model,
           sessionKey: row.key,
+          acpRuntime,
           acpBackend: entry?.acp?.backend,
         });
         return Object.assign({}, row, {
diff --git a/src/commands/status.summary.runtime.ts b/src/commands/status.summary.runtime.ts
@@ -164,6 +164,7 @@ function resolveSessionRuntimeLabel(params: {
     provider: params.provider,
     model: params.model,
     sessionKey: params.sessionKey,
+    acpRuntime: params.entry?.acp != null,
     acpBackend: params.entry?.acp?.backend,
   });
   const id = normalizeOptionalLowercaseString(runtime.id);
diff --git a/src/gateway/server-methods/sessions.ts b/src/gateway/server-methods/sessions.ts
@@ -1817,6 +1817,7 @@ export const sessionsHandlers: GatewayRequestHandlers = {
       provider: resolvedDisplayModel.provider,
       model: resolvedDisplayModel.model,
       sessionKey: target.canonicalKey ?? key,
+      acpRuntime: applied.entry?.acp != null,
       acpBackend: applied.entry?.acp?.backend,
     });
     const result: SessionsPatchResult = {
diff --git a/src/gateway/session-utils.ts b/src/gateway/session-utils.ts
@@ -1024,6 +1024,7 @@ export function listAgentsForGateway(cfg: OpenClawConfig): {
           provider: resolvedModel.provider,
           model: resolvedModel.model,
           sessionKey: resolveAgentMainSessionKey({ cfg, agentId: id }),
+          acpRuntime: false,
         }),
       },
       model ? { model } : {},
@@ -1735,6 +1736,7 @@ export function buildGatewaySessionRow(params: {
     provider: rowModelProvider,
     model: rowModel,
     sessionKey: key,
+    acpRuntime: entry?.acp != null,
     acpBackend: entry?.acp?.backend,
   });
   const estimatedCostUsd = lightweight
