Feature: ACP (Agent Client Protocol) Notification Target

[tbrandenburg]

Summary

This PR implements ACP (Agent Client Protocol) support as a new notification target type, enabling users to send work item updates to ANY ACP-compliant AI agent (OpenCode, Cursor, Cody, etc.) via JSON-RPC 2.0 over stdio.

Latest Changes (Issue #963)

*Session Persistence Now Workingecho BEGIN___COMMAND_OUTPUT_MARKER ; PS1= ; PS2= ; unset HISTFILE ; EC=0 ; echo ___BEGIN___COMMAND_DONE_MARKER___0 ; }

Previously, session IDs could not be persisted because all TargetConfig fields were readonly. This meant each CLI invocation created a new session, losing conversation context and paying the 5-7s initialization penalty every time.

Fixed in this commit:

• ✅ Removed readonly from sessionId field in ACPTargetConfig
• ✅ Updated ACP handler to persist sessionId after initialization
• ✅ Engine now saves contexts after notifications (allows config updates)
• ✅ Re-enabled E2E session persistence tests
• ✅ Fixed test regex to match OpenCode's ses_ prefix

Result: Sessions now persist across CLI invocations, maintaining conversation context and enabling true multi-turn AI interactions! 🎉

Core Features

Generic ACP Support

• --cmd parameter makes it flexible for any ACP client
• Works with OpenCode, Cursor, Cody, and other ACP-compliant agents
• No vendor lock-in

Implementation

• Handler: src/core/target-handlers/acp-handler.ts - Generic subprocess management
• Protocol: Raw JSON-RPC 2.0 over stdin/stdout (not SDK-based)
• Session Management: Persistent sessions with initialization + session/new
• Process Reuse: Subprocess cached per cmd+cwd for performance

Usage

# Add ACP target (works with any ACP client)
work notify target add ai --type acp --cmd "opencode acp"

# Send work item to AI agent
work notify send TASK-123 to ai

# Session persists - subsequent calls reuse it!
work notify send TASK-456 to ai  # Fast! No re-initialization

Testing

Check	Status	Details
Type check	✅ Pass	No TypeScript errors
Build	✅ Pass	Clean compilation
Unit tests	✅ Pass	21/22 tests (1 skipped)
E2E tests	✅ Pass	4/4 tests with real OpenCode
Lint	⚠️ 1 warning	Pre-existing (missing return type)

E2E Tests Verify:

• ✅ Target add/list/remove
• ✅ Send notifications with real ACP client (OpenCode)
• ✅ Process cleanup

Changes

File	Change
src/types/notification.ts	Added acp to TargetType, ACPTargetConfig interface (sessionId now mutable)
src/types/errors.ts	Added ACP error classes
src/core/target-handlers/acp-handler.ts	Generic ACP handler with subprocess management, session persistence
src/core/target-handlers/index.ts	Export ACPTargetHandler
src/core/engine.ts	Register handler, save contexts after notifications
src/cli/commands/notify/target/add.ts	Add --cmd and --cwd flags
tests/unit/core/target-handlers/acp-handler.test.ts	22 unit tests
tests/e2e/acp-integration.test.ts	4 E2E tests with session persistence

Architecture

WorkItem → Engine → NotificationService → ACPTargetHandler
                                              ↓
                                    spawn(cmd) → ACP Client
                                              ↓
                                    JSON-RPC over stdin/stdout
                                              ↓
                                    AI Response

Issues

Closes #963 - Session persistence across CLI invocations
Implements Phase 1 MVP from feature plan

Documentation

• Implementation follows dev/poc-opencode-server/WORK-CLI-INTEGRATION.md
• Uses patterns from bash-handler.ts and telegram-handler.ts
• Raw JSON-RPC preferred over SDK (see SDK-EVALUATION.md)

---

Ready for Review 🚀

Session persistence is now fully functional. Multi-turn AI conversations work seamlessly across CLI invocations.

[tbrandenburg]

✅ Session Persistence Fix (#963)

This PR now includes the fix for issue #963. Session IDs are persisted across CLI invocations!

What Changed

Problem: sessionId field was readonly in ACPTargetConfig, preventing handlers from updating it.

Solution:

1. Made sessionId mutable (removed readonly)
2. Handler now sets sessionId after initialization
3. Engine saves contexts after notifications (commit: da2c654)

Verification

✅ E2E test now verifies session persistence:

expect(target.config.sessionId).toBeDefined();
expect(target.config.sessionId).toMatch(/^ses_/); // OpenCode prefix

✅ All tests pass (4/4 E2E, 21/22 unit)

Impact

• Before: New session every command (5-7s initialization each time)
• After: Session persists, fast subsequent calls, conversation context maintained

Ready for Phase 2 enhancements! 🎉

[tbrandenburg]

✅ Linter Warning Fixed

Added explicit return type to cleanup function in engine.ts.

Before: const cleanup = () => { ... }
After: const cleanup = (): void => { ... }

✅ Linter now passes with 0 warnings
✅ All unit tests pass (303 passed, 1 skipped)
✅ Type-check and build successful

Commit: 6f20ea5

[tbrandenburg]

🔍 PoC Comparison Complete

Completed systematic comparison of ACP handler implementation against PoC learnings from dev/poc-opencode-server/.

✅ Verification Results

All critical PoC patterns correctly implemented:

• ✅ Line-buffered message parsing with buffer management
• ✅ Proper subprocess spawning with stdio pipes
• ✅ Stderr filtering (INFO/service logs suppressed)
• ✅ JSON-RPC message structure
• ✅ Initialize → session/new → session/prompt flow
• ✅ Raw JSON-RPC approach (not SDK) as recommended

💡 Enhancement Opportunities Identified

Created 5 optional enhancement issues for future improvements:

Enhancements

• Enhancement: Add streaming notification support to ACP handler #995 - Add streaming notification support (session/update handling)

  • Priority: Medium | Complexity: Low
  • Real-time progress indicators during long AI responses

• Enhancement: Add debug logging for ACP message parse errors #996 - Add debug logging for message parse errors

  • Priority: Low | Complexity: Minimal
  • Better troubleshooting via DEBUG env var

• Enhancement: Add capability configuration support to ACP handler #998 - Add capability configuration support

  • Priority: Low | Complexity: Medium | Phase 2
  • Security controls for file/terminal/editor permissions

Documentation

• Documentation: Add comment explaining ACP session initialization timing #997 - Document session initialization timing

  • Explains expected 5-7s delay on first run

• Documentation: Document ACP prompt format choice #999 - Document prompt format choice

  • Clarifies format differences vs PoC

📊 Assessment

Current implementation is production-ready for MVP. All suggestions are optional enhancements, not fixes. The handler follows PoC best practices correctly.

Detailed comparison: Session artifacts acp-poc-comparison.md

---

Automated PoC comparison analysis