feat: Support Conversation API Alpha2

[Copilot]

Description

Adds first-class support for the Dapr Conversation API (Alpha2) to the JS SDK, including user-facing types, a client interface, both gRPC and HTTP implementations, comprehensive unit tests, and Testcontainers integration tests.

Changes Made

• Types (src/types/conversation/Conversation.type.ts): Added user-facing TypeScript types for the Alpha2 Conversation API, including message roles (developer, system, user, assistant, tool), tool definitions, tool calls, and response types.
• ConversationOptions: Optional parameters for converse() including contextId, metadata, scrubPii, temperature, tools, toolChoice, promptCacheRetention, and responseFormat.
• Client interface (src/interfaces/Client/IClientConversation.ts): Defines converse(conversationComponentName, inputs, options?) with inputs as a required parameter and conversationComponentName as the first positional parameter for clarity.
• gRPC implementation (src/implementation/Client/GRPCClient/conversation.ts): Maps user-facing types to proto schemas via ConnectRPC bindings and calls converseAlpha2.
• HTTP implementation (src/implementation/Client/HTTPClient/conversation.ts): Maps to the v1.0-alpha2/conversation/{name}/converse REST endpoint, including promptCacheRetention and responseFormat in the request body.
• DaprClient integration (src/implementation/Client/DaprClient.ts): Exposes client.conversation.converse() for both gRPC and HTTP transports.
• Exports (src/index.ts): All new conversation types and interfaces are exported from the package index.
• Unit tests (test/unit/protocols/http/conversation.test.ts): 39 tests for HTTPClientConversation covering all message roles, optional parameters, request body building, response mapping, tool calls, assistant without tool calls, multiple content items, edge cases, and error propagation.
• Unit tests (test/unit/protocols/grpc/conversation.test.ts): 33 tests for GRPCClientConversation covering all message roles, proto message building, tool building, response mapping, multiple content items, error handling, and edge cases.
• Integration tests (test/e2e/common/conversation.test.ts): 42 Testcontainers-based integration tests (21 HTTP + 21 gRPC) exercising the conversation API against a real Dapr 1.16 sidecar with the conversation.echo component. Tests cover:
  • Basic message roles (user, system, developer, assistant, tool)
  • Options passing (metadata, temperature, toolChoice, contextId, scrubPii)
  • Multiple inputs and multiple content items
  • Tool definitions (single and multiple)
  • Multi-turn tool invocation flows (user → assistant tool call → tool result → follow-up)
  • All five roles in a single conversation
  • Assistant messages with multiple parallel tool calls
  • Named messages (name field on developer, system, and user roles)
  • Input-level scrubPii
  • Combined options (contextId + metadata + temperature + scrubPii)
  • Error handling for non-existent components
• Test helper (test/e2e/helpers/containers.ts): Added buildConversationEchoComponent() helper for creating the echo conversation component used in integration tests.
• Test script (package.json): Added test:e2e:common:conversation script and wired it into the test:e2e:common pipeline.
• Coverage: 100% statements, 100% functions, 100% lines, ~91% branches across both implementations.

Note: The Conversation API Alpha2 requires Dapr >= 1.16.0. The integration tests use Dapr 1.16.0 images by default (overridable via DAPR_RUNTIME_VER env var).

Issue reference

N/A — this implements the Alpha2 Conversation API surface for the JS SDK.

Checklist

Please make sure you've completed the relevant tasks for this PR, out of the following list:

• Code compiles correctly
• Created/updated tests
• Extended the documentation

[WhitWaldo]

Please address the changes

[WhitWaldo]

This file is not necessary and can be deleted.

[Copilot]

Deleted in c5d621d.

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• buf.build
  • Triggering command: /home/REDACTED/work/js-sdk/js-sdk/node_modules/@bufbuild/buf-linux-x64/bin/buf /home/REDACTED/work/js-sdk/js-sdk/node_modules/@bufbuild/buf-linux-x64/bin/buf generate (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[WhitWaldo]

Could you please add unit and integration tests proving that this works? Please strive for at least 80% test coverage for unit tests and as many integration test paths as you can manage.

[Copilot]

Could you please add unit and integration tests proving that this works? Please strive for at least 80% test coverage for unit tests and as many integration test paths as you can manage.

Added 68 unit tests across two test files in b56e5a2:

• test/unit/protocols/http/conversation.test.ts — 37 tests for HTTPClientConversation
• test/unit/protocols/grpc/conversation.test.ts — 31 tests for GRPCClientConversation

Coverage: 100% statements, 100% functions, 100% lines, ~91% branches. Tests cover all 5 message roles, all optional parameters, request/response mapping, tool calls, edge cases, and error propagation.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• buf.build
  • Triggering command: /home/REDACTED/work/js-sdk/js-sdk/node_modules/@bufbuild/buf-linux-x64/bin/buf /home/REDACTED/work/js-sdk/js-sdk/node_modules/@bufbuild/buf-linux-x64/bin/buf generate (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[WhitWaldo]

Please also add integration tests utilizing Testcontainers

[Copilot]

Please also add integration tests utilizing Testcontainers

Added in 23c0044. Created test/e2e/common/conversation.test.ts with 14 integration tests (7 HTTP + 7 gRPC) exercising the conversation API against a real Dapr 1.16 sidecar with the conversation.echo component. Tests cover: simple user messages, system messages, metadata passing, temperature option, multiple inputs, multiple content items, and error handling for non-existent components. Also added buildConversationEchoComponent() helper to containers.ts and test:e2e:common:conversation script to package.json.

Note: The conversation alpha2 API requires Dapr >= 1.16.0, so the test uses its own image constants defaulting to 1.16.0 instead of the shared 1.15.x constants.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• 224.0.0.251
  • Triggering command: REDACTED, pid is -1 (packet block)
• buf.build
  • Triggering command: /home/REDACTED/work/js-sdk/js-sdk/node_modules/@bufbuild/buf-linux-x64/bin/buf /home/REDACTED/work/js-sdk/js-sdk/node_modules/@bufbuild/buf-linux-x64/bin/buf generate (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[WhitWaldo]

@copilot Please add some integration tests that comprehensively validate agent roles and tool invocation.

[Copilot]

@copilot Please add some integration tests that comprehensively validate agent roles and tool invocation.

Added 9 new integration tests per protocol (18 total) in e59c960, covering:

• Developer role messages
• Assistant role messages in conversation history
• Tool role messages with toolId (tool results)
• Tool definitions in options (single and multiple)
• toolChoice option
• Multi-turn tool invocation flow: user → assistant tool call → tool result → follow-up user
• All five roles (developer, system, user, assistant, tool) in a single conversation
• Multiple parallel tool calls from a single assistant message

Total integration tests are now 32 (16 HTTP + 16 gRPC), all passing.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• 224.0.0.251
  • Triggering command: REDACTED, pid is -1 (packet block)
• buf.build
  • Triggering command: /home/REDACTED/work/js-sdk/js-sdk/node_modules/@bufbuild/buf-linux-x64/bin/buf /home/REDACTED/work/js-sdk/js-sdk/node_modules/@bufbuild/buf-linux-x64/bin/buf generate (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[WhitWaldo]

@copilot Are there any other aspects of this implementation that could be validated by another integration or unit test? We're aiming for comprehensive coverage.

[Copilot]

@copilot Are there any other aspects of this implementation that could be validated by another integration or unit test? We're aiming for comprehensive coverage.

Added 10 more integration tests (5 per protocol) and 4 more unit tests in 9bfdb8b to fill the remaining coverage gaps:

Integration tests added (now 42 total: 21 HTTP + 21 gRPC):

• contextId option passing
• scrubPii at request level
• scrubPii at input level
• Named messages (name field on developer, system, and user roles)
• Combined options (contextId + metadata + temperature + scrubPii in one request)

Unit tests added (now 72 total: 39 HTTP + 33 gRPC):

• HTTP: assistant message without toolCalls property (parity with gRPC)
• HTTP: multiple content items in a single message (parity with gRPC)
• gRPC: error propagation from converseAlpha2 (parity with HTTP)
• gRPC: original error object preservation

The remaining untestable areas are promptCacheRetention and responseFormat in integration tests — these are HTTP-only fields not yet in the proto, and the echo component doesn't process them. They are covered in the HTTP unit tests already.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• 224.0.0.251
  • Triggering command: REDACTED, pid is -1 (packet block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)