fallback and do not reconstruct historic tool calls or system notices.

- If multiple ACP clients share the same Gateway session key, event and cancel

routing are best-effort rather than strictly isolated per client. Prefer the

default isolated `acp:<uuid>` sessions when you need clean editor-local

default isolated `acp-bridge:<uuid>` sessions when you need clean editor-local

turns.

- Gateway stop states are translated into ACP stop reasons, but that mapping is

less expressive than a fully ACP-native runtime.

```

Each ACP session maps to a single Gateway session key. One agent can have many

sessions; ACP defaults to an isolated `acp:<uuid>` session unless you override

sessions; ACP defaults to an isolated `acp-bridge:<uuid>` session unless you override

the key or label.

Per-session `mcpServers` are not supported in bridge mode. If an ACP client

## Session mapping

By default, ACP sessions get an isolated Gateway session key with an `acp:` prefix.

To reuse a known session, pass a session key or label:

By default, ACP bridge sessions get an isolated Gateway session key with an

`acp-bridge:` prefix. These normal-model bridge sessions are synthetic and

subject to stale-entry pruning and entry-count caps. To reuse a known session,

pass a session key or label:

- `--session <key>`: use a specific Gateway session key.

- `--session-label <label>`: resolve an existing session by label.

import { createInMemorySessionStore } from "@openclaw/acp-core/session";

import { describe, expect, it, vi } from "vitest";

import type { GatewayClient } from "../gateway/client.js";

import { isAcpSessionKey } from "../sessions/session-key-utils.js";

import {

createNewSessionRequest,

createLoadSessionRequest,

});

describe("acp session UX bridge behavior", () => {

it("uses a non-runtime namespace for generated bridge sessions", async () => {

const sessionStore = createInMemorySessionStore();

const agent = new AcpGatewayAgent(createAcpConnection(), createAcpGateway(), {

sessionStore,

});

const result = await agent.newSession(createNewSessionRequest());

const sessionKey = sessionStore.getSession(result.sessionId)?.sessionKey;

expect(sessionKey).toMatch(/^acp-bridge:/);

expect(isAcpSessionKey(sessionKey)).toBe(false);

sessionStore.clearAllSessionsForTest();

});

it("returns initial modes and thought-level config options for new sessions", async () => {

const sessionStore = createInMemorySessionStore();

const agent = new AcpGatewayAgent(createAcpConnection(), createAcpGateway(), {

const meta = parseSessionMeta(params["_meta"]);

const sessionKey = await this.resolveSessionKeyFromMeta({

meta,

fallbackKey: `acp:${sessionId}`,

fallbackKey: `acp-bridge:${sessionId}`,

});

const session = this.sessionStore.createSession({

function isSyntheticSessionMaintenanceKey(sessionKey: string): boolean {

const parsed = parseAgentSessionKey(sessionKey);

const rest = normalizeLowercaseStringOrEmpty(parsed?.rest ?? sessionKey);

// ACP bridge sessions use normal model dispatch, but remain synthetic and disposable.

return (

isSubagentSessionKey(sessionKey) ||

isAcpSessionKey(sessionKey) ||

isCronSessionKey(sessionKey) ||

rest.startsWith("acp-bridge:") ||

rest.startsWith("hook:") ||

rest.startsWith("node:") ||

rest === "heartbeat" ||

});

describe("isProtectedSessionMaintenanceEntry", () => {

it("treats generated ACP bridge sessions as disposable", () => {

expect(

isProtectedSessionMaintenanceEntry("agent:main:acp-bridge:session-1", {

...makeEntry(Date.now()),

chatType: "group",

}),

).toBe(false);

});

it("does not protect synthetic sessions just because they carry group metadata", () => {

expect(

isProtectedSessionMaintenanceEntry("agent:main:subagent:worker", {