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 (account-level)

Design note: store is deliberately not set

The plugin does not set store=true on requests. Whether metadata persists and surfaces in the OpenAI Usage Dashboard is governed entirely by the account-level Stored Completions setting, which the terminus owner controls. Setting store from inside the plugin would change persistence behavior as a side effect of a telemetry opt-in, breaking the existing argument layout and storage semantics — same responsibility split as Bedrock (CloudWatch) and Vertex (billing export). The credential's help text in provider/openai.yaml documents this expectation in both English and Simplified Chinese.

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 and Stored Completions enabled on the OpenAI account, requests carry dify_app_id and dify_source, enabling per-app filtering.

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.2)
• 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/ (14 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).
• 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.

[gemini-code-assist]

Since normalize_metadata_value is designed to coerce non-string inputs (such as integers) via str(), the type hint for s should be Any instead of str to avoid static analysis or type-checking warnings.

Suggested change

	from typing import Optional
	_MAX_VALUE_LENGTH = 512
	def normalize_metadata_value(s: str) -> str:
	from typing import Any, Optional
	_MAX_VALUE_LENGTH = 512
	def normalize_metadata_value(s: Any) -> str:

[gemini-code-assist]

The app_id parameter in build_dify_metadata can be of any type (since it is passed to normalize_metadata_value which handles non-string coercion). We should update its type hint to Any as well.

Suggested change

	def build_dify_metadata(app_id: Optional[str]) -> Optional[dict[str, str]]:
	def build_dify_metadata(app_id: Any) -> Optional[dict[str, str]]:

[gemini-code-assist]

There is an inconsistency between build_dify_metadata and normalize_metadata_value. The docstring and tests for normalize_metadata_value explicitly state that non-string falsy inputs like a numeric 0 should not be dropped. However, build_dify_metadata uses if not app_id:, which will evaluate to True for 0 (or 0.0, False), causing it to return None and silently drop the metadata.

To fix this and align with the design intent, we should explicitly check for None and empty string "".

Suggested change

	if not app_id:
	return None
	if app_id is None or app_id == "":
	return None

[gemini-code-assist]

If target already contains a "metadata" key (e.g., set by other parts of the application or user-defined parameters), assigning target["metadata"] = metadata will completely overwrite it, leading to data loss. We should merge the new metadata into the existing dictionary if it already exists.

Suggested change

	if metadata is not None:
	target["metadata"] = metadata
	if metadata is not None:
	if "metadata" in target and isinstance(target["metadata"], dict):
	target["metadata"].update(metadata)
	else:
	target["metadata"] = metadata

[gemini-code-assist]

To ensure that existing metadata is not overwritten and is instead merged correctly, we should add a unit test covering this scenario.

def test_apply_silent_on_session_lookup_failure():
    # Without a Dify session context, get_current_session raises; the
    # helper must swallow that and leave target unchanged.
    target: dict = {}
    apply_dify_metadata_if_enabled(target, {"enable_request_metadata": "enabled"})
    assert "metadata" not in target


def test_apply_merges_with_existing_metadata(monkeypatch):
    # Mock get_current_session to return a session with an app_id
    class MockSession:
        app_id = "test_app"

    monkeypatch.setattr("dify_plugin.get_current_session", lambda: MockSession())

    target = {"metadata": {"existing_key": "existing_value"}}
    apply_dify_metadata_if_enabled(target, {"enable_request_metadata": "enabled"})
    assert target["metadata"] == {
        "existing_key": "existing_value",
        "dify_app_id": "test_app",
        "dify_source": "dify",
    }