graphlit-client 1.0.20260419003 → 1.0.20260420001

package/dist/client.d.ts

@@ -3119,6 +3119,32 @@ declare class Graphlit {
      * with `intermediateMessages` rather than a single tool-call list.
      */
     private detectTaskCompleteInMessages;
+    /**
+     * Extract the `final_message` argument from a task_complete invocation
+     * within a list of tool calls. Handles both direct invocation and
+     * meta-executor wrapping (mirrors `detectTaskComplete`).
+     *
+     * Returns undefined if task_complete was not called, the arg is missing,
+     * or the arg is not a non-empty string.
+     */
+    private extractTaskCompleteFinalMessage;
+    /**
+     * Scan a list of messages for a task_complete invocation's `final_message`
+     * arg. Convenience wrapper over `extractTaskCompleteFinalMessage`.
+     */
+    private extractTaskCompleteFinalMessageFromMessages;
+    /**
+     * Sanitize task_complete's `final_message` payload out of persisted
+     * intermediate messages. The tool call record (name, id, timing, ordering)
+     * is preserved as a completion marker, but its `final_message` arg is
+     * stripped because that content is already stored as the turn's assistant
+     * text via `completion`. Keeping the tool call without the payload yields
+     * the same storage win as full removal while preserving the trace.
+     *
+     * Handles both direct and meta-executor (`execute_tool({tool: ...})`)
+     * invocations, matching `detectTaskComplete`.
+     */
+    private sanitizeTaskCompletePayload;
     /**
      * Run LLM-as-judge quality assessment on a completed agent run.
      */

package/dist/client.js

@@ -6981,22 +6981,32 @@ class Graphlit {
             }
             // Build tools list with task_complete prepended.
             //
-            // task_complete is a bare completion signal — it takes no arguments.
-            // The agent's user-facing answer MUST be in its final assistant message
-            // (the `fullMessage` / `finalAssistantMessage` on the turn result); this
-            // tool only marks the run as done.
+            // task_complete's optional `final_message` parameter is the explicit
+            // commitment of the agent's user-facing answer. When provided, it
+            // becomes the persisted assistant message for that turn AND the run's
+            // `finalMessage`, overriding any prose the model wrote around the call.
             //
-            // Earlier versions had a `summary` field. That consistently caused the
-            // model to stuff its answer into the tool argument and then write a
-            // useless prose message ("answer delivered above") — the user would see
-            // the empty prose, not the answer. Removing the field eliminates the
-            // hiding place.
+            // An earlier version used a `summary` field. The name encouraged
+            // truncated summarization — the model would stuff a short summary into
+            // the arg and emit useless prose like "answer delivered above". The
+            // field name `final_message` and description below are explicit: this
+            // IS the full answer, not a summary, and it replaces surrounding prose.
+            //
+            // If the model omits `final_message`, the SDK falls back to the last
+            // turn whose assistant text was substantive AND did not itself call
+            // task_complete — so a throwaway completion turn can't overwrite the
+            // real answer in a prior turn.
             const taskCompleteTool = {
                 name: "task_complete",
-                description: "Signal that you have completed the assigned task. Your full answer must already be in your assistant message BEFORE calling this — that prose is what the user sees. This tool takes no arguments; it only ends the run.",
+                description: "Signal that you have completed the assigned task. Provide your complete, final user-facing answer as `final_message` — full prose, not a summary. That string becomes the assistant message the user sees; do not also emit the answer as plain text around this call. Calling this tool ends the run.",
                 schema: JSON.stringify({
                     type: "object",
-                    properties: {},
+                    properties: {
+                        final_message: {
+                            type: "string",
+                            description: "Your complete, final answer to the user as full prose. Replaces any assistant text written around this tool call.",
+                        },
+                    },
                 }),
             };
             const allTools = [
@@ -7254,9 +7264,39 @@ class Graphlit {
                 finally {
                     uiAdapter.dispose();
                 }
-                // 8. Complete conversation (persist turn)
-                const trimmedMessage = loopResult.finalAssistantMessage;
-                if (trimmedMessage) {
+                // 8. Detect task_complete and extract its optional `final_message`
+                // arg BEFORE persistence. When provided, it replaces the turn's
+                // assistant prose as the canonical answer — see the task_complete
+                // tool schema above.
+                const taskCompleteThisTurn = this.detectTaskCompleteInMessages(loopResult.intermediateMessages);
+                const taskCompleteFinalMessage = taskCompleteThisTurn
+                    ? this.extractTaskCompleteFinalMessageFromMessages(loopResult.intermediateMessages)
+                    : undefined;
+                // Resolve the assistant message to persist for this turn:
+                //   - task_complete({final_message}) → final_message (authoritative)
+                //   - task_complete() with no arg, prior substantive answer exists →
+                //     drop the turn's prose so throwaway text like "delivered above"
+                //     doesn't pollute chat history
+                //   - task_complete() with no arg, no prior answer → keep the prose
+                //     (single-shot completion case)
+                //   - normal turn → keep the prose
+                let assistantMessageToPersist;
+                if (taskCompleteThisTurn) {
+                    if (taskCompleteFinalMessage) {
+                        assistantMessageToPersist = taskCompleteFinalMessage;
+                    }
+                    else if (finalMessage) {
+                        assistantMessageToPersist = "";
+                    }
+                    else {
+                        assistantMessageToPersist = loopResult.finalAssistantMessage;
+                    }
+                }
+                else {
+                    assistantMessageToPersist = loopResult.finalAssistantMessage;
+                }
+                // 8b. Complete conversation (persist turn)
+                if (assistantMessageToPersist) {
                     const completionTime = uiAdapter.getCompletionTime();
                     const ttft = uiAdapter.getTTFT();
                     const throughput = uiAdapter.getThroughput();
@@ -7265,13 +7305,20 @@ class Graphlit {
                             return undefined;
                         return `PT${ms / 1000}S`;
                     };
-                    let turnMessageInputs = loopResult.intermediateMessages.length > 0
-                        ? loopResult.intermediateMessages
+                    // Sanitize task_complete's final_message arg before persistence —
+                    // the content is already saved as the turn's assistant text, so
+                    // keeping it in the tool-call arguments would double-store it.
+                    // The tool call record itself stays as a completion marker.
+                    const sanitizedIntermediates = taskCompleteThisTurn
+                        ? this.sanitizeTaskCompletePayload(loopResult.intermediateMessages)
+                        : loopResult.intermediateMessages;
+                    let turnMessageInputs = sanitizedIntermediates.length > 0
+                        ? sanitizedIntermediates
                         : undefined;
                     if (loopResult.lastRoundReasoning) {
                         const completionInput = {
                             role: Types.ConversationRoleTypes.Assistant,
-                            message: trimmedMessage,
+                            message: assistantMessageToPersist,
                             timestamp: new Date().toISOString(),
                             thinkingContent: loopResult.lastRoundReasoning.content,
                         };
@@ -7284,7 +7331,7 @@ class Graphlit {
                             completionInput,
                         ];
                     }
-                    await this.completeConversation(trimmedMessage, conversationId, millisecondsToTimeSpan(completionTime), millisecondsToTimeSpan(ttft), throughput, undefined, turnMessageInputs, options?.correlationId);
+                    await this.completeConversation(assistantMessageToPersist, conversationId, millisecondsToTimeSpan(completionTime), millisecondsToTimeSpan(ttft), throughput, undefined, turnMessageInputs, options?.correlationId);
                     // Emit completion event
                     uiAdapter.handleEvent({
                         type: "complete",
@@ -7293,12 +7340,11 @@ class Graphlit {
                 }
                 // 9. Build TurnResult
                 const turnDuration = Date.now() - turnStart;
-                const taskCompleteThisTurn = this.detectTaskCompleteInMessages(loopResult.intermediateMessages);
                 const turnToolNames = [...new Set(loopResult.toolCallNames)].sort();
                 const turnResult = {
                     turnNumber: turn,
                     prompt: currentPrompt,
-                    responseText: loopResult.fullMessage,
+                    responseText: taskCompleteFinalMessage || loopResult.fullMessage,
                     toolCalls: turnToolNames,
                     toolCallCount: loopResult.toolCallCount,
                     durationMs: turnDuration,
@@ -7314,7 +7360,25 @@ class Graphlit {
                 lastTurnUsage = undefined;
                 turnResults.push(turnResult);
                 totalToolCalls += loopResult.toolCallCount;
-                finalMessage = loopResult.finalAssistantMessage || loopResult.fullMessage;
+                // Update finalMessage with priority:
+                //   - task_complete({final_message}) → authoritative
+                //   - task_complete() without arg → keep prior finalMessage (avoids
+                //     throwaway completion-turn prose overwriting a real answer)
+                //   - normal turn → this turn's assistant text
+                if (taskCompleteThisTurn) {
+                    if (taskCompleteFinalMessage) {
+                        finalMessage = taskCompleteFinalMessage;
+                    }
+                    else if (!finalMessage) {
+                        // No prior answer — this turn's prose is all we have
+                        finalMessage =
+                            loopResult.finalAssistantMessage || loopResult.fullMessage;
+                    }
+                }
+                else {
+                    finalMessage =
+                        loopResult.finalAssistantMessage || loopResult.fullMessage;
+                }
                 lastContextWindow = loopResult.contextWindow;
                 // 10. Notify callback
                 options?.onTurnComplete?.(turnResult);
@@ -7564,6 +7628,107 @@ class Graphlit {
         }
         return false;
     }
+    /**
+     * Extract the `final_message` argument from a task_complete invocation
+     * within a list of tool calls. Handles both direct invocation and
+     * meta-executor wrapping (mirrors `detectTaskComplete`).
+     *
+     * Returns undefined if task_complete was not called, the arg is missing,
+     * or the arg is not a non-empty string.
+     */
+    extractTaskCompleteFinalMessage(toolCalls) {
+        if (!toolCalls)
+            return undefined;
+        for (const tc of toolCalls) {
+            if (!tc?.arguments)
+                continue;
+            let args;
+            try {
+                args = JSON.parse(tc.arguments);
+            }
+            catch {
+                continue;
+            }
+            // Direct invocation: args ARE the task_complete params
+            if (tc.name === "task_complete") {
+                const fm = args.final_message;
+                if (typeof fm === "string" && fm.trim().length > 0)
+                    return fm;
+                continue;
+            }
+            // Meta-executor wrapping: { tool: "task_complete", parameters: {...} }
+            if (args.tool === "task_complete") {
+                const params = args.parameters;
+                const fm = params?.final_message;
+                if (typeof fm === "string" && fm.trim().length > 0)
+                    return fm;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Scan a list of messages for a task_complete invocation's `final_message`
+     * arg. Convenience wrapper over `extractTaskCompleteFinalMessage`.
+     */
+    extractTaskCompleteFinalMessageFromMessages(messages) {
+        for (const msg of messages) {
+            const fm = this.extractTaskCompleteFinalMessage(msg.toolCalls);
+            if (fm)
+                return fm;
+        }
+        return undefined;
+    }
+    /**
+     * Sanitize task_complete's `final_message` payload out of persisted
+     * intermediate messages. The tool call record (name, id, timing, ordering)
+     * is preserved as a completion marker, but its `final_message` arg is
+     * stripped because that content is already stored as the turn's assistant
+     * text via `completion`. Keeping the tool call without the payload yields
+     * the same storage win as full removal while preserving the trace.
+     *
+     * Handles both direct and meta-executor (`execute_tool({tool: ...})`)
+     * invocations, matching `detectTaskComplete`.
+     */
+    sanitizeTaskCompletePayload(messages) {
+        return messages.map((msg) => {
+            if (!msg.toolCalls || msg.toolCalls.length === 0)
+                return msg;
+            let mutated = false;
+            const sanitizedToolCalls = msg.toolCalls.map((tc) => {
+                if (!tc || !tc.arguments)
+                    return tc;
+                let args;
+                try {
+                    args = JSON.parse(tc.arguments);
+                }
+                catch {
+                    return tc;
+                }
+                // Direct invocation: args ARE the task_complete params
+                if (tc.name === "task_complete" && "final_message" in args) {
+                    const { final_message: _dropped, ...rest } = args;
+                    void _dropped;
+                    mutated = true;
+                    return { ...tc, arguments: JSON.stringify(rest) };
+                }
+                // Meta-executor wrapping: { tool: "task_complete", parameters: {...} }
+                if (args.tool === "task_complete") {
+                    const params = args.parameters;
+                    if (params && "final_message" in params) {
+                        const { final_message: _dropped, ...restParams } = params;
+                        void _dropped;
+                        mutated = true;
+                        return {
+                            ...tc,
+                            arguments: JSON.stringify({ ...args, parameters: restParams }),
+                        };
+                    }
+                }
+                return tc;
+            });
+            return mutated ? { ...msg, toolCalls: sanitizedToolCalls } : msg;
+        });
+    }
     /**
      * Run LLM-as-judge quality assessment on a completed agent run.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphlit-client",
-  "version": "1.0.20260419003",
+  "version": "1.0.20260420001",
   "description": "Graphlit API Client for TypeScript",
   "type": "module",
   "main": "./dist/client.js",