feat(openai): attach Dify app_id as request metadata (opt-in)

[mas-sakai]

Summary

Adds opt-in support for attaching the Dify app_id as OpenAI request metadata, so usage on the OpenAI Usage Dashboard can be filtered per Dify app.

When the new enable_request_metadata credential is set to enabled, the plugin reads app_id from the current Dify session (via get_current_session() from the SDK) and attaches {dify_app_id, dify_source} as the metadata field on both chat.completions.create and responses.create. The default is disabled, so behavior is unchanged unless the operator opts in.

This is the OpenAI counterpart of the same feature already shipped for Vertex AI (#3168) and Bedrock (#3201). The responsibility split mirrors those plugins:

Plugin	What the plugin attaches	What the operator must enable
Vertex AI	labels on generateContent	BigQuery billing export
Bedrock	requestMetadata on Converse	CloudWatch invocation logging
OpenAI	metadata on Chat / Responses	Stored Completions on the OpenAI account — the plugin enables store=true automatically

Design note: store is set to true alongside metadata

E2E verification against a live OpenAI account showed the API rejects metadata when store is false:

BadRequestError: The 'metadata' parameter is only allowed when 'store' is enabled.

Enabling the metadata feature therefore inherently requires store=true. The plugin makes this explicit: apply_dify_metadata_if_enabled sets store=true alongside the metadata (a non-destructive merge that respects an explicit store value already on the request). This means requests and responses are persisted to Stored Completions on the OpenAI account when the operator opts in. The credential's help text in provider/openai.yaml documents this storage behavior in both English and Simplified Chinese, and links to the OpenAI store reference.

Bedrock (#3201) and Vertex AI (#3168) do not have this constraint, so their plugins remain unchanged.

Related:

• Pass app_id to model plugins for provider-side cost attribution dify#35772
• Pass session (with app_id) to model plugin instances (parity with tool plugins) dify-plugin-sdks#311
• feat: expose session context to model plugins via get_current_session() dify-plugin-sdks#313 (SDK branch this plugin currently pins)
• feat(vertex_ai): support GenerateContentConfig labels for Dify app_id propagation #3168 (Vertex AI counterpart)
• feat(bedrock): attach Dify app_id as Converse requestMetadata (opt-in) #3201 (Bedrock counterpart)

Note

Draft / dependency. pyproject.toml temporarily pins dify_plugin to the fork branch ryuta-kobayashi-ug/dify-plugin-sdks@feat/pass-session-to-model-plugins because it carries the get_current_session() API used here (langgenius/dify-plugin-sdks#313). The pin will revert to a versioned dify_plugin spec once that SDK change merges and a release ships.

Change Type

• Documentation / non-plugin change
• Non-LLM plugin (tools, extensions, datasource, etc.)
• LLM plugin

Screenshots / Videos

Before	After
Usage Dashboard rows are anonymous; per-app filtering is impossible.	With opt-in enabled, the plugin sets store=true and attaches dify_app_id and dify_source, so requests are recorded to Stored Completions and can be filtered per app.

End-to-end screenshots will be added once the dependent SDK change (#313) ships and a Dify deployment can be exercised against a live OpenAI account with Stored Completions enabled.

LLM Plugin Checklist

Areas affected by this change

• Message flow (system messages, user ↔ assistant turn-taking)
• Tool interaction flow (multi-round usage, Agent App and Agent Node)
• Multimodal input (images, PDFs, audio, video, etc.)
• Multimodal output (images, audio, video, etc.)
• Structured output (JSON, XML, etc.)
• Token consumption metrics
• Other LLM functionality (reasoning, grounding, prompt caching, etc.) — request metadata for billing/observability
• New models / model parameter fixes

The change is additive and behind a credential that defaults to disabled. No existing message flow, tool, multimodal, structured-output, or token-accounting code path is altered. Only _chat_generate and _build_responses_api_params gain a one-line opt-in hook that mutates the request kwargs immediately before the OpenAI client call.

Version

• Bumped top-level version in manifest.yaml (0.4.1 → 0.4.3)
• dify_plugin declared in pyproject.toml and locked in uv.lock (currently pinned to the SDK branch carrying fix getnumtoken retrun list[int] #313 — see Draft note above)

Testing

• Unit tests — uv run pytest tests/ (22 passed): covers normalization (UUID passthrough, punctuation, mixed case, non-ASCII, 512-char truncation, empty string, non-string coercion), build_dify_metadata (None / empty / source marker / UUID passthrough / length normalization), and apply_dify_metadata_if_enabled (no-op on missing or disabled credential, silent on session-lookup failure, non-destructive metadata merge, and the new store=true behavior: sets store=true on opt-in, preserves an explicit caller-supplied store, and never touches store when disabled).
• Local deployment — Dify version: pending (blocked on SDK fix getnumtoken retrun list[int] #313 release; will retest after the pin is reverted)
• SaaS (cloud.dify.ai)

[gemini-code-assist]

Code Review

This pull request introduces an optional feature to attach Dify metadata (such as dify_app_id and dify_source) to OpenAI Chat Completions and Responses API requests, enabling per-app filtering in the OpenAI Usage Dashboard. The changes include a new helper module _metadata.py for metadata normalization and injection, integration within the LLM generation workflows, updated provider credential schemas, and a suite of unit tests. The review feedback highlights opportunities to improve type safety by using Any for coerced inputs, fix a logical inconsistency where falsy non-string values (like 0) are dropped, prevent overwriting existing metadata by merging dictionaries, and add a corresponding unit test.