Kiro ACP Wrapper

A Node.js wrapper for integrating Kiro CLI with OpenClaw's ACP (Agent Control Protocol) runtime, enabling persistent multi-message coding sessions.

Purpose

This wrapper acts as a bridge between OpenClaw's acpx runner and kiro-cli acp, solving a critical process lifecycle issue:

Problem: kiro-cli spawns a child process (kiro-cli-chat) that doesn't exit when the parent terminates, causing "Session is active in another process" errors on subsequent messages.

Solution: The wrapper explicitly discovers and kills all descendant processes with proper delays, ensuring clean session handoffs and enabling true session persistence.

Features

• ✅ Persistent Sessions - Maintains conversation context across multiple messages
• ✅ Clean Process Cleanup - Kills entire process tree including kiro-cli-chat
• ✅ Argument Forwarding - Supports --agent, --model, and --trust-all-tools flags
• ✅ Optional Logging - Debug traffic via KIRO_ACP_WRAPPER_LOG environment variable

Installation

Ensure kiro-cli is installed and available in your PATH:

which kiro-cli

If not installed, follow the Kiro CLI installation guide.

Configuration

Add to your ~/.acpx/config.json:

{
  "agents": {
    "kiro": {
      "command": "/home/node/kiro-acp/kiro-acp-wrapper.js",
      "runtime": "acp",
      "description": "Kiro CLI development agent"
    }
  }
}

With Logging Enabled

{
  "agents": {
    "kiro": {
      "command": "/home/node/kiro-acp/kiro-acp-wrapper.js",
      "runtime": "acp",
      "description": "Kiro CLI development agent",
      "env": {
        "KIRO_ACP_WRAPPER_LOG": "/tmp/kiro-acp.log"
      }
    }
  }
}

With Custom Agent and Model

{
  "agents": {
    "kiro-custom": {
      "command": "/home/node/kiro-acp/kiro-acp-wrapper.js --agent my-agent --model claude-sonnet-4 --trust-all-tools",
      "runtime": "acp",
      "description": "Kiro with custom configuration"
    }
  }
}

Usage

From OpenClaw

Spawn a persistent kiro session:

sessions_spawn({
  agentId: "kiro",
  runtime: "acp",
  mode: "session",
  thread: true,
  task: "Help me refactor this code"
})

Send follow-up messages:

sessions_send({
  sessionKey: "agent:kiro:acp:<session-id>",
  message: "Now add error handling"
})

From Command Line

# Direct usage (for testing)
acpx --agent kiro

How It Works

1. Spawns kiro-cli with detached: true to create separate process group
2. Pipes I/O between acpx and kiro-cli with optional logging
3. On cleanup (stdin close or SIGTERM):
   • Uses pgrep -P <pid> to find all descendant processes
   • Kills descendants first (SIGTERM)
   • Waits 1 second for descendants to exit
   • Kills main process (SIGTERM)
   • Waits 1 second for main process to exit
   • Wrapper exits after 1.5 second delay
4. Total cleanup time: ~3.5 seconds ensures session locks are released

Logging

Enable logging to debug issues:

# Set in acpx config or export manually
export KIRO_ACP_WRAPPER_LOG=/tmp/kiro-acp.log

# View logs
tail -f /tmp/kiro-acp.log

Log entries show:

• [IN] - Messages from acpx to kiro-cli
• [OUT] - Messages from kiro-cli to acpx
• [ERR] - Stderr output from kiro-cli
• Spawned kiro-cli PID: <pid> - Process creation
• Found descendants: <pids> - Child process discovery
• Killed descendant <pid> - Cleanup actions
• CHILD EXIT: code=<code> signal=<signal> - Process termination

Troubleshooting

"Session is active in another process" errors

This means a previous kiro-cli process didn't exit cleanly. Solutions:

1. Kill zombie processes:

   pkill -9 kiro-cli
   pkill -9 kiro-cli-chat

2. Check if cleanup delays are sufficient:

   • Enable logging and check if descendants are being killed
   • Look for "Killed descendant" messages in logs

3. Verify pgrep is available:

   which pgrep

Wrapper exits with code 1

This is expected behavior when kiro-cli encounters errors. Check:

• kiro-cli is properly installed: kiro-cli --version
• You're authenticated: kiro-cli login
• The session ID is valid

No log file created

The KIRO_ACP_WRAPPER_LOG environment variable must be set in the acpx config, not in your shell. Verify:

# Check acpx config
cat ~/.acpx/config.json | grep -A 5 kiro

Requirements

• Node.js - For running the wrapper script
• kiro-cli - Installed and available in PATH
• OpenClaw - With acpx support
• pgrep - For finding descendant processes (standard on Linux/macOS)

Technical Details

Why Descendant Process Killing?

kiro-cli spawns kiro-cli-chat as a detached child process. When kiro-cli exits, kiro-cli-chat continues running and holds the session lock. Standard process group killing doesn't work because kiro-cli-chat is in a different process group.

The wrapper solves this by:

1. Using pgrep -P <pid> to find all children
2. Explicitly killing each child process
3. Waiting for processes to fully exit before the wrapper exits

Why the Delays?

Processes don't exit instantly when sent SIGTERM. They need time to:

• Flush buffers
• Close file handles
• Release locks
• Clean up resources

The 1-second delays after killing ensure processes have fully exited and released session locks before the next wrapper instance starts.

Development

# Clone/navigate to project
cd ~/kiro-acp

# View git history
git log --oneline

# Test changes
echo "" > /tmp/kiro-acp.log
# ... spawn session and test ...
cat /tmp/kiro-acp.log

License

This project is licensed under the Public Domain (Unlicense). See LICENSE for details.