feat(conversation): Conversation API alpha2

[WhitWaldo]

Description

The Dapr runtime exposes a ConverseAlpha2 gRPC method (and corresponding HTTP endpoint POST /v1.0-alpha2/conversation/{name}/converse) that replaces the now-deprecated Alpha1 Conversation API. The JS SDK should add first-class support for this new API surface.

The proto definitions (src/proto/dapr/proto/runtime/v1/ai.proto) and generated bindings are already present in the repository, but no high-level client method is exposed.

Background

Alpha2 is a significant redesign over Alpha1. Key differences:

Feature	Alpha1 (deprecated)	Alpha2
Input format	Flat string content + optional role	Structured typed messages (developer, system, user, assistant, tool) via ConversationMessage oneof
Tool support	None	ConversationTools with function definitions, tool_choice, tool call results in responses
Response format	Simple string result	ConversationResultAlpha2 with choices[], finish_reason, tool_calls, model, token usage stats
Structured output	None	response_format (JSON Schema via google.protobuf.Struct)
Prompt caching	None	prompt_cache_retention (google.protobuf.Duration)
Token usage	None	CompletionUsage with completion/prompt token breakdowns

Scope

1. TypeScript types (src/types/conversation/) — User-facing interfaces for:

   • ConversationRequestAlpha2 (name, contextId, inputs, metadata, temperature, scrubPii, tools, toolChoice, responseFormat, promptCacheRetention)
   • ConversationInputAlpha2 (messages, scrubPii)
   • ConversationMessage — discriminated union for developer/system/user/assistant/tool message types
   • ConversationMessageContent (text)
   • ConversationTools / ConversationToolsFunction — function tool definitions with JSON Schema parameters
   • ConversationToolCalls / ConversationToolCallsOfFunction — tool call results from LLM
   • ConversationResponseAlpha2 (contextId, outputs)
   • ConversationResultAlpha2 (choices, model, usage)
   • ConversationResultChoices (finishReason, index, message)
   • ConversationResultMessage (content, toolCalls)
   • Usage types (completionTokens, promptTokens, totalTokens, details breakdowns)

2. Client interface (src/interfaces/Client/IClientConversation.ts) — e.g.:

converse(request: ConversationRequestAlpha2): Promise<ConversationResponseAlpha2>

3. gRPC imlpementation (src/implementation/Client/GRPCClient/conversation.ts) — Map user-facing types ↔ proto schemas, call client.converseAlpha2()
4. HTTP implementation (src/implementation/Client/HTTPClient/conversation.ts) — POST /v1.0-alpha2/conversation/{name}/converse
5. DaprClient integration — Add conversation property to DaprClient
6. Exports — Export all new types/interfaces from src/index.ts
7. Tests — Unit tests for type mapping; E2E test if a conversation component is available in testcontainers

Target Usage

const response = await client.conversation.converse({
  name: "my-llm",
  inputs: [{
    messages: [
      { ofUser: { content: [{ text: "What is Dapr?" }] } }
    ]
  }],
  tools: [{
    function: { name: "search", description: "Search the docs", parameters: { type: "object", properties: {} } }
  }],
  toolChoice: "auto",
  temperature: 0.7,
});

// response.outputs[0].choices[0].message.content
// response.outputs[0].choices[0].message.toolCalls
// response.outputs[0].choices[0].finishReason
// response.outputs[0].usage.totalTokens

References

• Proto source: src/proto/dapr/proto/runtime/v1/ai.proto (messages) + dapr.proto line 252 (rpc definition)
• ConnectRPC binding: src/proto/dapr/proto/runtime/v1/dapr_connect.{js,d.ts} — ConverseAlpha2 service method
• OpenAI reference: openai-go chatcompletion.go
• Dapr runtime API docs for Conversation Alpha2

Acceptance Criteria

• DaprClient exposes a conversation.converse() method for both gRPC and HTTP protocols
• All Alpha2 proto fields are represented in user-facing TypeScript types
• Tool calling round-trip works (send tools → receive tool_calls → send tool results)
• Deprecated Alpha1 types/methods are NOT added
• Unit tests cover type mapping between user types and proto schemas
• Types are exported from the package index