docs(functions): clarify where invoke metadata reaches code functions (#2731)

> 🤖 **This text was AI-generated.**

The `invoke()` docstring said top-level `metadata` is passed to the
function as its `metadata` argument. That is true for prompts
(`{{metadata}}`), but not for code functions. The runtime sends
top-level `metadata` as hook data, and a Python handler's `metadata`
argument is only filled from `input`:

```typescript
await invoke({ ..., input: { input: "x" }, metadata: { marker: "top" } });
```

```python
def handler(input=None, metadata=None, hooks=None):
    metadata        # None
    hooks.metadata  # {"marker": "top"}
```

A customer's scorer therefore saw an empty `metadata` argument on every
row.

The docstring now explains that code functions receive top-level
metadata through the hooks (the second handler argument in TypeScript,
`hooks.metadata` in Python), and shows how to fill the `metadata`
argument by nesting it in `input`:

```typescript
await invoke({ ..., input: { input: "x", metadata: { marker: "nested" } } });
```

The runtime behaviour is unchanged. The same wrong sentence also appears
in the generated `js/src/generated_plain_types.ts`. It comes from the
backend typespec (`typespecs/src/functions.ts`) and needs fixing there,
then regenerating.

Mirrors braintrustdata/braintrust-sdk-python#1073.

Refs: SDK-791

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: AbhiPrasad

.changeset/clarify-invoke-metadata-docs.md

@@ -0,0 +1,5 @@
+---
+"braintrust": patch
+---
+
+docs(functions): clarify where invoke metadata reaches code functions

js/src/functions/invoke.ts

@@ -78,8 +78,10 @@ export interface InvokeFunctionArgs<
 
   /**
    * Additional metadata to add to the span. This will be logged as the `metadata` field in the span.
-   * It will also be available as the {{metadata}} field in the prompt and as the `metadata` argument
-   * to the function.
+   * It will also be available as the {{metadata}} field in the prompt. For code functions, it is passed
+   * through the hooks (the handler's second argument in TypeScript, `hooks.metadata` in Python), not
+   * as the handler's `metadata` argument, which is read from `input`. To fill the handler's `metadata`
+   * argument, nest it in `input`, e.g. `invoke({ ..., input: { input: ..., metadata: { ... } } })`.
    */
   metadata?: Record<string, unknown>;
   /**