@vellumai/assistant 0.11.2-staging.2 → 0.11.2

package/src/providers/openai/orphaned-tool-result.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared wire-serialization rule for OpenAI tool results.
+ *
+ * Both OpenAI transports reject a tool result whose call was never emitted
+ * earlier in the same request: chat-completions rejects a `tool`-role message
+ * whose `tool_call_id` has no preceding assistant `tool_calls` entry, and the
+ * Responses API rejects a `function_call_output` whose `call_id` has no
+ * preceding `function_call`. Both therefore serialize a result as its native
+ * paired item only on a backward match, and degrade an unmatched one into
+ * plain text carried by the accompanying user message.
+ *
+ * The text payload and the orphan decision are identical across the two
+ * transports, so they live here; only the paired wire shape (and which media
+ * kinds each transport accepts alongside it) differs, and that stays at the
+ * call sites.
+ *
+ * Distinct from `agent/history-repair`'s `[orphaned <type> for <id>]:` marker,
+ * which operates one layer up on persisted history: it repairs the stored
+ * conversation shape (naming the id, and covering `web_search_tool_result`
+ * too) before any transport is chosen. This marker means "the call never
+ * reached this request's wire payload", so the id it would name is absent by
+ * construction. Keeping the two readable apart tells an operator which layer
+ * degraded the block.
+ */
+
+import type { ContentBlock, ToolResultContent } from "../types.js";
+
+/** Text prefix marking a tool result whose call is absent from the request. */
+const ORPHANED_MARKER = "[orphaned tool result]";
+
+/** Text prefix marking a tool result the executor reported as failed. */
+const ERROR_MARKER = "[ERROR]";
+
+/**
+ * How a tool result should be serialized for an OpenAI transport:
+ *
+ * - `paired`: its call was emitted earlier in this request, so the transport
+ *   emits its native tool-output item carrying `payload`.
+ * - `orphaned`: no matching call, so `block` is folded into the user message
+ *   instead of being sent as a rejectable tool-output item.
+ */
+export type ToolResultSerialization =
+  | { kind: "paired"; payload: string }
+  | { kind: "orphaned"; block: ContentBlock };
+
+/**
+ * Flatten a tool result's text (its own `content` plus any text in
+ * `contentBlocks`), mark executor failures, and decide whether the request
+ * can carry it as a paired tool-output item.
+ *
+ * `emittedCallIds` holds the ids already emitted as calls earlier in the same
+ * request, so membership is a backward match by construction. Media in
+ * `contentBlocks` is not consulted: each transport accepts a different set and
+ * collects it separately.
+ */
+export function serializeToolResult(
+  toolResult: ToolResultContent,
+  emittedCallIds: ReadonlySet<string>,
+): ToolResultSerialization {
+  let text = toolResult.content;
+  const extraText = (toolResult.contentBlocks ?? [])
+    .filter(
+      (cb): cb is Extract<ContentBlock, { type: "text" }> => cb.type === "text",
+    )
+    .map((cb) => cb.text);
+  if (extraText.length > 0) {
+    text = text + "\n" + extraText.join("\n");
+  }
+
+  const payload = toolResult.is_error ? `${ERROR_MARKER} ${text}` : text;
+
+  if (!emittedCallIds.has(toolResult.tool_use_id)) {
+    return {
+      kind: "orphaned",
+      block: { type: "text", text: `${ORPHANED_MARKER} ${payload}` },
+    };
+  }
+  return { kind: "paired", payload };
+}

package/src/providers/openai/responses-provider.ts

@@ -26,6 +26,7 @@ import {
   normalizeOpenAIAPIError,
 } from "./api-error-normalization.js";
 import { detectOpenAICompatibleContextOverflow } from "./chat-completions-provider.js";
+import { serializeToolResult } from "./orphaned-tool-result.js";
 
 const log = getLogger("openai-responses");
 
@@ -758,11 +759,16 @@ export class OpenAIResponsesProvider implements Provider {
     messages = resolveMediaReferences(messages);
     const result: unknown[] = [];
 
+    // `call_id`s emitted as `function_call` items earlier in this request.
+    // The API rejects a `function_call_output` whose `call_id` has no
+    // preceding `function_call`, so tool results are only serialized as
+    // outputs when their call was emitted first (backward matches only).
+    const emittedCallIds = new Set<string>();
     for (const msg of messages) {
       if (msg.role === "assistant") {
-        this.appendAssistantItems(result, msg);
+        this.appendAssistantItems(result, msg, emittedCallIds);
       } else {
-        this.appendUserItems(result, msg);
+        this.appendUserItems(result, msg, emittedCallIds);
       }
     }
 
@@ -887,8 +893,16 @@ export class OpenAIResponsesProvider implements Provider {
     }
   }
 
-  /** Convert an assistant message's content blocks to Responses input items. */
-  private appendAssistantItems(result: unknown[], msg: Message): void {
+  /**
+   * Convert an assistant message's content blocks to Responses input items.
+   * Every `function_call` emitted is recorded in `emittedCallIds` so the
+   * user-item conversion can pair `tool_result` blocks against it.
+   */
+  private appendAssistantItems(
+    result: unknown[],
+    msg: Message,
+    emittedCallIds: Set<string>,
+  ): void {
     const textParts: string[] = [];
 
     for (const block of msg.content) {
@@ -912,6 +926,7 @@ export class OpenAIResponsesProvider implements Provider {
             name: block.name,
             arguments: JSON.stringify(block.input),
           });
+          emittedCallIds.add(block.id);
           break;
         case "server_tool_use":
           textParts.push(`[Web search: ${block.name}]`);
@@ -932,8 +947,18 @@ export class OpenAIResponsesProvider implements Provider {
     }
   }
 
-  /** Convert a user message's content blocks to Responses input items. */
-  private appendUserItems(result: unknown[], msg: Message): void {
+  /**
+   * Convert a user message's content blocks to Responses input items.
+   * A `tool_result` whose `tool_use_id` was not emitted as a `function_call`
+   * earlier in this request (`emittedCallIds`) is orphaned; the API rejects
+   * an unmatched `function_call_output`, so its content is degraded into the
+   * plain user message instead of dropped.
+   */
+  private appendUserItems(
+    result: unknown[],
+    msg: Message,
+    emittedCallIds: Set<string>,
+  ): void {
     // Separate tool results from other blocks
     const toolResults = msg.content.filter(
       (b): b is Extract<ContentBlock, { type: "tool_result" }> =>
@@ -948,33 +973,34 @@ export class OpenAIResponsesProvider implements Provider {
 
     // Emit tool results as function_call_output items
     const toolResultImages: ContentBlock[] = [];
+    const orphanedResultBlocks: ContentBlock[] = [];
     for (const tr of toolResults) {
-      let textContent = tr.content;
-      if (tr.contentBlocks && tr.contentBlocks.length > 0) {
-        const extraText = tr.contentBlocks
-          .filter(
-            (cb): cb is Extract<ContentBlock, { type: "text" }> =>
-              cb.type === "text",
-          )
-          .map((cb) => cb.text);
-        if (extraText.length > 0) {
-          textContent = textContent + "\n" + extraText.join("\n");
-        }
-        for (const cb of tr.contentBlocks) {
-          if (cb.type === "image") {
-            toolResultImages.push(cb);
-          }
+      // This transport carries images only; the text payload and the orphan
+      // decision are the shared cross-transport rule.
+      for (const cb of tr.contentBlocks ?? []) {
+        if (cb.type === "image") {
+          toolResultImages.push(cb);
         }
       }
+      const serialized = serializeToolResult(tr, emittedCallIds);
+      if (serialized.kind === "orphaned") {
+        orphanedResultBlocks.push(serialized.block);
+        continue;
+      }
       result.push({
         type: "function_call_output",
         call_id: tr.tool_use_id,
-        output: tr.is_error ? `[ERROR] ${textContent}` : textContent,
+        output: serialized.payload,
       });
     }
 
-    // Emit remaining content + any tool result images as a user message
-    const userContent = [...otherBlocks, ...toolResultImages];
+    // Emit remaining content, degraded orphaned results, and any tool result
+    // images as a user message
+    const userContent = [
+      ...otherBlocks,
+      ...orphanedResultBlocks,
+      ...toolResultImages,
+    ];
     if (userContent.length > 0) {
       result.push(this.toResponsesUserMessage(userContent));
     }

package/src/runtime/routes/secret-routes.ts

@@ -756,8 +756,14 @@ export const ROUTES: RouteDefinition[] = [
     }),
     responseBody: z.object({
       success: z.boolean(),
-      type: z.string(),
-      name: z.string(),
+      type: z.string().optional(),
+      name: z.string().optional(),
+      error: z
+        .string()
+        .optional()
+        .describe(
+          "Why the secret was not stored (e.g. provider-side API key validation failed). Present only when success is false.",
+        ),
     }),
     handler: handleAddSecret,
   },