openapi: keep the file-emit hint on the fast serve path

The content-addressed serve path rebuilds a tool def from the persisted
binding instead of re-parsing the spec. The re-parse path (kept as the
fallback) appends the ToolFile emit contract to a file-returning tool's
description at the projection step; the fast path bypassed that step and
served the bare description, so a file-returning operation lost the
contract whenever it was served from the binding (the common case once a
spec is persisted).

Apply the hint at the same projection step in the fast path, sourced from
the binding's response fileHint (already inspected for the output schema),
so a file tool carries the contract identically whether served fast or via
the fallback. No persist-path or schema change: existing rows pick it up on
the next list. Covered by the tool-descriptions e2e scenario.

Author: RhysSullivan

packages/plugins/openapi/src/sdk/backing.ts

@@ -290,26 +290,36 @@ const decodeDefsJson = Schema.decodeUnknownOption(Schema.fromJsonString(DefsJson
 
 /** Rebuild a tool def from a stored operation binding, no spec parse. Mirrors
  *  `openApiToolDefsFromCompiled` but sources its schemas from the persisted
- *  binding (params/body/response carry `$ref`s into the shared defs blob). */
+ *  binding (params/body/response carry `$ref`s into the shared defs blob). The
+ *  file-emit hint is applied here, at the same ToolDef projection step the
+ *  re-parse path applies it, so a file-returning op carries the contract
+ *  whether it is served fast (from the binding) or via the spec fallback. */
 const toolDefFromStoredOperation = (op: StoredOperation): ToolDef => {
   const binding = op.binding;
+  const returnsFile = Option.match(binding.responseBody, {
+    onNone: () => false,
+    onSome: (responseBody) => Option.isSome(responseBody.fileHint),
+  });
   return {
     name: ToolName.make(op.toolName),
-    description: op.description ?? `${binding.method.toUpperCase()} ${binding.pathTemplate}`,
+    description: withFileEmitHint(
+      op.description ?? `${binding.method.toUpperCase()} ${binding.pathTemplate}`,
+      returnsFile,
+    ),
     inputSchema: normalizeOpenApiRefs(
       buildInputSchema(
         binding.parameters,
         Option.getOrUndefined(binding.requestBody),
         binding.servers ?? [],
       ),
     ),
-    outputSchema: Option.match(binding.responseBody, {
-      onNone: () => undefined,
-      onSome: (responseBody) =>
-        Option.isSome(responseBody.fileHint)
-          ? ToolFileJsonSchema
-          : normalizeOpenApiRefs(Option.getOrUndefined(responseBody.schema)),
-    }),
+    outputSchema: returnsFile
+      ? ToolFileJsonSchema
+      : Option.match(binding.responseBody, {
+          onNone: () => undefined,
+          onSome: (responseBody) =>
+            normalizeOpenApiRefs(Option.getOrUndefined(responseBody.schema)),
+        }),
     annotations: annotationsForOperation(binding.method, binding.pathTemplate),
   };
 };