synthos 0.10.0 → 0.11.0

package/service-connectors/canva/connector.json

@@ -0,0 +1,67 @@
+{
+    "id": "canva",
+    "name": "Canva",
+    "category": "Design",
+    "description": "Create, autofill, export, and manage Canva designs, brand templates, and assets via the Canva Connect API.",
+    "baseUrl": "https://api.canva.com/rest/v1",
+    "authStrategy": "oauth2",
+    "authKey": "Authorization",
+    "authorizationUrl": "https://www.canva.com/api/oauth/authorize",
+    "tokenUrl": "https://api.canva.com/rest/v1/oauth/token",
+    "usePkce": true,
+    "scopeSeparator": " ",
+    "scopes": [
+        "profile:read",
+        "design:meta:read",
+        "design:content:read",
+        "design:content:write",
+        "asset:read",
+        "asset:write",
+        "brandtemplate:meta:read",
+        "brandtemplate:content:read",
+        "folder:read"
+    ],
+    "fields": [
+        { "name": "clientId", "label": "Client ID", "type": "text" },
+        { "name": "clientSecret", "label": "Client Secret", "type": "password" }
+    ],
+    "hints": [
+        "REST API. Auth is OAuth 2.0 with PKCE (S256) — required by Canva for ALL clients (public AND confidential). The proxy handles the PKCE handshake automatically.",
+        "User profile: GET /users/me/profile — returns the authenticated user's display_name and user_id. Use this as a connection smoke test.",
+        "List designs: GET /designs?query=&continuation=&ownership=any&sort_by=relevance",
+        "  Cursor pagination via `continuation` (opaque string). Pass back the value from the previous response's `continuation` field to fetch the next page.",
+        "Get a design: GET /designs/{designId} — returns title, urls (edit_url, view_url), thumbnail, page_count.",
+        "Create a blank design: POST /designs  Body: { design_type: { type: \"preset\", name: \"presentation\" } }   Other preset names: doc, whiteboard, presentation, instagrampost, instagramstory, facebookcover, etc. Or use { type: \"custom\", width, height } for custom dimensions.",
+        "Export a design (PNG, PDF, JPG, MP4, GIF, PPTX) — async two-step:",
+        "  1) POST /exports  Body: { design_id, format: { type: \"png\" } }   Response: { job: { id, status: \"in_progress\" } }",
+        "  2) Poll GET /exports/{jobId} until status === \"success\". Response then includes `urls` (signed download URLs, expire after a short window — fetch immediately).",
+        "  Format options: png (no compression flag), jpg (quality 1-100), pdf (size, pages), mp4 (quality), gif, pptx.",
+        "Asset upload — binary only, no URL pass-through. Two-step async:",
+        "  1) POST /asset-uploads  Headers: Content-Type: application/octet-stream, Asset-Upload-Metadata: <base64url JSON {name_base64, tags?}>   Body: raw bytes.",
+        "  2) Poll GET /asset-uploads/{jobId} until status === \"success\". Response then includes asset.id (use in autofill / design references).",
+        "  Pexels URLs cannot be passed directly — fetch the image, then upload the bytes here. Max ~25MB per asset.",
+        "List brand templates: GET /brand-templates?query=&continuation=  Returns templates the user has access to (Canva Enterprise required for full brand template access).",
+        "Get template dataset (autofill schema): GET /brand-templates/{brandTemplateId}/dataset   Returns the named text fields and image placeholders the template accepts.",
+        "Autofill a brand template — async two-step (very high-value for programmatic design generation):",
+        "  1) POST /autofills  Body: { brand_template_id, data: { <field_name>: { type: \"text\" | \"image\" | \"chart\", text?: \"...\", asset_id?: \"...\" } } }   Response: { job: { id, status: \"in_progress\" } }",
+        "  2) Poll GET /autofills/{jobId} until status === \"success\". Response includes design_id of the new design — then fetch via /designs/{designId} for edit_url/thumbnail or export it.",
+        "  Image fields require an asset_id from a prior /asset-uploads — you cannot pass a URL.",
+        "Comments: GET/POST /designs/{designId}/comments and /designs/{designId}/comments/{commentId}/replies (requires comment:read / comment:write scopes — not in default scope list above; add if needed).",
+        "Folders: GET /folders/{folderId}, GET /folders/{folderId}/items?continuation=  — list designs/templates within a folder.",
+        "Async job pattern (used by exports, asset uploads, autofills): poll the GET endpoint with a small backoff (start 500ms, cap ~5s). Status values: in_progress, success, failed. On failed the response includes an `error` object with `code` and `message`.",
+        "Error shape: { code: \"<machine_code>\", message: \"...\" } with appropriate HTTP status (400/401/403/404/429/5xx). Common codes: invalid_request, unauthorized, forbidden, not_found, rate_limit_exceeded, internal_error.",
+        "Rate limits: per-token request budgets. On 429, honor the Retry-After response header (seconds).",
+        "Refresh tokens: Canva rotates refresh tokens — every refresh returns a new refresh_token and invalidates the old one. The proxy stores the latest automatically; do not cache refresh tokens client-side.",
+        "IMPORTANT: Do NOT include access_token in body or query params — the proxy attaches the Authorization: Bearer header automatically."
+    ],
+    "onboarding": {
+        "url": "https://www.canva.com/developers/",
+        "steps": [
+            "Sign in to Canva and go to canva.com/developers",
+            "Create a new integration (Connect API) and choose 'Public' or 'Team' depending on who will use it",
+            "Add the redirect URI shown in Synthos (typically http://localhost:<port>/api/connectors/callback) to the integration's allowed redirect URIs",
+            "Enable the scopes the integration needs: profile:read, design:meta:read, design:content:read, design:content:write, asset:read, asset:write, brandtemplate:meta:read, brandtemplate:content:read, folder:read",
+            "Copy the Client ID and Client Secret into the fields below"
+        ]
+    }
+}

package/service-connectors/elevenlabs/connector.json

@@ -15,7 +15,7 @@
         "  Request headers: Accept: audio/mpeg, Content-Type: application/json",
         "  Request body: { text: string, model_id: \"eleven_multilingual_v2\" }",
         "  Response: raw audio/mpeg binary — use resp.arrayBuffer() then new Blob([buf], {type:\"audio/mpeg\"}) and URL.createObjectURL() to play",
-        "  IMPORTANT: The proxy returns raw binary, NOT JSON. Call fetch(\"/api/connectors\", ...) directly instead of synthos.connectors.call() for TTS, since the helper parses JSON.",
+        "  IMPORTANT: The proxy returns raw binary, NOT JSON. Call fetch(\"/api/connectors\", ...) directly instead of synthos.connector.call() for TTS, since the helper parses JSON.",
         "Default voice: \"Rachel\" (voice_id: 21m00Tcm4TlvDq8ikWAM) is a good general-purpose voice.",
         "Max text length: 5000 characters per request."
     ],

package/src/builders/anthropic.ts

@@ -1,4 +1,5 @@
 import { anthropic as createAnthropicModel, completePrompt, ContentBlock } from '../models';
+import { ToolDefinition, ToolHandler } from '../models/types';
 import { parseChangeList, getTransformInstr } from '../service/transformPage';
 import { Attachment, Builder, BuilderResult, CHANGE_OPS_SCHEMA, CHANGE_OPS_SCHEMA_NO_RANGED, ContextSection } from './types';
 
@@ -15,6 +16,10 @@ export interface AnthropicBuilderOptions {
     isFirstEdit?: boolean;
     /** When true, retry the last edit — forces Opus + no ranged writes, skips classification. */
     tryAgain?: boolean;
+    /** Number of messages in the chat history (used for early-conversation bypass). */
+    historyLength?: number;
+    /** Pre-computed classification result — skips re-classifying in the builder. */
+    preClassified?: ClassifyResult;
 }
 
 // ---------------------------------------------------------------------------
@@ -23,13 +28,23 @@ export interface AnthropicBuilderOptions {
 
 export type Classification = 'question' | 'easy-change' | 'medium-change' | 'hard-change' | 're-write';
 
+/** Sketches passed to the classifier so it can decide which sections to expand. */
+export interface ClassifierSection {
+    /** Section title (e.g. "<CONFIGURED_AGENTS>"). */
+    title: string;
+    /** Compact one-line summary the classifier reads. */
+    sketch: string;
+}
+
 export interface ClassifyResult {
     classification: Classification;
     /** When classification is "question", this contains the answer text. */
     answer?: string;
+    /** Section titles the classifier picked to render in full. Empty = render all sketches. */
+    expand: string[];
 }
 
-const CLASSIFIER_SYSTEM_PROMPT = `You classify user messages for a web page builder. Default to a change request. Only classify as "question" when the user is purely asking for information with zero implication that anything should change.
+const CLASSIFIER_SYSTEM_PROMPT = `You classify user messages for a web page builder and pick which context sections the builder needs. Default to a change request. Only classify as "question" when the user is purely asking for information with zero implication that anything should change.
 
 <DECISION_RULES>
 Step 1 — Is this a pure information question with zero change implication?
@@ -43,40 +58,91 @@ Step 2 — Classify complexity:
   "hard-change": Complex new features, significant new JS, games, animations, restructuring layout, forms with validation, multi-step work.
   "re-write": Complete page overhaul, fundamental restructure, "start over", "rebuild", "redo the whole page".
 
+Step 3 — Which context sections does the model need to fulfill this request?
+  Read the AVAILABLE_SECTIONS list in the user message — each line is "<SECTION_TITLE>: <one-line sketch>" describing what's in the section.
+  Return an "expand" array of section titles (matching exactly, including the angle brackets) the model needs in full.
+  Include a title only if the page currently uses that feature OR the user's request will likely require it.
+  Sections you don't expand will still be visible to the model as their sketch — so the model knows the section exists, just not the full content.
+  Omit sections that are clearly unrelated to this request.
+
 <OUTPUT_FORMAT>
 Return only JSON. No other text.
-- Change: { "classification": "easy-change" } or { "classification": "medium-change" } or { "classification": "hard-change" } or { "classification": "re-write" }
-- Question: { "classification": "question", "answer": "<brief answer>" }`;
+- Change: { "classification": "easy-change", "expand": ["<FLUENTLM_COMPONENTS>"] }
+- Question: { "classification": "question", "answer": "<brief answer>", "expand": [] }`;
 
 export async function classifyRequest(
     apiKey: string,
     pageHtml: string,
-    userMessage: string
+    userMessage: string,
+    sections?: ClassifierSection[],
 ): Promise<ClassifyResult> {
     try {
-        const sonnet = createAnthropicModel({ apiKey, model: 'claude-sonnet-4-5' });
+        const sonnet = createAnthropicModel({ apiKey, model: 'claude-sonnet-4-6' });
+        const sectionList = (sections ?? [])
+            .map(s => `${s.title}: ${s.sketch}`)
+            .join('\n');
+        const sectionsBlock = sectionList
+            ? `\n\n<AVAILABLE_SECTIONS>\n${sectionList}`
+            : '';
         const result = await sonnet({
             system: { role: 'system', content: CLASSIFIER_SYSTEM_PROMPT },
-            prompt: { role: 'user', content: `<PAGE_HTML>\n${pageHtml}\n\n<USER_MESSAGE>\n${userMessage}` },
+            prompt: { role: 'user', content: `<PAGE_HTML>\n${pageHtml}\n\n<USER_MESSAGE>\n${userMessage}${sectionsBlock}` },
             jsonMode: true,
         });
 
         if (!result.completed || !result.value) {
-            return { classification: 'hard-change' };
+            return { classification: 'hard-change', expand: [] };
         }
 
         const parsed = JSON.parse(result.value);
         const c = parsed.classification;
+        const allowed = new Set((sections ?? []).map(s => s.title));
+        const expand = parseExpand(parsed.expand, allowed);
+
         if (c === 'question') {
-            return { classification: 'question', answer: typeof parsed.answer === 'string' ? parsed.answer : '' };
+            return { classification: 'question', answer: typeof parsed.answer === 'string' ? parsed.answer : '', expand };
         }
         if (c === 'easy-change' || c === 'medium-change' || c === 'hard-change' || c === 're-write') {
-            return { classification: c };
+            return { classification: c, expand };
         }
-        return { classification: 'hard-change' };
+        return { classification: 'hard-change', expand };
     } catch {
-        return { classification: 'hard-change' };
+        return { classification: 'hard-change', expand: [] };
+    }
+}
+
+/**
+ * Validate the classifier's expand[] against the set of titles it was offered.
+ * Unknown / non-string entries are dropped silently.
+ */
+function parseExpand(raw: unknown, allowed: Set<string>): string[] {
+    if (!Array.isArray(raw)) return [];
+    const out: string[] = [];
+    for (const item of raw) {
+        if (typeof item === 'string' && allowed.has(item)) {
+            out.push(item);
+        }
     }
+    return out;
+}
+
+// ---------------------------------------------------------------------------
+// Lightweight question heuristic — replaces Sonnet classifier for Q&A detection
+// ---------------------------------------------------------------------------
+
+const QUESTION_WORDS = /^(?:what|how|why|where|when|which|is|are|does|do|can|could|should|would|will)\b/i;
+const ACTION_VERBS = /\b(?:add|change|make|create|build|fix|update|remove|delete|move|replace|resize|rewrite|redo|redesign)\b/i;
+
+/**
+ * Returns true when the message is very likely a pure information question
+ * (no intent to modify the page). Used to bypass the full Sonnet classifier.
+ */
+export function isLikelyQuestion(message: string): boolean {
+    const trimmed = message.trim();
+    if (!trimmed.endsWith('?')) return false;
+    if (!QUESTION_WORDS.test(trimmed)) return false;
+    if (ACTION_VERBS.test(trimmed)) return false;
+    return true;
 }
 
 // ---------------------------------------------------------------------------
@@ -100,32 +166,32 @@ export function createAnthropicBuilder(
     const name = productName ?? 'SynthOS';
 
     return {
-        async run(currentPage, additionalSections, userMessage, newBuild, attachments?): Promise<BuilderResult> {
+        async run(currentPage, additionalSections, userMessage, newBuild, attachments?, tools?, toolHandlers?, onToolCall?): Promise<BuilderResult> {
             try {
                 const isOpus = options?.model?.startsWith('claude-opus-');
                 const noRanged = CHANGE_OPS_SCHEMA_NO_RANGED;
 
                 // Non-Opus models or missing apiKey: existing behavior
                 if (!isOpus || !options?.apiKey) {
-                    return buildWithModel(complete, currentPage, additionalSections, userMessage, userInstructions, name, attachments);
+                    return buildWithModel(complete, currentPage, additionalSections, userMessage, userInstructions, name, attachments, undefined, tools, toolHandlers, onToolCall);
                 }
 
                 // Console errors bypass classification — always route to Opus with no ranged writes
                 if (userMessage.includes('CONSOLE_ERRORS:')) {
                     console.log('classifyRequest: console errors detected → routing to ' + options.model! + ' (no ranged)');
-                    return buildWithModel(complete, currentPage, additionalSections, userMessage, userInstructions, name, attachments, noRanged);
+                    return buildWithModel(complete, currentPage, additionalSections, userMessage, userInstructions, name, attachments, noRanged, tools, toolHandlers, onToolCall);
                 }
 
                 // New builds always use Opus with no ranged writes
                 if (newBuild) {
                     console.log('classifyRequest: new build → routing to ' + options.model! + ' (no ranged)');
-                    return buildWithModel(complete, currentPage, additionalSections, userMessage, userInstructions, name, attachments, noRanged);
+                    return buildWithModel(complete, currentPage, additionalSections, userMessage, userInstructions, name, attachments, noRanged, tools, toolHandlers, onToolCall);
                 }
 
                 // First edit to a saved page (v0→v1) — force Opus with no ranged writes
                 if (options?.isFirstEdit) {
                     console.log('classifyRequest: first edit (v0→v1) → routing to ' + options.model! + ' (no ranged)');
-                    return buildWithModel(complete, currentPage, additionalSections, userMessage, userInstructions, name, attachments, noRanged);
+                    return buildWithModel(complete, currentPage, additionalSections, userMessage, userInstructions, name, attachments, noRanged, tools, toolHandlers, onToolCall);
                 }
 
                 // Try again — force Opus with no ranged writes, skip classification
@@ -133,12 +199,54 @@ export function createAnthropicBuilder(
                     console.log('classifyRequest: try again → routing to claude-opus-4-6 (no ranged)');
                     let opus: completePrompt = createAnthropicModel({ apiKey: options.apiKey!, model: 'claude-opus-4-6' });
                     if (options.wrapModel) opus = options.wrapModel(opus);
-                    return buildWithModel(opus, currentPage, additionalSections, userMessage, userInstructions, name, attachments, noRanged);
+                    return buildWithModel(opus, currentPage, additionalSections, userMessage, userInstructions, name, attachments, noRanged, tools, toolHandlers, onToolCall);
                 }
 
-                // Classify the request using Sonnet
-                const classifyResult = await classifyRequest(options.apiKey, currentPage.content, userMessage);
-                console.log(`classifyRequest: "${classifyResult.classification}" → routing to ${routeLabel(classifyResult.classification, options.model!)}`);
+                // --- Opt-1: Smart classification bypass ---
+
+                // Small pages (<5KB) — Opus cost delta is negligible; classifier cost exceeds savings
+                if (currentPage.content.length < 5_000) {
+                    console.log('classifyRequest: small page (<5KB) → routing to ' + options.model! + ' (no ranged, bypass)');
+                    return buildWithModel(complete, currentPage, additionalSections, userMessage, userInstructions, name, attachments, noRanged, tools, toolHandlers, onToolCall);
+                }
+
+                // Image attachments — always structural changes; classifier can't inspect images
+                if (attachments && attachments.length > 0) {
+                    console.log('classifyRequest: image attachments → routing to ' + options.model! + ' (no ranged, bypass)');
+                    return buildWithModel(complete, currentPage, additionalSections, userMessage, userInstructions, name, attachments, noRanged, tools, toolHandlers, onToolCall);
+                }
+
+                // Early conversations (history <= 2) — almost always builds/edits
+                if (typeof options.historyLength === 'number' && options.historyLength <= 2) {
+                    console.log('classifyRequest: early conversation (history <= 2) → routing to ' + options.model! + ' (no ranged, bypass)');
+                    return buildWithModel(complete, currentPage, additionalSections, userMessage, userInstructions, name, attachments, noRanged, tools, toolHandlers, onToolCall);
+                }
+
+                // Keyword-based Q&A detection — lightweight heuristic replaces full-page Sonnet call
+                if (isLikelyQuestion(userMessage)) {
+                    console.log('classifyRequest: likely question (heuristic) → routing to claude-sonnet-4-6 (Q&A, no page HTML)');
+                    let sonnet: completePrompt = createAnthropicModel({ apiKey: options.apiKey, model: 'claude-sonnet-4-6' });
+                    if (options.wrapModel) sonnet = options.wrapModel(sonnet);
+                    // Lightweight Q&A call — send only user message + page summary, not full HTML
+                    const pageTitle = currentPage.content.match(/<title[^>]*>([^<]*)<\/title>/i)?.[1] ?? 'untitled';
+                    const elementCount = (currentPage.content.match(/<[a-z]/gi) ?? []).length;
+                    const pageSummary = `Page: "${pageTitle}" (${elementCount} elements)`;
+                    const qaResult = await sonnet({
+                        system: { role: 'system', content: 'You are a helpful assistant for a web page builder. Answer the user\'s question briefly and accurately based on the page summary provided.' },
+                        prompt: { role: 'user', content: `${pageSummary}\n\n${userMessage}` },
+                    });
+                    if (qaResult.completed && qaResult.value) {
+                        return { kind: 'reply', text: qaResult.value };
+                    }
+                    // Fallback to classifier if Q&A call fails
+                }
+
+                // Classify the request — use pre-computed result if available, otherwise call Sonnet
+                const classifyResult = options.preClassified
+                    ?? await classifyRequest(options.apiKey, currentPage.content, userMessage);
+                if (!options.preClassified) {
+                    console.log(`classifyRequest: "${classifyResult.classification}" → routing to ${routeLabel(classifyResult.classification, options.model!)}`);
+                }
 
                 // Questions — answer was already provided by the classifier
                 if (classifyResult.classification === 'question') {
@@ -147,20 +255,20 @@ export function createAnthropicBuilder(
 
                 // Easy changes use Sonnet with default schema (ranged allowed)
                 if (classifyResult.classification === 'easy-change') {
-                    let sonnet: completePrompt = createAnthropicModel({ apiKey: options.apiKey, model: 'claude-sonnet-4-5' });
+                    let sonnet: completePrompt = createAnthropicModel({ apiKey: options.apiKey, model: 'claude-sonnet-4-6' });
                     if (options.wrapModel) sonnet = options.wrapModel(sonnet);
-                    return buildWithModel(sonnet, currentPage, additionalSections, userMessage, userInstructions, name, attachments);
+                    return buildWithModel(sonnet, currentPage, additionalSections, userMessage, userInstructions, name, attachments, undefined, tools, toolHandlers, onToolCall);
                 }
 
                 // Medium changes use Sonnet with no ranged writes
                 if (classifyResult.classification === 'medium-change') {
-                    let sonnet: completePrompt = createAnthropicModel({ apiKey: options.apiKey, model: 'claude-sonnet-4-5' });
+                    let sonnet: completePrompt = createAnthropicModel({ apiKey: options.apiKey, model: 'claude-sonnet-4-6' });
                     if (options.wrapModel) sonnet = options.wrapModel(sonnet);
-                    return buildWithModel(sonnet, currentPage, additionalSections, userMessage, userInstructions, name, attachments, noRanged);
+                    return buildWithModel(sonnet, currentPage, additionalSections, userMessage, userInstructions, name, attachments, noRanged, tools, toolHandlers, onToolCall);
                 }
 
                 // Hard changes and re-writes use Opus with no ranged writes
-                return buildWithModel(complete, currentPage, additionalSections, userMessage, userInstructions, name, attachments, noRanged);
+                return buildWithModel(complete, currentPage, additionalSections, userMessage, userInstructions, name, attachments, noRanged, tools, toolHandlers, onToolCall);
             } catch (err: unknown) {
                 return { kind: 'error', error: err instanceof Error ? err : new Error(String(err)) };
             }
@@ -172,6 +280,12 @@ export function createAnthropicBuilder(
 // Build flow — shared prompt construction + model call + parsing
 // ---------------------------------------------------------------------------
 
+/**
+ * Appended to <INSTRUCTIONS> when tools are bound so the model knows it may
+ * fetch additional context on demand.
+ */
+export const TOOLS_INSTRUCTION_HINT = 'You may call the provided tools to load additional context only if you need it. You may call multiple tools in parallel in a single turn.';
+
 export async function buildWithModel(
     model: completePrompt,
     currentPage: ContextSection,
@@ -180,7 +294,10 @@ export async function buildWithModel(
     userInstructions: string | undefined,
     productName: string,
     attachments?: Attachment[],
-    outputSchema?: Record<string, unknown>
+    outputSchema?: Record<string, unknown>,
+    tools?: ToolDefinition[],
+    toolHandlers?: Record<string, ToolHandler>,
+    onToolCall?: (names: string[]) => void,
 ): Promise<BuilderResult> {
     // -- System message: all static content (cacheable) --
     const systemParts: string[] = [];
@@ -200,6 +317,9 @@ export async function buildWithModel(
         }
     }
     instructionParts.push(getTransformInstr(productName));
+    if (tools && tools.length > 0) {
+        instructionParts.push(TOOLS_INSTRUCTION_HINT);
+    }
     const instructions = instructionParts.filter(s => s.trim() !== '').join('\n');
     systemParts.push(`<INSTRUCTIONS>\n${instructions}`);
 
@@ -227,6 +347,7 @@ export async function buildWithModel(
         prompt: { role: 'user', content: promptContent },
         cacheSystem: true,
         outputSchema: outputSchema ?? CHANGE_OPS_SCHEMA,
+        ...(tools && tools.length > 0 && { tools, toolHandlers: toolHandlers ?? {}, onToolCall }),
     });
 
     if (!result.completed) {
@@ -243,8 +364,8 @@ export async function buildWithModel(
 
 function routeLabel(classification: Classification, configuredModel: string): string {
     if (classification === 'question') return 'classifier (answered inline)';
-    if (classification === 'easy-change') return 'claude-sonnet-4-5';
-    if (classification === 'medium-change') return 'claude-sonnet-4-5 (no ranged)';
+    if (classification === 'easy-change') return 'claude-sonnet-4-6';
+    if (classification === 'medium-change') return 'claude-sonnet-4-6 (no ranged)';
     if (classification === 're-write') return configuredModel + ' (re-write)';
     return configuredModel + ' (no ranged)';
 }
@@ -254,10 +375,14 @@ function routeLabel(classification: Classification, configuredModel: string): st
 // ---------------------------------------------------------------------------
 
 export function parseBuilderResponse(raw: string): BuilderResult {
-    // Try parsing as a JSON object with a kind discriminator
+    // Try parsing as a JSON object with a changes array + optional message
     try {
         const parsed = JSON.parse(raw);
         if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            if (Array.isArray(parsed.changes)) {
+                const message = typeof parsed.message === 'string' ? parsed.message : undefined;
+                return { kind: 'transforms', changes: parsed.changes, message };
+            }
             if (parsed.kind === 'transforms' && Array.isArray(parsed.changes)) {
                 return { kind: 'transforms', changes: parsed.changes };
             }
@@ -265,7 +390,7 @@ export function parseBuilderResponse(raw: string): BuilderResult {
                 return { kind: 'reply', text: parsed.text };
             }
         }
-        // Bare array — backward compat
+        // Bare array — backward compat (no message field available)
         if (Array.isArray(parsed)) {
             return { kind: 'transforms', changes: parsed };
         }