feat(acp): integrate ACP harness for agent communication by floreks · Pull Request #4072 · pluralsh/console

floreks · 2026-08-28T10:49:36Z

Added new acp package for handling ACP session lifecycle.
Implemented provider-neutral Agent Client Protocol (ACP) harness.
Created acp.go, acp_session.go, acp_turn.go, and acp_client.go for structuring ACP tool logic and session management.
Extracted opencode session export functionality into ExportSession method for reusability.
Updated imports to add support for ACP logic and made necessary code refactoring for cleaner management.
Removed redundant session export logic from artifacts.go.
Updated go.sum with new dependencies for ACP SDK integration.

Test Plan

Test environment: https://console.plrl-dev-aws.onplural.sh/

Checklist

I have added a meaningful title and summary to convey the impact of this PR to a user.
If required, I have updated the Plural documentation accordingly.
I have added tests to cover my changes.
I have deployed the agent to a test environment and verified that it works as expected (required only when changing agent code).

Plural Flow: console

- Added new `acp` package for handling ACP session lifecycle. - Implemented provider-neutral Agent Client Protocol (ACP) harness. - Created `acp.go`, `acp_session.go`, `acp_turn.go`, and `acp_client.go` for structuring ACP tool logic and session management. - Extracted opencode session export functionality into `ExportSession` method for reusability. - Updated imports to add support for ACP logic and made necessary code refactoring for cleaner management. - Removed redundant session export logic from `artifacts.go`. - Updated `go.sum` with new dependencies for ACP SDK integration.

linear · 2026-08-28T10:49:39Z

PROD-5162

soffi-ai · 2026-08-28T10:49:52Z

Soffi AI Summary

This PR integrates the Agent Client Protocol (ACP) as a provider-neutral harness for AI agent communication in the deployment operator. The motivation is to decouple agent session management from any specific AI provider (e.g., opencode) by implementing the ACP SDK — a structured, protocol-level interface for session lifecycle, prompting, tool output, and message routing. This allows the harness to support multiple coding agents (opencode today, others tomorrow) through a single, well-tested abstraction layer.

Key changes:

A new acp package implements the full ACP harness: session creation/resumption, turn management, tool output processing, and message mapping to Console's agent message model.
A StdioProcess abstraction is introduced in the exec package to wrap agent subprocess I/O (stdin/stdout/stderr) in a clean interface, enabling the ACP client to communicate with agent processes over stdio pipes.
Opencode's ACP-specific session export logic is extracted into a reusable ExportSession method and its redundant copy removed from artifacts.go.
Opencode's existing harness is slimmed down by offloading ACP concerns to the new package, and a new opencode_config.go centralizes its configuration types.
The usage package is extended to support richer token/usage tracking from ACP responses.
Comprehensive unit tests cover session update ordering, session ID validation, mismatched session rejection, ACP client lifecycle, and stdio process behavior.
The opencode Docker image version is bumped in CI/CD workflows to match.

Changes

ACP harness for provider-neutral agent communication

Introduced the core acp package with acp.go, acp_session.go, acp_turn.go, acp_client.go, and acp_mapping.go to implement a provider-neutral Agent Client Protocol harness. This replaces ad-hoc provider-specific session wiring with a structured lifecycle (session creation, turn management, tool output processing, and Console message routing) backed by the coder/acp-go-sdk. (faefd06)
Enhanced file-read operations within the ACP harness by adding context-awareness checks, improving robustness under cancellation. (b5fdd1c)
Added unit tests for the ACP tool and enhanced agent-mode configuration, ensuring session lifecycle and mode-setting behave correctly end-to-end. (c2f5efd)
Refactored session lifecycle management within the ACP harness, extracting opencode's ExportSession into a reusable method and removing the duplicate export logic from artifacts.go. Also introduced StdioProcess in the exec package to cleanly wrap agent subprocess I/O over pipes. (d6bb720)
Enhanced tool output processing in the ACP harness to correctly aggregate and forward partial and complete agent message chunks to Console. (f914b76)
Switched ACP tool methods from value receivers to pointer receivers for correctness with mutable session state. (0992f93)
Improved session handling robustness and expanded tests: validated session ID binding, rejection of mismatched session IDs, handling of updates sent before NewSession responds, and empty session ID guards. (70b0b0f)

opencode version bump in CI/CD

Updated OPENCODE_VERSION in the deployment-operator agent-harness CD workflow to track the latest opencode release. (f9b8388)
Second update to OPENCODE_VERSION in the CD workflow, aligning the deployed image with the current opencode build. (7420b8d)

Updated: 2026-08-31 14:07 UTC

Deploy in Soffi

socket-security · 2026-08-28T10:50:15Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	golang/github.com/coder/acp-go-sdk@v0.13.5

View full report

floreks · 2026-08-28T10:55:18Z

plural deploy to dev

greptile-apps · 2026-08-28T10:57:14Z

Greptile Summary

The PR introduces a provider-neutral ACP harness for agent session lifecycle, messaging, configuration, usage tracking, and artifact export.

Integrates OpenCode with ACP and updates its runtime image to version 1.18.23.
Adds bounded, cancellation-aware ACP text-file reads and validates regular-file size.
Adds stdio process lifecycle support and ACP-focused unit tests.

Confidence Score: 5/5

The PR appears safe to merge because the previously reported unbounded ACP file-read failure is now bounded.

No blocking failure remains.

Important Files Changed

Filename	Overview
go/deployment-operator/pkg/agentrun-harness/tool/acp/acp_client.go	Adds ACP filesystem callbacks and fixes the previously reported unbounded-read path with regular-file validation, a 16 MiB byte cap, and context checks.
go/deployment-operator/pkg/agentrun-harness/tool/acp/acp_session.go	Implements ACP initialization, session creation and resumption, prompt execution, cancellation, and bounded process shutdown.
go/deployment-operator/pkg/agentrun-harness/tool/acp/acp.go	Defines the provider-neutral ACP tool, configuration hooks, message delivery, session state, and artifact upload behavior.
go/deployment-operator/pkg/agentrun-harness/tool/acp/acp_client_test.go	Covers normal file operations, invalid paths and sessions, canceled reads, and oversized-file rejection.
go/deployment-operator/pkg/agentrun-harness/tool/acp/opencode.go	Adapts OpenCode process launch, configuration, and session export to the ACP harness.
go/deployment-operator/pkg/harness/exec/exec_stdio.go	Adds stdio-oriented process lifecycle handling used by ACP connections.

_{Reviews (3): Last reviewed commit: "feat(acp): improve session handling and ..." | Re-trigger Greptile}

- Add context cancellation checks in `ReadTextFile` for robustness. - Introduce a limit on text file read size with `maxTextFileBytes`. - Implement `contextReader

floreks · 2026-08-28T11:06:19Z

@greptileai

- Bump OPENCODE_VERSION from 1.17.3 to 1.18.23 for deployment compatibility.

- Add `TestNewOpenCodeSelectsConfiguredAgentForRunMode` to verify agent selection based on run mode. - Update `opencode_args_test.go` to use `Default*Agent` constants. - Change `opencode_types.go` to export `Default*Agent` constants. - Modify `opencode.go` files to utilize exported `Default*Agent` constants.

floreks · 2026-08-28T11:39:18Z

plural deploy to dev

- Introduce `sessionAttempt` and `sessionDetails` structs for clearer separation of attempts and session configurations - Implement session attempt lifecycle methods: `startAttempt`, `run`, `stop`, `initialize`, `openSession`, `createSession`, `resumeSession` - Add error handling improvements: `fail`, `promptFailure` - Consolidate process rejection logic into `rejectProcess` - Refine session configuration with `setModelConfig` and `setModeConfig` functions for cleaner configuration flow

- Bump `opencode` version from 1.17.3 to 1.18.23 in deployment workflow file for compatibility.

- Add test `TestToolOutputPrefersContentOverRawOutput` to prioritize content over raw output in tool messages. - Add test `TestToolOutputFallsBackToRawOutputWithoutContent` to ensure raw output is used when content is unavailable. - Simplify `normalizeUsage` function logic to use `max` for total token calculation. - Refactor `acp_turn.go` to improve tool output handling by checking and formatting content and raw output effectively.

…-consider-moving-agent-harness-to-use-agent-client-protocol

- Update `ConfigureSystemPrompt` and `systemPromptInput` methods to use pointer receivers in `tool/v1/tool.go` - Modify `ConfigureSkills` and related methods to use pointer receivers in `v1/skills.go` - Change test functions in `acp_test.go` to test new tool behaviors - Simplify tool management logic by removing redundant flusher handlers in `acp.go` and `acp_turn.go` - Enhance cumulative cost tracking by introducing a new `RecordCumulativeCost` method

- Introduced `newSessionUpdates` to handle pre-response session updates - Enhanced `NewSession` to process updates using `SessionUpdate` - Added test `TestRunPromptHandlesUpdatesSentBeforeNewSessionResponse` to verify update handling order - Added test `TestRunPromptRejectsMismatchedInitialSessionUpdate` to ensure proper session update matching - Added test `TestSessionUpdateRejectsEmptySessionIDBeforeBinding` to enforce session ID validation - Refactored session config functions into methods: `setSessionConfig`, `setModelConfig`, `setModeConfig` - Introduced `startAttempt` for clearer session initiation logic - Created `validate` method for comprehensive tool configuration checks - Updated error messages for consistency with lowecase conventions - Reorganized `toolCall` and `toolUpdateEvents` to streamline tool communication logic

floreks · 2026-08-31T14:42:49Z

@greptileai

floreks self-assigned this Aug 28, 2026

floreks added the enhancement New feature or request label Aug 28, 2026

greptile-apps Bot reviewed Aug 28, 2026

View reviewed changes

Comment thread go/deployment-operator/pkg/agentrun-harness/tool/acp/acp_client.go Outdated

feat(acp): enhance file read functionality with context checks

b5fdd1c

- Add context cancellation checks in `ReadTextFile` for robustness. - Introduce a limit on text file read size with `maxTextFileBytes`. - Implement `contextReader

floreks added 2 commits August 28, 2026 13:19

chore(ci): update OPENCODE_VERSION in deployment workflow

f9b8388

- Bump OPENCODE_VERSION from 1.17.3 to 1.18.23 for deployment compatibility.

floreks added 6 commits August 28, 2026 14:03

chore(ci): update OPENCODE_VERSION in deployment workflow

7420b8d

- Bump `opencode` version from 1.17.3 to 1.18.23 in deployment workflow file for compatibility.

Merge remote-tracking branch 'origin/master' into sebastian/prod-5162…

4a85707

…-consider-moving-agent-harness-to-use-agent-client-protocol

Navigation Menu

Uh oh!

feat(acp): integrate ACP harness for agent communication - #4072

feat(acp): integrate ACP harness for agent communication#4072
floreks wants to merge 10 commits into
masterfrom
sebastian/prod-5162-consider-moving-agent-harness-to-use-agent-client-protocol

floreks commented Aug 28, 2026 •

edited

Loading

Uh oh!

linear Bot commented Aug 28, 2026

Uh oh!

soffi-ai Bot commented Aug 28, 2026 •

edited

Loading

Changes

ACP harness for provider-neutral agent communication

opencode version bump in CI/CD

Uh oh!

socket-security Bot commented Aug 28, 2026 •

edited

Loading

Uh oh!

floreks commented Aug 28, 2026

Uh oh!

greptile-apps Bot commented Aug 28, 2026 •

edited

Loading

Important Files Changed

Uh oh!

Uh oh!

floreks commented Aug 28, 2026

Uh oh!

floreks commented Aug 28, 2026

Uh oh!

floreks commented Aug 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

floreks commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Plan

Checklist

Uh oh!

linear Bot commented Aug 28, 2026

Uh oh!

soffi-ai Bot commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

ACP harness for provider-neutral agent communication

opencode version bump in CI/CD

Uh oh!

socket-security Bot commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

floreks commented Aug 28, 2026

Uh oh!

greptile-apps Bot commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Uh oh!

Uh oh!

floreks commented Aug 28, 2026

Uh oh!

floreks commented Aug 28, 2026

Uh oh!

floreks commented Aug 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

floreks commented Aug 28, 2026 •

edited

Loading

soffi-ai Bot commented Aug 28, 2026 •

edited

Loading

socket-security Bot commented Aug 28, 2026 •

edited

Loading

greptile-apps Bot commented Aug 28, 2026 •

edited

Loading