feat(vaultai): GetStructuredMessageAsync — structured output(JSON schema) + 멀티모달 이미지 인라인 (0.6.0)

- IVaultAiClient에 GetStructuredMessageAsync(agentId, prompt, outputSchema, images?) 신설
  + VaultAiImage(MimeType, Data, FileName?) record
- 이미지는 vault-ai wire 계약(file 콘텐츠 + ImageBlock data[base64])으로 인라인 전달
  — 채널 세션 파일업로드 경유 불필요(서버-투-서버)
- 응답 최상위 output 1순위, 폴백=마지막 text 파트 JSON 파싱, 둘 다 없으면 예외(silent-failure 방지)
- 소비처: yesung-oms 주문서 smart-fill (라이브 실증: gemini structured output + 이미지 인식)
- 모노버전 0.5.0 → 0.6.0 (additive minor)

Author: birdnamoo

Directory.Build.props

@@ -11,7 +11,7 @@
 
   <PropertyGroup>
     <!-- 버전 (모노 버전: 5개 라이브러리 모두 동일) -->
-    <Version>0.5.0</Version>
+    <Version>0.6.0</Version>
   </PropertyGroup>
 
   <PropertyGroup>

src/Iyu.VaultAi/IVaultAiClient.cs

@@ -1,6 +1,23 @@
+using System.Text.Json.Nodes;
+
 namespace Iyu.VaultAi;
 
+/// <summary>agent 메시지에 첨부할 이미지(멀티모달 입력). MimeType: image/png·jpeg·gif·webp.</summary>
+public sealed record VaultAiImage(string MimeType, byte[] Data, string? FileName = null);
+
 public interface IVaultAiClient
 {
     Task<string> GetMessageAsync(Guid agentId, string prompt, CancellationToken ct = default);
+
+    /// <summary>
+    /// structured output 호출 — vault-ai agent에 JSON schema(<paramref name="outputSchema"/>)를 지정해
+    /// 스키마 준수 JSON을 응답 output으로 직접 수신한다. 이미지(멀티모달)를 함께 보낼 수 있다.
+    /// 응답에 유효한 output이 없으면 예외를 던진다(silent-failure 방지).
+    /// </summary>
+    Task<JsonNode> GetStructuredMessageAsync(
+        Guid agentId,
+        string prompt,
+        JsonNode outputSchema,
+        IReadOnlyList<VaultAiImage>? images = null,
+        CancellationToken ct = default);
 }

src/Iyu.VaultAi/VaultAiClient.cs

@@ -2,6 +2,7 @@
 using System.Net.Http.Headers;
 using System.Net.Http.Json;
 using System.Text.Json;
+using System.Text.Json.Nodes;
 
 namespace Iyu.VaultAi;
 
@@ -75,4 +76,86 @@ public async Task<string> GetMessageAsync(Guid agentId, string prompt, Cancellat
 
         return text ?? string.Empty;
     }
+
+    public async Task<JsonNode> GetStructuredMessageAsync(
+        Guid agentId,
+        string prompt,
+        JsonNode outputSchema,
+        IReadOnlyList<VaultAiImage>? images = null,
+        CancellationToken ct = default)
+    {
+        // content 파트 조립 — 텍스트 + (선택) 이미지. 이미지는 vault-ai wire 계약상
+        // "file" 콘텐츠의 data 블록([{type:"image", mimeType, data(base64)}])으로 실린다
+        // (VaultAI.WebServer VaultFileContent/ImageBlock — 채널 파일업로드 경유 없이 인라인 전달).
+        var content = new List<object> { new { type = "text", text = prompt } };
+        foreach (var img in images ?? [])
+        {
+            content.Add(new
+            {
+                type = "file",
+                id = Guid.NewGuid().ToString(),
+                fileName = img.FileName ?? "image",
+                contentType = img.MimeType,
+                contentSize = img.Data.LongLength,
+                data = new object[]
+                {
+                    new { type = "image", mimeType = img.MimeType, data = Convert.ToBase64String(img.Data) },
+                },
+            });
+        }
+
+        var response = await _http.PostAsJsonAsync(
+            $"api/agents/{agentId}/messages",
+            new
+            {
+                messages = new[]
+                {
+                    new
+                    {
+                        role = "user",
+                        id = Guid.NewGuid().ToString(),
+                        content = (object)content,
+                        createdAt = DateTimeOffset.UtcNow.ToString("o")
+                    }
+                },
+                stream = false,
+                output = outputSchema,   // JSON schema → 응답 output으로 구조화 수신
+            }, ct);
+
+        if (!response.IsSuccessStatusCode)
+        {
+            var errorBody = await response.Content.ReadAsStringAsync(ct);
+            var snippet   = errorBody.Length > 1000 ? errorBody[..1000] + "…(중략)" : errorBody;
+            throw new HttpRequestException(
+                $"vault-ai 응답 {(int)response.StatusCode} ({response.StatusCode}): {snippet}");
+        }
+
+        var json = await response.Content.ReadAsStringAsync(ct);
+        var root = JsonNode.Parse(json);
+
+        // 1순위: 응답 최상위 output(서버가 파싱해 준 구조화 결과).
+        var output = root?["output"];
+        if (output is not null) return output;
+
+        // 폴백: 마지막 text 파트를 JSON으로 파싱(구버전 서버·output 미주입 경로 호환).
+        var contentArr = root?["message"]?["content"] as JsonArray;
+        var lastText = contentArr?
+            .OfType<JsonObject>()
+            .Where(o => (string?)o["type"] == "text")
+            .Select(o => (string?)o["text"])
+            .LastOrDefault(t => !string.IsNullOrWhiteSpace(t));
+        if (lastText is not null)
+        {
+            try { return JsonNode.Parse(lastText) ?? throw new JsonException("null JSON"); }
+            catch (JsonException ex)
+            {
+                var snippet = lastText.Length > 500 ? lastText[..500] + "…(중략)" : lastText;
+                throw new HttpRequestException($"vault-ai 응답 text가 유효한 JSON이 아닙니다: {ex.Message} — {snippet}");
+            }
+        }
+
+        // output도 text도 없음 — 스키마 불일치를 조용히 흘리지 않는다(silent-failure 방지).
+        var bodySnippet = json.Length > 1000 ? json[..1000] + "…(중략)" : json;
+        throw new HttpRequestException($"vault-ai 응답에 output/text가 없습니다: {bodySnippet}");
+    }
 }