ACP SDK v0.16.x Breaking Change: listSessions Method Renamed

• Primary Error Message: "Method not found": session/list
• JSON-RPC Error Code: -32601 (Method not found)
• Occurrence: Consistent, 100% failure rate on ACP SDK v0.16.x

Reproduction Command

echo '{"jsonrpc": "2.0","id": 2,"method": "session/list","params": {}}' | openclaw acp

Full Error Output

Error handling request { jsonrpc: '2.0', id: 1, method: 'session/list', params: {} } {
  code: -32601,
  message: '"Method not found": session/list',
  data: { method: 'session/list' }
}

Affected Environments

• OpenClaw Version: 2026.3.13 (commit 61d171a)
• Operating Systems: Ubuntu 24.04, macOS, Windows (all affected)
• Install Method: npm global, Docker, local build

SDK Breaking Change Background

The ACP TypeScript SDK v0.16.0 (released with PR #84) promoted unstable_listSessions from experimental to stable status, renaming it to listSessions.

Technical Failure Sequence

1. Pre-v0.16.0 State: The ACP server recognized the JSON-RPC method session/list which mapped internally to unstable_listSessions.
2. OpenClaw Translator Implementation: File src/acp/translator.ts:484 sends method name session/list to the ACP server.
3. Post-v0.16.0 Change: The ACP server now maps session/list to the new stable listSessions method instead of unstable_listSessions.
4. Translation Layer Mismatch: The translator.ts file contains a method name mapping table that still references the old unstable_* namespace conventions, causing the server to reject the request as an unknown method.

Code Location Analysis

// src/acp/translator.ts:484 (approximate context)
const SESSION_METHODS = {
  'session/list': 'unstable_listSessions',  // ← This mapping is now stale
  // ... other mappings
};

Affected Method Translations

• session/list → Previously: unstable_listSessions → Now expected: listSessions

Option 1: Update OpenClaw Source (Recommended)

Modify the method translation mapping in src/acp/translator.ts around line 484:

Before (Stale Code)

const SESSION_METHODS = {
  'session/list': 'unstable_listSessions',
  // ... other session-related methods
};

After (Fixed Code)

const SESSION_METHODS = {
  'session/list': 'listSessions',
  // ... other session-related methods
};

Option 2: Downgrade ACP SDK (Quick Workaround)

# Uninstall current ACP SDK
npm uninstall @agentclientprotocol/typescript-sdk

# Install compatible version (pre-v0.16.0)
npm install @agentclientprotocol/[email protected]

# Verify version
npm list @agentclientprotocol/typescript-sdk

Option 3: Runtime Method Patching (Temporary)

# Locate the ACP SDK compiled JS file
find node_modules/@agentclientprotocol -name "*.js" | xargs grep -l "unstable_listSessions"

# Create a patch script (patch-unstable.js)
const fs = require('fs');
const path = require('path');

// Path to the compiled ACP SDK
const sdkPath = './node_modules/@agentclientprotocol/typescript-sdk/dist/index.js';

// Read the file
let content = fs.readFileSync(sdkPath, 'utf8');

// Replace all instances of unstable_listSessions with listSessions
content = content.replace(/unstable_listSessions/g, 'listSessions');

// Write back
fs.writeFileSync(sdkPath, content);
console.log('Patched ACP SDK successfully');

# Execute the patch
node patch-unstable.js

Option 4: Override Translator Method Resolution

Add a method alias in your OpenClaw configuration or custom translator plugin:

# openclaw.config.js or openclaw.config.ts
export default {
  acp: {
    methodAliases: {
      'session/list': 'listSessions'
    }
  }
};

Test 1: Basic Session List Command

# Execute the original failing command
echo '{"jsonrpc": "2.0","id": 2,"method": "session/list","params": {}}' | openclaw acp

# Expected: Valid JSON-RPC response with session list
# Exit code: 0

Test 2: Verify Method Resolution

# Test with verbose logging enabled
OPENCLAW_LOG_LEVEL=debug echo '{"jsonrpc": "2.0","id": 2,"method": "session/list","params": {}}' | openclaw acp

# Look for successful method resolution in logs:
# [DEBUG] Method resolved: session/list -> listSessions

Test 3: SDK Version Confirmation

# Check installed ACP SDK version
npm list @agentclientprotocol/typescript-sdk

# Expected output for fixed state:
# └── @agentclientprotocol/[email protected]

# Or if using 0.15.x workaround:
# └── @agentclientprotocol/[email protected]

Test 4: Verify Translator Mapping

# Check translator.ts for correct method mapping
grep -n "session/list" src/acp/translator.ts

# Expected output should show:
# 'session/list': 'listSessions',

Expected Successful Response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "sessions": [
      // ... session objects
    ]
  }
}

• Cache Invalidation: After patching the SDK, clear Node.js module cache and any compiled transpiled files:

  # Clear cache and rebuild
  rm -rf node_modules/.cache
  npm rebuild
  # For TypeScript projects:
  npx tsc --clean && npx tsc

• Transitive Dependency Issues: Other packages may depend on the old SDK version. Check for peer dependency warnings:

  npm ls @agentclientprotocol/typescript-sdk

• Lock File Conflicts: The package-lock.json may pin the old SDK version. Update with:

  rm package-lock.json
  npm install

• Docker Layer Caching: If using Docker, ensure the build process picks up the patched SDK:

  # Force rebuild of SDK layer
  docker build --no-cache --build-arg UPDATE_SDK=true .

• Multiple ACP SDK Instances: Some environments may have multiple installations. Verify the correct one is being used:

  node -e "console.log(require.resolve('@agentclientprotocol/typescript-sdk'))"

• Version Pinning in CI/CD: CI pipelines may have SDK versions pinned in environment variables or config files—update those as well.
• TypeScript Definitions: Type definitions may still reference the old unstable_listSessions. Update type imports if using TypeScript:

  // Old import (now broken)
  import { unstable_listSessions } from '@agentclientprotocol/typescript-sdk';
  // New import
  import { listSessions } from ‘@agentclientprotocol/typescript-sdk’;

• -32601 Method not found
  General JSON-RPC error when the requested method does not exist on the server. Often indicates SDK version mismatch or method renaming.
• ACPT_001: Unsupported protocol version
  Version negotiation failure between OpenClaw and ACP server when protocol versions are incompatible.
• ERR_MODULE_NOT_FOUND
  Node.js module resolution error when the ACP SDK path has changed due to package restructuring.
• Historical Issue: unstable_* Method Deprecation (SDK v0.14.x)
  Previous deprecation warning cycle that announced the eventual removal of the unstable_ prefix.
• Related GitHub Issue: ACP SDK PR #84
  Official release notes and diff for the v0.16.0 breaking change.
• OpenClaw Commit: 61d171a
  Current affected OpenClaw version. The translator.ts file at line 484 requires update to support SDK v0.16.x.