Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.
Python agentagentic-aiagentic-frameworkagentic-workflowaiautomationclaudedeepseekgenaigptllmlow-codemcpnextjsno-codeopenaipythonskillsworkflow
refactor(agent): replace Agenton with native Pydantic AI modules (#43833)
盐粒 Yanlicc14bb83e0f5
diff --git a/api/clients/agent_backend/__init__.py b/api/clients/agent_backend/__init__.pyindex dbdc93cfbad..f4936663b9b 100644--- a/api/clients/agent_backend/__init__.py+++ b/api/clients/agent_backend/__init__.py@@ -17,7 +17,6 @@ from clients.agent_backend.errors import ()from clients.agent_backend.event_adapter import (AgentBackendAgentMessageDeltaInternalEvent,- AgentBackendDeferredToolCallInternalEvent,AgentBackendInternalEvent,AgentBackendInternalEventType,AgentBackendRunCancelledInternalEvent,@@ -57,7 +56,6 @@ __all__ = ["WORKFLOW_USER_PROMPT_LAYER_ID","AgentBackendAgentAppRunInput","AgentBackendAgentMessageDeltaInternalEvent",- "AgentBackendDeferredToolCallInternalEvent","AgentBackendError","AgentBackendHTTPError","AgentBackendInternalEvent",diff --git a/api/clients/agent_backend/event_adapter.py b/api/clients/agent_backend/event_adapter.pyindex a8850ada4ec..b692ba437df 100644--- a/api/clients/agent_backend/event_adapter.py+++ b/api/clients/agent_backend/event_adapter.py@@ -2,9 +2,7 @@The adapter does not define a new cross-service event contract. It consumes``dify_agent.protocol.RunEvent`` and produces small API-internal models that the-workflow Agent Node maps to Graphon/AppQueue events. Deferred external tool calls-remain Dify Agent ``run_succeeded`` payloads on the wire; API code turns them-into an internal event so workflow pause/session handling stays local to API.+workflow Agent Node maps to Graphon/AppQueue events.Agent-message deltas are exposed as annotations on ``PydanticAIStreamRunEvent``so API code does not have to parse Pydantic AI stream-event internals topreserve streaming. The terminal answer remains the ``run_succeeded`` output.@@ -15,9 +13,7 @@ from __future__ import annotationsfrom enum import StrEnumfrom typing import Annotated, Literal, cast-from agenton.compositor import CompositorSessionSnapshotfrom dify_agent.protocol import (- DeferredToolCallPayload,PydanticAIStreamRunEvent,RunCancelledEvent,RunEvent,@@ -26,6 +22,7 @@ from dify_agent.protocol import (RunStartedEvent,RunSucceededEvent,)+from dify_agent.protocol.snapshot import SessionSnapshotfrom pydantic import BaseModel, ConfigDict, Field, JsonValue, TypeAdapter_EVENT_DATA_ADAPTER = TypeAdapter(object)@@ -37,7 +34,6 @@ class AgentBackendInternalEventType(StrEnum):RUN_STARTED = "run_started"STREAM_EVENT = "stream_event"AGENT_MESSAGE_DELTA = "agent_message_delta"- DEFERRED_TOOL_CALL = "deferred_tool_call"RUN_SUCCEEDED = "run_succeeded"RUN_FAILED = "run_failed"RUN_CANCELLED = "run_cancelled"@@ -78,17 +74,7 @@ class AgentBackendRunSucceededInternalEvent(AgentBackendInternalEventBase):type: Literal[AgentBackendInternalEventType.RUN_SUCCEEDED] = AgentBackendInternalEventType.RUN_SUCCEEDEDoutput: JsonValue- session_snapshot: CompositorSessionSnapshot- usage: dict[str, JsonValue] | None = None---class AgentBackendDeferredToolCallInternalEvent(AgentBackendInternalEventBase):- """API-internal representation of a Dify Agent deferred external tool call."""-- type: Literal[AgentBackendInternalEventType.DEFERRED_TOOL_CALL] = AgentBackendInternalEventType.DEFERRED_TOOL_CALL- deferred_tool_call: DeferredToolCallPayload- message: str | None = None- session_snapshot: CompositorSessionSnapshot+ session_snapshot: SessionSnapshotusage: dict[str, JsonValue] | None = None@@ -99,7 +85,7 @@ class AgentBackendRunFailedInternalEvent(AgentBackendInternalEventBase):error: strerror_type: RunFailureType | None = Nonereason: str | None = None- session_snapshot: CompositorSessionSnapshot | None = None+ session_snapshot: SessionSnapshot | None = Noneusage: dict[str, JsonValue] | None = None@@ -109,7 +95,7 @@ class AgentBackendRunCancelledInternalEvent(AgentBackendInternalEventBase):type: Literal[AgentBackendInternalEventType.RUN_CANCELLED] = AgentBackendInternalEventType.RUN_CANCELLEDreason: str | None = Nonemessage: str | None = None- session_snapshot: CompositorSessionSnapshot | None = None+ session_snapshot: SessionSnapshot | None = Noneusage: dict[str, JsonValue] | None = None@@ -117,7 +103,6 @@ type AgentBackendInternalEvent = Annotated[AgentBackendRunStartedInternalEvent| AgentBackendStreamInternalEvent| AgentBackendAgentMessageDeltaInternalEvent- | AgentBackendDeferredToolCallInternalEvent| AgentBackendRunSucceededInternalEvent| AgentBackendRunFailedInternalEvent| AgentBackendRunCancelledInternalEvent,@@ -158,19 +143,6 @@ class AgentBackendRunEventAdapter:)]case RunSucceededEvent():- if "deferred_tool_call" in event.data.model_fields_set:- if event.data.deferred_tool_call is None:- raise TypeError("run_succeeded deferred_tool_call branch is missing payload")- return [- AgentBackendDeferredToolCallInternalEvent(- run_id=event.run_id,- source_event_id=event.id,- deferred_tool_call=event.data.deferred_tool_call,- message=_deferred_tool_call_message(event.data.deferred_tool_call),- session_snapshot=event.data.session_snapshot,- usage=_agent_run_usage(event.data.usage),- )- ]return [AgentBackendRunSucceededInternalEvent(run_id=event.run_id,@@ -206,21 +178,6 @@ class AgentBackendRunEventAdapter:raise TypeError(f"unsupported agent backend run event: {type(event).__name__}")-def _deferred_tool_call_message(payload: DeferredToolCallPayload) -> str:- """Return a concise workflow pause message from deferred-tool arguments."""- args = payload.args- if isinstance(args, dict):- question = args.get("question")- if isinstance(question, str) and question.strip():- return question-- title = args.get("title")- if isinstance(title, str) and title.strip():- return title-- return f"Agent backend requested external input via deferred tool '{payload.tool_name}'."--def _agent_run_usage(usage: object | None) -> dict[str, JsonValue] | None:"""Return JSON-safe usage metadata from optional Agent backend usage."""if usage is None:diff --git a/api/clients/agent_backend/fake_client.py b/api/clients/agent_backend/fake_client.pyindex c016f2ce6bf..1fe7b3660c9 100644--- a/api/clients/agent_backend/fake_client.py+++ b/api/clients/agent_backend/fake_client.py@@ -11,13 +11,11 @@ from collections.abc import Callable, Iteratorfrom datetime import UTC, datetimefrom enum import StrEnum-from agenton.compositor import CompositorSessionSnapshotfrom dify_agent.protocol import (CancelRunRequest,CancelRunResponse,CreateRunRequest,CreateRunResponse,- DeferredToolCallPayload,RunCancelledEvent,RunCancelledEventData,RunEvent,@@ -28,6 +26,7 @@ from dify_agent.protocol import (RunSucceededEvent,RunSucceededEventData,)+from dify_agent.protocol.snapshot import SessionSnapshot_FIXED_TIME = datetime(2026, 1, 1, tzinfo=UTC)@@ -41,7 +40,6 @@ class FakeAgentBackendScenario(StrEnum):SUCCESS = "success"FAILED = "failed"- PAUSED = "paused"class FakeAgentBackendRunClient:@@ -89,7 +87,7 @@ class FakeAgentBackendRunClient:data=RunCancelledEventData(reason=request.reason,message=request.message,- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(),),)@@ -127,13 +125,6 @@ class FakeAgentBackendRunClient:updated_at=_FIXED_TIME,error="fake failure",)- case FakeAgentBackendScenario.PAUSED:- return RunStatusResponse(- run_id=run_id,- status="succeeded",- created_at=_FIXED_TIME,- updated_at=_FIXED_TIME,- )def _events(self, run_id: str) -> tuple[RunEvent, ...]:match self.scenario:@@ -146,7 +137,7 @@ class FakeAgentBackendRunClient:created_at=_FIXED_TIME,data=RunSucceededEventData(output={"text": "hello agent"},- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(),),),)@@ -160,25 +151,7 @@ class FakeAgentBackendRunClient:data=RunFailedEventData(error="fake failure",reason="unit_test",- session_snapshot=CompositorSessionSnapshot(layers=[]),- ),- ),- )- case FakeAgentBackendScenario.PAUSED:- return (- RunStartedEvent(id="1-0", run_id=run_id, created_at=_FIXED_TIME),- RunSucceededEvent(- id="2-0",- run_id=run_id,- created_at=_FIXED_TIME,- data=RunSucceededEventData(- deferred_tool_call=DeferredToolCallPayload(- tool_call_id="fake-ask-human-1",- tool_name="ask_human",- args={"question": "Agent requested human input."},- metadata={"layer_type": "dify.ask_human", "schema_version": 1},- ),- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(),),),)diff --git a/api/clients/agent_backend/request_builder.py b/api/clients/agent_backend/request_builder.pyindex d7a3b8ddc38..47b007cd99c 100644--- a/api/clients/agent_backend/request_builder.py+++ b/api/clients/agent_backend/request_builder.py@@ -3,10 +3,9 @@This module is intentionally an adapter, not a wire DTO package. The emittedobject is always ``dify_agent.protocol.CreateRunRequest`` so the Agent backendprotocol has a single owner. API-only context such as Agent Soul vs workflow job-prompt is preserved in layer names and metadata until the dedicated product-schemas land in later phases. Dify-owned execution identifiers are emitted as an-explicit ``dify.execution_context`` layer so the run request stays fully-composition-driven.+prompt is preserved in registered module names. Execution identifiers live in+execution_context Config; model, tool and resource references are explicit Config+fields. The wire request contains current Config and optional state-only snapshot."""from __future__ import annotations@@ -15,29 +14,21 @@ import refrom collections.abc import Mappingfrom typing import ClassVar, Literal-from agenton.compositor import CompositorSessionSnapshot-from agenton.layers import ExitIntent-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig-from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID-from dify_agent.layers.ask_human import DIFY_ASK_HUMAN_LAYER_TYPE_ID, DifyAskHumanLayerConfig-from dify_agent.layers.config import DIFY_CONFIG_LAYER_TYPE_ID, DifyConfigLayerConfig-from dify_agent.layers.dify_core_tools import DIFY_CORE_TOOLS_LAYER_TYPE_ID, DifyCoreToolsLayerConfig+from dify_agent.layers.config import DifyConfigLayerConfig+from dify_agent.layers.dify_core_tools import DifyCoreToolsLayerConfigfrom dify_agent.layers.dify_plugin import (- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,- DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,DifyPluginLLMLayerConfig,DifyPluginToolsLayerConfig,)from dify_agent.layers.execution_context import (- DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,DifyExecutionContextLayerConfig,)-from dify_agent.layers.knowledge import DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID, DifyKnowledgeBaseLayerConfig-from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig-from dify_agent.layers.runtime import DIFY_RUNTIME_LAYER_TYPE_ID, DifyRuntimeLayerConfig-from dify_agent.layers.shell import DIFY_SHELL_LAYER_TYPE_ID, DifyShellLayerConfig+from dify_agent.layers.knowledge import DifyKnowledgeBaseLayerConfig+from dify_agent.layers.output import DifyOutputLayerConfig+from dify_agent.layers.prompt import Config as PromptConfig+from dify_agent.layers.runtime import DifyRuntimeLayerConfig+from dify_agent.layers.shell import DifyShellLayerConfigfrom dify_agent.layers.user_prompt import (- DIFY_USER_PROMPT_LAYER_TYPE_ID,DifyUserPromptFileConfig,DifyUserPromptLayerConfig,)@@ -46,11 +37,10 @@ from dify_agent.protocol import (DIFY_AGENT_MODEL_LAYER_ID,DIFY_AGENT_OUTPUT_LAYER_ID,CreateRunRequest,- DeferredToolResultsPayload,- LayerExitSignals,RunComposition,RunLayerSpec,)+from dify_agent.protocol.snapshot import SessionSnapshotfrom pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validatorAGENT_SOUL_PROMPT_LAYER_ID = "agent_soul_prompt"@@ -63,22 +53,10 @@ DIFY_CONFIG_LAYER_ID = "config"DIFY_PLUGIN_TOOLS_LAYER_ID = "tools"DIFY_CORE_TOOLS_LAYER_ID = "core_tools"DIFY_KNOWLEDGE_BASE_LAYER_ID = "knowledge"-DIFY_ASK_HUMAN_LAYER_ID = "ask_human"DIFY_SHELL_LAYER_ID = "shell"type AgentConfigVersionKind = Literal["snapshot", "draft", "build_draft"]-def _shell_layer_deps() -> dict[str, str]:- return {- "execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID,- "runtime": DIFY_RUNTIME_LAYER_ID,- }---def _config_layer_deps() -> dict[str, str]:- return {"shell": DIFY_SHELL_LAYER_ID}--def _markdown_backtick_fence(text: str) -> str:"""Choose a fence that will not terminate inside the prompt body."""longest_backtick_run = max((len(match.group(0)) for match in re.finditer(r"`+", text)), default=0)@@ -213,18 +191,9 @@ class AgentBackendWorkflowNodeRunInput(BaseModel):core_tools: DifyCoreToolsLayerConfig | None = Noneknowledge: DifyKnowledgeBaseLayerConfig | None = Noneconfig_layer_config: DifyConfigLayerConfig | None = None- # Human-in-the-loop ask_human deferred tool (dify.ask_human). Present only when- # the Agent Soul configures human involvement; a deferred call ends the run and- # the workflow pauses via the existing HITL form mechanism (ENG-635).- ask_human_config: DifyAskHumanLayerConfig | None = None- # Inject the sandboxed shell graph. Requires a deployment-selected runtime- # backend plus the product-resolved persistent Binding.include_shell: bool = Falseshell_config: DifyShellLayerConfig | None = None- session_snapshot: CompositorSessionSnapshot | None = None- # Human tool results fed back into a continuation run after a HITL submission- # (ENG-638). Keyed by the original deferred tool_call_id.- deferred_tool_results: DeferredToolResultsPayload | None = None+ session_snapshot: SessionSnapshot | None = Noneinclude_history: bool = Truemetadata: dict[str, JsonValue] = Field(default_factory=dict)@@ -260,17 +229,9 @@ class AgentBackendAgentAppRunInput(BaseModel):core_tools: DifyCoreToolsLayerConfig | None = Noneknowledge: DifyKnowledgeBaseLayerConfig | None = Noneconfig_layer_config: DifyConfigLayerConfig | None = None- # Human-in-the-loop ask_human deferred tool (dify.ask_human). Present only when- # the Agent Soul configures human involvement (ENG-635).- ask_human_config: DifyAskHumanLayerConfig | None = None- # Inject the sandboxed shell graph. Requires a deployment-selected runtime- # backend plus the product-resolved persistent Binding.include_shell: bool = Falseshell_config: DifyShellLayerConfig | None = None- session_snapshot: CompositorSessionSnapshot | None = None- # Human tool results fed back into a continuation run after a HITL submission- # (ENG-638). Keyed by the original deferred tool_call_id.- deferred_tool_results: DeferredToolResultsPayload | None = None+ session_snapshot: SessionSnapshot | None = Noneinclude_history: bool = Truemetadata: dict[str, JsonValue] = Field(default_factory=dict)@@ -293,7 +254,7 @@ class AgentBackendRunRequestBuilder:Layer graph: optional Agent Soul system prompt → user prompt →execution context → optional shell / config / history(multi-turn) → LLM → optional plugin-direct tools / core-routed tools /- knowledge search / ask_human / structured output. Mirrors the+ knowledge search / structured output. Mirrors theworkflow-node layer ordering minus the workflow-job / previous-nodeprompt."""@@ -306,9 +267,7 @@ class AgentBackendRunRequestBuilder:layers.append(RunLayerSpec(name=AGENT_SOUL_PROMPT_LAYER_ID,- type=PLAIN_PROMPT_LAYER_TYPE_ID,- metadata={**run_input.metadata, "origin": "agent_soul"},- config=PromptLayerConfig(prefix=agent_soul_prompt),+ config=(PromptConfig(prefix=agent_soul_prompt)).model_dump(mode="json"),))@@ -316,15 +275,13 @@ class AgentBackendRunRequestBuilder:[RunLayerSpec(name=AGENT_APP_USER_PROMPT_LAYER_ID,- type=DIFY_USER_PROMPT_LAYER_TYPE_ID,- metadata={**run_input.metadata, "origin": "agent_app_user_prompt"},- config=DifyUserPromptLayerConfig(text=run_input.user_prompt, files=run_input.user_files),+ config=(+ DifyUserPromptLayerConfig(text=run_input.user_prompt, files=run_input.user_files)+ ).model_dump(mode="json"),),RunLayerSpec(name=DIFY_EXECUTION_CONTEXT_LAYER_ID,- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- metadata=run_input.metadata,- config=run_input.execution_context,+ config=(run_input.execution_context).model_dump(mode="json"),),])@@ -334,9 +291,9 @@ class AgentBackendRunRequestBuilder:layers.append(RunLayerSpec(name=DIFY_RUNTIME_LAYER_ID,- type=DIFY_RUNTIME_LAYER_TYPE_ID,- metadata=run_input.metadata,- config=DifyRuntimeLayerConfig(backend_binding_ref=run_input.backend_binding_ref),+ config=(DifyRuntimeLayerConfig(backend_binding_ref=run_input.backend_binding_ref)).model_dump(+ mode="json"+ ),))# Sandboxed bash workspace (dify.shell). It enters before config so@@ -344,10 +301,7 @@ class AgentBackendRunRequestBuilder:layers.append(RunLayerSpec(name=DIFY_SHELL_LAYER_ID,- type=DIFY_SHELL_LAYER_TYPE_ID,- deps=_shell_layer_deps(),- metadata=run_input.metadata,- config=run_input.shell_config or DifyShellLayerConfig(),+ config=(run_input.shell_config or DifyShellLayerConfig()).model_dump(mode="json"),))@@ -355,10 +309,7 @@ class AgentBackendRunRequestBuilder:layers.append(RunLayerSpec(name=DIFY_CONFIG_LAYER_ID,- type=DIFY_CONFIG_LAYER_TYPE_ID,- deps=_config_layer_deps(),- metadata=run_input.metadata,- config=run_input.config_layer_config,+ config=(run_input.config_layer_config).model_dump(mode="json"),))@@ -366,38 +317,31 @@ class AgentBackendRunRequestBuilder:layers.append(RunLayerSpec(name=DIFY_AGENT_HISTORY_LAYER_ID,- type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,- metadata={**run_input.metadata, "origin": "agent_session_history"},))layers.append(RunLayerSpec(name=DIFY_AGENT_MODEL_LAYER_ID,- type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,- deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},- metadata=run_input.metadata,- config=DifyPluginLLMLayerConfig(- plugin_id=run_input.model.plugin_id,- model_provider=run_input.model.model_provider,- model=run_input.model.model,- model_settings=_agent_model_settings(run_input.model.model_settings),- context_window_tokens=run_input.model.context_window_tokens,- ),+ config=(+ DifyPluginLLMLayerConfig(+ plugin_id=run_input.model.plugin_id,+ model_provider=run_input.model.model_provider,+ model=run_input.model.model,+ model_settings=_agent_model_settings(run_input.model.model_settings),+ context_window_tokens=run_input.model.context_window_tokens,+ )+ ).model_dump(mode="json"),))if run_input.tools is not None and run_input.tools.tools:- plugin_tool_deps = {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}- if include_shell:- plugin_tool_deps["shell"] = DIFY_SHELL_LAYER_IDlayers.append(RunLayerSpec(name=DIFY_PLUGIN_TOOLS_LAYER_ID,- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,- deps=plugin_tool_deps,- metadata=run_input.metadata,- config=run_input.tools,+ config=(+ run_input.tools.model_copy(update={"shell": DIFY_SHELL_LAYER_ID if include_shell else None})+ ).model_dump(mode="json"),))@@ -405,10 +349,7 @@ class AgentBackendRunRequestBuilder:layers.append(RunLayerSpec(name=DIFY_CORE_TOOLS_LAYER_ID,- type=DIFY_CORE_TOOLS_LAYER_TYPE_ID,- deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},- metadata=run_input.metadata,- config=run_input.core_tools,+ config=(run_input.core_tools).model_dump(mode="json"),))@@ -416,23 +357,7 @@ class AgentBackendRunRequestBuilder:layers.append(RunLayerSpec(name=DIFY_KNOWLEDGE_BASE_LAYER_ID,- type=DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID,- deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},- metadata=run_input.metadata,- config=run_input.knowledge,- )- )-- if run_input.ask_human_config is not None:- # Human-in-the-loop ask_human deferred tool (dify.ask_human). A call ends- # the run with a deferred_tool_call; the caller pauses (workflow HITL) and- # later resumes with deferred_tool_results. Needs the history layer above.- layers.append(- RunLayerSpec(- name=DIFY_ASK_HUMAN_LAYER_ID,- type=DIFY_ASK_HUMAN_LAYER_TYPE_ID,- metadata=run_input.metadata,- config=run_input.ask_human_config,+ config=(run_input.knowledge).model_dump(mode="json"),))@@ -440,13 +365,13 @@ class AgentBackendRunRequestBuilder:layers.append(RunLayerSpec(name=DIFY_AGENT_OUTPUT_LAYER_ID,- type=DIFY_OUTPUT_LAYER_TYPE_ID,- metadata=run_input.metadata,- config=DifyOutputLayerConfig(- json_schema=run_input.output.json_schema,- description=run_input.output.description,- strict=run_input.output.strict,- ),+ config=(+ DifyOutputLayerConfig(+ json_schema=run_input.output.json_schema,+ description=run_input.output.description,+ strict=run_input.output.strict,+ )+ ).model_dump(mode="json"),))@@ -455,8 +380,6 @@ class AgentBackendRunRequestBuilder:idempotency_key=run_input.idempotency_key,metadata=run_input.metadata,session_snapshot=run_input.session_snapshot,- deferred_tool_results=run_input.deferred_tool_results,- on_exit=LayerExitSignals(default=ExitIntent.SUSPEND),)def build_for_workflow_node(self, run_input: AgentBackendWorkflowNodeRunInput) -> CreateRunRequest:@@ -465,7 +388,7 @@ class AgentBackendRunRequestBuilder:Layer graph mirrors the workflow surface: prompts → execution context →optional shell / config / history → LLM → optionalplugin-direct tools / core-routed tools / knowledge search /- ask_human / structured output.+ structured output."""layers: list[RunLayerSpec] = []agent_soul_prompt = _agent_soul_prompt_for_layer(@@ -476,9 +399,7 @@ class AgentBackendRunRequestBuilder:layers.append(RunLayerSpec(name=AGENT_SOUL_PROMPT_LAYER_ID,- type=PLAIN_PROMPT_LAYER_TYPE_ID,- metadata={**run_input.metadata, "origin": "agent_soul"},- config=PromptLayerConfig(prefix=agent_soul_prompt),+ config=(PromptConfig(prefix=agent_soul_prompt)).model_dump(mode="json"),))@@ -486,21 +407,15 @@ class AgentBackendRunRequestBuilder:[RunLayerSpec(name=WORKFLOW_NODE_JOB_PROMPT_LAYER_ID,- type=PLAIN_PROMPT_LAYER_TYPE_ID,- metadata={**run_input.metadata, "origin": "workflow_node_job"},- config=PromptLayerConfig(user=run_input.workflow_node_job_prompt),+ config=(PromptConfig(user=run_input.workflow_node_job_prompt)).model_dump(mode="json"),),RunLayerSpec(name=WORKFLOW_USER_PROMPT_LAYER_ID,- type=PLAIN_PROMPT_LAYER_TYPE_ID,- metadata={**run_input.metadata, "origin": "workflow_user_prompt"},- config=PromptLayerConfig(user=run_input.user_prompt),+ config=(PromptConfig(user=run_input.user_prompt)).model_dump(mode="json"),),RunLayerSpec(name=DIFY_EXECUTION_CONTEXT_LAYER_ID,- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- metadata=run_input.metadata,- config=run_input.execution_context,+ config=(run_input.execution_context).model_dump(mode="json"),),])@@ -510,9 +425,9 @@ class AgentBackendRunRequestBuilder:layers.append(RunLayerSpec(name=DIFY_RUNTIME_LAYER_ID,- type=DIFY_RUNTIME_LAYER_TYPE_ID,- metadata=run_input.metadata,- config=DifyRuntimeLayerConfig(backend_binding_ref=run_input.backend_binding_ref),+ config=(DifyRuntimeLayerConfig(backend_binding_ref=run_input.backend_binding_ref)).model_dump(+ mode="json"+ ),))# Sandboxed bash workspace (dify.shell). It enters before config so@@ -520,10 +435,7 @@ class AgentBackendRunRequestBuilder:layers.append(RunLayerSpec(name=DIFY_SHELL_LAYER_ID,- type=DIFY_SHELL_LAYER_TYPE_ID,- deps=_shell_layer_deps(),- metadata=run_input.metadata,- config=run_input.shell_config or DifyShellLayerConfig(),+ config=(run_input.shell_config or DifyShellLayerConfig()).model_dump(mode="json"),))@@ -531,10 +443,7 @@ class AgentBackendRunRequestBuilder:layers.append(RunLayerSpec(name=DIFY_CONFIG_LAYER_ID,- type=DIFY_CONFIG_LAYER_TYPE_ID,- deps=_config_layer_deps(),- metadata=run_input.metadata,- config=run_input.config_layer_config,+ config=(run_input.config_layer_config).model_dump(mode="json"),))@@ -542,8 +451,6 @@ class AgentBackendRunRequestBuilder:layers.append(RunLayerSpec(name=DIFY_AGENT_HISTORY_LAYER_ID,- type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,- metadata={**run_input.metadata, "origin": "agent_session_history"},))@@ -551,31 +458,26 @@ class AgentBackendRunRequestBuilder:[RunLayerSpec(name=DIFY_AGENT_MODEL_LAYER_ID,- type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,- deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},- metadata=run_input.metadata,- config=DifyPluginLLMLayerConfig(- plugin_id=run_input.model.plugin_id,- model_provider=run_input.model.model_provider,- model=run_input.model.model,- model_settings=_agent_model_settings(run_input.model.model_settings),- context_window_tokens=run_input.model.context_window_tokens,- ),+ config=(+ DifyPluginLLMLayerConfig(+ plugin_id=run_input.model.plugin_id,+ model_provider=run_input.model.model_provider,+ model=run_input.model.model,+ model_settings=_agent_model_settings(run_input.model.model_settings),+ context_window_tokens=run_input.model.context_window_tokens,+ )+ ).model_dump(mode="json"),),])if run_input.tools is not None and run_input.tools.tools:- plugin_tool_deps = {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}- if include_shell:- plugin_tool_deps["shell"] = DIFY_SHELL_LAYER_IDlayers.append(RunLayerSpec(name=DIFY_PLUGIN_TOOLS_LAYER_ID,- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,- deps=plugin_tool_deps,- metadata=run_input.metadata,- config=run_input.tools,+ config=(+ run_input.tools.model_copy(update={"shell": DIFY_SHELL_LAYER_ID if include_shell else None})+ ).model_dump(mode="json"),))@@ -583,10 +485,7 @@ class AgentBackendRunRequestBuilder:layers.append(RunLayerSpec(name=DIFY_CORE_TOOLS_LAYER_ID,- type=DIFY_CORE_TOOLS_LAYER_TYPE_ID,- deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},- metadata=run_input.metadata,- config=run_input.core_tools,+ config=(run_input.core_tools).model_dump(mode="json"),))@@ -594,23 +493,7 @@ class AgentBackendRunRequestBuilder:layers.append(RunLayerSpec(name=DIFY_KNOWLEDGE_BASE_LAYER_ID,- type=DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID,- deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},- metadata=run_input.metadata,- config=run_input.knowledge,- )- )-- if run_input.ask_human_config is not None:- # Human-in-the-loop ask_human deferred tool (dify.ask_human). A call ends- # the run with a deferred_tool_call; the caller pauses (workflow HITL) and- # later resumes with deferred_tool_results. Needs the history layer above.- layers.append(- RunLayerSpec(- name=DIFY_ASK_HUMAN_LAYER_ID,- type=DIFY_ASK_HUMAN_LAYER_TYPE_ID,- metadata=run_input.metadata,- config=run_input.ask_human_config,+ config=(run_input.knowledge).model_dump(mode="json"),))@@ -618,13 +501,13 @@ class AgentBackendRunRequestBuilder:layers.append(RunLayerSpec(name=DIFY_AGENT_OUTPUT_LAYER_ID,- type=DIFY_OUTPUT_LAYER_TYPE_ID,- metadata=run_input.metadata,- config=DifyOutputLayerConfig(- json_schema=run_input.output.json_schema,- description=run_input.output.description,- strict=run_input.output.strict,- ),+ config=(+ DifyOutputLayerConfig(+ json_schema=run_input.output.json_schema,+ description=run_input.output.description,+ strict=run_input.output.strict,+ )+ ).model_dump(mode="json"),))@@ -633,8 +516,6 @@ class AgentBackendRunRequestBuilder:idempotency_key=run_input.idempotency_key,metadata=run_input.metadata,session_snapshot=run_input.session_snapshot,- deferred_tool_results=run_input.deferred_tool_results,- on_exit=LayerExitSignals(default=ExitIntent.SUSPEND),)diff --git a/api/controllers/console/app/completion.py b/api/controllers/console/app/completion.pyindex 591219459b0..c76e0ec435e 100644--- a/api/controllers/console/app/completion.py+++ b/api/controllers/console/app/completion.py@@ -17,7 +17,6 @@ from controllers.common.schema import register_response_schema_models, register_from controllers.console import console_nsfrom controllers.console.agent.app_helpers import resolve_agent_runtime_app_modelfrom controllers.console.app.error import (- AgentSessionConfigurationChangedError,AppUnavailableError,CompletionRequestError,ConversationCompletedError,@@ -622,10 +621,6 @@ def _raise_agent_stream_error_before_response(response):if isinstance(response, _ClosableStream):response.close()message = error_payload.get("message")- if error_payload.get("code") == AgentSessionConfigurationChangedError.error_code:- raise AgentSessionConfigurationChangedError(- str(message or AgentSessionConfigurationChangedError.description)- )raise CompletionRequestError(str(message or "Agent App chat failed."))return _prepend_stream_chunks(buffered, chunk, iterator)diff --git a/api/controllers/console/app/error.py b/api/controllers/console/app/error.pyindex c2808f149a5..391b25630b8 100644--- a/api/controllers/console/app/error.py+++ b/api/controllers/console/app/error.py@@ -1,7 +1,3 @@-from core.app.apps.agent_app.errors import (- AGENT_SESSION_CONFIGURATION_CHANGED_ERROR_CODE,- AGENT_SESSION_CONFIGURATION_CHANGED_MESSAGE,-)from libs.exception import BaseHTTPException@@ -53,12 +49,6 @@ class CompletionRequestError(BaseHTTPException):code = 400-class AgentSessionConfigurationChangedError(BaseHTTPException):- error_code = AGENT_SESSION_CONFIGURATION_CHANGED_ERROR_CODE- description = AGENT_SESSION_CONFIGURATION_CHANGED_MESSAGE- code = 409--class AppMoreLikeThisDisabledError(BaseHTTPException):error_code = "app_more_like_this_disabled"description = "The 'More like this' feature is disabled. Please refresh your page."diff --git a/api/core/app/apps/agent_app/app_generator.py b/api/core/app/apps/agent_app/app_generator.pyindex 294c18eb6a8..6cb48fa0497 100644--- a/api/core/app/apps/agent_app/app_generator.py+++ b/api/core/app/apps/agent_app/app_generator.py@@ -33,7 +33,6 @@ from core.app.apps.agent_app.app_runner import AgentAppRunnerfrom core.app.apps.agent_app.errors import (AgentAppGeneratorError,AgentAppNotPublishedError,- AgentSessionSnapshotIncompatibleError,)from core.app.apps.agent_app.generate_response_converter import AgentAppGenerateResponseConverterfrom core.app.apps.agent_app.runtime_request_builder import AgentAppRuntimeRequestBuilder@@ -63,7 +62,6 @@ from models.agent import (AgentConfigVersionKind,AgentScope,AgentStatus,- AgentWorkingResourceStatus,AgentWorkspaceBinding,AgentWorkspaceOwnerType,)@@ -216,172 +214,6 @@ class AgentAppGenerator(MessageBasedAppGenerator):)return AgentAppGenerateResponseConverter.convert(response=response, invoke_from=invoke_from)- def resume_after_form_submission(- self,- *,- app_model: App,- user: Account | EndUser,- conversation_id: str,- form_id: str,- invoke_from: InvokeFrom,- session: Session,- ) -> None:- """Resume an Agent App conversation after a submitted ask_human HITL form.-- ENG-635: triggered by a background task (not an HTTP request). Runs one- blocking turn with no user query; the runner threads the human's reply- into the agent run as deferred_tool_results and the assistant answer is- persisted to the conversation. Live streaming to a reconnected client is- out of scope here — the message is persisted and can be re-fetched.- """- conversation = ConversationService.get_conversation(- app_model=app_model, conversation_id=conversation_id, user=user, session=session- )- draft_type, draft_id = self._resolve_resume_draft(- app_model=app_model,- conversation=conversation,- user=user,- form_id=form_id,- session=session,- )- agent, agent_config_id, agent_config_version_kind, agent_soul = self._resolve_agent(- app_model,- invoke_from=invoke_from,- draft_type=draft_type,- draft_id=draft_id,- user=user,- session=session,- conversation=conversation,- )-- app_model_config = (- session.get(AppModelConfig, app_model.app_model_config_id) if app_model.app_model_config_id else None- )- annotation_reply = load_annotation_reply_config(session, app_model.id) if app_model_config else None-- app_config = AgentAppConfigManager.get_app_config(- app_model=app_model,- agent_soul=agent_soul,- annotation_reply=annotation_reply,- app_model_config=app_model_config,- conversation=conversation,- )- model_conf = ModelConfigConverter.convert(app_config)- trace_manager = TraceQueueManager(app_model.id, user.id if isinstance(user, Account) else user.session_id)-- # ENG-638: the agent backend requires the resume composition's layer- # names to match the suspended snapshot, which includes the per-turn- # user-prompt layer. So re-send the original user message (the paused- # turn's query); the continuation is driven by deferred_tool_results and- # the restored snapshot, not by re-processing this prompt. A blank prompt- # would drop the user-prompt layer and fail the snapshot match.- paused_message = session.scalar(- select(Message)- .where(Message.conversation_id == conversation.id, Message.query != "")- .order_by(Message.created_at.desc())- .limit(1)- )- resume_query = paused_message.query if paused_message and paused_message.query else "(resumed)"-- application_generate_entity = AgentAppGenerateEntity(- task_id=str(uuid.uuid4()),- app_config=app_config,- model_conf=model_conf,- conversation_id=conversation.id,- # A resume carries no new user inputs; the human's answer is the- # submitted form, threaded in by the runner as deferred_tool_results.- # The query re-sends the paused turn's message (see above).- inputs={},- query=resume_query,- files=[],- parent_message_id=UUID_NIL,- user_id=user.id,- stream=False,- invoke_from=invoke_from,- extras={"auto_generate_conversation_name": False},- call_depth=0,- trace_manager=trace_manager,- agent_id=agent.id,- agent_config_snapshot_id=agent_config_id,- agent_config_version_kind=agent_config_version_kind,- agent_llm_gateway_enabled=True,- )-- conversation, message = self._init_generate_records(- application_generate_entity,- conversation,- session=session,- )-- queue_manager = MessageBasedAppQueueManager(- task_id=application_generate_entity.task_id,- user_id=application_generate_entity.user_id,- invoke_from=application_generate_entity.invoke_from,- conversation_id=conversation.id,- app_mode=conversation.mode,- message_id=message.id,- )-- context = contextvars.copy_context()- worker_thread = threading.Thread(- target=self._generate_worker,- kwargs={- "flask_app": current_app._get_current_object(), # type: ignore- "context": context,- "application_generate_entity": application_generate_entity,- "queue_manager": queue_manager,- "conversation_id": conversation.id,- "message_id": message.id,- "user_from": UserFrom.ACCOUNT if isinstance(user, Account) else UserFrom.END_USER,- # Resume continues a paused agent run; skip input guards (see _generate_worker).- "is_resume": True,- },- )- worker_thread.start()-- # Blocking: drive the chat task pipeline to persist the assistant answer.- self._handle_response(- application_generate_entity=application_generate_entity,- queue_manager=queue_manager,- conversation=conversation,- message=message,- user=user,- stream=False,- )-- @staticmethod- def _resolve_resume_draft(- *,- app_model: App,- conversation: Any,- user: Account | EndUser,- form_id: str,- session: Session,- ) -> tuple[str | None, str | None]:- if conversation.invoke_from != InvokeFrom.DEBUGGER:- return None, None- if not isinstance(user, Account):- return AgentConfigDraftType.DRAFT.value, None-- build_draft = session.scalar(- select(AgentConfigDraft)- .join(- AgentWorkspaceBinding,- AgentWorkspaceBinding.id == AgentConfigDraft.agent_workspace_binding_id,- )- .where(- AgentConfigDraft.tenant_id == app_model.tenant_id,- AgentConfigDraft.draft_type == AgentConfigDraftType.DEBUG_BUILD,- AgentConfigDraft.account_id == user.id,- AgentWorkspaceBinding.tenant_id == app_model.tenant_id,- AgentWorkspaceBinding.status == AgentWorkingResourceStatus.ACTIVE,- AgentWorkspaceBinding.pending_form_id == form_id,- )- )- if build_draft is not None:- return AgentConfigDraftType.DEBUG_BUILD.value, build_draft.id- return AgentConfigDraftType.DRAFT.value, None-def _generate_worker(self,*,@@ -392,7 +224,6 @@ class AgentAppGenerator(MessageBasedAppGenerator):conversation_id: str,message_id: str,user_from: UserFrom,- is_resume: bool = False,) -> None:from libs.flask_utils import preserve_flask_contexts@@ -402,46 +233,36 @@ class AgentAppGenerator(MessageBasedAppGenerator):message = self._get_message(message_id)app_config = application_generate_entity.app_config- if is_resume:- # ENG-638: a resume continues a paused agent run; the human's- # reply is threaded in by the runner as deferred_tool_results.- # The query is the replayed paused-turn message, kept only to- # match the suspended snapshot's layers — it is NOT new- # end-user input, so input guards must NOT run. Moderation or an- # annotation match on the replayed query would short-circuit the- # turn and drop the human reply, stranding the ask_human session.- query = application_generate_entity.query or ""- else:- # Apply app-level input guards (content moderation + annotation- # reply) before reaching the Agent backend, mirroring the EasyUI- # chat / agent-chat runners. These can short-circuit the turn.- with session_factory.get_session_maker().begin() as session:- app_model = session.get(App, app_config.app_id)- if app_model is None:- raise AgentAppGeneratorError("App not found")- handled, query, annotation_reply = self._run_input_guards(- session=session,- application_generate_entity=application_generate_entity,- app_model=app_model,- message=message,- queue_manager=queue_manager,- )- if annotation_reply:- from core.app.apps.agent_app.app_runner import publish_text_answer- from core.app.entities.queue_entities import QueueAnnotationReplyEvent-- queue_manager.publish(- QueueAnnotationReplyEvent(message_annotation_id=annotation_reply.id),- PublishFrom.APPLICATION_MANAGER,- )- publish_text_answer(- queue_manager=queue_manager,- model_name=application_generate_entity.model_conf.model,- answer=annotation_reply.content,- user_query=query,- )- if handled:- return+ # Apply app-level input guards (content moderation + annotation+ # reply) before reaching the Agent backend, mirroring the EasyUI+ # chat / agent-chat runners. These can short-circuit the turn.+ with session_factory.get_session_maker().begin() as session:+ app_model = session.get(App, app_config.app_id)+ if app_model is None:+ raise AgentAppGeneratorError("App not found")+ handled, query, annotation_reply = self._run_input_guards(+ session=session,+ application_generate_entity=application_generate_entity,+ app_model=app_model,+ message=message,+ queue_manager=queue_manager,+ )+ if annotation_reply:+ from core.app.apps.agent_app.app_runner import publish_text_answer+ from core.app.entities.queue_entities import QueueAnnotationReplyEvent++ queue_manager.publish(+ QueueAnnotationReplyEvent(message_annotation_id=annotation_reply.id),+ PublishFrom.APPLICATION_MANAGER,+ )+ publish_text_answer(+ queue_manager=queue_manager,+ model_name=application_generate_entity.model_conf.model,+ answer=annotation_reply.content,+ user_query=query,+ )+ if handled:+ returndify_context = DifyRunContext(tenant_id=app_config.tenant_id,@@ -491,15 +312,6 @@ class AgentAppGenerator(MessageBasedAppGenerator):)except GenerateTaskStoppedError:pass- except AgentSessionSnapshotIncompatibleError as error:- logger.info(- "Agent App session snapshot no longer matches the current composition",- extra={- "agent_id": application_generate_entity.agent_id,- "conversation_id": conversation_id,- },- )- queue_manager.publish_error(error, PublishFrom.APPLICATION_MANAGER)except Exception as e:logger.exception("Unknown Error in Agent App generate worker")queue_manager.publish_error(e, PublishFrom.APPLICATION_MANAGER)diff --git a/api/core/app/apps/agent_app/app_runner.py b/api/core/app/apps/agent_app/app_runner.pyindex f155c07a333..c8315afee5b 100644--- a/api/core/app/apps/agent_app/app_runner.py+++ b/api/core/app/apps/agent_app/app_runner.py@@ -3,7 +3,7 @@Unlike the legacy ``AgentChatAppRunner`` (which runs an in-process ReAct loop),this runner delegates to the Agent backend, consumes the streamed event flow,republishes the assistant answer through the existing EasyUI chat task-pipeline, and saves the latest Agenton snapshot on the persistent Binding.+pipeline, and saves the latest module state snapshot on the persistent Binding."""from __future__ import annotations@@ -15,13 +15,10 @@ from collections.abc import Mappingfrom decimal import Decimalfrom typing import Any, Literal-from dify_agent.layers.ask_human import AskHumanToolArgs-from dify_agent.protocol import DeferredToolResultsPayloadfrom pydantic import JsonValuefrom clients.agent_backend import (AgentBackendAgentMessageDeltaInternalEvent,- AgentBackendDeferredToolCallInternalEvent,AgentBackendError,AgentBackendInternalEventType,AgentBackendRunCancelledInternalEvent,@@ -51,9 +48,6 @@ from core.app.entities.queue_entities import (QueueLLMChunkEvent,QueueMessageEndEvent,)-from core.repositories.human_input_repository import HumanInputFormRepository, HumanInputFormRepositoryImpl-from core.workflow.nodes.agent_v2.ask_human_hitl import AskHumanFormBuildError, create_ask_human_form-from core.workflow.nodes.agent_v2.ask_human_resume import build_deferred_tool_results, resolve_ask_human_formfrom extensions.ext_database import dbfrom graphon.file import Filefrom graphon.model_runtime.entities.llm_entities import LLMResult, LLMResultChunk, LLMResultChunkDelta, LLMUsage@@ -664,8 +658,6 @@ class AgentAppRunner:agent_config_version_kind=AgentConfigVersionKind(agent_config_version_kind),build_draft_id=build_draft_id,)- # ENG-638: if a prior turn paused on ask_human and the form is now answered,- # resume by threading the human's reply into this run as deferred_tool_results.stored = self._session_store.load_or_create(scope)runtime = self._build_runtime(dify_context=dify_context,@@ -681,7 +673,6 @@ class AgentAppRunner:image_detail_config=image_detail_config,idempotency_key=message_id,stored=stored,- message_id=message_id,)create_response = self._agent_backend_client.create_run(runtime.request)@@ -696,23 +687,6 @@ class AgentAppRunner:binding_id=runtime.binding_id,)- if isinstance(terminal, AgentBackendDeferredToolCallInternalEvent):- # ENG-635: the agent asked a human. End this turn with the question and- # a conversation-owned HITL form; a form submission resumes the run.- self._pause_for_ask_human(- terminal=terminal,- scope=scope,- dify_context=dify_context,- agent_soul=agent_soul,- conversation_id=conversation_id,- message_id=message_id,- model_name=model_name,- runtime=runtime,- queue_manager=queue_manager,- query=query,- )- return-terminal_usage = Noneif isinstance(terminal,@@ -810,14 +784,8 @@ class AgentAppRunner:image_detail_config: ImagePromptMessageContent.DETAIL | None,idempotency_key: str,stored: StoredAgentAppSession,- message_id: str | None,) -> AgentAppRuntimeRequest:session_snapshot = stored.session_snapshot- deferred_tool_results = (- self._resolve_pending_ask_human(stored=stored, dify_context=dify_context, message_id=message_id)- if message_id is not None- else None- )return self._request_builder.build(AgentAppRuntimeBuildContext(dify_context=dify_context,@@ -833,99 +801,9 @@ class AgentAppRunner:binding_id=binding_id,backend_binding_ref=backend_binding_ref,session_snapshot=session_snapshot,- deferred_tool_results=deferred_tool_results,))- def _pause_for_ask_human(- self,- *,- terminal: AgentBackendDeferredToolCallInternalEvent,- scope: AgentAppSessionScope,- dify_context: DifyRunContext,- agent_soul: AgentSoulConfig,- conversation_id: str,- message_id: str,- model_name: str,- runtime: AgentAppRuntimeRequest,- queue_manager: AppQueueManager,- query: str,- ) -> None:- """End the chat turn on a dify.ask_human call: create a conversation-owned- HITL form, persist the pause correlation, and surface the question."""- try:- created = create_ask_human_form(- deferred_tool_call=terminal.deferred_tool_call,- # Chat forms have no workflow node; key by the turn's message id.- node_id=message_id,- default_node_title="Agent",- contacts=agent_soul.human.contacts,- repository=self._build_form_repository(dify_context),- conversation_id=conversation_id,- )- except AskHumanFormBuildError as error:- raise AgentBackendError(f"Failed to build ask_human form for Agent App chat: {error}") from error-- # Persist the snapshot + correlation so a form submission can start the- # second run with the human's answer (ENG-637/638 columns, conversation owner).- self._save_session(- scope=scope,- binding_id=runtime.binding_id,- snapshot=terminal.session_snapshot,- pending_form_id=created.form_id,- pending_tool_call_id=terminal.deferred_tool_call.tool_call_id,- )-- # The structured form is delivered via the HITL surface(s); the chat turn- # ends by echoing the agent's question so the conversation reflects the ask.- self._publish_answer(- queue_manager=queue_manager,- model_name=model_name,- answer=self._ask_human_message(created.args),- query=query,- usage=_llm_usage_from_agent_backend(terminal.usage),- )-- def _resolve_pending_ask_human(- self,- *,- stored: StoredAgentAppSession,- dify_context: DifyRunContext,- message_id: str,- ) -> DeferredToolResultsPayload | None:- """Build deferred_tool_results when a pending ask_human form is answered."""- if stored.pending_form_id is None or stored.pending_tool_call_id is None:- return None- outcome = resolve_ask_human_form(- form_id=stored.pending_form_id,- tenant_id=dify_context.tenant_id,- node_id=message_id,- )- if outcome is None or outcome.deferred_result is None:- # Form missing or still waiting — run a normal turn, no resume.- return None- return build_deferred_tool_results(- tool_call_id=stored.pending_tool_call_id,- result=outcome.deferred_result,- )-- def _build_form_repository(self, dify_context: DifyRunContext) -> HumanInputFormRepository:- invoke_source = dify_context.invoke_from.value- return HumanInputFormRepositoryImpl(- tenant_id=dify_context.tenant_id,- app_id=dify_context.app_id,- workflow_execution_id=None,- invoke_source=invoke_source,- submission_actor_id=dify_context.user_id if invoke_source in {"debugger", "explore"} else None,- )-- @staticmethod- def _ask_human_message(args: AskHumanToolArgs) -> str:- parts = [args.question]- if args.markdown:- parts.append(args.markdown)- return "\n\n".join(parts)-def _consume_stream(self,run_id: str,@@ -1090,25 +968,6 @@ class AgentAppRunner:exc_info=True,)- def _publish_answer(- self,- *,- queue_manager: AppQueueManager,- model_name: str,- answer: str,- query: str | None,- usage: LLMUsage | None = None,- ) -> None:- # MVP: emit the full answer as a single chunk + message-end. The chat- # task pipeline streams the chunk over SSE and persists the message.- publish_text_answer(- queue_manager=queue_manager,- model_name=model_name,- answer=answer,- user_query=query,- usage=usage,- )-def _publish_terminal_answer(self,*,@@ -1167,16 +1026,12 @@ class AgentAppRunner:scope: AgentAppSessionScope,binding_id: str,snapshot: Any,- pending_form_id: str | None = None,- pending_tool_call_id: str | None = None,) -> bool:try:self._session_store.save_active_snapshot(scope=scope,binding_id=binding_id,snapshot=snapshot,- pending_form_id=pending_form_id,- pending_tool_call_id=pending_tool_call_id,)return Trueexcept Exception:diff --git a/api/core/app/apps/agent_app/errors.py b/api/core/app/apps/agent_app/errors.pyindex bdcd38abfdf..51b4e77116a 100644--- a/api/core/app/apps/agent_app/errors.py+++ b/api/core/app/apps/agent_app/errors.py@@ -1,24 +1,6 @@-from core.app.apps.exc import AppGenerateError--AGENT_SESSION_CONFIGURATION_CHANGED_ERROR_CODE = "agent_session_configuration_changed"-AGENT_SESSION_CONFIGURATION_CHANGED_MESSAGE = (- "The Agent configuration changed after this conversation started. Start a new conversation to continue."-)--class AgentAppGeneratorError(ValueError):"""Raised when an Agent App turn cannot be set up."""class AgentAppNotPublishedError(AgentAppGeneratorError):"""Raised when a public Agent App runtime is requested before publish."""---class AgentSessionSnapshotIncompatibleError(AppGenerateError):- """Raised when a retained session snapshot no longer matches the current composition."""-- error_code = AGENT_SESSION_CONFIGURATION_CHANGED_ERROR_CODE- status_code = 409-- def __init__(self) -> None:- super().__init__(AGENT_SESSION_CONFIGURATION_CHANGED_MESSAGE)diff --git a/api/core/app/apps/agent_app/runtime_request_builder.py b/api/core/app/apps/agent_app/runtime_request_builder.pyindex 5f05b0c99d6..cc4a63d45d6 100644--- a/api/core/app/apps/agent_app/runtime_request_builder.py+++ b/api/core/app/apps/agent_app/runtime_request_builder.py@@ -13,7 +13,6 @@ from __future__ import annotationsfrom dataclasses import dataclassfrom typing import Any, Literal, cast-from agenton.compositor import CompositorSessionSnapshotfrom dify_agent.layers.execution_context import (DifyExecutionContextInvokeFrom,DifyExecutionContextLayerConfig,@@ -25,7 +24,8 @@ from dify_agent.layers.user_prompt import (DifyUserPromptFileType,DifyUserPromptImageConfig,)-from dify_agent.protocol import CreateRunRequest, DeferredToolResultsPayload+from dify_agent.protocol import CreateRunRequest+from dify_agent.protocol.snapshot import SessionSnapshotfrom clients.agent_backend import (AgentBackendAgentAppRunInput,@@ -46,7 +46,6 @@ from core.workflow.nodes.agent_v2.dify_tools_builder import ()from core.workflow.nodes.agent_v2.runtime_request_builder import (append_runtime_warnings,- build_ask_human_layer_config,build_config_aware_soul_mention_resolver,build_config_layer_config,build_knowledge_layer_config,@@ -59,8 +58,6 @@ from models.agent_config_entities import AgentSoulConfig, AgentSoulToolsConfigfrom models.provider_ids import ModelProviderIDfrom services.agent.prompt_mentions import expand_prompt_mentions-from .errors import AgentSessionSnapshotIncompatibleError-class AgentAppRuntimeRequestBuildError(ValueError):"""Raised when Agent App state cannot be mapped to a valid run request."""@@ -87,9 +84,7 @@ class AgentAppRuntimeBuildContext:files: tuple[File, ...] = ()image_detail_config: ImagePromptMessageContent.DETAIL | None = Noneagent_config_version_kind: Literal["snapshot", "draft", "build_draft"] = "snapshot"- session_snapshot: CompositorSessionSnapshot | None = None- # ENG-638: set when resuming a chat turn after a submitted ask_human form.- deferred_tool_results: DeferredToolResultsPayload | None = None+ session_snapshot: SessionSnapshot | None = None@dataclass(frozen=True, slots=True)@@ -206,16 +201,13 @@ class AgentAppRuntimeRequestBuilder:core_tools=tool_layers.core_tools,knowledge=knowledge_config,config_layer_config=config_layer_config,- ask_human_config=build_ask_human_layer_config(agent_soul),include_shell=dify_config.AGENT_SHELL_ENABLED,shell_config=build_shell_layer_config(agent_soul),session_snapshot=context.session_snapshot,- deferred_tool_results=context.deferred_tool_results,idempotency_key=context.idempotency_key,metadata=metadata,))- self._validate_session_snapshot_layers(request)redacted = cast(dict[str, Any], redact_for_agent_backend_log(request))return AgentAppRuntimeRequest(request=request,@@ -245,24 +237,6 @@ class AgentAppRuntimeRequestBuilder:for file in files]- @staticmethod- def _validate_session_snapshot_layers(request: CreateRunRequest) -> None:- """Reject stale snapshots before they reach the Agent backend.-- Draft rows are updated in place, so their IDs cannot prove that a- retained snapshot still belongs to the current composition. Agenton- requires the ordered layer names to match exactly; enforce the same- invariant at the API boundary and return a product-level error.- """-- snapshot = request.session_snapshot- if snapshot is None:- return- snapshot_layer_names = tuple(layer.name for layer in snapshot.layers)- composition_layer_names = tuple(layer.name for layer in request.composition.layers)- if snapshot_layer_names != composition_layer_names:- raise AgentSessionSnapshotIncompatibleError()-def _build_tool_layers(self,*,diff --git a/api/core/app/apps/agent_app/session_store.py b/api/core/app/apps/agent_app/session_store.pyindex 07478da10f1..b1c5110900f 100644--- a/api/core/app/apps/agent_app/session_store.py+++ b/api/core/app/apps/agent_app/session_store.py@@ -4,7 +4,7 @@ from __future__ import annotationsfrom dataclasses import dataclass-from agenton.compositor import CompositorSessionSnapshot+from dify_agent.protocol.snapshot import SessionSnapshotfrom sqlalchemy import selectfrom sqlalchemy.orm import Session@@ -54,9 +54,7 @@ class StoredAgentAppSession:binding_id: strworkspace_id: strbackend_binding_ref: str- session_snapshot: CompositorSessionSnapshot | None- pending_form_id: str | None = None- pending_tool_call_id: str | None = None+ session_snapshot: SessionSnapshot | Noneclass AgentAppWorkspaceStore:@@ -141,9 +139,7 @@ class AgentAppWorkspaceStore:*,scope: AgentAppSessionScope,binding_id: str,- snapshot: CompositorSessionSnapshot | None,- pending_form_id: str | None = None,- pending_tool_call_id: str | None = None,+ snapshot: SessionSnapshot | None,) -> None:if snapshot is None:return@@ -151,25 +147,17 @@ class AgentAppWorkspaceStore:tenant_id=scope.tenant_id,binding_id=binding_id,session_snapshot=snapshot.model_dump_json(),- pending_form_id=pending_form_id,- pending_tool_call_id=pending_tool_call_id,)@staticmethoddef _stored(scope: AgentAppSessionScope, binding: AgentWorkspaceBinding) -> StoredAgentAppSession:- snapshot = (- CompositorSessionSnapshot.model_validate_json(binding.session_snapshot)- if binding.session_snapshot- else None- )+ snapshot = SessionSnapshot.model_validate_json(binding.session_snapshot) if binding.session_snapshot else Nonereturn StoredAgentAppSession(scope=scope,binding_id=binding.id,workspace_id=binding.workspace_id,backend_binding_ref=binding.backend_binding_ref,session_snapshot=snapshot,- pending_form_id=binding.pending_form_id,- pending_tool_call_id=binding.pending_tool_call_id,)diff --git a/api/core/repositories/human_input_repository.py b/api/core/repositories/human_input_repository.pyindex b144d1f88d4..4d35c05e0f9 100644--- a/api/core/repositories/human_input_repository.py+++ b/api/core/repositories/human_input_repository.py@@ -63,9 +63,7 @@ class FormCreateParams:display_in_ui: boolresolved_default_values: Mapping[str, Any]form_kind: HumanInputFormKind = HumanInputFormKind.RUNTIME- # ENG-635: the conversation this form belongs to. Set together with- # workflow_execution_id for chatflow runs; set alone (workflow_execution_id None)- # for Agent v2 chat ask_human forms, which have no workflow run.+ # Chatflow forms also belong to a conversation.conversation_id: str | None = Noneform_id: str | None = None@@ -230,8 +228,7 @@ class HumanInputFormRecord:recipient_id: str | Nonerecipient_type: RecipientType | Noneaccess_token: str | None- # ENG-635: Agent v2 chat owner (NULL for workflow-owned forms). Trailing +- # defaulted so existing record constructions stay source-compatible.+ # Retain chatflow conversation correlation alongside the workflow run owner.conversation_id: str | None = None@property@@ -450,15 +447,8 @@ class HumanInputFormRepositoryImpl:if not app_id:raise ValueError("app_id is required to create a human input form")workflow_execution_id = params.workflow_execution_id or self._workflow_execution_id- # A RUNTIME form must be owned by at least one of: a workflow run (workflow /- # Human-Input / agent node) or a conversation turn (ENG-635: Agent v2 chat- # ask_human; chatflow runs set both — workflow_run_id and conversation_id).- if (- params.form_kind == HumanInputFormKind.RUNTIME- and workflow_execution_id is None- and params.conversation_id is None- ):- raise ValueError("a runtime human input form requires a workflow_execution_id or conversation_id")+ if params.form_kind == HumanInputFormKind.RUNTIME and workflow_execution_id is None:+ raise ValueError("a runtime human input form requires a workflow_execution_id")with session_factory.create_session() as session, session.begin():form_id = params.form_id or str(uuidv7())diff --git a/api/core/workflow/nodes/agent_v2/agent_node.py b/api/core/workflow/nodes/agent_v2/agent_node.pyindex 9fd533e5fae..8d5c30a33b1 100644--- a/api/core/workflow/nodes/agent_v2/agent_node.py+++ b/api/core/workflow/nodes/agent_v2/agent_node.py@@ -4,12 +4,11 @@ import loggingfrom collections.abc import Generator, Mapping, Sequencefrom typing import TYPE_CHECKING, Any, override-from agenton.compositor import CompositorSessionSnapshotfrom dify_agent.protocol import CancelRunRequest+from dify_agent.protocol.snapshot import SessionSnapshotfrom clients.agent_backend import (AgentBackendAgentMessageDeltaInternalEvent,- AgentBackendDeferredToolCallInternalEvent,AgentBackendError,AgentBackendHTTPError,AgentBackendInternalEventType,@@ -24,11 +23,7 @@ from clients.agent_backend import (AgentBackendValidationError,)from core.app.entities.app_invoke_entities import DIFY_RUN_CONTEXT_KEY, DifyRunContext-from core.repositories.human_input_repository import HumanInputFormRepository, HumanInputFormRepositoryImpl-from core.workflow.nodes.human_input.pause_reason import HumanInputRequired-from core.workflow.nodes.human_input.session_binding import default_session_bindingfrom core.workflow.system_variables import SystemVariableKey, get_system_text-from graphon.entities.pause_reason import HitlRequired, SchedulingPausefrom graphon.enums import (BuiltinNodeTypes,ErrorStrategy,@@ -40,12 +35,10 @@ from graphon.graph_events import NodeRunPauseRequestedEventfrom graphon.node_events import NodeEventBase, NodeRunResult, StreamCompletedEventfrom graphon.nodes.base.node import Nodefrom graphon.nodes.base.variable_template_parser import VariableTemplateParser-from models.agent_config_entities import AgentSoulConfig, WorkflowNodeJobConfig, WorkflowOutputRoutes+from models.agent_config_entities import WorkflowNodeJobConfig, WorkflowOutputRoutesfrom services.agent.prompt_mentions import extract_workflow_node_output_selectorsfrom services.agent.workspace_service import AgentWorkspaceNotFoundError-from .ask_human_hitl import AskHumanFormBuildError, build_ask_human_pause_reason-from .ask_human_resume import build_deferred_tool_results, resolve_ask_human_formfrom .binding_resolver import WorkflowAgentBindingError, WorkflowAgentBindingResolverfrom .entities import DifyAgentNodeDatafrom .output_adapter import WorkflowAgentOutputAdapter@@ -74,10 +67,7 @@ logger = logging.getLogger(__name__)# Stream + started events are filtered out before we yield; transport errors# are surfaced as a separate StreamCompletedEvent in the second tuple slot.type _TerminalAgentBackendEvent = (- AgentBackendRunSucceededInternalEvent- | AgentBackendRunFailedInternalEvent- | AgentBackendRunCancelledInternalEvent- | AgentBackendDeferredToolCallInternalEvent+ AgentBackendRunSucceededInternalEvent | AgentBackendRunFailedInternalEvent | AgentBackendRunCancelledInternalEvent)@@ -137,16 +127,6 @@ class DifyAgentNode(Node[DifyAgentNodeData]):def populate_start_event(self, event) -> None:event.extras["agent_node"] = {"version": "2", "agent_node_kind": self.node_data.agent_node_kind}- @staticmethod- def _to_graph_pause_reason(reason: HumanInputRequired | SchedulingPause) -> HitlRequired | SchedulingPause:- if isinstance(reason, HumanInputRequired):- return HitlRequired(- session_id=default_session_binding.issue_session_id_for_form(form_id=reason.form_id),- node_id=reason.node_id,- node_title=reason.node_title,- )- return reason-@overridedef _run(self) -> Generator[NodeEventBase | NodeRunPauseRequestedEvent]:inputs: dict[str, Any] = {}@@ -182,8 +162,7 @@ class DifyAgentNode(Node[DifyAgentNodeData]):self.graph_runtime_state.variable_pool,SystemVariableKey.WORKFLOW_EXECUTION_ID,)- # Set on chatflow (advanced-chat) runs; None for a pure workflow run. Lets an- # ask_human form be tagged with its conversation in addition to workflow_run_id.+ # Chatflow sessions also carry their owning conversation.conversation_id = get_system_text(self.graph_runtime_state.variable_pool,SystemVariableKey.CONVERSATION_ID,@@ -253,40 +232,10 @@ class DifyAgentNode(Node[DifyAgentNodeData]):custom_outputs = list(node_job.declared_outputs)outputs_by_name = {output.name: output for output in custom_outputs}- # ──── ENG-638: resume after a submitted/timed-out ask_human form ────- # graphon re-executes this _run when the outer workflow resumes. If a- # pending ask_human form is now terminal, thread the human's answer into- # the second Agent run as deferred_tool_results; if it is somehow still- # waiting, re-emit the same pause defensively.- deferred_tool_results = Nonestored_session = self._session_store.load_or_create_node_execution_session(session_scope,home_snapshot_id=bundle.snapshot.home_snapshot_id,)- if stored_session.pending_form_id is not None:- resume_outcome = resolve_ask_human_form(- form_id=stored_session.pending_form_id,- tenant_id=dify_ctx.tenant_id,- node_id=self._node_id,- )- if resume_outcome is not None and resume_outcome.repause is not None:- yield self._pause_event(- reason=resume_outcome.repause,- inputs=inputs,- process_data=process_data,- metadata=metadata,- )- return- if (- resume_outcome is not None- and resume_outcome.deferred_result is not None- and stored_session.pending_tool_call_id is not None- ):- deferred_tool_results = build_deferred_tool_results(- tool_call_id=stored_session.pending_tool_call_id,- result=resume_outcome.deferred_result,- )-# ──── Retry loop (Stage 4 §7) ────attempt = 0while True:@@ -306,7 +255,6 @@ class DifyAgentNode(Node[DifyAgentNodeData]):backend_binding_ref=stored_session.backend_binding_ref,attempt=attempt,session_snapshot=stored_session.session_snapshot,- deferred_tool_results=deferred_tool_results,))except WorkflowAgentRuntimeRequestBuildError as error:@@ -386,65 +334,6 @@ class DifyAgentNode(Node[DifyAgentNodeData]):)return- if isinstance(terminal_event, AgentBackendDeferredToolCallInternalEvent):- # ENG-636: a dify.ask_human deferred call pauses the *outer*- # workflow through the existing HITL form path. Any other deferred- # tool (none today) falls back to a generic scheduling pause. The- # form is built *before* the snapshot is saved so its id can be- # persisted as the pause correlation (ENG-637).- try:- pause_request = build_ask_human_pause_reason(- deferred_tool_call=terminal_event.deferred_tool_call,- node_id=self._node_id,- default_node_title=bundle.agent.name or self._node_id,- workflow_run_id=workflow_run_id,- conversation_id=conversation_id,- contacts=AgentSoulConfig.model_validate(bundle.snapshot.config_snapshot_dict).human.contacts,- repository=self._build_human_input_form_repository(- dify_ctx=dify_ctx, workflow_run_id=workflow_run_id- ),- )- except AskHumanFormBuildError as error:- yield self._failure_event(- inputs=inputs,- process_data=process_data,- metadata=metadata,- error=str(error),- error_type="agent_ask_human_form_build_error",- )- return-- # ENG-637: persist the awaiting-form id + deferred tool_call id- # next to the snapshot so the resumed node can rebuild- # deferred_tool_results from the submitted form.- pending_form_id: str | None = None- pending_tool_call_id: str | None = None- pause_reason: HumanInputRequired | SchedulingPause- if pause_request is not None:- pending_form_id = pause_request.form_id- pending_tool_call_id = terminal_event.deferred_tool_call.tool_call_id- pause_reason = pause_request- else:- pause_reason = SchedulingPause(- message=terminal_event.message- or "Agent backend run requested workflow pause for external input."- )- self._save_session_snapshot(- session_scope=session_scope,- binding_id=stored_session.binding_id,- snapshot=terminal_event.session_snapshot,- metadata=metadata,- pending_form_id=pending_form_id,- pending_tool_call_id=pending_tool_call_id,- )- yield self._pause_event(- reason=pause_reason,- inputs=inputs,- process_data=process_data,- metadata=metadata,- )- return-# A failed attempt does not retire the product-owned Binding. The# Workflow Run terminal lifecycle event owns that transition.if not isinstance(terminal_event, AgentBackendRunSucceededInternalEvent):@@ -586,15 +475,12 @@ class DifyAgentNode(Node[DifyAgentNodeData]):**dict(metadata.get("agent_backend") or {}),"stream_event_count": stream_event_count,}- # Narrow to the known terminal event types before returning- # to the caller. Deferred-tool events are terminal on the- # Dify Agent wire, then converted into workflow pause locally.+ # Narrow to known terminal event types before returning to the caller.if isinstance(internal_event,AgentBackendRunSucceededInternalEvent| AgentBackendRunFailedInternalEvent- | AgentBackendRunCancelledInternalEvent- | AgentBackendDeferredToolCallInternalEvent,+ | AgentBackendRunCancelledInternalEvent,):return internal_event, Nonecancellation = self._cancel_backend_run(@@ -690,44 +576,19 @@ class DifyAgentNode(Node[DifyAgentNodeData]):],}- def _build_human_input_form_repository(- self,- *,- dify_ctx: DifyRunContext,- workflow_run_id: str | None,- ) -> HumanInputFormRepository:- """Construct the existing HITL form repository for ask_human form creation.-- Mirrors the Human Input node's repository wiring (``node_runtime``) so the- ask_human form shares the same delivery/debug/console behavior: a- submission actor is only attributed for debugger/explore surfaces.- """- invoke_source = dify_ctx.invoke_from.value- return HumanInputFormRepositoryImpl(- tenant_id=dify_ctx.tenant_id,- app_id=dify_ctx.app_id,- workflow_execution_id=workflow_run_id,- invoke_source=invoke_source,- submission_actor_id=dify_ctx.user_id if invoke_source in {"debugger", "explore"} else None,- )-def _save_session_snapshot(self,*,session_scope: WorkflowAgentSessionScope,binding_id: str,- snapshot: CompositorSessionSnapshot | None,+ snapshot: SessionSnapshot | None,metadata: dict[str, Any],- pending_form_id: str | None = None,- pending_tool_call_id: str | None = None,) -> None:try:self._session_store.save_active_snapshot(scope=session_scope,binding_id=binding_id,snapshot=snapshot,- pending_form_id=pending_form_id,- pending_tool_call_id=pending_tool_call_id,)agent_backend = dict(metadata.get("agent_backend") or {})agent_backend["session_snapshot_persisted"] = snapshot is not None@@ -787,27 +648,6 @@ class DifyAgentNode(Node[DifyAgentNodeData]):))- def _pause_event(- self,- *,- reason: HumanInputRequired | SchedulingPause,- inputs: dict[str, Any],- process_data: dict[str, Any],- metadata: dict[str, Any],- ) -> NodeRunPauseRequestedEvent:- return NodeRunPauseRequestedEvent(- id=self.execution_id,- node_id=self._node_id,- node_type=self.node_type,- node_run_result=NodeRunResult(- status=WorkflowNodeExecutionStatus.PAUSED,- inputs=inputs,- process_data=process_data,- metadata={WorkflowNodeExecutionMetadataKey.AGENT_LOG: metadata},- ),- reason=self._to_graph_pause_reason(reason),- )-@staticmethoddef _agent_backend_error_type(error: AgentBackendError) -> str:if isinstance(error, AgentBackendValidationError):diff --git a/api/core/workflow/nodes/agent_v2/ask_human_hitl.py b/api/core/workflow/nodes/agent_v2/ask_human_hitl.pydeleted file mode 100644index 56b3b59d2ae..00000000000--- a/api/core/workflow/nodes/agent_v2/ask_human_hitl.py+++ /dev/null@@ -1,355 +0,0 @@-"""Map a ``dify.ask_human`` deferred tool call onto the existing HITL form path.--ENG-636. When an Agent backend run ends with a deferred ``dify.ask_human`` tool-call, the workflow Agent node pauses the *outer* workflow through the very same-HITL form path the Human Input node uses — reusing the form repository,-delivery channels, and submission endpoints unchanged. This module is a pure-translation layer: model-facing ask_human tool args become graphon form-entities (``HumanInputNodeData`` / ``FormInputConfig`` / ``UserActionConfig``)-plus Dify delivery configs and the enriched Dify-side pause reason payload.-The Graphon ``HitlRequired`` conversion stays at the node boundary.--The agent-side ``dify.ask_human`` contract is richer than the workflow form-schema in two places, handled here without widening the form vocabulary:--* ask_human fields carry a human label; graphon ``FormInputConfig`` does not.- Labels are rendered into ``form_content`` next to a ``{{#$output.<name>#}}``- marker — exactly how the Human Input node positions labelled inputs today.-* ask_human action ids are valid identifiers of any length; graphon- ``UserActionConfig.id`` caps ids at 20 chars. Over-long ids are clamped- deterministically (stable + collision-resistant) so the form always builds;- the human-visible action *label* is always preserved verbatim.-"""--from __future__ import annotations--import hashlib-from collections.abc import Mapping, Sequence-from dataclasses import dataclass-from typing import Any, assert_never--from dify_agent.layers.ask_human import (- AskHumanAction,- AskHumanField,- AskHumanFileField,- AskHumanFileListField,- AskHumanParagraphField,- AskHumanSelectField,- AskHumanToolArgs,-)-from dify_agent.protocol import DeferredToolCallPayload-from pydantic import ValidationError--from core.repositories.human_input_repository import FormCreateParams, HumanInputFormRepository-from core.workflow.human_input_adapter import (- DeliveryChannelConfig,- EmailDeliveryConfig,- EmailDeliveryMethod,- EmailRecipients,- ExternalRecipient,- InteractiveSurfaceDeliveryMethod,-)-from core.workflow.nodes.human_input.entities import (- FileInputConfig,- FileListInputConfig,- FormInputConfig,- HumanInputNodeData,- ParagraphInputConfig,- SelectInputConfig,- StringListSource,- StringSource,- UserActionConfig,-)-from core.workflow.nodes.human_input.enums import ButtonStyle, TimeoutUnit, ValueSourceType-from core.workflow.nodes.human_input.pause_reason import HumanInputRequired-from models.agent_config_entities import AgentHumanContactConfig--# Default ask_human tool name (see ``DifyAskHumanLayerConfig.tool_name``). The-# Agent node only knows how to translate this one deferred tool into a form.-DEFAULT_ASK_HUMAN_TOOL_NAME = "ask_human"--# Graphon ``UserActionConfig.id`` hard-caps identifiers at 20 chars.-_MAX_ACTION_ID_LEN = 20-# No timeout lives in the ask_human contract; reuse the Human Input node default.-_DEFAULT_TIMEOUT_HOURS = 36-_EMAIL_SUBJECT_MAX_LEN = 120--# ``ButtonStyle`` has no "destructive"; map the ask_human destructive intent onto-# the closest existing form style rather than extending the HITL vocabulary.-_ACTION_STYLE_TO_BUTTON: dict[str, ButtonStyle] = {- "default": ButtonStyle.DEFAULT,- "primary": ButtonStyle.PRIMARY,- "destructive": ButtonStyle.ACCENT,-}--# ask_human permits zero actions (a plain acknowledgement); the form surface-# needs at least one submit affordance.-_DEFAULT_SUBMIT_ACTION = UserActionConfig(id="submit", title="Submit", button_style=ButtonStyle.PRIMARY)---class AskHumanFormBuildError(ValueError):- """Raised when ask_human tool args cannot be mapped to a HITL form."""---def parse_ask_human_args(raw_args: object) -> AskHumanToolArgs:- """Validate the raw deferred-tool ``args`` payload into ``AskHumanToolArgs``."""- if isinstance(raw_args, AskHumanToolArgs):- return raw_args- if isinstance(raw_args, Mapping):- try:- return AskHumanToolArgs.model_validate(dict(raw_args))- except ValidationError as error:- raise AskHumanFormBuildError(f"invalid ask_human args: {error}") from error- raise AskHumanFormBuildError(f"ask_human args must be a mapping, got {type(raw_args).__name__}")---def _clamp_action_id(action_id: str) -> str:- """Return a stable graphon-safe (<= 20 char) action id.-- ask_human ids are already valid identifiers; ids within the limit pass- through untouched so the resume round-trip returns the model's exact id.- Over-long ids are truncated with a short content hash to stay deterministic- and collision-resistant while remaining a valid identifier.- """- if len(action_id) <= _MAX_ACTION_ID_LEN:- return action_id- digest = hashlib.blake2b(action_id.encode("utf-8"), digest_size=3).hexdigest()- prefix = action_id[: _MAX_ACTION_ID_LEN - len(digest) - 1]- return f"{prefix}_{digest}"---def _to_form_input(field: AskHumanField) -> FormInputConfig:- match field:- case AskHumanParagraphField():- default = (- StringSource(type=ValueSourceType.CONSTANT, value=field.default) if field.default is not None else None- )- return ParagraphInputConfig(output_variable_name=field.name, default=default)- case AskHumanSelectField():- return SelectInputConfig(- output_variable_name=field.name,- option_source=StringListSource(- type=ValueSourceType.CONSTANT,- value=[option.value for option in field.options],- ),- )- case AskHumanFileField():- return FileInputConfig(output_variable_name=field.name)- case AskHumanFileListField():- return FileListInputConfig(output_variable_name=field.name, number_limits=field.max_files or 0)- case _: # pragma: no cover - exhaustive over the discriminated union- assert_never(field)---def _to_user_actions(actions: Sequence[AskHumanAction]) -> list[UserActionConfig]:- if not actions:- return [_DEFAULT_SUBMIT_ACTION]- return [- UserActionConfig(- id=_clamp_action_id(action.id),- title=action.label,- button_style=_ACTION_STYLE_TO_BUTTON.get(action.style, ButtonStyle.DEFAULT),- )- for action in actions- ]---def _render_form_content(args: AskHumanToolArgs) -> str:- """Compose the markdown body, positioning each field's label + input marker.-- Graphon ``FormInputConfig`` carries no label, so the field label is written- into the content next to the ``{{#$output.<name>#}}`` marker that the form- surface replaces with the live input — identical to the Human Input node.- """- blocks: list[str] = []- if args.title:- blocks.append(f"## {args.title}")- blocks.append(args.question)- if args.markdown:- blocks.append(args.markdown)- for field in args.fields:- label = f"{field.label} *" if field.required else field.label- blocks.append(f"**{label}**\n\n{{{{#$output.{field.name}#}}}}")- return "\n\n".join(blocks)---def _resolved_default_values(args: AskHumanToolArgs) -> dict[str, Any]:- """Pre-fill map the form surface reads, keyed by output variable name.-- The graphon select input has no default field, so a select default can only- be conveyed here; paragraph defaults are included for a uniform pre-fill.- """- defaults: dict[str, Any] = {}- for field in args.fields:- if isinstance(field, AskHumanParagraphField | AskHumanSelectField) and field.default is not None:- defaults[field.name] = field.default- return defaults---def ask_human_args_to_node_data(args: AskHumanToolArgs, *, node_title: str) -> HumanInputNodeData:- """Translate validated ask_human args into a synthetic Human Input node config."""- return HumanInputNodeData(- title=node_title,- form_content=_render_form_content(args),- inputs=[_to_form_input(field) for field in args.fields],- user_actions=_to_user_actions(args.actions),- timeout=_DEFAULT_TIMEOUT_HOURS,- timeout_unit=TimeoutUnit.HOUR,- )---def build_delivery_methods(- contacts: Sequence[AgentHumanContactConfig],- *,- args: AskHumanToolArgs,-) -> list[DeliveryChannelConfig]:- """Build form delivery channels: always the interactive surface, plus email to- the configured human contacts (the recipients chosen in Agent Soul)."""- methods: list[DeliveryChannelConfig] = [InteractiveSurfaceDeliveryMethod()]-- seen: set[str] = set()- emails: list[str] = []- for contact in contacts:- email = (contact.email or "").strip()- if email and email not in seen:- seen.add(email)- emails.append(email)-- if emails:- subject = (args.title or args.question).strip()[:_EMAIL_SUBJECT_MAX_LEN]- if args.urgency == "high":- subject = f"[Action needed] {subject}"- body = f"{args.question}\n\nOpen the request: {EmailDeliveryConfig.URL_PLACEHOLDER}"- methods.append(- EmailDeliveryMethod(- config=EmailDeliveryConfig(- recipients=EmailRecipients(items=[ExternalRecipient(email=email) for email in emails]),- subject=subject,- body=body,- )- )- )- return methods---@dataclass(frozen=True, slots=True)-class AskHumanFormCreated:- """A created ask_human HITL form, owner-agnostic (workflow run or conversation)."""-- form_id: str- args: AskHumanToolArgs- node_data: HumanInputNodeData- node_title: str- resolved_default_values: dict[str, Any]---def create_ask_human_form(- *,- deferred_tool_call: DeferredToolCallPayload,- node_id: str,- default_node_title: str,- contacts: Sequence[AgentHumanContactConfig],- repository: HumanInputFormRepository,- workflow_run_id: str | None = None,- conversation_id: str | None = None,- display_in_ui: bool = True,-) -> AskHumanFormCreated:- """Create a HITL form from an ask_human deferred call (caller verified tool_name).-- The form is owned by exactly one of ``workflow_run_id`` (workflow Agent node)- or ``conversation_id`` (Agent v2 chat). Raises ``AskHumanFormBuildError`` on- invalid args, a missing owner, or a repository failure.- """- if not workflow_run_id and not conversation_id:- raise AskHumanFormBuildError("an ask_human HITL form requires a workflow_run_id or conversation_id")-- args = parse_ask_human_args(deferred_tool_call.args)- node_title = args.title or default_node_title- node_data = ask_human_args_to_node_data(args, node_title=node_title)- resolved_default_values = _resolved_default_values(args)-- try:- form = repository.create_form(- FormCreateParams(- workflow_execution_id=workflow_run_id,- conversation_id=conversation_id,- node_id=node_id,- form_config=node_data,- # No workflow-variable placeholders to resolve — the content is- # fully model-authored, so rendered == template.- rendered_content=node_data.form_content,- delivery_methods=build_delivery_methods(contacts, args=args),- display_in_ui=display_in_ui,- resolved_default_values=resolved_default_values,- )- )- except ValueError as error:- raise AskHumanFormBuildError(f"failed to create ask_human HITL form: {error}") from error-- return AskHumanFormCreated(- form_id=form.id,- args=args,- node_data=node_data,- node_title=node_title,- resolved_default_values=resolved_default_values,- )---def build_ask_human_pause_reason(- *,- deferred_tool_call: DeferredToolCallPayload,- node_id: str,- default_node_title: str,- workflow_run_id: str | None,- contacts: Sequence[AgentHumanContactConfig],- repository: HumanInputFormRepository,- conversation_id: str | None = None,- expected_tool_name: str = DEFAULT_ASK_HUMAN_TOOL_NAME,- display_in_ui: bool = True,-) -> HumanInputRequired | None:- """Create a workflow HITL form for an ask_human call and return its pause reason.-- Returns ``None`` when the deferred call is *not* the ask_human tool, letting- the caller fall back to a generic scheduling pause. Raises- ``AskHumanFormBuildError`` when the call is ask_human but its args or the form- cannot be built — the caller should surface that as a node failure rather- than a silent, unresumable pause.- """- if deferred_tool_call.tool_name != expected_tool_name:- return None- if not workflow_run_id:- raise AskHumanFormBuildError("workflow_run_id is required to create an ask_human HITL form")-- created = create_ask_human_form(- deferred_tool_call=deferred_tool_call,- node_id=node_id,- default_node_title=default_node_title,- contacts=contacts,- repository=repository,- workflow_run_id=workflow_run_id,- # A chatflow agent node also belongs to a conversation; tag the form so it is- # queryable per conversation. None for a pure workflow run (workflow_run_id only).- conversation_id=conversation_id,- display_in_ui=display_in_ui,- )- return HumanInputRequired(- form_id=created.form_id,- form_content=created.node_data.form_content,- inputs=list(created.node_data.inputs),- actions=list(created.node_data.user_actions),- node_id=node_id,- node_title=created.node_title,- resolved_default_values=created.resolved_default_values,- )---__all__ = [- "DEFAULT_ASK_HUMAN_TOOL_NAME",- "AskHumanFormBuildError",- "AskHumanFormCreated",- "ask_human_args_to_node_data",- "build_ask_human_pause_reason",- "build_delivery_methods",- "create_ask_human_form",- "parse_ask_human_args",-]diff --git a/api/core/workflow/nodes/agent_v2/ask_human_resume.py b/api/core/workflow/nodes/agent_v2/ask_human_resume.pydeleted file mode 100644index 84d473e2c29..00000000000--- a/api/core/workflow/nodes/agent_v2/ask_human_resume.py+++ /dev/null@@ -1,162 +0,0 @@-"""Resume an Agent run after a dify.ask_human HITL form reaches a terminal state.--ENG-638. When the outer workflow resumes (the human submitted the form, or it-timed out), graphon re-executes the Agent node's ``_run``. This module reads the-correlated HITL form (by ``pending_form_id``) and maps it back into the-agent-side ``dify.ask_human`` contract so the node can start a *second* Agent run-that carries the human's answer:--* submitted -> AskHumanToolResult(status="submitted", action, values)-* timeout -> AskHumanToolResult(status="timeout")-* expired (global timeout) -> invalid resume state; the workflow must not resume-* still waiting (defensive: the host resumed us early) -> re-emit the same- Dify-side ``HumanInputRequired`` pause rebuilt from the stored form definition.--It only *reads* existing HITL form state — it never mutates the form or the HITL-submission flow. The DB read (``resolve_ask_human_form``) is kept thin so the-mapping (``map_form_to_outcome``) stays pure and unit-testable.-"""--from __future__ import annotations--import json-from dataclasses import dataclass--from dify_agent.layers.ask_human import (- AskHumanResultStatus,- AskHumanSelectedAction,- AskHumanToolResult,-)-from dify_agent.protocol import DeferredToolResultsPayload-from pydantic import JsonValue-from sqlalchemy import select--from core.db.session_factory import session_factory-from core.workflow.nodes.human_input.entities import FormDefinition-from core.workflow.nodes.human_input.enums import HumanInputFormStatus-from core.workflow.nodes.human_input.pause_reason import HumanInputRequired-from models.human_input import HumanInputForm--# A WAITING form has not been answered yet. TIMEOUT is resumable through the-# agent-facing "timeout" result, but EXPIRED is a global timeout and therefore-# an invalid resume state, matching the ordinary Human Input callback boundary.-_FORM_STATUS_TO_RESULT: dict[HumanInputFormStatus, AskHumanResultStatus] = {- HumanInputFormStatus.SUBMITTED: "submitted",- HumanInputFormStatus.TIMEOUT: "timeout",-}---@dataclass(frozen=True, slots=True)-class AskHumanResumeOutcome:- """Result of inspecting a correlated ask_human form on workflow resume.-- Exactly one of ``deferred_result`` / ``repause`` is set:- * ``deferred_result`` — the form reached a terminal state; start the second run.- * ``repause`` — the form is still waiting; re-emit this pause defensively.- """-- deferred_result: AskHumanToolResult | None = None- repause: HumanInputRequired | None = None---def resolve_ask_human_form(*, form_id: str, tenant_id: str, node_id: str) -> AskHumanResumeOutcome | None:- """Load the correlated form and map it to a resume outcome.-- Returns ``None`` when the form no longer exists (correlation lost) — the- caller should fall back to a normal (non-resume) Agent run.- """- with session_factory.create_session() as session:- form = session.scalar(- select(HumanInputForm).where(- HumanInputForm.id == form_id,- HumanInputForm.tenant_id == tenant_id,- )- )- if form is None:- return None- return map_form_to_outcome(- status=form.status,- selected_action_id=form.selected_action_id,- submitted_data=form.submitted_data,- rendered_content=form.rendered_content,- form_definition=form.form_definition,- form_id=form.id,- node_id=node_id,- )---def map_form_to_outcome(- *,- status: HumanInputFormStatus,- selected_action_id: str | None,- submitted_data: str | None,- rendered_content: str,- form_definition: str,- form_id: str,- node_id: str,-) -> AskHumanResumeOutcome:- """Map a terminal (or still-waiting) HITL form to a resume outcome. Pure."""- definition = FormDefinition.model_validate_json(form_definition)- if status == HumanInputFormStatus.WAITING:- return AskHumanResumeOutcome(repause=_rebuild_pause(definition=definition, form_id=form_id, node_id=node_id))- if status == HumanInputFormStatus.EXPIRED:- msg = f"cannot resume globally expired ask_human form, form_id={form_id}"- raise AssertionError(msg)-- result_status = _FORM_STATUS_TO_RESULT.get(status, "unavailable")- if result_status != "submitted":- return AskHumanResumeOutcome(deferred_result=AskHumanToolResult(status=result_status))- return AskHumanResumeOutcome(- deferred_result=AskHumanToolResult(- status="submitted",- action=_selected_action(selected_action_id=selected_action_id, definition=definition),- values=_submitted_values(submitted_data),- rendered_content=rendered_content,- )- )---def build_deferred_tool_results(*, tool_call_id: str, result: AskHumanToolResult) -> DeferredToolResultsPayload:- """Wrap an ask_human result as the deferred-tool-results payload for resume."""- return DeferredToolResultsPayload(calls={tool_call_id: result.model_dump(mode="json")})---def _submitted_values(submitted_data: str | None) -> dict[str, JsonValue]:- if not submitted_data:- return {}- parsed = json.loads(submitted_data)- if not isinstance(parsed, dict):- return {}- return {str(key): value for key, value in parsed.items()}---def _selected_action(*, selected_action_id: str | None, definition: FormDefinition) -> AskHumanSelectedAction | None:- if selected_action_id is None:- return None- # The form's user_action title is the verbatim ask_human action label set at- # form-build time; fall back to the id only if the action is somehow missing.- label = next(- (action.title for action in definition.user_actions if action.id == selected_action_id),- selected_action_id,- )- return AskHumanSelectedAction(id=selected_action_id, label=label)---def _rebuild_pause(*, definition: FormDefinition, form_id: str, node_id: str) -> HumanInputRequired:- return HumanInputRequired(- form_id=form_id,- form_content=definition.rendered_content or definition.form_content,- inputs=list(definition.inputs),- actions=list(definition.user_actions),- node_id=node_id,- node_title=definition.node_title or node_id,- resolved_default_values=dict(definition.default_values),- )---__all__ = [- "AskHumanResumeOutcome",- "build_deferred_tool_results",- "map_form_to_outcome",- "resolve_ask_human_form",-]diff --git a/api/core/workflow/nodes/agent_v2/output_adapter.py b/api/core/workflow/nodes/agent_v2/output_adapter.pyindex 9897959e652..051f2670857 100644--- a/api/core/workflow/nodes/agent_v2/output_adapter.py+++ b/api/core/workflow/nodes/agent_v2/output_adapter.py@@ -4,7 +4,6 @@ from collections.abc import Mapping, Sequencefrom typing import Any, Protocolfrom clients.agent_backend import (- AgentBackendDeferredToolCallInternalEvent,AgentBackendInternalEvent,AgentBackendInternalEventType,AgentBackendRunCancelledInternalEvent,@@ -338,7 +337,6 @@ class WorkflowAgentOutputAdapter:if isinstance(event,AgentBackendRunSucceededInternalEvent- | AgentBackendDeferredToolCallInternalEvent| AgentBackendRunFailedInternalEvent| AgentBackendRunCancelledInternalEvent,):diff --git a/api/core/workflow/nodes/agent_v2/runtime_feature_manifest.py b/api/core/workflow/nodes/agent_v2/runtime_feature_manifest.pyindex 8456711973c..30df6cecebb 100644--- a/api/core/workflow/nodes/agent_v2/runtime_feature_manifest.py+++ b/api/core/workflow/nodes/agent_v2/runtime_feature_manifest.py@@ -17,15 +17,13 @@ SUPPORTED_AGENT_BACKEND_FEATURES = frozenset("knowledge","env","sandbox",- # ENG-635: human involvement is exposed at runtime as the dify.ask_human- # deferred tool; a call pauses via the existing HITL form mechanism.- "human",})RESERVED_AGENT_BACKEND_FEATURES = frozenset({"memory",+ "human",})@@ -54,7 +52,6 @@ def build_runtime_feature_manifest(agent_soul: AgentSoulConfig) -> dict[str, Anyreserved_status["tools.cli_tools"] = "supported_by_shell_bootstrap"reserved_status["env"] = "supported_by_shell_bootstrap"reserved_status["sandbox"] = "forwarded_to_shell_layer_config"- reserved_status["human"] = "supported_by_ask_human_hitl" if agent_soul.human.contacts else "not_configured"return {"supported": sorted(SUPPORTED_AGENT_BACKEND_FEATURES),diff --git a/api/core/workflow/nodes/agent_v2/runtime_request_builder.py b/api/core/workflow/nodes/agent_v2/runtime_request_builder.pyindex 11403182af0..0dcdcb35b36 100644--- a/api/core/workflow/nodes/agent_v2/runtime_request_builder.py+++ b/api/core/workflow/nodes/agent_v2/runtime_request_builder.py@@ -5,9 +5,7 @@ from collections.abc import Mapping, Sequencefrom dataclasses import dataclassfrom typing import Any, Literal, Protocol, assert_never, cast-from agenton.compositor import CompositorSessionSnapshotfrom dify_agent.agent_stub.protocol import AgentStubFileMapping-from dify_agent.layers.ask_human import DifyAskHumanLayerConfigfrom dify_agent.layers.config import (DifyConfigFileConfig,DifyConfigLayerConfig,@@ -35,7 +33,8 @@ from dify_agent.layers.shell import (DifyShellLayerConfig,DifyShellSecretRefConfig,)-from dify_agent.protocol import CreateRunRequest, DeferredToolResultsPayload+from dify_agent.protocol import CreateRunRequest+from dify_agent.protocol.snapshot import SessionSnapshotfrom pydantic import BaseModel, ValidationErrorfrom sqlalchemy.exc import OperationalError@@ -138,10 +137,7 @@ class WorkflowAgentRuntimeBuildContext:# Stage 4 §7 / D-4: 0 for the first run, then incremented per retry. Drives the# idempotency key so the backend treats each retry as a fresh request.attempt: int = 0- session_snapshot: CompositorSessionSnapshot | None = None- # ENG-638: set when resuming after a submitted ask_human HITL form; threads- # the human's answer back into the second Agent run keyed by tool_call_id.- deferred_tool_results: DeferredToolResultsPayload | None = None+ session_snapshot: SessionSnapshot | None = None@dataclass(frozen=True, slots=True)@@ -273,11 +269,9 @@ class WorkflowAgentRuntimeRequestBuilder:core_tools=tool_layers.core_tools,knowledge=knowledge_config,config_layer_config=config_layer_config,- ask_human_config=build_ask_human_layer_config(agent_soul),include_shell=dify_config.AGENT_SHELL_ENABLED,shell_config=build_shell_layer_config(agent_soul),session_snapshot=context.session_snapshot,- deferred_tool_results=context.deferred_tool_results,idempotency_key=self._idempotency_key(context),metadata=metadata,)@@ -853,20 +847,6 @@ def _knowledge_model_config(model: AgentKnowledgeModelConfig | None) -> DifyKnow)-def build_ask_human_layer_config(agent_soul: AgentSoulConfig) -> DifyAskHumanLayerConfig | None:- """Enable the dify.ask_human deferred tool when the soul configures human involvement.-- HITL is opt-in: only when at least one human contact is configured does the- model get the ``ask_human`` tool (recipients for the resulting form come from- those contacts, ENG-635). Returns ``None`` to leave the tool off entirely.- The tool/field guardrails use the layer defaults; ``human.tools`` semantics are- out of scope this round.- """- if not agent_soul.human.contacts:- return None- return DifyAskHumanLayerConfig()--def append_runtime_warnings(metadata: dict[str, Any], warnings: list[dict[str, str]]) -> None:"""Merge build-time warnings into the metadata runtime-support manifest."""if not warnings:diff --git a/api/core/workflow/nodes/agent_v2/session_store.py b/api/core/workflow/nodes/agent_v2/session_store.pyindex dd5f5117efe..0392ba72729 100644--- a/api/core/workflow/nodes/agent_v2/session_store.py+++ b/api/core/workflow/nodes/agent_v2/session_store.py@@ -6,7 +6,7 @@ import jsonimport timefrom dataclasses import dataclass-from agenton.compositor import CompositorSessionSnapshot+from dify_agent.protocol.snapshot import SessionSnapshotfrom sqlalchemy import selectfrom sqlalchemy.orm import Session@@ -96,9 +96,7 @@ class StoredWorkflowAgentSession:binding_id: strworkspace_id: strbackend_binding_ref: str- session_snapshot: CompositorSessionSnapshot | None- pending_form_id: str | None = None- pending_tool_call_id: str | None = None+ session_snapshot: SessionSnapshot | Noneclass WorkflowAgentWorkspaceStore:@@ -236,9 +234,7 @@ class WorkflowAgentWorkspaceStore:*,scope: WorkflowAgentSessionScope,binding_id: str,- snapshot: CompositorSessionSnapshot | None,- pending_form_id: str | None = None,- pending_tool_call_id: str | None = None,+ snapshot: SessionSnapshot | None,) -> None:if snapshot is None:return@@ -246,8 +242,6 @@ class WorkflowAgentWorkspaceStore:tenant_id=scope.tenant_id,binding_id=binding_id,session_snapshot=snapshot.model_dump_json(),- pending_form_id=pending_form_id,- pending_tool_call_id=pending_tool_call_id,)def retire_workflow_run(self, *, tenant_id: str, app_id: str, workflow_run_id: str) -> list[str]:@@ -359,19 +353,13 @@ class WorkflowAgentWorkspaceStore:scope: WorkflowAgentSessionScope,binding: AgentWorkspaceBinding,) -> StoredWorkflowAgentSession:- snapshot = (- CompositorSessionSnapshot.model_validate_json(binding.session_snapshot)- if binding.session_snapshot- else None- )+ snapshot = SessionSnapshot.model_validate_json(binding.session_snapshot) if binding.session_snapshot else Nonereturn StoredWorkflowAgentSession(scope=scope,binding_id=binding.id,workspace_id=binding.workspace_id,backend_binding_ref=binding.backend_binding_ref,session_snapshot=snapshot,- pending_form_id=binding.pending_form_id,- pending_tool_call_id=binding.pending_tool_call_id,)diff --git a/api/extensions/ext_celery.py b/api/extensions/ext_celery.pyindex a91009b4884..9f7096197d1 100644--- a/api/extensions/ext_celery.py+++ b/api/extensions/ext_celery.py@@ -182,7 +182,6 @@ def init_app(app: DifyApp) -> Celery:"tasks.install_default_plugins_task", # tenant default plugin installation"tasks.new_agent_beta_task", # New Agent Beta eligibility checks"tasks.refresh_billing_vector_space_task", # billing vector-space cache refresh- "tasks.app_generate.resume_agent_app_task", # ENG-635: Agent v2 chat ask_human resume"tasks.workflow_run_archive_download_tasks", # workflow-run archive download preparation]day = dify_config.CELERY_BEAT_SCHEDULER_TIMEdiff --git a/api/models/human_input.py b/api/models/human_input.pyindex 7d35cf990c7..99e0e5f65c3 100644--- a/api/models/human_input.py+++ b/api/models/human_input.py@@ -40,12 +40,7 @@ class HumanInputForm(DefaultFieldsMixin, Base):tenant_id: Mapped[str] = mapped_column(StringUUID, nullable=False)app_id: Mapped[str] = mapped_column(StringUUID, nullable=False)workflow_run_id: Mapped[str | None] = mapped_column(StringUUID, nullable=True)- # ENG-635: a RUNTIME form is tagged with its owning workflow run and/or its- # conversation. Workflow / Human-Input / agent-node forms always set- # workflow_run_id, and ALSO set conversation_id when the run has a conversation- # (chatflow / advanced-chat). Agent v2 chat ask_human forms set only- # conversation_id (the new Agent App has no workflow_run_id). At least one is set;- # resume routing prefers workflow_run_id when both are present.+ # Chatflow forms retain their conversation for lookup and deletion.conversation_id: Mapped[str | None] = mapped_column(StringUUID, nullable=True)form_kind: Mapped[HumanInputFormKind] = mapped_column(EnumText(HumanInputFormKind),diff --git a/api/services/agent/workspace_service.py b/api/services/agent/workspace_service.pyindex 344f6b38905..3c9a7fc7516 100644--- a/api/services/agent/workspace_service.py+++ b/api/services/agent/workspace_service.py@@ -189,8 +189,6 @@ class AgentWorkspaceService:tenant_id: str,binding_id: str,session_snapshot: str,- pending_form_id: str | None = None,- pending_tool_call_id: str | None = None,) -> None:with session_factory.create_session() as session:binding = session.scalar(@@ -203,8 +201,6 @@ class AgentWorkspaceService:if binding is None:raise AgentWorkspaceNotFoundError("ACTIVE Binding is unavailable")binding.session_snapshot = session_snapshot- binding.pending_form_id = pending_form_id- binding.pending_tool_call_id = pending_tool_call_idsession.commit()@classmethoddiff --git a/api/services/human_input_service.py b/api/services/human_input_service.pyindex 66a1a88c524..416c3a0c5d2 100644--- a/api/services/human_input_service.py+++ b/api/services/human_input_service.py@@ -223,12 +223,9 @@ class HumanInputService:if result.form_kind != HumanInputFormKind.RUNTIME:return- # A RUNTIME form is owned by a workflow run (workflow Agent node) or a- # conversation (ENG-635: Agent v2 chat). Route the resume accordingly.+ # Runtime Human Input forms resume their owning workflow run.if result.workflow_run_id is not None:self.enqueue_resume(result.workflow_run_id)- elif result.conversation_id is not None:- self.enqueue_agent_app_resume(conversation_id=result.conversation_id, form_id=result.form_id)def ensure_form_active(self, form: Form) -> None:if form.submitted:@@ -289,22 +286,6 @@ class HumanInputService:logger.warning("App mode %s does not support resume for workflow run %s", app.mode, workflow_run_id)- def enqueue_agent_app_resume(self, *, conversation_id: str, form_id: str) -> None:- """ENG-635: resume an Agent v2 chat after its ask_human form is submitted.-- Enqueues a background turn for the conversation; the Agent App runner- continues the agent run, threading the human's reply into the request as- ``deferred_tool_results``.- """- from tasks.app_generate.resume_agent_app_task import resume_agent_app_execution-- try:- resume_agent_app_execution.apply_async(- kwargs={"conversation_id": conversation_id, "form_id": form_id},- )- except Exception: # pragma: no cover- logger.exception("Failed to enqueue Agent App resume for conversation %s form %s", conversation_id, form_id)-def _load_variable_pool_for_form(self, form: Form) -> ReadOnlyVariablePool | None:workflow_run_id = form.workflow_run_idif workflow_run_id is None:diff --git a/api/tasks/app_generate/resume_agent_app_task.py b/api/tasks/app_generate/resume_agent_app_task.pydeleted file mode 100644index eac6d273425..00000000000--- a/api/tasks/app_generate/resume_agent_app_task.py+++ /dev/null@@ -1,78 +0,0 @@-"""Background resume of an Agent v2 chat after a submitted ask_human HITL form.--ENG-635. When a human submits a conversation-owned ask_human form (delivered via-email/webapp), ``HumanInputService`` enqueues this task. It reconstructs the-conversation context and runs one blocking Agent App turn; the runner detects the-answered form and continues the agent run with the human's reply-(``deferred_tool_results``), persisting the assistant answer to the conversation.-"""--from __future__ import annotations--import logging--from celery import shared_task--from core.app.apps.agent_app.app_generator import AgentAppGenerator-from core.app.entities.app_invoke_entities import InvokeFrom-from extensions.ext_database import db-from models.account import Account-from models.human_input import HumanInputForm-from models.model import App, Conversation, EndUser-from tasks.app_generate.workflow_execute_task import WORKFLOW_BASED_APP_EXECUTION_QUEUE--logger = logging.getLogger(__name__)---@shared_task(queue=WORKFLOW_BASED_APP_EXECUTION_QUEUE, name="resume_agent_app_execution")-def resume_agent_app_execution(*, conversation_id: str, form_id: str) -> None:- form = db.session.get(HumanInputForm, form_id)- if form is None or form.conversation_id != conversation_id:- logger.warning("Agent App resume: form %s missing or conversation mismatch", form_id)- return-- app_model = db.session.get(App, form.app_id)- if app_model is None:- logger.warning("Agent App resume: app %s not found for form %s", form.app_id, form_id)- return-- conversation = db.session.get(Conversation, conversation_id)- if conversation is None:- logger.warning("Agent App resume: conversation %s not found", conversation_id)- return-- user = _resolve_conversation_user(app_model=app_model, conversation=conversation)- if user is None:- logger.warning("Agent App resume: no user resolvable for conversation %s", conversation_id)- return-- try:- AgentAppGenerator().resume_after_form_submission(- app_model=app_model,- user=user,- conversation_id=conversation_id,- form_id=form_id,- invoke_from=_resolve_invoke_from(conversation),- session=db.session(),- )- except Exception:- logger.exception("Agent App resume failed for conversation %s form %s", conversation_id, form_id)- finally:- db.session.close()---def _resolve_conversation_user(*, app_model: App, conversation: Conversation) -> Account | EndUser | None:- if conversation.from_account_id:- account = db.session.get(Account, conversation.from_account_id)- if account is not None:- account.set_tenant_id_with_session(app_model.tenant_id, session=db.session())- return account- if conversation.from_end_user_id:- return db.session.get(EndUser, conversation.from_end_user_id)- return None---def _resolve_invoke_from(conversation: Conversation) -> InvokeFrom:- if conversation.invoke_from is None:- return InvokeFrom.WEB_APP- return InvokeFrom.value_of(conversation.invoke_from.value)diff --git a/api/tasks/human_input_timeout_tasks.py b/api/tasks/human_input_timeout_tasks.pyindex 7325602e7d2..acaccf2474c 100644--- a/api/tasks/human_input_timeout_tasks.py+++ b/api/tasks/human_input_timeout_tasks.py@@ -106,17 +106,11 @@ def check_and_handle_human_input_timeouts(limit: int = 100) -> None:session_factory=session_factory,)elif record.workflow_run_id is not None:- # Workflow Agent node / Human Input node form: resume the workflow.+ # Human Input node form: resume the workflow.service.enqueue_resume(record.workflow_run_id)- elif record.conversation_id is not None:- # ENG-635: Agent v2 chat ask_human form is conversation-owned (no- # workflow_run_id). Resume the chat turn so the timeout is threaded- # back to the agent run as the ask_human deferred_tool_result- # (status="timeout"), mirroring HumanInputService.submit_form_by_token.- service.enqueue_agent_app_resume(conversation_id=record.conversation_id, form_id=record.form_id)else:logger.warning(- "Timed-out form %s has neither workflow_run_id nor conversation_id; skipping resume",+ "Timed-out form %s has no workflow_run_id; skipping resume",record.form_id,)except Exception:diff --git a/api/tests/unit_tests/clients/agent_backend/test_event_adapter.py b/api/tests/unit_tests/clients/agent_backend/test_event_adapter.pyindex 623d06b0258..b4fcc34d578 100644--- a/api/tests/unit_tests/clients/agent_backend/test_event_adapter.py+++ b/api/tests/unit_tests/clients/agent_backend/test_event_adapter.py@@ -1,10 +1,7 @@from decimal import Decimal-import pytest-from agenton.compositor import CompositorSessionSnapshotfrom dify_agent.protocol import (AgentRunUsage,- DeferredToolCallPayload,PydanticAIStreamRunEvent,RunCancelledEvent,RunCancelledEventData,@@ -15,11 +12,11 @@ from dify_agent.protocol import (RunSucceededEvent,RunSucceededEventData,)+from dify_agent.protocol.snapshot import SessionSnapshotfrom pydantic_ai.messages import FinalResultEventfrom clients.agent_backend import (AgentBackendAgentMessageDeltaInternalEvent,- AgentBackendDeferredToolCallInternalEvent,AgentBackendInternalEventType,AgentBackendRunCancelledInternalEvent,AgentBackendRunEventAdapter,@@ -78,7 +75,7 @@ def test_event_adapter_maps_pydantic_ai_stream_event_agent_message_delta_annotatdef test_event_adapter_maps_run_succeeded_to_final_output():- snapshot = CompositorSessionSnapshot(layers=[])+ snapshot = SessionSnapshot(layers={})adapted = AgentBackendRunEventAdapter().adapt(RunSucceededEvent(id="3-0",@@ -170,102 +167,6 @@ def test_event_adapter_maps_run_failed_to_failed_result():]-def test_event_adapter_maps_deferred_tool_call_success_to_internal_event():- snapshot = CompositorSessionSnapshot(layers=[])- deferred_tool_call = DeferredToolCallPayload(- tool_call_id="tool-call-1",- tool_name="ask_human",- args={"question": "Need review"},- metadata={"layer_type": "dify.ask_human", "schema_version": 1},- )- adapted = AgentBackendRunEventAdapter().adapt(- RunSucceededEvent(- id="5-0",- run_id="run-1",- data=RunSucceededEventData(deferred_tool_call=deferred_tool_call, session_snapshot=snapshot),- )- )-- assert adapted == [- AgentBackendDeferredToolCallInternalEvent(- run_id="run-1",- source_event_id="5-0",- deferred_tool_call=deferred_tool_call,- message="Need review",- session_snapshot=snapshot,- )- ]---def test_event_adapter_rejects_deferred_tool_call_success_without_payload():- snapshot = CompositorSessionSnapshot(layers=[])-- with pytest.raises(TypeError, match="deferred_tool_call branch is missing payload"):- _ = AgentBackendRunEventAdapter().adapt(- RunSucceededEvent(- id="5-1",- run_id="run-1",- data=RunSucceededEventData(deferred_tool_call=None, session_snapshot=snapshot),- )- )---def test_event_adapter_uses_deferred_tool_call_title_as_pause_message_fallback():- snapshot = CompositorSessionSnapshot(layers=[])- deferred_tool_call = DeferredToolCallPayload(- tool_call_id="tool-call-1",- tool_name="ask_human",- args={"title": "Review required"},- metadata={},- )-- adapted = AgentBackendRunEventAdapter().adapt(- RunSucceededEvent(- id="5-2",- run_id="run-1",- data=RunSucceededEventData(deferred_tool_call=deferred_tool_call, session_snapshot=snapshot),- )- )-- assert adapted == [- AgentBackendDeferredToolCallInternalEvent(- run_id="run-1",- source_event_id="5-2",- deferred_tool_call=deferred_tool_call,- message="Review required",- session_snapshot=snapshot,- )- ]---def test_event_adapter_uses_generic_deferred_tool_call_pause_message_when_args_have_no_label():- snapshot = CompositorSessionSnapshot(layers=[])- deferred_tool_call = DeferredToolCallPayload(- tool_call_id="tool-call-1",- tool_name="ask_human",- args={"question": " ", "title": " "},- metadata={},- )-- adapted = AgentBackendRunEventAdapter().adapt(- RunSucceededEvent(- id="5-3",- run_id="run-1",- data=RunSucceededEventData(deferred_tool_call=deferred_tool_call, session_snapshot=snapshot),- )- )-- assert adapted == [- AgentBackendDeferredToolCallInternalEvent(- run_id="run-1",- source_event_id="5-3",- deferred_tool_call=deferred_tool_call,- message="Agent backend requested external input via deferred tool 'ask_human'.",- session_snapshot=snapshot,- )- ]--def test_event_adapter_maps_run_cancelled_to_terminal_cancelled():adapted = AgentBackendRunEventAdapter().adapt(RunCancelledEvent(diff --git a/api/tests/unit_tests/clients/agent_backend/test_fake_client.py b/api/tests/unit_tests/clients/agent_backend/test_fake_client.pyindex 6ad82633036..6ed717ef502 100644--- a/api/tests/unit_tests/clients/agent_backend/test_fake_client.py+++ b/api/tests/unit_tests/clients/agent_backend/test_fake_client.py@@ -71,20 +71,6 @@ def test_fake_client_cancel_run_returns_cancelled_status():assert cancelled.status == "cancelled"-def test_fake_client_paused_scenario_returns_deferred_tool_call_success_event():- """The API pause scenario follows the Dify Agent deferred-tool wire shape."""- client = FakeAgentBackendRunClient(scenario=FakeAgentBackendScenario.PAUSED)-- status = client.wait_run("fake-run-1")- events = list(client.stream_events("fake-run-1"))-- assert status.status == "succeeded"- assert status.error is None- assert events[-1].type == "run_succeeded"- assert events[-1].data.deferred_tool_call is not None- assert events[-1].data.deferred_tool_call.tool_name == "ask_human"--def test_fake_client_success_wait_run_returns_succeeded_status():"""Covers the default SUCCESS branch of ``wait_run`` directly."""status = FakeAgentBackendRunClient().wait_run("fake-run-1")diff --git a/api/tests/unit_tests/clients/agent_backend/test_request_builder.py b/api/tests/unit_tests/clients/agent_backend/test_request_builder.pyindex 29771083de6..c1da744b4b3 100644--- a/api/tests/unit_tests/clients/agent_backend/test_request_builder.py+++ b/api/tests/unit_tests/clients/agent_backend/test_request_builder.py@@ -1,30 +1,13 @@from typing import Any, castimport pytest-from agenton.layers import ExitIntent-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig-from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID-from dify_agent.layers.dify_core_tools import (- DIFY_CORE_TOOLS_LAYER_TYPE_ID,- DifyCoreToolConfig,- DifyCoreToolsLayerConfig,-)-from dify_agent.layers.dify_plugin import (- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,- DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,- DifyPluginLLMLayerConfig,- DifyPluginToolConfig,- DifyPluginToolsLayerConfig,-)-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig-from dify_agent.layers.knowledge import DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID, DifyKnowledgeBaseLayerConfig-from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID-from dify_agent.layers.shell import DIFY_SHELL_LAYER_TYPE_ID, DifyShellEnvVarConfig, DifyShellLayerConfig-from dify_agent.layers.user_prompt import (- DIFY_USER_PROMPT_LAYER_TYPE_ID,- DifyUserPromptDownloadConfig,- DifyUserPromptImageConfig,-)+from dify_agent.layers.dify_core_tools import DifyCoreToolConfig, DifyCoreToolsLayerConfig+from dify_agent.layers.dify_plugin import DifyPluginLLMLayerConfig, DifyPluginToolConfig, DifyPluginToolsLayerConfig+from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig+from dify_agent.layers.knowledge import DifyKnowledgeBaseLayerConfig+from dify_agent.layers.prompt import Config as PromptConfig+from dify_agent.layers.shell import DifyShellEnvVarConfig, DifyShellLayerConfig+from dify_agent.layers.user_prompt import DifyUserPromptDownloadConfig, DifyUserPromptImageConfigfrom dify_agent.protocol import (DIFY_AGENT_HISTORY_LAYER_ID,DIFY_AGENT_MODEL_LAYER_ID,@@ -99,7 +82,6 @@ def test_request_builder_outputs_dify_agent_create_run_request():DIFY_AGENT_MODEL_LAYER_ID,DIFY_AGENT_OUTPUT_LAYER_ID,]- assert request.on_exit.default is ExitIntent.SUSPENDassert request.idempotency_key == "workflow-run-1:node-execution-1"assert request.metadata == {"workflow_id": "workflow-1", "node_id": "node-1"}assert "purpose" not in dumped@@ -109,11 +91,6 @@ def test_request_builder_separates_agent_soul_and_workflow_job_prompt():request = AgentBackendRunRequestBuilder().build_for_workflow_node(_run_input())layers = {layer.name: layer for layer in request.composition.layers}- assert layers[AGENT_SOUL_PROMPT_LAYER_ID].type == PLAIN_PROMPT_LAYER_TYPE_ID- assert layers[AGENT_SOUL_PROMPT_LAYER_ID].metadata["origin"] == "agent_soul"- assert layers[WORKFLOW_NODE_JOB_PROMPT_LAYER_ID].metadata["origin"] == "workflow_node_job"- assert layers[WORKFLOW_USER_PROMPT_LAYER_ID].metadata["origin"] == "workflow_user_prompt"-dumped = request.model_dump(mode="json")assert dumped["composition"]["layers"][0]["config"]["prefix"] == "You are a careful reviewer."workflow_job_config = dumped["composition"]["layers"][1]["config"]@@ -136,7 +113,7 @@ def test_request_builder_forwards_plugin_specific_model_settings_via_extra_body(request = AgentBackendRunRequestBuilder().build_for_workflow_node(run_input)layers = {layer.name: layer for layer in request.composition.layers}- model_config = cast(DifyPluginLLMLayerConfig, layers[DIFY_AGENT_MODEL_LAYER_ID].config)+ model_config = DifyPluginLLMLayerConfig.model_validate(layers[DIFY_AGENT_MODEL_LAYER_ID].config)assert model_config.model_settings == {"temperature": 0.7,@@ -159,7 +136,7 @@ def test_agent_app_request_builder_keeps_agent_soul_prompt_for_snapshot_and_drafrequest = AgentBackendRunRequestBuilder().build_for_agent_app(run_input)layers = {layer.name: layer for layer in request.composition.layers}- prompt_config = cast(PromptLayerConfig, layers[AGENT_SOUL_PROMPT_LAYER_ID].config)+ prompt_config = PromptConfig.model_validate(layers[AGENT_SOUL_PROMPT_LAYER_ID].config)assert prompt_config.prefix == original_prompt@@ -175,7 +152,7 @@ def test_agent_app_request_builder_wraps_agent_soul_prompt_for_build_draft():request = AgentBackendRunRequestBuilder().build_for_agent_app(run_input)layers = {layer.name: layer for layer in request.composition.layers}- prompt_config = cast(PromptLayerConfig, layers[AGENT_SOUL_PROMPT_LAYER_ID].config)+ prompt_config = PromptConfig.model_validate(layers[AGENT_SOUL_PROMPT_LAYER_ID].config)assert prompt_config.prefix != original_promptassert prompt_config.prefix.startswith("You are running in build mode.")assert "```text\nYou are Iris.\n```" in prompt_config.prefix@@ -192,7 +169,7 @@ def test_agent_app_request_builder_uses_longer_fence_for_build_draft_prompt_bodyrequest = AgentBackendRunRequestBuilder().build_for_agent_app(run_input)layers = {layer.name: layer for layer in request.composition.layers}- prompt_config = cast(PromptLayerConfig, layers[AGENT_SOUL_PROMPT_LAYER_ID].config)+ prompt_config = PromptConfig.model_validate(layers[AGENT_SOUL_PROMPT_LAYER_ID].config)assert "````text" in prompt_config.prefixassert "```python" in prompt_config.prefix@@ -201,19 +178,17 @@ def test_request_builder_sets_model_and_output_layer_contract_ids():request = AgentBackendRunRequestBuilder().build_for_workflow_node(_run_input())layers = {layer.name: layer for layer in request.composition.layers}- assert layers[DIFY_EXECUTION_CONTEXT_LAYER_ID].type == DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID- execution_context_config = cast(DifyExecutionContextLayerConfig, layers[DIFY_EXECUTION_CONTEXT_LAYER_ID].config)+ execution_context_config = DifyExecutionContextLayerConfig.model_validate(+ layers[DIFY_EXECUTION_CONTEXT_LAYER_ID].config+ )assert execution_context_config.user_id == "user-1"assert execution_context_config.user_from == "account"assert execution_context_config.agent_mode == "workflow_run"assert execution_context_config.invoke_from == "debugger"- assert layers[DIFY_AGENT_HISTORY_LAYER_ID].type == PYDANTIC_AI_HISTORY_LAYER_TYPE_ID- assert layers[DIFY_AGENT_MODEL_LAYER_ID].type == DIFY_PLUGIN_LLM_LAYER_TYPE_ID- model_config = cast(DifyPluginLLMLayerConfig, layers[DIFY_AGENT_MODEL_LAYER_ID].config)+ model_config = DifyPluginLLMLayerConfig.model_validate(layers[DIFY_AGENT_MODEL_LAYER_ID].config)assert model_config.plugin_id == "langgenius/openai"assert "credentials" not in model_config.model_dump(mode="json")- assert layers[DIFY_AGENT_MODEL_LAYER_ID].deps == {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}- assert layers[DIFY_AGENT_OUTPUT_LAYER_ID].type == DIFY_OUTPUT_LAYER_TYPE_ID+ assert layers[DIFY_AGENT_MODEL_LAYER_ID].config["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_IDdef test_request_builder_adds_dify_plugin_tools_layer_when_configured():@@ -238,9 +213,8 @@ def test_request_builder_adds_dify_plugin_tools_layer_when_configured():request = AgentBackendRunRequestBuilder().build_for_workflow_node(run_input)layers = {layer.name: layer for layer in request.composition.layers}- assert layers[DIFY_PLUGIN_TOOLS_LAYER_ID].type == DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID- assert layers[DIFY_PLUGIN_TOOLS_LAYER_ID].deps == {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}- tools_config = cast(DifyPluginToolsLayerConfig, layers[DIFY_PLUGIN_TOOLS_LAYER_ID].config)+ assert layers[DIFY_PLUGIN_TOOLS_LAYER_ID].config["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_ID+ tools_config = DifyPluginToolsLayerConfig.model_validate(layers[DIFY_PLUGIN_TOOLS_LAYER_ID].config)assert tools_config.tools[0].tool_name == "current_time"@@ -264,8 +238,7 @@ def test_request_builder_adds_dify_core_tools_layer_when_configured():request = AgentBackendRunRequestBuilder().build_for_workflow_node(run_input)layers = {layer.name: layer for layer in request.composition.layers}- assert layers[DIFY_CORE_TOOLS_LAYER_ID].type == DIFY_CORE_TOOLS_LAYER_TYPE_ID- assert layers[DIFY_CORE_TOOLS_LAYER_ID].deps == {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}+ assert layers[DIFY_CORE_TOOLS_LAYER_ID].config["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_IDdef test_request_builder_adds_knowledge_layer_when_configured():@@ -288,9 +261,8 @@ def test_request_builder_adds_knowledge_layer_when_configured():layers = {layer.name: layer for layer in request.composition.layers}assert DIFY_KNOWLEDGE_BASE_LAYER_ID in layers- assert layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].type == DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID- assert layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].deps == {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}- knowledge_config = cast(DifyKnowledgeBaseLayerConfig, layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].config)+ assert layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].config["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_ID+ knowledge_config = DifyKnowledgeBaseLayerConfig.model_validate(layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].config)assert knowledge_config.sets[0].dataset_ids == ["dataset-1"]@@ -359,11 +331,11 @@ def test_workflow_request_builder_adds_shell_layer_when_include_shell():assert DIFY_SHELL_LAYER_ID in layersshell = layers[DIFY_SHELL_LAYER_ID]- assert shell.type == DIFY_SHELL_LAYER_TYPE_ID# The shell layer depends on execution_context so the agent server can mint# per-command Agent Stub env for sandbox CLI forwarding.- assert shell.deps == {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID, "runtime": "runtime"}- shell_config = cast(DifyShellLayerConfig, shell.config)+ assert shell.config["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_ID+ assert shell.config["runtime"] == "runtime"+ shell_config = DifyShellLayerConfig.model_validate(shell.config)assert shell_config.env[0].name == "PROJECT_NAME"@@ -390,14 +362,13 @@ def test_agent_app_request_builder_emits_multimodal_user_prompt_layer():request = AgentBackendRunRequestBuilder().build_for_agent_app(run_input)layer = next(layer for layer in request.composition.layers if layer.name == "agent_app_user_prompt")- assert layer.type == DIFY_USER_PROMPT_LAYER_TYPE_ID- assert layer.config.text == "List files."- assert layer.config.files == run_input.user_files+ assert layer.config["text"] == "List files."+ assert layer.config["files"] == [f.model_dump(mode="json") for f in run_input.user_files]restored_request = CreateRunRequest.model_validate_json(request.model_dump_json())restored_layer = next(layer for layer in restored_request.composition.layers if layer.name == "agent_app_user_prompt")- assert restored_layer.config == layer.config.model_dump(mode="json")+ assert restored_layer.config == layer.configassert "locators" not in restored_layer.config@@ -438,7 +409,7 @@ def test_agent_app_request_builder_keeps_build_draft_prompt_when_agent_soul_promrequest = AgentBackendRunRequestBuilder().build_for_agent_app(run_input)layers = {layer.name: layer for layer in request.composition.layers}- prompt_config = cast(PromptLayerConfig, layers[AGENT_SOUL_PROMPT_LAYER_ID].config)+ prompt_config = PromptConfig.model_validate(layers[AGENT_SOUL_PROMPT_LAYER_ID].config)assert "You are running in build mode." in prompt_config.prefixassert "No task prompt was provided." in prompt_config.prefix@@ -451,12 +422,9 @@ def test_agent_app_request_builder_adds_shell_layer_when_include_shell():layers = {layer.name: layer for layer in request.composition.layers}assert DIFY_SHELL_LAYER_ID in layers- assert layers[DIFY_SHELL_LAYER_ID].type == DIFY_SHELL_LAYER_TYPE_ID- assert layers[DIFY_SHELL_LAYER_ID].deps == {- "execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID,- "runtime": "runtime",- }- shell_config = cast(DifyShellLayerConfig, layers[DIFY_SHELL_LAYER_ID].config)+ assert layers[DIFY_SHELL_LAYER_ID].config["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_ID+ assert layers[DIFY_SHELL_LAYER_ID].config["runtime"] == "runtime"+ shell_config = DifyShellLayerConfig.model_validate(layers[DIFY_SHELL_LAYER_ID].config)assert shell_config.env[0].name == "APP_ENV"@@ -480,52 +448,6 @@ def test_agent_app_request_builder_adds_knowledge_layer_when_configured():layers = {layer.name: layer for layer in request.composition.layers}assert DIFY_KNOWLEDGE_BASE_LAYER_ID in layers- assert layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].type == DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID- assert layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].deps == {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}- knowledge_config = cast(DifyKnowledgeBaseLayerConfig, layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].config)+ assert layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].config["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_ID+ knowledge_config = DifyKnowledgeBaseLayerConfig.model_validate(layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].config)assert knowledge_config.sets[0].dataset_ids == ["dataset-1", "dataset-2"]---# ── ENG-635 / ENG-638: ask_human layer injection + deferred_tool_results ─────---def test_ask_human_layer_injected_when_configured():- from dify_agent.layers.ask_human import DIFY_ASK_HUMAN_LAYER_TYPE_ID, DifyAskHumanLayerConfig-- from clients.agent_backend.request_builder import DIFY_ASK_HUMAN_LAYER_ID-- run_input = _run_input().model_copy(update={"ask_human_config": DifyAskHumanLayerConfig()})- request = AgentBackendRunRequestBuilder().build_for_workflow_node(run_input)-- layers = {layer.name: layer for layer in request.composition.layers}- assert DIFY_ASK_HUMAN_LAYER_ID in layers- assert layers[DIFY_ASK_HUMAN_LAYER_ID].type == DIFY_ASK_HUMAN_LAYER_TYPE_ID- # the deferred tool needs the history layer to resume, so history must precede it- names = [layer.name for layer in request.composition.layers]- assert names.index(DIFY_AGENT_HISTORY_LAYER_ID) < names.index(DIFY_ASK_HUMAN_LAYER_ID)---def test_no_ask_human_layer_when_unconfigured():- from clients.agent_backend.request_builder import DIFY_ASK_HUMAN_LAYER_ID-- request = AgentBackendRunRequestBuilder().build_for_workflow_node(_run_input())- assert all(layer.name != DIFY_ASK_HUMAN_LAYER_ID for layer in request.composition.layers)---def test_deferred_tool_results_threaded_into_request():- from dify_agent.protocol import DeferredToolResultsPayload-- payload = DeferredToolResultsPayload(- calls={- "tool-call-1": {- "status": "submitted",- "action": {"id": "submit", "label": "Submit"},- "values": {"x": "y"},- }- }- )- run_input = _run_input().model_copy(update={"deferred_tool_results": payload})- request = AgentBackendRunRequestBuilder().build_for_workflow_node(run_input)-- assert request.deferred_tool_results is not None- assert "tool-call-1" in request.deferred_tool_results.callsdiff --git a/api/tests/unit_tests/controllers/console/agent/test_agent_controllers.py b/api/tests/unit_tests/controllers/console/agent/test_agent_controllers.pyindex 2e2eae45a68..cb71e5ebea7 100644--- a/api/tests/unit_tests/controllers/console/agent/test_agent_controllers.py+++ b/api/tests/unit_tests/controllers/console/agent/test_agent_controllers.py@@ -54,7 +54,7 @@ from controllers.console.agent.roster import (from controllers.console.app import completion as completion_controllerfrom controllers.console.app import message as message_controllerfrom controllers.console.app.completion import AgentBuildChatFinalizeApi, AgentChatMessageApi, AgentChatMessageStopApi-from controllers.console.app.error import AgentSessionConfigurationChangedError, CompletionRequestError+from controllers.console.app.error import CompletionRequestErrorfrom controllers.console.app.message import (AgentChatMessageListApi,AgentMessageApi,@@ -1754,39 +1754,6 @@ def test_agent_chat_stream_preflight_raises_first_error_event() -> None:assert stream.closed is True-def test_agent_chat_stream_preflight_preserves_session_configuration_error() -> None:- class ClosableStream:- def __init__(self) -> None:- self.closed = False- self._chunks = iter(- [- "event: ping\n\n",- (- 'data: {"event":"error","message":"Start a new conversation to continue.",'- '"code":"agent_session_configuration_changed","status":409}\n\n'- ),- ]- )-- def __iter__(self) -> Self:- return self-- def __next__(self) -> str:- return next(self._chunks)-- def close(self) -> None:- self.closed = True-- stream = ClosableStream()- with pytest.raises(AgentSessionConfigurationChangedError) as exc_info:- completion_controller._raise_agent_stream_error_before_response(stream)- assert exc_info.value.code == 409- assert exc_info.value.error_code == "agent_session_configuration_changed"- assert exc_info.value.description is not None- assert "Start a new conversation" in exc_info.value.description- assert stream.closed is True--def test_agent_chat_stream_preflight_preserves_first_normal_event() -> None:stream = iter(["event: ping\n\n", 'data: {"event":"message","answer":"hello"}\n\n', 'data: {"event":"message_end"}\n\n']diff --git a/api/tests/unit_tests/core/app/apps/agent_app/test_app_generator.py b/api/tests/unit_tests/core/app/apps/agent_app/test_app_generator.pyindex 93d9a182aa3..a4e2cc02ac4 100644--- a/api/tests/unit_tests/core/app/apps/agent_app/test_app_generator.py+++ b/api/tests/unit_tests/core/app/apps/agent_app/test_app_generator.py@@ -24,7 +24,6 @@ from core.app.apps.agent_app.app_generator import (AgentAppGenerator,AgentAppGeneratorError,)-from core.app.apps.agent_app.errors import AgentSessionSnapshotIncompatibleErrorfrom core.app.apps.exc import GenerateTaskStoppedErrorfrom core.app.entities.app_invoke_entities import InvokeFrom, UserFromfrom core.app.entities.queue_entities import QueueAnnotationReplyEvent@@ -381,7 +380,6 @@ class TestGenerateWorker:mocker: MockerFixture,queue_manager,*,- is_resume=False,query="query",session_scope_config_version_id="s",files=(),@@ -404,7 +402,6 @@ class TestGenerateWorker:conversation_id="conv",message_id="msg",user_from=UserFrom.END_USER,- is_resume=is_resume,)def test_happy_path_runs_backend(self, generator: AgentAppGenerator, mocker: MockerFixture):@@ -480,20 +477,6 @@ class TestGenerateWorker:assert events == ["commit", "publish"]runner.run.assert_not_called()- def test_resume_skips_input_guards_and_consumes_reply(self, generator, mocker: MockerFixture):- # ENG-638 (review): on resume the replayed query is NOT new end-user input.- # Input guards must be skipped, even if moderation/annotation would match,- # so the run continues and the human reply (deferred_tool_results) is used.- runner, _ = self._wire(generator, mocker, handled=True) # guards WOULD short-circuit- queue_manager = mocker.MagicMock()-- self._call(generator, mocker, queue_manager, is_resume=True, query="the approved reply")-- generator._run_input_guards.assert_not_called()- runner.run.assert_called_once()- # the replayed paused-turn query flows straight to the runner (snapshot match)- assert runner.run.call_args.kwargs["query"] == "the approved reply"-def test_generate_task_stopped_is_swallowed(self, generator, mocker: MockerFixture):self._wire(generator, mocker, run_side_effect=GenerateTaskStoppedError())queue_manager = mocker.MagicMock()@@ -505,123 +488,3 @@ class TestGenerateWorker:queue_manager = mocker.MagicMock()self._call(generator, mocker, queue_manager)assert queue_manager.publish_error.called-- def test_session_configuration_change_is_published_without_unknown_error_log(- self,- generator: AgentAppGenerator,- mocker: MockerFixture,- ) -> None:- error = AgentSessionSnapshotIncompatibleError()- self._wire(generator, mocker, run_side_effect=error)- queue_manager = mocker.MagicMock()- info_log = mocker.patch(f"{MODULE}.logger.info")- exception_log = mocker.patch(f"{MODULE}.logger.exception")-- self._call(generator, mocker, queue_manager)-- queue_manager.publish_error.assert_called_once_with(error, module.PublishFrom.APPLICATION_MANAGER)- info_log.assert_called_once()- exception_log.assert_not_called()---class TestResumeAfterFormSubmission:- """ENG-638: a resume turn re-sends the paused turn's original query so the- composition's user-prompt layer matches the suspended snapshot (never blank)."""-- def _wire(self, generator, mocker: MockerFixture):- generator._resolve_agent = mocker.MagicMock(return_value=(_agent(), "snap1", "draft", AgentSoulConfig()))- generator._init_generate_records = mocker.MagicMock(return_value=(_conversation(), _message()))- generator._handle_response = mocker.MagicMock(return_value=None)- get_conversation = mocker.patch(- f"{MODULE}.ConversationService.get_conversation",- return_value=_conversation(),- )- mocker.patch(f"{MODULE}.AgentAppConfigManager.get_app_config", return_value=mocker.MagicMock(variables=[]))- mocker.patch(f"{MODULE}.load_annotation_reply_config", return_value={"enabled": False})- mocker.patch(f"{MODULE}.ModelConfigConverter.convert", return_value=mocker.MagicMock())- mocker.patch(f"{MODULE}.TraceQueueManager", return_value=mocker.MagicMock())- mocker.patch(f"{MODULE}.MessageBasedAppQueueManager", return_value=mocker.MagicMock())- mocker.patch(f"{MODULE}.threading.Thread", return_value=mocker.MagicMock())- generator._resolve_resume_draft = mocker.MagicMock(return_value=(None, None))- return (- mocker.patch(- f"{MODULE}.AgentAppGenerateEntity", return_value=mocker.MagicMock(task_id="t", user_id="user")- ),- get_conversation,- )-- def test_resume_resends_paused_turn_query(self, generator, mocker: MockerFixture):- entity, get_conversation = self._wire(generator, mocker)- session = _session()- config = AppModelConfig(app_id="app1")- config.id = "config-1"- session.add_all([config, _conversation(), _message(query="original question")])- session.commit()- app_model = _app(app_model_config_id=config.id)- user = _account()-- generator.resume_after_form_submission(- app_model=app_model,- user=user,- conversation_id="conv",- form_id="form-1",- invoke_from=InvokeFrom.WEB_APP,- session=session,- )-- # The paused turn's query is re-sent verbatim — never blank.- assert entity.call_args.kwargs["query"] == "original question"- assert "agent_runtime_exit_intent" not in entity.call_args.kwargs- get_conversation.assert_called_once_with(- app_model=app_model,- conversation_id="conv",- user=user,- session=session,- )- assert generator._init_generate_records.call_args.kwargs["session"] is session- assert session.get(AppModelConfig, "config-1") is config- assert generator._resolve_agent.call_args.kwargs["session"] is session-- def test_resume_falls_back_to_placeholder_when_no_paused_message(self, generator, mocker: MockerFixture):- entity, _ = self._wire(generator, mocker)- session = _session()-- generator.resume_after_form_submission(- app_model=_app(),- user=_account(),- conversation_id="conv",- form_id="form-1",- invoke_from=InvokeFrom.WEB_APP,- session=session,- )-- # No prior user message -> a non-blank placeholder, still never blank.- assert entity.call_args.kwargs["query"] == "(resumed)"-- def test_resume_uses_build_draft_for_debugger_conversation(self, generator, mocker: MockerFixture):- self._wire(generator, mocker)- conversation = _conversation(invoke_from=InvokeFrom.DEBUGGER)- mocker.patch(f"{MODULE}.ConversationService.get_conversation", return_value=conversation)- generator._resolve_resume_draft.return_value = ("debug_build", "draft-build-1")- account_user = Account(name="Test Account", email="[email protected]")- account_user.id = "user"- session = _session()- config = AppModelConfig(app_id="app1")- config.id = "config-1"- session.add_all([config, conversation, _message(query="original question")])- session.commit()- app_model = _app(app_model_config_id=config.id)-- generator.resume_after_form_submission(- app_model=app_model,- user=account_user,- conversation_id="conv",- form_id="form-1",- invoke_from=InvokeFrom.DEBUGGER,- session=session,- )-- assert generator._resolve_agent.call_args.kwargs["draft_type"] == "debug_build"- assert generator._resolve_agent.call_args.kwargs["draft_id"] == "draft-build-1"- assert generator._resolve_agent.call_args.kwargs["session"] is session- assert generator._resolve_agent.call_args.kwargs["conversation"] is conversationdiff --git a/api/tests/unit_tests/core/app/apps/agent_app/test_app_runner.py b/api/tests/unit_tests/core/app/apps/agent_app/test_app_runner.pyindex 1099a252dea..78f060d9df5 100644--- a/api/tests/unit_tests/core/app/apps/agent_app/test_app_runner.py+++ b/api/tests/unit_tests/core/app/apps/agent_app/test_app_runner.py@@ -12,9 +12,6 @@ from typing import Any, overridefrom unittest.mock import MagicMockimport pytest-from agenton.compositor import CompositorSessionSnapshot, LayerSessionSnapshot-from agenton.layers import LifecycleState-from dify_agent.layers.ask_human import AskHumanToolResultfrom dify_agent.protocol import (AgentRunUsage,CancelRunRequest,@@ -30,6 +27,7 @@ from dify_agent.protocol import (RunSucceededEvent,RunSucceededEventData,)+from dify_agent.protocol.snapshot import SessionSnapshotfrom pydantic_ai.messages import (FunctionToolCallEvent,FunctionToolResultEvent,@@ -53,7 +51,6 @@ from clients.agent_backend import ()from core.app.apps.agent_app import app_runner as app_runner_modulefrom core.app.apps.agent_app.app_runner import AgentAppRunner-from core.app.apps.agent_app.errors import AgentSessionSnapshotIncompatibleErrorfrom core.app.apps.agent_app.runtime_request_builder import AgentAppRuntimeBuildContext, AgentAppRuntimeRequestBuilderfrom core.app.apps.agent_app.session_store import AgentAppSessionScope, StoredAgentAppSessionfrom core.app.apps.exc import GenerateTaskStoppedError@@ -64,7 +61,6 @@ from core.app.entities.queue_entities import (QueueLLMChunkEvent,QueueMessageEndEvent,)-from core.workflow.nodes.agent_v2.ask_human_resume import AskHumanResumeOutcomefrom core.workflow.nodes.agent_v2.dify_tools_builder import WorkflowAgentToolLayersfrom graphon.model_runtime.entities.llm_entities import LLMResult, LLMUsagefrom graphon.model_runtime.errors.invoke import InvokeRateLimitError@@ -306,7 +302,7 @@ class _StreamingFakeAgentBackendRunClient(FakeAgentBackendRunClient):created_at=created_at,data=RunSucceededEventData(output={"text": "hello agent"},- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),usage=AgentRunUsage(prompt_tokens=3,prompt_unit_price=Decimal(5),@@ -382,7 +378,7 @@ class _StreamingSingleAgentMessageDeltaFakeAgentBackendRunClient(FakeAgentBackencreated_at=created_at,data=RunSucceededEventData(output={"text": "hello agent"},- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),)@@ -405,7 +401,7 @@ class _NullOutputFakeAgentBackendRunClient(FakeAgentBackendRunClient):created_at=created_at,data=RunSucceededEventData(output=None,- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),)@@ -435,7 +431,7 @@ class _StreamingTextNullOutputFakeAgentBackendRunClient(FakeAgentBackendRunCliencreated_at=created_at,data=RunSucceededEventData(output=None,- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),)@@ -472,7 +468,7 @@ class _AgentAnswerStreamingFakeAgentBackendRunClient(FakeAgentBackendRunClient):created_at=created_at,data=RunSucceededEventData(output={"text": "final answer"},- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),)@@ -520,7 +516,7 @@ class _ProcessStreamingFakeAgentBackendRunClient(FakeAgentBackendRunClient):created_at=created_at,data=RunSucceededEventData(output={"text": "final answer"},- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),)@@ -528,7 +524,7 @@ class _ProcessStreamingFakeAgentBackendRunClient(FakeAgentBackendRunClient):class _FakeSessionStore:def __init__(self,- loaded: CompositorSessionSnapshot | None = None,+ loaded: SessionSnapshot | None = None,loaded_session: StoredAgentAppSession | None = None,binding_id: str = "binding-1",workspace_id: str = "workspace-1",@@ -544,7 +540,7 @@ class _FakeSessionStore:tuple[AgentAppSessionScope,str,- CompositorSessionSnapshot | None,+ SessionSnapshot | None,str | None,str | None,]@@ -567,17 +563,15 @@ class _FakeSessionStore:*,scope: AgentAppSessionScope,binding_id: str,- snapshot: CompositorSessionSnapshot | None,- pending_form_id: str | None = None,- pending_tool_call_id: str | None = None,+ snapshot: SessionSnapshot | None,) -> None:- self.saved.append((scope, binding_id, snapshot, pending_form_id, pending_tool_call_id))+ self.saved.append((scope, binding_id, snapshot))class _ExplodingSessionStore(_FakeSessionStore):- def __init__(self, loaded: CompositorSessionSnapshot | None = None) -> None:+ def __init__(self, loaded: SessionSnapshot | None = None) -> None:super().__init__(loaded=loaded)- self.save_attempts: list[CompositorSessionSnapshot | None] = []+ self.save_attempts: list[SessionSnapshot | None] = []@overridedef save_active_snapshot(@@ -585,11 +579,9 @@ class _ExplodingSessionStore(_FakeSessionStore):*,scope: AgentAppSessionScope,binding_id: str,- snapshot: CompositorSessionSnapshot | None,- pending_form_id: str | None = None,- pending_tool_call_id: str | None = None,+ snapshot: SessionSnapshot | None,) -> None:- del scope, binding_id, pending_form_id, pending_tool_call_id+ del scope, binding_idself.save_attempts.append(snapshot)raise RuntimeError("session save failed")@@ -630,7 +622,7 @@ def _dify_ctx() -> DifyRunContext:)-def _compatible_session_snapshot() -> CompositorSessionSnapshot:+def _compatible_session_snapshot() -> SessionSnapshot:request = (AgentAppRuntimeRequestBuilder(dify_tools_builder=_NoToolsBuilder(), # type: ignore[arg-type]@@ -650,12 +642,7 @@ def _compatible_session_snapshot() -> CompositorSessionSnapshot:).request)- return CompositorSessionSnapshot(- layers=[- LayerSessionSnapshot(name=layer.name, lifecycle_state=LifecycleState.SUSPENDED, runtime_state={})- for layer in request.composition.layers- ]- )+ return SessionSnapshot(layers={layer.name: {} for layer in request.composition.layers})def _runner(@@ -744,7 +731,6 @@ def test_successful_turn_publishes_chunk_and_message_end_and_saves_session() ->_run(_runner(client, store), qm)assert client.request is not None- assert client.request.on_exit.default.value == "suspend"# One LLM chunk + one message-end, carrying the backend's answer text.chunk_events = [e for e in qm.events if isinstance(e, QueueLLMChunkEvent)]end_events = [e for e in qm.events if isinstance(e, QueueMessageEndEvent)]@@ -756,14 +742,11 @@ def test_successful_turn_publishes_chunk_and_message_end_and_saves_session() ->assert _saved_user_query(qm) == "hello"# The conversation session snapshot is persisted for multi-turn continuity.assert store.saved- saved_scope, saved_binding_id, saved_snapshot, pending_form_id, pending_tool_call_id = store.saved[0]+ saved_scope, saved_binding_id, saved_snapshot = store.saved[0]assert saved_scope.conversation_id == "conv-1"assert saved_scope.agent_config_snapshot_id == "snap-1"assert saved_binding_id == "binding-1"assert saved_snapshot is not None- # A successful turn carries no ask_human pause correlation.- assert pending_form_id is None- assert pending_tool_call_id is Nonedef test_turn_uses_resolved_backend_binding_before_backend_invocation() -> None:@@ -1355,19 +1338,17 @@ def test_prior_session_snapshot_is_threaded_into_request() -> None:assert client.request.session_snapshot is prior-def test_incompatible_session_snapshot_is_rejected_before_backend_invocation() -> None:+def test_snapshot_with_removed_optional_prompt_is_forwarded_to_runtime() -> None:compatible = _compatible_session_snapshot()- stale = CompositorSessionSnapshot(- layers=[layer for layer in compatible.layers if layer.name != "agent_soul_prompt"]+ snapshot = SessionSnapshot(+ layers={name: state for name, state in compatible.layers.items() if name != "agent_soul_prompt"})client = FakeAgentBackendRunClient()- store = _FakeSessionStore(loaded=stale)-- with pytest.raises(AgentSessionSnapshotIncompatibleError, match="Start a new conversation"):- _run(_runner(client, store), _FakeQueueManager())-- assert client.request is None- assert store.saved == []+ store = _FakeSessionStore(loaded=snapshot)+ _run(_runner(client, store), _FakeQueueManager())+ assert client.request is not None+ assert client.request.session_snapshot is snapshot+ assert len(store.saved) == 1def test_debug_session_scope_can_reuse_conversation_across_config_snapshots() -> None:@@ -1405,7 +1386,7 @@ def test_failed_run_raises_agent_backend_error() -> None:_run(_runner(client, store), qm)# No message-end on failure; post-exit session state is still saved.assert not [e for e in qm.events if isinstance(e, QueueMessageEndEvent)]- assert store.saved[0][2] == CompositorSessionSnapshot(layers=[])+ assert store.saved[0][2] == SessionSnapshot(layers={})def test_failed_run_persists_partial_usage(sqlite_session: Session) -> None:@@ -1477,7 +1458,7 @@ def test_snapshot_save_failure_preserves_original_app_outcome(outcome: str) -> Nwith pytest.raises(expected_error, match="fake failure" if outcome == "failed" else None):_run(_runner(client, store), queue_manager)- assert store.save_attempts == [CompositorSessionSnapshot(layers=[])]+ assert store.save_attempts == [SessionSnapshot(layers={})]@pytest.mark.parametrize(@@ -1573,7 +1554,7 @@ def test_stopped_task_waits_for_cancelled_snapshot_and_saves_session() -> None:assert client.cancelled_run_ids == ["fake-run-1"]assert len(store.saved) == 1- assert store.saved[0][2] == CompositorSessionSnapshot(layers=[])+ assert store.saved[0][2] == SessionSnapshot(layers={})def test_stopped_task_persists_partial_usage(sqlite_session: Session) -> None:@@ -1610,73 +1591,3 @@ def test_terminal_output_to_answer_handles_plain_string_and_dict() -> None:assert AgentAppRunner._terminal_output_to_answer("plain text") == "plain text"assert AgentAppRunner._terminal_output_to_answer({"text": "hi"}) == "hi"assert AgentAppRunner._terminal_output_to_answer({"a": 1}) == '{"a": 1}'---def test_ask_human_pauses_turn_creates_form_and_persists_correlation() -> None:- # ENG-635/637: the PAUSED scenario emits a dify.ask_human deferred call, so- # the chat turn ends by creating a conversation-owned HITL form + saving the- # pause correlation, instead of crashing. Stub the form repo (DB-free).- client = _UsagePausedClient()- store = _FakeSessionStore()- qm = _FakeQueueManager()- runner = _runner(client, store)-- fake_repo = MagicMock()- fake_repo.create_form.return_value = MagicMock(id="form-1")- runner._build_form_repository = lambda dify_context: fake_repo # type: ignore[assignment]-- _run(runner, qm)-- # The conversation-owned form was created and the agent's question surfaced.- fake_repo.create_form.assert_called_once()- created_params = fake_repo.create_form.call_args.args[0]- assert created_params.conversation_id == "conv-1"- assert created_params.workflow_execution_id is None- assert [e for e in qm.events if isinstance(e, QueueMessageEndEvent)]- assert _saved_user_query(qm) == "hello"- assert _llm_result(qm).usage.total_tokens == 8- # The pause correlation is persisted so a form submission can resume the run.- assert store.saved- assert store.saved[0][3] == "form-1"- assert store.saved[0][4] == "fake-ask-human-1"---def test_submitted_form_resumes_turn_with_deferred_tool_results(monkeypatch: pytest.MonkeyPatch) -> None:- # ENG-638: a turn that runs while a pending form is answered threads the- # human's reply into the request as deferred_tool_results.- snapshot = _compatible_session_snapshot()- stored = StoredAgentAppSession(- scope=AgentAppSessionScope(- tenant_id="tenant-1",- app_id="app-1",- conversation_id="conv-1",- agent_id="agent-1",- agent_config_snapshot_id="snap-1",- home_snapshot_id="home-1",- ),- binding_id="binding-1",- workspace_id="workspace-1",- backend_binding_ref="backend-binding-1",- session_snapshot=snapshot,- pending_form_id="form-1",- pending_tool_call_id="call-1",- )- store = _FakeSessionStore(loaded_session=stored)- submitted = AskHumanResumeOutcome(deferred_result=AskHumanToolResult(status="submitted", values={"ok": True}))- monkeypatch.setattr(- "core.app.apps.agent_app.app_runner.resolve_ask_human_form",- lambda **_kwargs: submitted,- )-- client = FakeAgentBackendRunClient() # SUCCESS -> the resumed run completes- qm = _FakeQueueManager()- _run(_runner(client, store), qm)-- assert client.request is not None- assert client.request.deferred_tool_results is not None- assert set(client.request.deferred_tool_results.calls) == {"call-1"}- # ENG-638: the resume composition must keep the user-prompt layer so it- # matches the suspended snapshot's layer names (the agent backend rejects a- # mismatch). A resume therefore re-sends a non-blank query, never blank.- layer_names = [layer.name for layer in client.request.composition.layers]- assert "agent_app_user_prompt" in layer_namesdiff --git a/api/tests/unit_tests/core/app/apps/agent_app/test_runtime_request_builder.py b/api/tests/unit_tests/core/app/apps/agent_app/test_runtime_request_builder.pyindex b93f0e6ff90..f7a122427f4 100644--- a/api/tests/unit_tests/core/app/apps/agent_app/test_runtime_request_builder.py+++ b/api/tests/unit_tests/core/app/apps/agent_app/test_runtime_request_builder.py@@ -6,13 +6,14 @@ from __future__ import annotationsfrom types import SimpleNamespaceimport pytest-from agenton.compositor import CompositorSessionSnapshot, LayerSessionSnapshot-from agenton.layers import LifecycleState-from dify_agent.layers.config import DifyConfigSkillConfig+from dify_agent.layers.config import DifyConfigLayerConfig, DifyConfigSkillConfigfrom dify_agent.layers.dify_core_tools import DifyCoreToolConfig, DifyCoreToolsLayerConfig-from dify_agent.layers.dify_plugin import DifyPluginToolConfig, DifyPluginToolsLayerConfig+from dify_agent.layers.dify_plugin import DifyPluginLLMLayerConfig, DifyPluginToolConfig, DifyPluginToolsLayerConfigfrom dify_agent.layers.execution_context import DifyExecutionContextLayerConfig+from dify_agent.layers.knowledge import DifyKnowledgeBaseLayerConfig+from dify_agent.layers.prompt import Config as PromptConfigfrom dify_agent.layers.user_prompt import DifyUserPromptLayerConfig+from dify_agent.protocol.snapshot import SessionSnapshotfrom clients.agent_backend import (DIFY_CONFIG_LAYER_ID,@@ -23,7 +24,6 @@ from clients.agent_backend import (AgentBackendRunRequestBuilder,)from clients.agent_backend.request_builder import DIFY_SHELL_LAYER_ID-from core.app.apps.agent_app.errors import AgentSessionSnapshotIncompatibleErrorfrom core.app.apps.agent_app.runtime_request_builder import (AgentAppRuntimeBuildContext,AgentAppRuntimeRequestBuilder,@@ -90,7 +90,6 @@ class TestBuildForAgentApp:]assert "workflow_node_job_prompt" not in names# Agent App keeps layers alive across turns by default.- assert request.on_exit.default.value == "suspend"def test_blank_user_prompt_rejected(self):with pytest.raises(ValueError, match="must not be blank"):@@ -171,7 +170,7 @@ def _ctx(*,query: str = "hello",agent_config_version_kind: str = "snapshot",- session_snapshot: CompositorSessionSnapshot | None = None,+ session_snapshot: SessionSnapshot | None = None,files: tuple[File, ...] = (),image_detail_config: ImagePromptMessageContent.DETAIL | None = None,) -> AgentAppRuntimeBuildContext:@@ -238,13 +237,8 @@ def _document_file() -> File:)-def _snapshot_for_layer_names(layer_names: list[str]) -> CompositorSessionSnapshot:- return CompositorSessionSnapshot(- layers=[- LayerSessionSnapshot(name=name, lifecycle_state=LifecycleState.SUSPENDED, runtime_state={})- for name in layer_names- ]- )+def _snapshot_for_layer_names(layer_names: list[str]) -> SessionSnapshot:+ return SessionSnapshot(layers={name: {} for name in layer_names})class TestAgentAppRuntimeRequestBuilder:@@ -269,18 +263,17 @@ class TestAgentAppRuntimeRequestBuilder:]# plugin_id / provider normalized for plugin-daemon transport.llm = next(layer for layer in req.composition.layers if layer.name == "llm")- assert llm.config.plugin_id == "langgenius/openai"- assert llm.config.model_provider == "openai"- assert llm.config.context_window_tokens == 32_768+ assert DifyPluginLLMLayerConfig.model_validate(llm.config).plugin_id == "langgenius/openai"+ assert DifyPluginLLMLayerConfig.model_validate(llm.config).model_provider == "openai"+ assert DifyPluginLLMLayerConfig.model_validate(llm.config).context_window_tokens == 32_768assert model_context_window_calls == [(context.dify_context, "langgenius/openai/openai", "gpt-4o-mini")]# execution context carries conversation + agent_app invoke source.exec_ctx = next(layer for layer in req.composition.layers if layer.name == "execution_context")- assert exec_ctx.config.conversation_id == "conv-1"+ assert DifyExecutionContextLayerConfig.model_validate(exec_ctx.config).conversation_id == "conv-1"# Real Dify access context forwarded; agent run mode in agent_mode.- assert exec_ctx.config.user_from == "end-user"- assert exec_ctx.config.invoke_from == "web-app"- assert exec_ctx.config.agent_mode == "agent_app"- assert req.on_exit.default.value == "suspend"+ assert DifyExecutionContextLayerConfig.model_validate(exec_ctx.config).user_from == "end-user"+ assert DifyExecutionContextLayerConfig.model_validate(exec_ctx.config).invoke_from == "web-app"+ assert DifyExecutionContextLayerConfig.model_validate(exec_ctx.config).agent_mode == "agent_app"# LLM credentials are resolved by API and never enter the Agent request.assert "credentials" not in result.redacted_request["composition"]["layers"][-1]["config"]assert result.metadata["conversation_id"] == "conv-1"@@ -418,7 +411,7 @@ class TestAgentAppRuntimeRequestBuilder:("previous_prompt", "current_prompt"),[("", "You are Iris."), ("You are Iris.", "")],)- def test_build_rejects_session_snapshot_after_layer_topology_changes(+ def test_build_preserves_snapshot_when_optional_prompt_modules_change(self,previous_prompt: str,current_prompt: str,@@ -433,18 +426,9 @@ class TestAgentAppRuntimeRequestBuilder:current_soul = _soul_with_model()current_soul.prompt.system_prompt = current_prompt- with pytest.raises(AgentSessionSnapshotIncompatibleError) as exc_info:- builder.build(- _ctx(- current_soul,- agent_config_version_kind="draft",- session_snapshot=snapshot,- )- )-- assert exc_info.value.error_code == "agent_session_configuration_changed"- assert exc_info.value.status_code == 409- assert "Start a new conversation" in str(exc_info.value)+ result = builder.build(_ctx(current_soul, agent_config_version_kind="draft", session_snapshot=snapshot))+ assert result.request.session_snapshot is snapshot+ assert ("agent_soul_prompt" in {s.name for s in result.request.composition.layers}) == bool(current_prompt)def test_build_reuses_session_snapshot_when_config_changes_without_changing_layers(self) -> None:builder = AgentAppRuntimeRequestBuilder(@@ -473,9 +457,9 @@ class TestAgentAppRuntimeRequestBuilder:result = builder.build(_ctx(_soul_with_model(), agent_config_version_kind="build_draft"))prompt_layer = next(layer for layer in result.request.composition.layers if layer.name == "agent_soul_prompt")- assert prompt_layer.config.prefix != _soul_with_model().prompt- assert prompt_layer.config.prefix.startswith("You are running in build mode.")- assert "```text\nYou are Iris.\n```" in prompt_layer.config.prefix+ assert PromptConfig.model_validate(prompt_layer.config).prefix != _soul_with_model().prompt+ assert PromptConfig.model_validate(prompt_layer.config).prefix.startswith("You are running in build mode.")+ assert "```text\nYou are Iris.\n```" in PromptConfig.model_validate(prompt_layer.config).prefixdef test_build_propagates_draft_version_kind_without_wrapping_prompt(self):builder = AgentAppRuntimeRequestBuilder(@@ -490,9 +474,12 @@ class TestAgentAppRuntimeRequestBuilder:)config_layer = next(layer for layer in result.request.composition.layers if layer.name == DIFY_CONFIG_LAYER_ID)- assert prompt_layer.config.prefix == "You are Iris."- assert execution_context.config.agent_config_version_kind == "draft"- assert config_layer.config.config_version.kind == "draft"+ assert PromptConfig.model_validate(prompt_layer.config).prefix == "You are Iris."+ assert (+ DifyExecutionContextLayerConfig.model_validate(execution_context.config).agent_config_version_kind+ == "draft"+ )+ assert DifyConfigLayerConfig.model_validate(config_layer.config).config_version.kind == "draft"def test_build_includes_plugin_tools_layer_returned_by_injected_builder_for_draft(self):soul = _soul_with_model()@@ -565,8 +552,8 @@ class TestAgentAppRuntimeRequestBuilder:result = builder.build(_ctx(soul))llm = next(layer for layer in result.request.composition.layers if layer.name == "llm")- assert llm.config.plugin_id == "langgenius/openai"- assert llm.config.model_provider == "openai"+ assert DifyPluginLLMLayerConfig.model_validate(llm.config).plugin_id == "langgenius/openai"+ assert DifyPluginLLMLayerConfig.model_validate(llm.config).model_provider == "openai"def test_build_normalizes_legacy_three_segment_model_plugin_id(self):soul = _soul_with_model()@@ -578,8 +565,8 @@ class TestAgentAppRuntimeRequestBuilder:result = builder.build(_ctx(soul))llm = next(layer for layer in result.request.composition.layers if layer.name == "llm")- assert llm.config.plugin_id == "langgenius/openai"- assert llm.config.model_provider == "openai"+ assert DifyPluginLLMLayerConfig.model_validate(llm.config).plugin_id == "langgenius/openai"+ assert DifyPluginLLMLayerConfig.model_validate(llm.config).model_provider == "openai"def test_build_maps_agent_soul_knowledge_to_knowledge_layer(self):soul = AgentSoulConfig.model_validate(@@ -613,9 +600,10 @@ class TestAgentAppRuntimeRequestBuilder:result = builder.build(_ctx(soul))knowledge = next(layer for layer in result.request.composition.layers if layer.name == "knowledge")- assert knowledge.type == "dify.knowledge_base"- assert knowledge.deps == {"execution_context": "execution_context"}- dumped_config = knowledge.config.model_dump(mode="json", by_alias=True)+ assert knowledge.config["execution_context"] == "execution_context"+ dumped_config = DifyKnowledgeBaseLayerConfig.model_validate(knowledge.config).model_dump(+ mode="json", by_alias=True+ )knowledge_set = dumped_config["sets"][0]assert [dataset["id"] for dataset in knowledge_set["datasets"]] == ["dataset-1", "dataset-2"]assert knowledge_set["query"] == {"mode": "generated_query", "value": None}@@ -693,18 +681,21 @@ class TestAgentAppConfigLayer:result = builder.build(_ctx(_soul_with_model_and_skill()))config = next(layer for layer in result.request.composition.layers if layer.name == DIFY_CONFIG_LAYER_ID)- assert config.type == "dify.config"- assert config.deps == {"shell": DIFY_SHELL_LAYER_ID}- assert config.config.agent_id == "agent-1"- assert config.config.config_version is not None- assert config.config.config_version.id == "snap-1"- assert config.config.config_version.kind == "snapshot"- assert config.config.config_version.writable is False- assert [skill.name for skill in config.config.skills] == ["tender-analyzer"]- assert [file_ref.name for file_ref in config.config.files] == ["sample.pdf"]- assert config.config.note == "Read the proposal first."- assert config.config.mentioned_skill_names == ["tender-analyzer"]- assert config.config.mentioned_file_names == []+ assert config.config["shell"] == DIFY_SHELL_LAYER_ID+ assert DifyConfigLayerConfig.model_validate(config.config).agent_id == "agent-1"+ assert DifyConfigLayerConfig.model_validate(config.config).config_version is not None+ assert DifyConfigLayerConfig.model_validate(config.config).config_version.id == "snap-1"+ assert DifyConfigLayerConfig.model_validate(config.config).config_version.kind == "snapshot"+ assert DifyConfigLayerConfig.model_validate(config.config).config_version.writable is False+ assert [skill.name for skill in DifyConfigLayerConfig.model_validate(config.config).skills] == [+ "tender-analyzer"+ ]+ assert [file_ref.name for file_ref in DifyConfigLayerConfig.model_validate(config.config).files] == [+ "sample.pdf"+ ]+ assert DifyConfigLayerConfig.model_validate(config.config).note == "Read the proposal first."+ assert DifyConfigLayerConfig.model_validate(config.config).mentioned_skill_names == ["tender-analyzer"]+ assert DifyConfigLayerConfig.model_validate(config.config).mentioned_file_names == []# shell enters first; config uses that shell to materialize mentioned targets.names = [layer.name for layer in result.request.composition.layers]assert names.index(DIFY_SHELL_LAYER_ID) == names.index("execution_context") + 2@@ -719,7 +710,8 @@ class TestAgentAppConfigLayer:result = builder.build(_ctx(_soul_with_model()))layers = {layer.name: layer for layer in result.request.composition.layers}- assert layers[DIFY_CONFIG_LAYER_ID].config.model_dump(mode="json") == {+ assert DifyConfigLayerConfig.model_validate(layers[DIFY_CONFIG_LAYER_ID].config).model_dump(mode="json") == {+ "shell": "shell","agent_id": "agent-1","config_version": {"id": "snap-1", "kind": "snapshot", "writable": False},"skills": [],@@ -729,10 +721,8 @@ class TestAgentAppConfigLayer:"mentioned_skill_names": [],"mentioned_file_names": [],}- assert layers[DIFY_SHELL_LAYER_ID].deps == {- "execution_context": "execution_context",- "runtime": "runtime",- }+ assert layers[DIFY_SHELL_LAYER_ID].config["execution_context"] == "execution_context"+ assert layers[DIFY_SHELL_LAYER_ID].config["runtime"] == "runtime"def test_config_layer_for_build_draft_marks_config_writable(self):builder = AgentAppRuntimeRequestBuilder(@@ -742,7 +732,8 @@ class TestAgentAppConfigLayer:result = builder.build(_ctx(_soul_with_model_and_skill(), agent_config_version_kind="build_draft"))config = next(layer for layer in result.request.composition.layers if layer.name == DIFY_CONFIG_LAYER_ID)- assert config.config.model_dump(mode="json") == {+ assert DifyConfigLayerConfig.model_validate(config.config).model_dump(mode="json") == {+ "shell": "shell","agent_id": "agent-1","config_version": {"id": "snap-1", "kind": "build_draft", "writable": True},"skills": [@@ -781,10 +772,12 @@ class TestAgentAppConfigLayer:result = builder.build(_ctx(soul))config = next(layer for layer in result.request.composition.layers if layer.name == DIFY_CONFIG_LAYER_ID)- assert [skill.name for skill in config.config.skills] == ["workspace-skill"]- assert config.config.mentioned_skill_names == ["workspace-skill"]+ assert [skill.name for skill in DifyConfigLayerConfig.model_validate(config.config).skills] == [+ "workspace-skill"+ ]+ assert DifyConfigLayerConfig.model_validate(config.config).mentioned_skill_names == ["workspace-skill"]prompt_layer = next(layer for layer in result.request.composition.layers if layer.name == "agent_soul_prompt")- assert prompt_layer.config.prefix == "Use workspace-skill."+ assert PromptConfig.model_validate(prompt_layer.config).prefix == "Use workspace-skill."@pytest.mark.parametrize(("system_prompt", "expected_prefix"),@@ -813,8 +806,8 @@ class TestAgentAppConfigLayer:result = builder.build(_ctx(soul))prompt_layer = next(layer for layer in result.request.composition.layers if layer.name == "agent_soul_prompt")- assert prompt_layer.config.prefix == expected_prefix- assert "[§" not in prompt_layer.config.prefix+ assert PromptConfig.model_validate(prompt_layer.config).prefix == expected_prefix+ assert "[§" not in PromptConfig.model_validate(prompt_layer.config).prefixdef test_agent_app_runtime_missing_config_mentions_fall_back_without_marker_leak(self,@@ -830,8 +823,10 @@ class TestAgentAppConfigLayer:result = builder.build(_ctx(soul))prompt_layer = next(layer for layer in result.request.composition.layers if layer.name == "agent_soul_prompt")- assert prompt_layer.config.prefix == "Use Ghost Skill, Ghost File, and no-label.txt."- assert "[§" not in prompt_layer.config.prefix+ assert (+ PromptConfig.model_validate(prompt_layer.config).prefix == "Use Ghost Skill, Ghost File, and no-label.txt."+ )+ assert "[§" not in PromptConfig.model_validate(prompt_layer.config).prefixassert [warning["code"] for warning in result.metadata["runtime_support"]["unsupported_runtime_warnings"]] == ["mention_target_missing","mention_target_missing",diff --git a/api/tests/unit_tests/core/app/apps/agent_app/test_session_store.py b/api/tests/unit_tests/core/app/apps/agent_app/test_session_store.pyindex 54850885428..936d2fc79df 100644--- a/api/tests/unit_tests/core/app/apps/agent_app/test_session_store.py+++ b/api/tests/unit_tests/core/app/apps/agent_app/test_session_store.py@@ -1,7 +1,7 @@from unittest.mock import MagicMockimport pytest-from agenton.compositor import CompositorSessionSnapshot+from dify_agent.protocol.snapshot import SessionSnapshotfrom sqlalchemy.orm import Session, sessionmakerfrom core.app.apps.agent_app.session_store import AgentAppSessionScope, AgentAppWorkspaceStore@@ -167,7 +167,7 @@ def test_normal_conversation_pointer_does_not_create_replacement_binding(def test_save_snapshot_targets_binding(monkeypatch: pytest.MonkeyPatch) -> None:save = MagicMock()monkeypatch.setattr(AgentWorkspaceService, "save_binding_session_snapshot", save)- snapshot = CompositorSessionSnapshot(layers=[])+ snapshot = SessionSnapshot(layers={})AgentAppWorkspaceStore().save_active_snapshot(scope=_scope(), binding_id="binding-1", snapshot=snapshot)diff --git a/api/tests/unit_tests/core/app/task_pipeline/test_based_generate_task_pipeline.py b/api/tests/unit_tests/core/app/task_pipeline/test_based_generate_task_pipeline.pyindex 26b3f521a3e..18c2fdd97a2 100644--- a/api/tests/unit_tests/core/app/task_pipeline/test_based_generate_task_pipeline.py+++ b/api/tests/unit_tests/core/app/task_pipeline/test_based_generate_task_pipeline.py@@ -7,7 +7,6 @@ from dify_agent.protocol import RunFailureTypefrom sqlalchemy.orm import Sessionfrom clients.agent_backend.errors import AgentBackendRunFailedError-from core.app.apps.agent_app.errors import AgentSessionSnapshotIncompatibleErrorfrom core.app.apps.base_app_generate_response_converter import AppGenerateResponseConverterfrom core.app.entities.app_invoke_entities import InvokeFromfrom core.app.entities.queue_entities import QueueErrorEvent@@ -169,17 +168,6 @@ class TestBasedGenerateTaskPipeline:"message": "run limit reached (agent_run_id=run-1)",}- def test_stream_converter_preserves_agent_session_configuration_error(self):- data = AppGenerateResponseConverter._error_to_stream_response(AgentSessionSnapshotIncompatibleError())-- assert data == {- "code": "agent_session_configuration_changed",- "status": 409,- "message": (- "The Agent configuration changed after this conversation started. Start a new conversation to continue."- ),- }-def test_handle_output_moderation_when_flagged(self, pipeline):handler = Mock()handler.moderation_completion.return_value = ("filtered", True)diff --git a/api/tests/unit_tests/core/repositories/test_human_input_repository.py b/api/tests/unit_tests/core/repositories/test_human_input_repository.pyindex 6e149fdb697..6aaa0596152 100644--- a/api/tests/unit_tests/core/repositories/test_human_input_repository.py+++ b/api/tests/unit_tests/core/repositories/test_human_input_repository.py@@ -425,6 +425,28 @@ def test_create_form_adds_console_and_backstage_recipients(}+def test_create_runtime_form_requires_workflow_even_when_conversation_is_present() -> None:+ repo = HumanInputFormRepositoryImpl(tenant_id="tenant", app_id="app")+ params = FormCreateParams(+ workflow_execution_id=None,+ conversation_id="conversation",+ node_id="node",+ form_config=HumanInputNodeData(+ title="Title",+ delivery_methods=[],+ form_content="hello",+ inputs=[],+ user_actions=[UserActionConfig(id="submit", title="Submit")],+ ),+ rendered_content="hello",+ delivery_methods=[],+ display_in_ui=True,+ resolved_default_values={},+ )+ with pytest.raises(ValueError, match="requires a workflow_execution_id"):+ repo.create_form(params)++def test_submission_get_by_token_returns_none_when_missing_or_form_missing(repository_session: Session) -> None:repo = HumanInputFormSubmissionRepository()assert repo.get_by_token("tok") is Nonediff --git a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_agent_node.py b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_agent_node.pyindex f4632563260..ddf64c31d6b 100644--- a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_agent_node.py+++ b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_agent_node.py@@ -6,8 +6,6 @@ from unittest.mock import MagicMock, patchfrom uuid import UUID, uuid4import pytest-from agenton.compositor import CompositorSessionSnapshot-from dify_agent.layers.ask_human import AskHumanToolResultfrom dify_agent.protocol import (DIFY_AGENT_OUTPUT_LAYER_ID,CancelRunRequest,@@ -22,6 +20,7 @@ from dify_agent.protocol import (RunSucceededEvent,RunSucceededEventData,)+from dify_agent.protocol.snapshot import SessionSnapshotfrom pydantic_ai.messages import PartDeltaEvent, TextPartDeltafrom clients.agent_backend import (@@ -36,7 +35,6 @@ from clients.agent_backend import (from core.app.entities.app_invoke_entities import DIFY_RUN_CONTEXT_KEY, DifyRunContext, InvokeFrom, UserFromfrom core.workflow.file_reference import build_file_referencefrom core.workflow.nodes.agent_v2 import DifyAgentNode-from core.workflow.nodes.agent_v2.ask_human_resume import AskHumanResumeOutcomefrom core.workflow.nodes.agent_v2.binding_resolver import WorkflowAgentBindingBundle, WorkflowAgentBindingResolverfrom core.workflow.nodes.agent_v2.entities import DifyAgentNodeDatafrom core.workflow.nodes.agent_v2.output_adapter import WorkflowAgentOutputAdapter@@ -49,9 +47,7 @@ from core.workflow.nodes.agent_v2.session_store import (WorkflowAgentSessionScope,WorkflowAgentWorkspaceStore,)-from core.workflow.nodes.human_input.pause_reason import HumanInputRequiredfrom graphon.entities import GraphInitParams-from graphon.entities.pause_reason import HitlRequiredfrom graphon.enums import (BuiltinNodeTypes,ErrorStrategy,@@ -60,7 +56,6 @@ from graphon.enums import (WorkflowNodeExecutionStatus,)from graphon.file import File, FileTransferMethod, FileType-from graphon.graph_events import NodeRunPauseRequestedEventfrom graphon.node_events import StreamCompletedEventfrom graphon.runtime import GraphRuntimeStatefrom graphon.variables.segments import ArrayFileSegment, FileSegment, StringSegment@@ -159,7 +154,7 @@ class FakeBindingResolver(WorkflowAgentBindingResolver):class FakeSessionStore:def __init__(self,- snapshot: CompositorSessionSnapshot | None = None,+ snapshot: SessionSnapshot | None = None,*,binding_id: str = "binding-1",workspace_id: str = "workspace-1",@@ -177,7 +172,7 @@ class FakeSessionStore:tuple[WorkflowAgentSessionScope,str,- CompositorSessionSnapshot | None,+ SessionSnapshot | None,str | None,str | None,]@@ -210,28 +205,24 @@ class FakeSessionStore:*,scope: WorkflowAgentSessionScope,binding_id: str,- snapshot: CompositorSessionSnapshot | None,- pending_form_id: str | None = None,- pending_tool_call_id: str | None = None,+ snapshot: SessionSnapshot | None,) -> None:- self.saved.append((scope, binding_id, snapshot, pending_form_id, pending_tool_call_id))+ self.saved.append((scope, binding_id, snapshot))class ExplodingSessionStore(FakeSessionStore):- def __init__(self, snapshot: CompositorSessionSnapshot | None = None) -> None:+ def __init__(self, snapshot: SessionSnapshot | None = None) -> None:super().__init__(snapshot=snapshot)- self.save_attempts: list[CompositorSessionSnapshot | None] = []+ self.save_attempts: list[SessionSnapshot | None] = []def save_active_snapshot(self,*,scope: WorkflowAgentSessionScope,binding_id: str,- snapshot: CompositorSessionSnapshot | None,- pending_form_id: str | None = None,- pending_tool_call_id: str | None = None,+ snapshot: SessionSnapshot | None,) -> None:- del scope, binding_id, pending_form_id, pending_tool_call_id+ del scope, binding_idself.save_attempts.append(snapshot)raise RuntimeError("simulated DB failure")@@ -244,7 +235,7 @@ class FileOutputBackendClient(FakeAgentBackendRunClient):self.output_payload = output_payloaddef _events(self, run_id: str):- from agenton.compositor import CompositorSessionSnapshot+ from dify_agent.protocol.snapshot import SessionSnapshotfrom clients.agent_backend.fake_client import _FIXED_TIME@@ -256,7 +247,7 @@ class FileOutputBackendClient(FakeAgentBackendRunClient):created_at=_FIXED_TIME,data=RunSucceededEventData(output=self.output_payload,- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),),)@@ -274,7 +265,7 @@ class PlainTextOutputBackendClient(FakeAgentBackendRunClient):created_at=_FIXED_TIME,data=RunSucceededEventData(output="hello agent",- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),),)@@ -298,7 +289,7 @@ class AgentMessageDeltaBackendClient(FakeAgentBackendRunClient):created_at=created_at,data=RunSucceededEventData(output={"text": "hello agent"},- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),),)@@ -758,11 +749,11 @@ def test_agent_node_run_maps_failed_agent_backend_run_to_node_result():assert result.status == WorkflowNodeExecutionStatus.FAILEDassert result.error == "fake failure"assert result.error_type == "unit_test"- assert store.saved[0][2] == CompositorSessionSnapshot(layers=[])+ assert store.saved[0][2] == SessionSnapshot(layers={})def test_agent_node_saves_success_snapshot_and_reuses_existing_snapshot():- existing_snapshot = CompositorSessionSnapshot(layers=[])+ existing_snapshot = SessionSnapshot(layers={})store = FakeSessionStore(snapshot=existing_snapshot)client = FakeAgentBackendRunClient()node = _node(agent_backend_client=client, session_store=store)@@ -771,13 +762,10 @@ def test_agent_node_saves_success_snapshot_and_reuses_existing_snapshot():assert len(events) == 1assert store.saved- scope, binding_id, saved_snapshot, pending_form_id, pending_tool_call_id = store.saved[0]+ scope, binding_id, saved_snapshot = store.saved[0]assert scope.workflow_run_id == "workflow-run-1"assert binding_id == "binding-1"assert saved_snapshot is not None- # A successful terminal carries no ask_human pause correlation.- assert pending_form_id is None- assert pending_tool_call_id is Noneassert client.request is not Noneassert client.request.session_snapshot is existing_snapshot@@ -819,7 +807,7 @@ def test_agent_node_snapshot_save_failure_preserves_original_failure(failure_kinagent_backend = result.metadata[WorkflowNodeExecutionMetadataKey.AGENT_LOG]["agent_backend"]assert agent_backend["session_snapshot_persisted"] is Falseassert agent_backend["session_snapshot_persist_error"] == "workflow_agent_workspace_store_error"- assert store.save_attempts == [CompositorSessionSnapshot(layers=[])]+ assert store.save_attempts == [SessionSnapshot(layers={})]@pytest.mark.parametrize("terminal_type", ["failed", "cancelled"])@@ -838,137 +826,6 @@ def test_agent_node_terminal_without_snapshot_preserves_prior_session_without_wrassert store.saved == []-def test_agent_node_paused_run_requests_workflow_pause_and_persists_snapshot():- store = FakeSessionStore()- node = _node(scenario=FakeAgentBackendScenario.PAUSED, session_store=store)-- # ENG-636: the PAUSED scenario emits a dify.ask_human deferred call, so the- # node now builds a HITL form and pauses with HitlRequired. Stub the- # form repository so the unit test stays DB-free.- fake_repo = MagicMock()- fake_repo.create_form.return_value = MagicMock(id="form-1")- node._build_human_input_form_repository = lambda *, dify_ctx, workflow_run_id: fake_repo # type: ignore[assignment]-- events = list(node._run())-- assert len(events) == 1- assert isinstance(events[0], NodeRunPauseRequestedEvent)- assert isinstance(events[0].reason, HitlRequired)- assert events[0].reason.session_id == "form-1"- assert events[0].reason.node_id == "agent-node"- assert events[0].node_run_result.process_data == {- "agent_id": "agent-1",- "agent_config_snapshot_id": "snapshot-1",- "workflow_agent_binding_id": "binding-1",- }- fake_repo.create_form.assert_called_once()- assert store.saved- assert store.saved[0][1] == "binding-1"- # ENG-637: the awaiting form + deferred tool_call correlation is persisted.- assert store.saved[0][3] == "form-1"- assert store.saved[0][4] == "fake-ask-human-1"---def _pending_session(snapshot: CompositorSessionSnapshot) -> StoredWorkflowAgentSession:- return StoredWorkflowAgentSession(- scope=WorkflowAgentSessionScope(- tenant_id="tenant-1",- app_id="app-1",- workflow_id="workflow-1",- workflow_run_id="workflow-run-1",- node_id="agent-node",- node_execution_id="exec-1",- workflow_agent_binding_id="binding-1",- agent_id="agent-1",- agent_config_snapshot_id="snapshot-1",- ),- binding_id="binding-1",- workspace_id="workspace-1",- backend_binding_ref="backend-binding-1",- session_snapshot=snapshot,- pending_form_id="form-1",- pending_tool_call_id="call-1",- )---def test_agent_node_resumes_with_deferred_tool_results_after_submitted_form(monkeypatch: pytest.MonkeyPatch):- # ENG-638: a submitted form re-enters _run; the human's answer is threaded- # into the second Agent run as deferred_tool_results.- snapshot = CompositorSessionSnapshot(layers=[])- store = FakeSessionStore(snapshot=snapshot)- store.loaded_session = _pending_session(snapshot)-- def _fake_resolve(*, form_id: str, tenant_id: str, node_id: str) -> AskHumanResumeOutcome:- assert form_id == "form-1"- return AskHumanResumeOutcome(deferred_result=AskHumanToolResult(status="submitted", values={"note": "ok"}))-- monkeypatch.setattr("core.workflow.nodes.agent_v2.agent_node.resolve_ask_human_form", _fake_resolve)-- client = FakeAgentBackendRunClient() # SUCCESS scenario -> second run completes- node = _node(agent_backend_client=client, session_store=store)-- events = list(node._run())-- assert client.request is not None- assert client.request.deferred_tool_results is not None- assert set(client.request.deferred_tool_results.calls) == {"call-1"}- assert any(isinstance(event, StreamCompletedEvent) for event in events)---def test_agent_node_repauses_when_resumed_form_still_waiting(monkeypatch: pytest.MonkeyPatch):- snapshot = CompositorSessionSnapshot(layers=[])- store = FakeSessionStore(snapshot=snapshot)- store.loaded_session = _pending_session(snapshot)-- repause = HumanInputRequired(- form_id="form-1",- form_content="Approve?",- inputs=[],- actions=[],- node_id="agent-node",- node_title="Budget review",- )- monkeypatch.setattr(- "core.workflow.nodes.agent_v2.agent_node.resolve_ask_human_form",- lambda **_kwargs: AskHumanResumeOutcome(repause=repause),- )-- client = FakeAgentBackendRunClient()- node = _node(agent_backend_client=client, session_store=store)-- events = list(node._run())-- assert len(events) == 1- assert isinstance(events[0], NodeRunPauseRequestedEvent)- assert isinstance(events[0].reason, HitlRequired)- assert events[0].node_run_result.process_data["workflow_agent_binding_id"] == "binding-1"- assert client.request is None # no second Agent run was created---def test_agent_node_expired_ask_human_failure_keeps_binding_identity(monkeypatch: pytest.MonkeyPatch):- snapshot = CompositorSessionSnapshot(layers=[])- store = FakeSessionStore(snapshot=snapshot)- store.loaded_session = _pending_session(snapshot)-- def _raise_expired_form(**_kwargs):- raise AssertionError("cannot resume globally expired ask_human form, form_id=form-1")-- monkeypatch.setattr(- "core.workflow.nodes.agent_v2.agent_node.resolve_ask_human_form",- _raise_expired_form,- )-- events = list(_node(session_store=store)._run())-- assert len(events) == 1- result = cast(StreamCompletedEvent, events[0]).node_run_result- assert result.status == WorkflowNodeExecutionStatus.FAILED- assert result.error == "cannot resume globally expired ask_human form, form_id=form-1"- assert result.error_type == "agent_workflow_node_runtime_error"- assert result.process_data["workflow_agent_binding_id"] == "binding-1"- assert "agent_workspace_binding_id" not in result.process_data--def test_agent_node_unexpected_post_resolution_failure_keeps_binding_identity():class _FailingSessionStore(FakeSessionStore):def load_or_create_node_execution_session(diff --git a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_ask_human_hitl.py b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_ask_human_hitl.pydeleted file mode 100644index 52ca2d5c0ec..00000000000--- a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_ask_human_hitl.py+++ /dev/null@@ -1,351 +0,0 @@-"""Unit tests for the ask_human -> HITL form translation layer (ENG-636)."""--from __future__ import annotations--from typing import Any--import pytest-from dify_agent.layers.ask_human import AskHumanToolArgs-from dify_agent.protocol import DeferredToolCallPayload-from pytest_mock import MockerFixture-from sqlalchemy.orm import Session, sessionmaker--from core.repositories.human_input_repository import FormCreateParams, HumanInputFormRepositoryImpl-from core.workflow.human_input_adapter import (- EmailDeliveryMethod,- ExternalRecipient,- InteractiveSurfaceDeliveryMethod,-)-from core.workflow.nodes.agent_v2.ask_human_hitl import (- AskHumanFormBuildError,- ask_human_args_to_node_data,- build_ask_human_pause_reason,- build_delivery_methods,- parse_ask_human_args,-)-from core.workflow.nodes.human_input.entities import (- FileInputConfig,- FileListInputConfig,- ParagraphInputConfig,- SelectInputConfig,-)-from core.workflow.nodes.human_input.enums import ButtonStyle, TimeoutUnit-from core.workflow.nodes.human_input.pause_reason import HumanInputRequired-from models.agent_config_entities import AgentHumanContactConfig---def _args(**overrides: Any) -> AskHumanToolArgs:- payload: dict[str, Any] = {"question": "Approve the budget?"}- payload.update(overrides)- return AskHumanToolArgs.model_validate(payload)---def _deferred_call(args: dict[str, Any], *, tool_name: str = "ask_human") -> DeferredToolCallPayload:- return DeferredToolCallPayload(tool_call_id="call-1", tool_name=tool_name, args=args)---def repo(sqlite_session_factory: sessionmaker[Session], mocker: MockerFixture) -> HumanInputFormRepositoryImpl:- mocker.patch(- "core.repositories.human_input_repository.session_factory.create_session", side_effect=sqlite_session_factory- )- return HumanInputFormRepositoryImpl(tenant_id="tenant-1", app_id="app-1", workflow_execution_id="wf-1")---# ─────────────────────────── parse_ask_human_args ───────────────────────────---def test_parse_ask_human_args_from_mapping() -> None:- parsed = parse_ask_human_args({"question": "Need a decision"})- assert isinstance(parsed, AskHumanToolArgs)- assert parsed.question == "Need a decision"---def test_parse_ask_human_args_passthrough() -> None:- original = _args()- assert parse_ask_human_args(original) is original---def test_parse_ask_human_args_invalid_payload_raises() -> None:- with pytest.raises(AskHumanFormBuildError):- parse_ask_human_args({"question": ""}) # blank question is rejected---def test_parse_ask_human_args_non_mapping_raises() -> None:- with pytest.raises(AskHumanFormBuildError):- parse_ask_human_args("not a mapping")---# ───────────────────────── ask_human_args_to_node_data ──────────────────────---def test_node_data_maps_every_field_type() -> None:- args = _args(- fields=[- {"type": "paragraph", "name": "reason", "label": "Reason", "default": "n/a"},- {- "type": "select",- "name": "tier",- "label": "Tier",- "options": [{"value": "t1", "label": "Tier 1"}, {"value": "t2", "label": "Tier 2"}],- "default": "t2",- },- {"type": "file", "name": "doc", "label": "Document"},- {"type": "file-list", "name": "evidence", "label": "Evidence", "max_files": 3},- ],- )-- node_data = ask_human_args_to_node_data(args, node_title="Budget review")-- assert [type(i) for i in node_data.inputs] == [- ParagraphInputConfig,- SelectInputConfig,- FileInputConfig,- FileListInputConfig,- ]- paragraph, select, _file, file_list = node_data.inputs- assert isinstance(paragraph, ParagraphInputConfig)- assert isinstance(select, SelectInputConfig)- assert isinstance(file_list, FileListInputConfig)- assert paragraph.output_variable_name == "reason"- assert paragraph.default is not None- assert paragraph.default.value == "n/a"- assert select.option_source.value == ["t1", "t2"]- assert file_list.number_limits == 3- assert node_data.timeout == 36- assert node_data.timeout_unit == TimeoutUnit.HOUR- assert node_data.title == "Budget review"---def test_node_data_form_content_embeds_title_question_and_field_markers() -> None:- args = _args(- title="Decision needed",- markdown="Some **context** here.",- fields=[{"type": "paragraph", "name": "reason", "label": "Reason", "required": True}],- )-- content = ask_human_args_to_node_data(args, node_title="t").form_content-- assert "## Decision needed" in content- assert "Approve the budget?" in content- assert "Some **context** here." in content- # The label carries a required marker and positions the input via $output.- assert "**Reason ***" in content- assert "{{#$output.reason#}}" in content---def test_node_data_maps_action_styles_and_titles() -> None:- args = _args(- actions=[- {"id": "approve", "label": "Approve", "style": "primary"},- {"id": "reject", "label": "Reject", "style": "destructive"},- {"id": "later", "label": "Decide later"},- ],- )-- actions = ask_human_args_to_node_data(args, node_title="t").user_actions-- assert [(a.id, a.title, a.button_style) for a in actions] == [- ("approve", "Approve", ButtonStyle.PRIMARY),- ("reject", "Reject", ButtonStyle.ACCENT), # destructive -> accent- ("later", "Decide later", ButtonStyle.DEFAULT),- ]---def test_node_data_synthesizes_submit_action_when_none_given() -> None:- actions = ask_human_args_to_node_data(_args(), node_title="t").user_actions- assert len(actions) == 1- assert actions[0].id == "submit"- assert actions[0].button_style == ButtonStyle.PRIMARY---def test_node_data_clamps_overlong_action_id_deterministically() -> None:- long_id = "approve_the_quarterly_budget_request" # > 20 chars, valid identifier- args = _args(actions=[{"id": long_id, "label": "Approve"}])-- first = ask_human_args_to_node_data(args, node_title="t").user_actions[0]- second = ask_human_args_to_node_data(args, node_title="t").user_actions[0]-- assert len(first.id) <= 20- assert first.id.isidentifier()- assert first.id == second.id # stable across builds- assert first.title == "Approve" # label preserved verbatim---# ───────────────────────────── build_delivery_methods ──────────────────────---def test_delivery_always_includes_interactive_surface() -> None:- methods = build_delivery_methods([], args=_args())- assert len(methods) == 1- assert isinstance(methods[0], InteractiveSurfaceDeliveryMethod)---def test_delivery_adds_email_for_contacts_and_dedupes() -> None:- contacts = [- AgentHumanContactConfig(email="[email protected]"),- AgentHumanContactConfig(email="[email protected]"), # duplicate- AgentHumanContactConfig(email=None), # no email- AgentHumanContactConfig(email="[email protected]"),- ]-- methods = build_delivery_methods(contacts, args=_args())-- email_methods = [m for m in methods if isinstance(m, EmailDeliveryMethod)]- assert len(email_methods) == 1- recipients = email_methods[0].config.recipients.items- assert [r.email for r in recipients if isinstance(r, ExternalRecipient)] == ["[email protected]", "[email protected]"]---def test_delivery_high_urgency_prefixes_subject() -> None:- methods = build_delivery_methods(- [AgentHumanContactConfig(email="[email protected]")],- args=_args(title="Sign off", urgency="high"),- )- email_method = next(m for m in methods if isinstance(m, EmailDeliveryMethod))- assert email_method.config.subject.startswith("[Action needed] ")---# ─────────────────────────── build_ask_human_pause_reason ───────────────────---def test_pause_reason_none_for_non_ask_human_tool(repo: HumanInputFormRepositoryImpl) -> None:- result = build_ask_human_pause_reason(- deferred_tool_call=_deferred_call({"question": "q"}, tool_name="final_output"),- node_id="node-1",- default_node_title="Agent",- workflow_run_id="wf-1",- contacts=[],- repository=repo,- )- assert result is None---def test_pause_reason_requires_workflow_run_id(repo: HumanInputFormRepositoryImpl) -> None:- with pytest.raises(AskHumanFormBuildError):- build_ask_human_pause_reason(- deferred_tool_call=_deferred_call({"question": "q"}),- node_id="node-1",- default_node_title="Agent",- workflow_run_id="",- contacts=[],- repository=repo,- )---def test_pause_reason_builds_form_and_returns_dify_pause_reason(- repo: HumanInputFormRepositoryImpl, mocker: MockerFixture-) -> None:- create = mocker.spy(repo, "create_form")- contacts = [AgentHumanContactConfig(email="[email protected]")]-- result = build_ask_human_pause_reason(- deferred_tool_call=_deferred_call(- {- "title": "Approve?",- "question": "Please approve",- "fields": [{"type": "paragraph", "name": "note", "label": "Note"}],- "actions": [{"id": "ok", "label": "OK"}],- }- ),- node_id="node-1",- default_node_title="Agent fallback",- workflow_run_id="wf-1",- contacts=contacts,- repository=repo,- )-- assert result is not None- form = repo.get_form("node-1")- assert form is not None- assert result.form_id == form.id- assert isinstance(result, HumanInputRequired)- assert result.node_id == "node-1"- assert result.node_title == "Approve?" # args.title wins over default- assert [i.output_variable_name for i in result.inputs] == ["note"]- assert [a.id for a in result.actions] == ["ok"]-- params: FormCreateParams = create.call_args.args[0]- assert params.workflow_execution_id == "wf-1"- assert params.node_id == "node-1"- # No conversation_id passed -> pure workflow run owns the form by workflow_run_id only.- assert params.conversation_id is None- assert any(isinstance(m, EmailDeliveryMethod) for m in params.delivery_methods)---def test_pause_reason_forwards_conversation_id_for_chatflow(- repo: HumanInputFormRepositoryImpl, mocker: MockerFixture-) -> None:- # ENG-635 (review): an agent node running in a chatflow tags its ask_human form- # with the conversation in addition to the workflow run.- create = mocker.spy(repo, "create_form")-- build_ask_human_pause_reason(- deferred_tool_call=_deferred_call({"question": "Please approve"}),- node_id="node-1",- default_node_title="Agent",- workflow_run_id="wf-1",- conversation_id="conv-1",- contacts=[],- repository=repo,- )-- params: FormCreateParams = create.call_args.args[0]- assert params.workflow_execution_id == "wf-1"- assert params.conversation_id == "conv-1"---def test_pause_reason_falls_back_to_default_node_title(repo: HumanInputFormRepositoryImpl) -> None:- result = build_ask_human_pause_reason(- deferred_tool_call=_deferred_call({"question": "q with no title"}),- node_id="node-1",- default_node_title="Agent fallback",- workflow_run_id="wf-1",- contacts=[],- repository=repo,- )- assert result is not None- assert result.node_title == "Agent fallback"---def test_pause_reason_select_default_flows_into_resolved_defaults(- repo: HumanInputFormRepositoryImpl, mocker: MockerFixture-) -> None:- create = mocker.spy(repo, "create_form")- result = build_ask_human_pause_reason(- deferred_tool_call=_deferred_call(- {- "question": "pick",- "fields": [- {- "type": "select",- "name": "tier",- "label": "Tier",- "options": [{"value": "t1", "label": "Tier 1"}],- "default": "t1",- }- ],- }- ),- node_id="node-1",- default_node_title="Agent",- workflow_run_id="wf-1",- contacts=[],- repository=repo,- )- assert result is not None- params: FormCreateParams = create.call_args.args[0]- assert result.resolved_default_values == {"tier": "t1"}---def test_pause_reason_wraps_repository_value_error(repo: HumanInputFormRepositoryImpl, mocker: MockerFixture) -> None:- mocker.patch.object(repo, "create_form", side_effect=ValueError("db boom"))- with pytest.raises(AskHumanFormBuildError):- build_ask_human_pause_reason(- deferred_tool_call=_deferred_call({"question": "q"}),- node_id="node-1",- default_node_title="Agent",- workflow_run_id="wf-1",- contacts=[],- repository=repo,- )diff --git a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_ask_human_resume.py b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_ask_human_resume.pydeleted file mode 100644index 921966cc745..00000000000--- a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_ask_human_resume.py+++ /dev/null@@ -1,121 +0,0 @@-"""Unit tests for mapping a submitted/timed-out HITL form back to ask_human (ENG-638)."""--from __future__ import annotations--from datetime import datetime--import pytest-from dify_agent.layers.ask_human import AskHumanToolResult--from core.workflow.nodes.agent_v2.ask_human_resume import (- build_deferred_tool_results,- map_form_to_outcome,-)-from core.workflow.nodes.human_input.entities import FormDefinition, ParagraphInputConfig, UserActionConfig-from core.workflow.nodes.human_input.enums import HumanInputFormStatus-from core.workflow.nodes.human_input.pause_reason import HumanInputRequired---def _form_definition_json() -> str:- return FormDefinition(- form_content="Approve? {{#$output.note#}}",- inputs=[ParagraphInputConfig(output_variable_name="note")],- user_actions=[UserActionConfig(id="approve", title="Approve"), UserActionConfig(id="reject", title="Reject")],- rendered_content="Approve? <input>",- expiration_time=datetime(2026, 1, 1),- default_values={"note": "default"},- node_title="Budget review",- ).model_dump_json()---def test_map_submitted_form_to_result() -> None:- outcome = map_form_to_outcome(- status=HumanInputFormStatus.SUBMITTED,- selected_action_id="approve",- submitted_data='{"note": "looks good"}',- rendered_content="Approve? <input>",- form_definition=_form_definition_json(),- form_id="form-1",- node_id="node-1",- )-- assert outcome.repause is None- result = outcome.deferred_result- assert result is not None- assert result.status == "submitted"- assert result.action is not None- assert result.action.id == "approve"- assert result.action.label == "Approve" # verbatim label recovered from the form- assert result.values == {"note": "looks good"}- assert result.rendered_content == "Approve? <input>"---def test_map_timeout_form_to_timeout_result() -> None:- outcome = map_form_to_outcome(- status=HumanInputFormStatus.TIMEOUT,- selected_action_id=None,- submitted_data=None,- rendered_content="x",- form_definition=_form_definition_json(),- form_id="form-1",- node_id="node-1",- )- assert outcome.deferred_result is not None- assert outcome.deferred_result.status == "timeout"- assert outcome.deferred_result.action is None---def test_map_expired_form_rejects_invalid_resume_state() -> None:- with pytest.raises(AssertionError, match="globally expired ask_human form"):- map_form_to_outcome(- status=HumanInputFormStatus.EXPIRED,- selected_action_id=None,- submitted_data=None,- rendered_content="x",- form_definition=_form_definition_json(),- form_id="form-1",- node_id="node-1",- )---def test_map_waiting_form_rebuilds_pause() -> None:- outcome = map_form_to_outcome(- status=HumanInputFormStatus.WAITING,- selected_action_id=None,- submitted_data=None,- rendered_content="x",- form_definition=_form_definition_json(),- form_id="form-1",- node_id="node-1",- )-- assert outcome.deferred_result is None- pause = outcome.repause- assert isinstance(pause, HumanInputRequired)- assert pause.form_id == "form-1"- assert pause.node_id == "node-1"- assert pause.node_title == "Budget review"- assert [a.id for a in pause.actions] == ["approve", "reject"]- assert [i.output_variable_name for i in pause.inputs] == ["note"]---def test_map_submitted_without_action_id() -> None:- outcome = map_form_to_outcome(- status=HumanInputFormStatus.SUBMITTED,- selected_action_id=None,- submitted_data="{}",- rendered_content="x",- form_definition=_form_definition_json(),- form_id="form-1",- node_id="node-1",- )- assert outcome.deferred_result is not None- assert outcome.deferred_result.action is None- assert outcome.deferred_result.values == {}---def test_build_deferred_tool_results_keys_by_tool_call_id() -> None:- result = AskHumanToolResult(status="timeout")- payload = build_deferred_tool_results(tool_call_id="call-42", result=result)- assert set(payload.calls) == {"call-42"}- assert payload.calls["call-42"] == result.model_dump(mode="json")diff --git a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_binding_resolver.py b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_binding_resolver.pyindex f4dd2b3b4c1..d6142285774 100644--- a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_binding_resolver.py+++ b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_binding_resolver.py@@ -3,7 +3,7 @@ from unittest.mock import MagicMockfrom uuid import uuid4import pytest-from agenton.compositor import CompositorSessionSnapshot+from dify_agent.protocol.snapshot import SessionSnapshotfrom sqlalchemy import event, inspectfrom sqlalchemy.orm import ORMExecuteState, Session, sessionmakerfrom sqlalchemy.sql import Executable@@ -72,7 +72,7 @@ def _conversation_participant(base_home_snapshot_id=snapshot.home_snapshot_id,backend_binding_ref="participant-ref",status=AgentWorkingResourceStatus.ACTIVE,- session_snapshot=CompositorSessionSnapshot(layers=[]).model_dump_json(),+ session_snapshot=SessionSnapshot(layers={}).model_dump_json(),)session.add(participant)session.flush()@@ -165,7 +165,7 @@ def test_chatflow_keeps_participant_config_and_home_after_agent_update()assert stored.binding_id == participant.idassert stored.backend_binding_ref == participant.backend_binding_ref- assert stored.session_snapshot == CompositorSessionSnapshot(layers=[])+ assert stored.session_snapshot == SessionSnapshot(layers={})create_binding.assert_not_called()agent.status = AgentStatus.ARCHIVEDdiff --git a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_output_adapter.py b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_output_adapter.pyindex 9c8e5d76f74..ac635cf9afd 100644--- a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_output_adapter.py+++ b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_output_adapter.py@@ -2,8 +2,8 @@ from decimal import Decimalfrom unittest.mock import patchimport pytest-from agenton.compositor import CompositorSessionSnapshotfrom dify_agent.protocol import RunFailureType+from dify_agent.protocol.snapshot import SessionSnapshotfrom clients.agent_backend import (AgentBackendRunCancelledInternalEvent,@@ -49,7 +49,7 @@ def _succeeded(output: object) -> AgentBackendRunSucceededInternalEvent:run_id="run-1",source_event_id="2-0",output=output,- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),)@@ -130,7 +130,7 @@ def test_success_output_adapter_preserves_dict_output():run_id="run-1",source_event_id="2-0",output={"summary": "ok"},- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),inputs={},process_data={},@@ -152,7 +152,7 @@ def test_failure_output_adapter_preserves_backend_failed_reason():source_event_id="2-0",error="bad request",reason="validation",- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),usage={"prompt_tokens": 13,"completion_tokens": 8,@@ -216,7 +216,7 @@ def test_success_output_adapter_normalizes_string_and_scalar_outputs():run_id="run-1",source_event_id="2-0",output="hello",- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),inputs={},process_data={},@@ -227,7 +227,7 @@ def test_success_output_adapter_normalizes_string_and_scalar_outputs():run_id="run-2",source_event_id="2-0",output=3,- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),inputs={},process_data={},@@ -264,7 +264,7 @@ def test_success_output_adapter_normalizes_file_output_to_file_segments():}],},- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),inputs={},process_data={},@@ -343,7 +343,7 @@ def test_success_output_adapter_accepts_canonical_file_mapping_for_declared_filerun_id="run-1",source_event_id="2-0",output={"report": {"transfer_method": "tool_file", "reference": tool_reference}},- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),inputs={},process_data={},@@ -371,7 +371,7 @@ def test_success_output_adapter_accepts_canonical_datasource_file_mapping_for_derun_id="run-1",source_event_id="2-0",output={"report": {"transfer_method": "datasource_file", "reference": datasource_reference}},- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),inputs={},process_data={},@@ -393,7 +393,7 @@ def test_success_output_adapter_accepts_canonical_remote_url_mapping_for_declarerun_id="run-1",source_event_id="2-0",output={"report": {"transfer_method": "remote_url", "url": remote_url}},- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),inputs={},process_data={},@@ -418,7 +418,7 @@ def test_success_output_adapter_accepts_canonical_file_mapping_for_declared_arrarun_id="run-1",source_event_id="2-0",output={"attachments": [{"transfer_method": "tool_file", "reference": tool_reference}]},- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),inputs={},process_data={},@@ -444,7 +444,7 @@ def test_success_output_adapter_does_not_treat_generic_object_with_string_id_as_run_id="run-1",source_event_id="2-0",output={"meta": {"id": "123", "type": "summary"}},- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),inputs={},process_data={},@@ -460,7 +460,7 @@ def test_success_output_adapter_does_not_crash_on_generic_object_with_non_stringrun_id="run-1",source_event_id="2-0",output={"meta": {"id": 1, "name": "foo"}},- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),inputs={},process_data={},@@ -484,7 +484,7 @@ def test_success_output_adapter_preserves_nested_canonical_file_mapping_inside_o}}},- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),inputs={},process_data={},@@ -516,7 +516,7 @@ def test_success_output_adapter_preserves_nested_canonical_file_mapping_inside_g}]},- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),inputs={},process_data={},@@ -546,7 +546,7 @@ def test_success_output_adapter_maps_backend_usage_to_llm_usage_and_metadata():run_id="run-1",source_event_id="2-0",output={"summary": "ok"},- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),usage={"prompt_tokens": 10,"prompt_unit_price": "5",diff --git a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_runtime_request_builder.py b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_runtime_request_builder.pyindex ffcce503042..2678610cb80 100644--- a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_runtime_request_builder.py+++ b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_runtime_request_builder.py@@ -4,11 +4,12 @@ from types import SimpleNamespacefrom typing import castimport pytest-from agenton.compositor import CompositorSessionSnapshot-from dify_agent.layers.config import DifyConfigSkillConfig+from dify_agent.layers.config import DifyConfigLayerConfig, DifyConfigSkillConfigfrom dify_agent.layers.dify_core_tools import DifyCoreToolConfig, DifyCoreToolsLayerConfigfrom dify_agent.layers.dify_plugin import DifyPluginToolConfig, DifyPluginToolsLayerConfig+from dify_agent.layers.prompt import Config as PromptConfigfrom dify_agent.protocol import DIFY_AGENT_HISTORY_LAYER_ID, DIFY_AGENT_MODEL_LAYER_ID, DIFY_AGENT_OUTPUT_LAYER_ID+from dify_agent.protocol.snapshot import SessionSnapshotfrom clients.agent_backend import (DIFY_CONFIG_LAYER_ID,@@ -709,11 +710,8 @@ def test_builds_workflow_run_request_with_dify_plugin_tools_layer(monkeypatch: pdumped = result.request.model_dump(mode="json")layers = {layer["name"]: layer for layer in dumped["composition"]["layers"]}- assert layers[DIFY_PLUGIN_TOOLS_LAYER_ID]["type"] == "dify.plugin.tools"- assert layers[DIFY_PLUGIN_TOOLS_LAYER_ID]["deps"] == {- "execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID,- "shell": DIFY_SHELL_LAYER_ID,- }+ assert layers[DIFY_PLUGIN_TOOLS_LAYER_ID]["config"]["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_ID+ assert layers[DIFY_PLUGIN_TOOLS_LAYER_ID]["config"]["shell"] == DIFY_SHELL_LAYER_IDassert layers[DIFY_PLUGIN_TOOLS_LAYER_ID]["config"]["tools"][0]["tool_name"] == "current_time"assert result.metadata["agent_tools"] == {"dify_tool_count": 1,@@ -813,8 +811,7 @@ def test_build_maps_agent_soul_knowledge_to_knowledge_layer_config():dumped = result.request.model_dump(mode="json")layers = {layer["name"]: layer for layer in dumped["composition"]["layers"]}knowledge_layer = layers["knowledge"]- assert knowledge_layer["type"] == "dify.knowledge_base"- assert knowledge_layer["deps"] == {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}+ assert knowledge_layer["config"]["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_IDassert knowledge_layer["config"]["sets"] == [{"id": "support",@@ -954,7 +951,7 @@ def test_build_skips_knowledge_layer_when_agent_soul_has_no_sets():def test_build_passes_saved_session_snapshot_to_agent_backend_request():- session_snapshot = CompositorSessionSnapshot(layers=[])+ session_snapshot = SessionSnapshot(layers={})context = replace(_context(), session_snapshot=session_snapshot)result = WorkflowAgentRuntimeRequestBuilder().build(context)@@ -1458,6 +1455,7 @@ def test_build_config_layer_config_returns_empty_config_for_empty_agent_soul():assert config is not Noneassert config.model_dump(mode="json") == {+ "shell": "shell","agent_id": None,"config_version": {"id": None, "kind": "snapshot", "writable": False},"skills": [],@@ -1478,6 +1476,7 @@ def test_workflow_run_request_has_config_layer_with_empty_agent_soul(monkeypatchdumped = result.request.model_dump(mode="json")layers = {layer["name"]: layer for layer in dumped["composition"]["layers"]}assert layers[DIFY_CONFIG_LAYER_ID]["config"] == {+ "shell": "shell","agent_id": "agent-1","config_version": {"id": "snapshot-1", "kind": "snapshot", "writable": False},"skills": [],@@ -1487,10 +1486,8 @@ def test_workflow_run_request_has_config_layer_with_empty_agent_soul(monkeypatch"mentioned_skill_names": [],"mentioned_file_names": [],}- assert layers[DIFY_SHELL_LAYER_ID]["deps"] == {- "execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID,- "runtime": "runtime",- }+ assert layers[DIFY_SHELL_LAYER_ID]["config"]["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_ID+ assert layers[DIFY_SHELL_LAYER_ID]["config"]["runtime"] == "runtime"def test_workflow_run_request_contains_config_layer():@@ -1507,9 +1504,9 @@ def test_workflow_run_request_contains_config_layer():assert layer_names.index(DIFY_SHELL_LAYER_ID) == layer_names.index("execution_context") + 2assert layer_names.index(DIFY_CONFIG_LAYER_ID) == layer_names.index(DIFY_SHELL_LAYER_ID) + 1config = next(layer for layer in dumped["composition"]["layers"] if layer["name"] == DIFY_CONFIG_LAYER_ID)- assert config["type"] == "dify.config"- assert config["deps"] == {"shell": DIFY_SHELL_LAYER_ID}+ assert config["config"]["shell"] == DIFY_SHELL_LAYER_IDassert config["config"] == {+ "shell": "shell","agent_id": "agent-1","config_version": {"id": "snapshot-1", "kind": "snapshot", "writable": False},"skills": [@@ -1551,10 +1548,10 @@ def test_workflow_run_request_includes_bound_workspace_skills(monkeypatch: pytesresult = WorkflowAgentRuntimeRequestBuilder().build(context)config = next(layer for layer in result.request.composition.layers if layer.name == DIFY_CONFIG_LAYER_ID)- assert [skill.name for skill in config.config.skills] == ["workspace-skill"]- assert config.config.mentioned_skill_names == ["workspace-skill"]+ assert [skill.name for skill in DifyConfigLayerConfig.model_validate(config.config).skills] == ["workspace-skill"]+ assert DifyConfigLayerConfig.model_validate(config.config).mentioned_skill_names == ["workspace-skill"]soul_prompt = next(layer for layer in result.request.composition.layers if layer.name == "agent_soul_prompt")- assert soul_prompt.config.prefix == "Use workspace-skill."+ assert PromptConfig.model_validate(soul_prompt.config).prefix == "Use workspace-skill."def test_workflow_runtime_expands_config_mentions_in_agent_soul_prompt():@@ -1564,8 +1561,10 @@ def test_workflow_runtime_expands_config_mentions_in_agent_soul_prompt():result = WorkflowAgentRuntimeRequestBuilder().build(context)soul_prompt = next(layer for layer in result.request.composition.layers if layer.name == "agent_soul_prompt")- assert soul_prompt.config.prefix == "You are careful. Use tender-analyzer and sample.pdf."- assert "[§" not in soul_prompt.config.prefix+ assert (+ PromptConfig.model_validate(soul_prompt.config).prefix == "You are careful. Use tender-analyzer and sample.pdf."+ )+ assert "[§" not in PromptConfig.model_validate(soul_prompt.config).prefixdef test_workflow_runtime_missing_config_mentions_fall_back_to_label_then_name():@@ -1582,8 +1581,8 @@ def test_workflow_runtime_missing_config_mentions_fall_back_to_label_then_name()result = WorkflowAgentRuntimeRequestBuilder().build(context)soul_prompt = next(layer for layer in result.request.composition.layers if layer.name == "agent_soul_prompt")- assert soul_prompt.config.prefix == "Use Ghost Skill, Ghost File, and no-label.txt."- assert "[§" not in soul_prompt.config.prefix+ assert PromptConfig.model_validate(soul_prompt.config).prefix == "Use Ghost Skill, Ghost File, and no-label.txt."+ assert "[§" not in PromptConfig.model_validate(soul_prompt.config).prefixassert [warning["code"] for warning in result.metadata["runtime_support"]["unsupported_runtime_warnings"]] == ["mention_target_missing","mention_target_missing",@@ -1629,37 +1628,17 @@ def test_build_config_layer_config_excludes_missing_assets_from_runtime():]-# ── ENG-635: ask_human layer gating + feature manifest ───────────────────────---def test_build_ask_human_layer_config_gated_on_human_contacts():- from dify_agent.layers.ask_human import DifyAskHumanLayerConfig-- from core.workflow.nodes.agent_v2.runtime_request_builder import build_ask_human_layer_config-- # no human involvement configured -> tool stays off- assert build_ask_human_layer_config(AgentSoulConfig()) is None-- soul = AgentSoulConfig.model_validate(- {"human": {"contacts": [{"id": "c-1", "name": "David", "email": "[email protected]", "channel": "email"}]}}- )- config = build_ask_human_layer_config(soul)- assert isinstance(config, DifyAskHumanLayerConfig)- assert config.enabled is True---def test_feature_manifest_marks_human_supported_when_configured():+def test_feature_manifest_marks_human_reserved_when_configured():from core.workflow.nodes.agent_v2.runtime_feature_manifest import build_runtime_feature_manifestsoul = AgentSoulConfig.model_validate({"human": {"contacts": [{"id": "c-1", "name": "David", "email": "[email protected]", "channel": "email"}]}})manifest = build_runtime_feature_manifest(soul)- assert "human" in manifest["supported"]- assert "human" not in manifest["reserved"]- assert manifest["reserved_status"]["human"] == "supported_by_ask_human_hitl"- # configured human no longer produces a "not executed" warning- assert all("human" not in w["section"] for w in manifest["unsupported_runtime_warnings"])+ assert "human" not in manifest["supported"]+ assert "human" in manifest["reserved"]+ assert manifest["reserved_status"]["human"] == "reserved_not_executed"+ assert any("human" in w["section"] for w in manifest["unsupported_runtime_warnings"])def test_feature_manifest_marks_knowledge_supported_without_warning_when_configured():diff --git a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_session_store.py b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_session_store.pyindex e18e36a2adb..9ace4b35338 100644--- a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_session_store.py+++ b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_session_store.py@@ -5,9 +5,7 @@ from types import SimpleNamespacefrom unittest.mock import MagicMockimport pytest-from agenton.compositor import CompositorSessionSnapshot-from agenton.compositor.schemas import LayerSessionSnapshot-from agenton.layers.base import LifecycleState+from dify_agent.protocol.snapshot import SessionSnapshotfrom sqlalchemy import Engine, event, func, selectfrom sqlalchemy.orm import Session, sessionmaker@@ -197,15 +195,7 @@ def test_conversation_scope_reuses_existing_binding_on_later_turn(monkeypatch: pytest.MonkeyPatch,sqlite_session: Session,) -> None:- prior_snapshot = CompositorSessionSnapshot(- layers=[- LayerSessionSnapshot(- name="history",- lifecycle_state=LifecycleState.SUSPENDED,- runtime_state={"turn": 1},- )- ]- )+ prior_snapshot = SessionSnapshot(layers={"history": {"turn": 1}})workspace = AgentWorkspace(id="workspace-conversation",tenant_id="tenant-1",@@ -437,7 +427,7 @@ def test_save_snapshot_targets_binding(sqlite_session: Session) -> None:binding = _binding_row()sqlite_session.add_all([_workspace_row(), binding])sqlite_session.commit()- snapshot = CompositorSessionSnapshot(layers=[])+ snapshot = SessionSnapshot(layers={})WorkflowAgentWorkspaceStore().save_active_snapshot(scope=_scope(),diff --git a/api/tests/unit_tests/services/test_human_input_service.py b/api/tests/unit_tests/services/test_human_input_service.pyindex 57a3899a90a..840ac115c64 100644--- a/api/tests/unit_tests/services/test_human_input_service.py+++ b/api/tests/unit_tests/services/test_human_input_service.py@@ -370,36 +370,6 @@ def test_submit_form_by_token_calls_repository_and_enqueue(enqueue_spy.assert_called_once_with(sample_form_record.workflow_run_id)-def test_submit_form_by_token_enqueues_agent_app_resume_for_conversation_form(- form_repository: Callable[[HumanInputFormRecord | None], HumanInputFormSubmissionRepository],- sample_form_record: HumanInputFormRecord,- unbound_session_factory: sessionmaker[Session],- mocker: MockerFixture,-) -> None:- # ENG-635: a conversation-owned (Agent v2 chat) form routes to the chat- # resume, not the workflow resume.- conversation_record = dataclasses.replace(- sample_form_record,- workflow_run_id=None,- conversation_id="conv-1",- )- repo = form_repository(conversation_record)- service = HumanInputService(unbound_session_factory, form_repository=repo)- workflow_enqueue_spy = mocker.patch.object(service, "enqueue_resume")- chat_enqueue_spy = mocker.patch.object(service, "enqueue_agent_app_resume")-- service.submit_form_by_token(- recipient_type=RecipientType.STANDALONE_WEB_APP,- form_token="token",- selected_action_id="submit",- form_data={"field": "value"},- submission_end_user_id="end-user-id",- )-- chat_enqueue_spy.assert_called_once_with(conversation_id="conv-1", form_id=conversation_record.form_id)- workflow_enqueue_spy.assert_not_called()--def test_submit_form_by_token_skips_enqueue_for_delivery_test(form_repository: Callable[[HumanInputFormRecord | None], HumanInputFormSubmissionRepository],sample_form_record: HumanInputFormRecord,diff --git a/api/tests/unit_tests/tasks/test_human_input_timeout_tasks.py b/api/tests/unit_tests/tasks/test_human_input_timeout_tasks.pyindex 3b320f4a0ec..1b69892571b 100644--- a/api/tests/unit_tests/tasks/test_human_input_timeout_tasks.py+++ b/api/tests/unit_tests/tasks/test_human_input_timeout_tasks.py@@ -250,49 +250,3 @@ def test_check_and_handle_human_input_timeouts_omits_global_filter_when_disabledglobal_timeout_handler.assert_not_called()sqlite_session.refresh(old_unexpired_form)assert old_unexpired_form.status == HumanInputFormStatus.WAITING--[email protected]("sqlite_session", [(HumanInputForm,)], indirect=True)-def test_check_and_handle_human_input_timeouts_routes_conversation_owned_form_to_agent_app_resume(- monkeypatch: pytest.MonkeyPatch,- sqlite_task_database: None,- sqlite_session: Session,-):- # ENG-635 (review): a conversation-owned Agent v2 chat ask_human form has no- # workflow_run_id. On timeout it must enqueue the Agent App resume (so the- # timeout is threaded back as the ask_human result), instead of asserting on- # workflow_run_id — which previously raised and was swallowed by the except.- now = datetime(2025, 1, 1, 12, 0, 0)- monkeypatch.setattr(task_module, "naive_utc_now", lambda: now)- apply_config_overrides(monkeypatch, HUMAN_INPUT_GLOBAL_TIMEOUT_SECONDS=3600)-- form = _build_form(- form_id="form-chat",- form_kind=HumanInputFormKind.RUNTIME,- created_at=now - timedelta(minutes=5),- expiration_time=now - timedelta(seconds=1),- workflow_run_id=None,- conversation_id="conv-1",- node_id="agent",- )- sqlite_session.add(form)- sqlite_session.commit()-- repo = HumanInputFormSubmissionRepository()- mark_timeout_spy = MagicMock(wraps=repo.mark_timeout)- monkeypatch.setattr(repo, "mark_timeout", mark_timeout_spy)- service = _FakeService()- monkeypatch.setattr(task_module, "HumanInputFormSubmissionRepository", lambda: repo)- monkeypatch.setattr(task_module, "HumanInputService", lambda *_args, **_kwargs: service)- monkeypatch.setattr(task_module, "_handle_global_timeout", lambda **_kwargs: None)-- task_module.check_and_handle_human_input_timeouts(limit=100)-- # Node timeout (conversation forms are never "global"), routed to Agent App resume.- mark_timeout_spy.assert_called_once_with(- form_id="form-chat", timeout_status=HumanInputFormStatus.TIMEOUT, reason="node_timeout"- )- assert service.agent_app_resumed == [("conv-1", "form-chat")]- assert service.enqueued == []- sqlite_session.refresh(form)- assert form.status == HumanInputFormStatus.TIMEOUTdiff --git a/api/tests/unit_tests/tasks/test_resume_agent_app_task.py b/api/tests/unit_tests/tasks/test_resume_agent_app_task.pydeleted file mode 100644index ce063d3a6bb..00000000000--- a/api/tests/unit_tests/tasks/test_resume_agent_app_task.py+++ /dev/null@@ -1,258 +0,0 @@-"""Unit tests for the ``resume_agent_app_execution`` Celery task (ENG-635)."""--from __future__ import annotations--from collections.abc import Iterator-from datetime import UTC, datetime, timedelta-from uuid import uuid4--import pytest-from pytest_mock import MockerFixture-from sqlalchemy.orm import Session, scoped_session, sessionmaker--from core.app.entities.app_invoke_entities import InvokeFrom-from core.workflow.nodes.human_input.enums import HumanInputFormKind, HumanInputFormStatus-from models.account import Account, Tenant, TenantAccountJoin, TenantAccountRole-from models.enums import ConversationFromSource, EndUserType-from models.enums import InvokeFrom as StoredInvokeFrom-from models.human_input import HumanInputForm-from models.model import App, AppMode, Conversation, EndUser-from tasks.app_generate import resume_agent_app_task as mod-from tests.unit_tests.model_factories import make_app, make_conversation--MODULE = "tasks.app_generate.resume_agent_app_task"---def task_session(mocker: MockerFixture, sqlite_session_factory: sessionmaker[Session]) -> Iterator[Session]:- """Bind the task's Flask-SQLAlchemy session proxy to the shared SQLite database."""- registry = scoped_session(sqlite_session_factory)- mocker.patch.object(mod.db, "session", registry)- session = registry()- yield session- registry.remove()---def _app(*, app_id: str, tenant_id: str) -> App:- return make_app(- app_id=app_id,- tenant_id=tenant_id,- name="Agent app",- mode=AppMode.AGENT_CHAT,- icon_type=None,- enable_site=False,- enable_api=False,- )---def _conversation(- *,- conversation_id: str,- app_id: str,- account_id: str | None = None,- end_user_id: str | None = None,- invoke_from: StoredInvokeFrom = StoredInvokeFrom.WEB_APP,-) -> Conversation:- return make_conversation(- conversation_id=conversation_id,- app_id=app_id,- mode=AppMode.AGENT_CHAT,- name="Agent conversation",- inputs={},- invoke_from=invoke_from,- from_source=ConversationFromSource.API,- from_account_id=account_id,- from_end_user_id=end_user_id,- )---def _form(*, form_id: str, conversation_id: str, app_id: str) -> HumanInputForm:- return HumanInputForm(- id=form_id,- tenant_id=str(uuid4()),- app_id=app_id,- workflow_run_id=None,- conversation_id=conversation_id,- form_kind=HumanInputFormKind.RUNTIME,- node_id="ask-human",- form_definition="{}",- rendered_content="Question",- status=HumanInputFormStatus.WAITING,- expiration_time=datetime.now(UTC).replace(tzinfo=None) + timedelta(hours=1),- )---def _seed_account(session: Session, *, tenant_id: str, account_id: str) -> Account:- tenant = Tenant(name="Tenant")- tenant.id = tenant_id- account = Account(name="Account", email="[email protected]")- account.id = account_id- join = TenantAccountJoin(- tenant_id=tenant_id,- account_id=account_id,- current=True,- role=TenantAccountRole.NORMAL,- )- session.add_all([tenant, account, join])- return account---def test_resume_happy_path_account_user_sets_tenant_and_runs(mocker: MockerFixture, task_session: Session) -> None:- tenant_id, app_id, conversation_id, form_id, account_id = (str(uuid4()) for _ in range(5))- app = _app(app_id=app_id, tenant_id=tenant_id)- account = _seed_account(task_session, tenant_id=tenant_id, account_id=account_id)- conversation = _conversation(conversation_id=conversation_id, app_id=app_id, account_id=account_id)- task_session.add_all([app, conversation, _form(form_id=form_id, conversation_id=conversation_id, app_id=app_id)])- task_session.commit()- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")-- mod.resume_agent_app_execution(conversation_id=conversation_id, form_id=form_id)-- call = generator.return_value.resume_after_form_submission.call_args- assert call is not None- assert call.kwargs["conversation_id"] == conversation_id- assert call.kwargs["form_id"] == form_id- assert call.kwargs["user"] is account- assert call.kwargs["app_model"] is app- assert call.kwargs["invoke_from"] == InvokeFrom.WEB_APP- assert isinstance(call.kwargs["session"], Session)- assert account.current_tenant_id == tenant_id---def test_resume_end_user_path(mocker: MockerFixture, task_session: Session) -> None:- tenant_id, app_id, conversation_id, form_id, end_user_id = (str(uuid4()) for _ in range(5))- app = _app(app_id=app_id, tenant_id=tenant_id)- end_user = EndUser(- id=end_user_id,- tenant_id=tenant_id,- app_id=app_id,- type=EndUserType.BROWSER,- name="End user",- session_id="browser-session",- )- task_session.add_all(- [- app,- end_user,- _conversation(conversation_id=conversation_id, app_id=app_id, end_user_id=end_user_id),- _form(form_id=form_id, conversation_id=conversation_id, app_id=app_id),- ]- )- task_session.commit()- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")-- mod.resume_agent_app_execution(conversation_id=conversation_id, form_id=form_id)-- assert generator.return_value.resume_after_form_submission.call_args.kwargs["user"] is end_user---def test_resume_preserves_debugger_invoke_from(mocker: MockerFixture, task_session: Session) -> None:- tenant_id, app_id, conversation_id, form_id, account_id = (str(uuid4()) for _ in range(5))- app = _app(app_id=app_id, tenant_id=tenant_id)- _seed_account(task_session, tenant_id=tenant_id, account_id=account_id)- task_session.add_all(- [- app,- _conversation(- conversation_id=conversation_id,- app_id=app_id,- account_id=account_id,- invoke_from=StoredInvokeFrom.DEBUGGER,- ),- _form(form_id=form_id, conversation_id=conversation_id, app_id=app_id),- ]- )- task_session.commit()- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")-- mod.resume_agent_app_execution(conversation_id=conversation_id, form_id=form_id)-- assert generator.return_value.resume_after_form_submission.call_args.kwargs["invoke_from"] == InvokeFrom.DEBUGGER--[email protected]("task_session")-def test_resume_returns_when_form_missing(mocker: MockerFixture) -> None:- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")- mod.resume_agent_app_execution(conversation_id=str(uuid4()), form_id=str(uuid4()))- generator.assert_not_called()---def test_resume_returns_on_conversation_mismatch(mocker: MockerFixture, task_session: Session) -> None:- app_id, form_id = str(uuid4()), str(uuid4())- task_session.add(_form(form_id=form_id, conversation_id=str(uuid4()), app_id=app_id))- task_session.commit()- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")- mod.resume_agent_app_execution(conversation_id=str(uuid4()), form_id=form_id)- generator.assert_not_called()---def test_resume_returns_when_app_missing(mocker: MockerFixture, task_session: Session) -> None:- conversation_id, form_id = str(uuid4()), str(uuid4())- task_session.add(_form(form_id=form_id, conversation_id=conversation_id, app_id=str(uuid4())))- task_session.commit()- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")- mod.resume_agent_app_execution(conversation_id=conversation_id, form_id=form_id)- generator.assert_not_called()---def test_resume_returns_when_conversation_missing(mocker: MockerFixture, task_session: Session) -> None:- tenant_id, app_id, conversation_id, form_id = (str(uuid4()) for _ in range(4))- task_session.add_all(- [- _app(app_id=app_id, tenant_id=tenant_id),- _form(form_id=form_id, conversation_id=conversation_id, app_id=app_id),- ]- )- task_session.commit()- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")- mod.resume_agent_app_execution(conversation_id=conversation_id, form_id=form_id)- generator.assert_not_called()---def test_resume_returns_when_no_user_resolvable(mocker: MockerFixture, task_session: Session) -> None:- tenant_id, app_id, conversation_id, form_id = (str(uuid4()) for _ in range(4))- task_session.add_all(- [- _app(app_id=app_id, tenant_id=tenant_id),- _conversation(conversation_id=conversation_id, app_id=app_id),- _form(form_id=form_id, conversation_id=conversation_id, app_id=app_id),- ]- )- task_session.commit()- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")- mod.resume_agent_app_execution(conversation_id=conversation_id, form_id=form_id)- generator.assert_not_called()---def test_resume_returns_when_account_id_set_but_account_gone(mocker: MockerFixture, task_session: Session) -> None:- tenant_id, app_id, conversation_id, form_id = (str(uuid4()) for _ in range(4))- task_session.add_all(- [- _app(app_id=app_id, tenant_id=tenant_id),- _conversation(conversation_id=conversation_id, app_id=app_id, account_id=str(uuid4())),- _form(form_id=form_id, conversation_id=conversation_id, app_id=app_id),- ]- )- task_session.commit()- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")- mod.resume_agent_app_execution(conversation_id=conversation_id, form_id=form_id)- generator.assert_not_called()---def test_resume_swallows_generator_exception(mocker: MockerFixture, task_session: Session) -> None:- tenant_id, app_id, conversation_id, form_id, account_id = (str(uuid4()) for _ in range(5))- _seed_account(task_session, tenant_id=tenant_id, account_id=account_id)- task_session.add_all(- [- _app(app_id=app_id, tenant_id=tenant_id),- _conversation(conversation_id=conversation_id, app_id=app_id, account_id=account_id),- _form(form_id=form_id, conversation_id=conversation_id, app_id=app_id),- ]- )- task_session.commit()- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")- generator.return_value.resume_after_form_submission.side_effect = RuntimeError("boom")-- mod.resume_agent_app_execution(conversation_id=conversation_id, form_id=form_id)-- generator.return_value.resume_after_form_submission.assert_called_once()diff --git a/api/uv.lock b/api/uv.lockindex db7ac88a925..32b72147fea 100644--- a/api/uv.lock+++ b/api/uv.lock@@ -1,5 +1,5 @@version = 1-revision = 3+revision = 5requires-python = "==3.13.*"resolution-markers = ["sys_platform == 'win32'",@@ -1363,8 +1363,8 @@ requires-dist = [{ name = "openshell", marker = "extra == 'server'", specifier = ">=0.0.106,<0.1.0" },{ name = "pydantic", specifier = ">=2.12.5,<2.13" },{ name = "pydantic-ai-harness", specifier = ">=0.20.0,<0.21.0" },- { name = "pydantic-ai-slim", specifier = ">=2.30.0,<3.0.0" },- { name = "pydantic-ai-slim", extras = ["anthropic", "google", "openai"], marker = "extra == 'server'", specifier = ">=2.30.0,<3.0.0" },+ { name = "pydantic-ai-slim", specifier = "==2.31.0" },+ { name = "pydantic-ai-slim", extras = ["anthropic", "google", "openai"], marker = "extra == 'server'", specifier = "==2.31.0" },{ name = "pydantic-settings", marker = "extra == 'server'", specifier = ">=2.12.0,<3.0.0" },{ name = "redis", marker = "extra == 'server'", specifier = ">=7.4.0,<8.0.0" },{ name = "typing-extensions", specifier = ">=4.12.2,<5.0.0" },@@ -1392,6 +1392,7 @@ docs = [name = "dify-api"version = "1.17.1"source = { virtual = "." }+default-groups = ["kms", "storage", "tools", "trace-all", "vdb-all"]dependencies = [{ name = "aliyun-log-python-sdk" },{ name = "azure-identity" },diff --git a/dify-agent/README.md b/dify-agent/README.mdindex 033974aa6ba..3cac71369aa 100644--- a/dify-agent/README.md+++ b/dify-agent/README.md@@ -1,7 +1,8 @@# Dify Agent-Agenton documentation lives in [`docs/agenton/guide/index.md`](docs/agenton/guide/index.md) and-[`docs/agenton/examples/index.md`](docs/agenton/examples/index.md).+Dify Agent runs Pydantic AI with native capabilities and toolsets. Module+configuration and session state are JSON data; infrastructure services and+operation resources have explicit owners.-Dify Agent runtime documentation lives in [`docs/dify-agent/index.md`](docs/dify-agent/index.md).-Build all docs with `make docs` from this directory.+See [runtime documentation](docs/dify-agent/index.md) and the+[operations guide](docs/dify-agent/guide/index.md). Run `make docs` to build docs.diff --git a/dify-agent/docs/agenton/examples/index.md b/dify-agent/docs/agenton/examples/index.mddeleted file mode 100644index 61487f5a11e..00000000000--- a/dify-agent/docs/agenton/examples/index.md+++ /dev/null@@ -1,19 +0,0 @@-# Agenton examples--The Agenton examples live under `examples/agenton/agenton_examples` and are kept-importable as a package so documentation can reference real source files.--## Basics--```snippet {path="/examples/agenton/agenton_examples/basics.py"}-```--## Pydantic AI bridge--```snippet {path="/examples/agenton/agenton_examples/pydantic_ai_bridge.py"}-```--## Session snapshots--```snippet {path="/examples/agenton/agenton_examples/session_snapshot.py"}-```diff --git a/dify-agent/docs/agenton/guide/index.md b/dify-agent/docs/agenton/guide/index.mddeleted file mode 100644index e9d322d7c8a..00000000000--- a/dify-agent/docs/agenton/guide/index.md+++ /dev/null@@ -1,187 +0,0 @@-# Agenton user guide--Agenton composes reusable graph plans from `LayerNode`s and `LayerProvider`s.-The core is state-only: a `Compositor` stores no live layer instances, clients,-cleanup stacks, or run state. Each `Compositor.enter(...)` call creates a fresh-`CompositorRun` with new layer instances, direct dependency bindings, lifecycle-state, and an optional hydrated session snapshot.--## Config and runtime state--- **Graph config** is serializable topology: node `name`, provider `type`,- dependency mappings, and metadata. `LayerNodeConfig` deliberately contains no- layer config.-- **Per-run layer config** is passed to `Compositor.enter(configs=...)` as a- mapping keyed by node name. Providers validate each value with the layer's- `config_type` before any factory runs.-- **Runtime state** is serializable per-layer invocation state on- `layer.runtime_state`. Session snapshots persist only lifecycle state and this- model's JSON-safe data.-- **Live Python resources** such as clients, files, sockets, or process handles- stay outside Agenton core. Own them in application code or integration-specific- context managers that wrap compositor entry.--## Define a config-backed layer--Use a `LayerConfig` model for per-run config and inherit from a typed layer family-so `Layer.__init_subclass__` can infer schemas:--```python {test="skip" lint="skip"}-from dataclasses import dataclass--from pydantic import ConfigDict-from typing_extensions import Self, override--from agenton.layers import LayerConfig, NoLayerDeps, PlainLayer---class GreetingConfig(LayerConfig):- prefix: str-- model_config = ConfigDict(extra="forbid")---@dataclass(slots=True)-class GreetingLayer(PlainLayer[NoLayerDeps, GreetingConfig]):- type_id = "example.greeting"-- prefix: str-- @classmethod- @override- def from_config(cls, config: GreetingConfig) -> Self:- return cls(prefix=config.prefix)-- @property- @override- def prefix_prompts(self) -> list[str]:- return [self.prefix]-```--Omitted schema slots default to `EmptyLayerConfig` and `EmptyRuntimeState`.-Lifecycle hooks are no-argument methods on the layer instance; use `self.deps`-for dependencies and `self.runtime_state` for serializable mutable state.--## Live resources--Agenton does not own resource cleanup. Keep live resources in the surrounding-application and pass them to capability methods explicitly:--```python {test="skip" lint="skip"}-@dataclass(slots=True)-class ClientUserLayer(PlainLayer[NoLayerDeps]):- def make_client_user(self, *, http_client: httpx.AsyncClient) -> ClientUser:- return ClientUser(http_client)---compositor = Compositor([LayerNode("client_user", ClientUserLayer)])-async with httpx.AsyncClient() as http_client:- async with compositor.enter() as run:- layer = run.get_layer("client_user", ClientUserLayer)- user = layer.make_client_user(http_client=http_client)-```--This keeps deterministic cleanup at the integration boundary and leaves Agenton-snapshots limited to serializable runtime state.--## Build a compositor--Use providers for config-backed layers and pass per-run config at entry time:--```python {test="skip" lint="skip"}-from agenton.compositor import Compositor, CompositorConfig, LayerNodeConfig, LayerProvider-from agenton_collections.layers.plain import PromptLayer, PromptLayerConfig---providers = (- LayerProvider.from_layer_type(PromptLayer),- LayerProvider.from_layer_type(GreetingLayer),-)-compositor = Compositor.from_config(- CompositorConfig(- layers=[- LayerNodeConfig(name="prompt", type="plain.prompt"),- LayerNodeConfig(name="greeting", type="example.greeting"),- ]- ),- providers=providers,-)--async with compositor.enter(- configs={- "prompt": PromptLayerConfig(user="Answer with examples."),- "greeting": GreetingConfig(prefix="Hi"),- }-) as run:- prompts = run.prompts-```--Use `LayerProvider.from_factory(...)` when construction needs Python objects or-callables. Provider factories receive only validated config and must return a-fresh layer instance for every invocation. For node-specific construction with-`Compositor.from_config`, pass a `node_providers={"node_name": provider}` mapping-to override the provider selected by type id for that node.--## Dependencies--Layer dependencies bind direct layer instances onto `self.deps` for one run.-Dependency mappings use dependency field names as keys and compositor node names-as values:--```python {test="skip" lint="skip"}-class ModelDeps(LayerDeps):- plugin: PluginLayer---@dataclass(slots=True)-class ModelLayer(PlainLayer[ModelDeps]):- def make_model(self) -> Model:- return self.deps.plugin.make_provider()-```--Optional dependencies are assigned `None` when absent. Missing required-dependencies, unknown dependency keys, and dependency targets with the wrong layer-type fail before lifecycle hooks run.--## System prompts, user prompts, and tools--Layers expose four authoring surfaces:--- `prefix_prompts`: system prompt fragments collected in layer order.-- `suffix_prompts`: system prompt fragments collected in reverse layer order.-- `user_prompts`: user-message fragments collected in layer order.-- `tools`: tool entries collected in layer order.--`PromptLayer` accepts `prefix`, `user`, and `suffix` config fields. Aggregation is-available on the active `CompositorRun` as `run.prompts`, `run.user_prompts`, and-`run.tools`. For pydantic-ai, import-`agenton_collections.transformers.pydantic_ai.PYDANTIC_AI_TRANSFORMERS` and pass-it to `Compositor(...)` or `Compositor.from_config(...)` so tagged layer items are-converted to Pydantic AI prompt, user prompt, and tool values.--## Session snapshot and restore--Core Agenton run slots default to delete-on-exit. Call `run.suspend_on_exit()` or-`run.suspend_layer_on_exit(name)` inside the active context when the next snapshot-should be resumable:--```python {test="skip" lint="skip"}-async with compositor.enter(configs=configs) as run:- run.suspend_on_exit()--snapshot = run.session_snapshot-async with compositor.enter(configs=configs, session_snapshot=snapshot) as restored_run:- restored_layer = restored_run.get_layer("stateful", StatefulLayer)-```--`run.session_snapshot` is populated after context exit. Snapshots include ordered-layer names, non-active lifecycle states, and JSON-safe runtime state only. Active-state is rejected at the DTO boundary, and closed layers cannot be entered again.-To resume, pass the snapshot to a later `Compositor.enter(...)` call with the same-layer names and order.--See also:--- `examples/agenton/agenton_examples/basics.py`-- `examples/agenton/agenton_examples/pydantic_ai_bridge.py`-- `examples/agenton/agenton_examples/session_snapshot.py`diff --git a/dify-agent/docs/agenton/index.md b/dify-agent/docs/agenton/index.mddeleted file mode 100644index 2af61df2267..00000000000--- a/dify-agent/docs/agenton/index.md+++ /dev/null@@ -1,4 +0,0 @@-# Agenton documentation--- [User guide](guide/index.md) explains how to compose layers, register config-backed- plugins, use system/user prompts, and snapshot sessions.diff --git a/dify-agent/docs/dify-agent/concepts/run-lifecycle/index.md b/dify-agent/docs/dify-agent/concepts/run-lifecycle/index.mdindex e4a3593d986..69404705afe 100644--- a/dify-agent/docs/dify-agent/concepts/run-lifecycle/index.md+++ b/dify-agent/docs/dify-agent/concepts/run-lifecycle/index.md@@ -1,197 +1,38 @@-# Agent Run Lifecycle+# Agent run lifecycle-This page explains, from a caller's perspective, how an `agent run` relates to a-`workflow run` and how callers control Agenton layer exit behavior with exit-signals.+The server validates current Config, restored State and module references before+external operations. It creates fresh native Capability/Toolset instances and+runs Pydantic AI with a per-run Deps object. Current prompts and instructions are+built from that run's config.-## Relationship between agent runs and workflow runs+Native `wrap_run` scopes acquire operation resources and clean them in `finally`.+Runtime acquires a lease; Shell bootstraps once and removes tracked jobs on exit;+Config pulls mentioned assets on successful first initialization. Initialization+flags are written only after successful setup, so failures can retry. The API's+workflow terminal events own Workspace retirement and physical resource collection.-A `workflow run` is one full workflow execution. An `agent run` is one Agent-execution started by an Agent node while the workflow is running. They are not a-one-to-one mapping: one `workflow run` often contains multiple `agent run`s.+The runner saves captured conversation history in its outer `finally`, strips+transient instructions and marks unexecuted trailing tool calls interrupted.+If no messages were captured, restored history remains intact. Compaction rewrites+are included. A terminal state snapshot is built after capability cleanup for+success, failure and cancellation.-### First entry into an Agent node--When a `workflow run` first reaches an Agent node, the caller starts the first-`agent run` for that node.--The `agent run` enters the layers defined in its composition:--- If the request does not include `session_snapshot`, each layer enters with a- fresh state and initializes its own runtime state.-- If the request includes a previously returned `session_snapshot`, each layer- restores its runtime state from that snapshot and continues from there.--After entering layers, the Agent runs the LLM and tool calls until the current-`agent run` reaches a terminal result. This means the `agent run` has ended; it-does not necessarily mean the outer workflow has ended.--### Ending with a `final_output` tool call--If the Agent ends with a `final_output` tool call, the Agent node has produced-its final output for this pass. The caller should read the terminal output of the-current `agent run` and let the `workflow run` continue to downstream nodes.--The current `agent run` has ended, but the returned `session_snapshot` can still-be saved. If the same `workflow run` may enter the same Agent session again, the-caller should keep using that snapshot.--### Ending with a human tool call--If the Agent ends with a human tool call, the Agent needs human input before the-business process can continue. A common misconception is to treat this as a-paused agent run. **Agent runs do not have a pause state.** With a human tool, the-current `agent run` has ended; the outer `workflow run` is what should be paused.--The caller should handle this flow as follows:--1. Read the current `agent run` result and detect `deferred_tool_call` on the- terminal `run_succeeded` event.-2. Enter workflow HITL handling and pause graphon.-3. Wait for the human input to be completed.-4. When resuming the workflow, start a second `agent run` on the same Agent node- with the previous `session_snapshot`, matching composition, and- `deferred_tool_results` keyed by the original tool call id.-5. Keep the history layer active so Dify Agent can match the result to the- pending tool call stored in the previous run's message history.--In other words, a human tool does not mean “pause this agent run until it is-resumed.” It means “this agent run ended with a result that requires human-input.” After the caller completes HITL handling, it should create a new-`agent run` using the same history/session snapshot to continue.--### Entering another Agent node--When the same `workflow run` continues and reaches another Agent node, it starts-another `agent run`. That next Agent node may be a different Agent, or it may be-the same Agent reused by a roaster.--Therefore, callers should save and pass `session_snapshot` by Agent session, not-assume that one `workflow run` has only one `agent run`.--## Agent run exit signals--When an `agent run` ends, Dify Agent exits the layers that were entered by the-current run. Callers control whether each layer is suspended or deleted through-`CreateRunRequest.on_exit`.--Exit signals control the **layer lifecycle state**, not the execution state of an-`agent run`. The default policy is `suspend`, so any run that enters and exits its-compositor context can return a reusable `session_snapshot`, including failed or-cancelled runs. Failures or cancellations before entry have no new snapshot.--### Default: suspend layers--If a request does not explicitly set `on_exit`, it is equivalent to:+Snapshot v2 stores only JSON state:```json-{- "on_exit": {- "default": "suspend",- "layers": {}- }-}+{"schema_version": 2, "layers": {"history": {"messages": []}}}```-This means every entered layer exits as `suspended` and is written into the-returned `session_snapshot`. The caller can submit that snapshot in the next-`agent run` to resume those layers.--For normal Agent execution inside a workflow, including both `final_output` and-human-tool endings, callers should keep the default suspend policy unless they-know the Agent session will never be resumed.--### Delete layers when the workflow run ends--When the whole `workflow run` has ended, the caller should start one more cleanup-`agent run`:--- Reuse the last available `session_snapshot`.-- Omit the LLM layer, because this run is only for entering and cleaning existing- state; it does not need to call the model again.-- Exit layers with the `delete` signal.--The cleanup request should use an exit signal like this:--```json-{- "on_exit": {- "default": "delete",- "layers": {}- }-}-```--After this run, the corresponding layers exit through the delete path. A snapshot-returned after deletion should not be used to resume the Agent session again.--### Override selected layers--The caller can also suspend by default while deleting only selected layers:--```json-{- "on_exit": {- "default": "suspend",- "layers": {- "temporary_context": "delete"- }- }-}-```--Only `temporary_context` exits with `delete`; all other active layers exit with-the default `suspend` behavior.--## Exit signal API reference--Fields related to exit control in `CreateRunRequest`:--| Field | Type | Required | Meaning |-| --- | --- | --- | --- |-| `session_snapshot` | `CompositorSessionSnapshot \| None` | no | The session snapshot returned by the previous `agent run`. It resumes the same Agent session. |-| `on_exit` | `LayerExitSignals` | no | The exit policy used when this `agent run` exits layers. If omitted, all active layers are suspended by default. |--`LayerExitSignals` has this structure:--| Field | Type | Default | Meaning |-| --- | --- | --- | --- |-| `default` | `"suspend" \| "delete"` | `"suspend"` | Exit intent for layers not explicitly listed in `layers`. |-| `layers` | `dict[str, "suspend" \| "delete"]` | `{}` | Per-layer exit intent overrides by layer name. Each key must refer to a layer name in the current composition. |--Exit intent semantics:--| Exit intent | Layer exit state | Effect |-| --- | --- | --- |-| `suspend` | `suspended` | Keep the layer runtime state and make the returned `session_snapshot` usable by a later `agent run`. |-| `delete` | `closed` | Delete/close the layer context. The corresponding layer snapshot should not be resumed again. |--Python DTO example:--```python {test="skip" lint="skip"}-from agenton.layers import ExitIntent-from dify_agent.protocol import CreateRunRequest, LayerExitSignals---request = CreateRunRequest(- composition=composition,- session_snapshot=previous_snapshot,- on_exit=LayerExitSignals(- default=ExitIntent.SUSPEND,- layers={- "temporary_context": ExitIntent.DELETE,- },- ),-)-```--Notes:--- `on_exit` only controls layer exit behavior; it does not cancel an `agent run`.-- Agent runs do not have a pause state. Human-tool waiting is handled by the- outer workflow/HITL flow.-- Keys in `on_exit.layers` must refer to layer names in the current composition.-- Use `suspend` and save the returned `session_snapshot` when the same Agent- session needs to continue later.-- After the whole `workflow run` ends, start one more cleanup run without an LLM- layer and use `delete`.+Configurations, clients, lease handles, tokens, models and lifecycle enums are+excluded. State is keyed by name, so instruction order does not constrain resume;+known optional modules can be added or removed. The API resubmits current Config+and retains session ownership through `AgentWorkspaceBinding.session_snapshot`.+All snapshot readers use `SessionSnapshot` validation. Its `migrate_snapshot`+validator dispatches v1 (including unversioned legacy lists) to the data-only+`migrate_snapshot_v1_to_v2` helper. V2 is validated directly; unknown explicit+versions are rejected. Reading converts data in memory without updating stored+JSON; the API saves the terminal v2 snapshot through its existing session owner.+Known legacy names map to their meaningful State and removed AskHuman slots are+discarded. Their unanswered tool calls are marked interrupted so native history+repair closes them before the first new user turn. All runs use the native runner.+Unknown legacy names and malformed state are rejected.diff --git a/dify-agent/docs/dify-agent/concepts/runtime-resources/index.md b/dify-agent/docs/dify-agent/concepts/runtime-resources/index.mdindex 8f2ae9fc2b5..cecde67ffe9 100644--- a/dify-agent/docs/dify-agent/concepts/runtime-resources/index.md+++ b/dify-agent/docs/dify-agent/concepts/runtime-resources/index.md@@ -10,7 +10,7 @@ Dify separates persistent product resources from request-time execution:- a **RuntimeLease** is operation-scoped access to the physical Binding.`AgentWorkspaceBinding.id` is the participant, materialized Home, and persisted-Agenton session identity. `agent_id` identifies the source Agent. The same+module session identity. `agent_id` identifies the source Agent. The sameAgent can therefore have multiple active Bindings in one Workspace:each has an independent Home and session, while all may share Workspace files.@@ -19,11 +19,11 @@ physical representation. For example, current E2B maps one Binding and itsWorkspace to one E2B resource, while Local can attach multiple materializedHomes to one shared Workspace.-## Runtime layer graph+## Runtime modulesAgent requests do not expose separate Home, Workspace, or Sandbox layers. DifyAPI resolves the Binding selected by the product flow and sends its opaque-backend ref to the `dify.runtime` layer:+backend ref to the `runtime` module:```mermaidflowchart LR@@ -35,13 +35,13 @@ flowchart LRRT --> SH```-`DifyRuntimeLayer` calls the selected `ExecutionBindingBackend.acquire()` when-its resource context opens and `release()` when the operation ends. It exposes-the resulting `RuntimeLease` only while that context is active. The layer does+`runtime.Capability` calls the selected `ExecutionBindingBackend.acquire()` when+its native `wrap_run` scope opens and `release()` when the operation ends. It exposes+the resulting `RuntimeLease` only while that context is active. The module doesnot create, retire, or destroy persistent resources, and it stores no backend-SDK object in an Agenton session snapshot.+SDK object in an module session snapshot.-The Shell layer consumes `RuntimeLease.commands` and `RuntimeLease.layout`. It+The Shell module consumes `RuntimeLease.commands` and `RuntimeLease.layout`. Ittracks only request-local shell job ids and offsets.Closing a run clears that job state; it does not retire the Binding.@@ -56,7 +56,7 @@ Dify API is the lifecycle ledger. It stores three resource records:| `agent_workspace_bindings` | One materialized participant, private Home, and resumable session attached to a Workspace. | `backend_binding_ref` |Backend refs are opaque strings interpreted only by the selected backend-adapter. Dify API stores the latest Agenton session snapshot on the Binding, but+adapter. Dify API stores the latest module session snapshot on the Binding, butit does not serialize `RuntimeLease`, SDK clients, credentials, or temporaryaccess tokens.@@ -99,7 +99,6 @@ composition contains:```json{"name": "runtime",- "type": "dify.runtime","config": {"backend_binding_ref": "opaque-backend-binding-ref"}}```@@ -227,7 +226,7 @@ remain independently configurable. Runtime resources pause on timeout, but thisresource setting does not own the Agent run terminal state. It is not a retentionTTL and does not delete paused resources or immutable snapshots.-See the [Shell layer](../../user-manual/shell-layer/index.md) for request+See the [Shell module](../../user-manual/shell-layer/index.md) for requestcomposition, the [Operations Guide](../../guide/index.md) for Local and E2Bvalidation, and the [OpenShell guide](../../guide/openshell.md) for OpenShellconfiguration and validation.diff --git a/dify-agent/docs/dify-agent/examples/index.md b/dify-agent/docs/dify-agent/examples/index.mdindex 8624dc790e2..b004f4b33af 100644--- a/dify-agent/docs/dify-agent/examples/index.md+++ b/dify-agent/docs/dify-agent/examples/index.md@@ -1,8 +1,8 @@# Dify Agent examples-These examples live under `examples/dify_agent/dify_agent_examples`. They are-separated from Agenton examples because they depend on Dify Agent runtime services-such as the FastAPI server, Redis, or the plugin daemon.+These examples live under `examples/dify_agent/dify_agent_examples`. They use+registered modules and depend on the Agent server, Redis, Dify API, and plugin+daemon settings described in the operations guide.## Run a Dify plugin-daemon backed modeldiff --git a/dify-agent/docs/dify-agent/get-started/index.md b/dify-agent/docs/dify-agent/get-started/index.mdindex c2db758c454..459984e2056 100644--- a/dify-agent/docs/dify-agent/get-started/index.md+++ b/dify-agent/docs/dify-agent/get-started/index.md@@ -1,263 +1,25 @@-# Get started with Dify Agent--This guide walks through the smallest end-to-end path for the current Dify Agent-runtime: install dependencies, configure the server, start it, then use the Python-client to create one plugin-daemon-backed run.--## Prerequisites--Install or prepare:--- Python 3.13 or newer-- `uv`-- Redis-- a reachable Dify plugin daemon-- a plugin/provider already available through that plugin daemon, such as- `langgenius/openai`--## Install dependencies--From the repository root, enter the `dify-agent` package and install all extras-and dependency groups:--```bash-cd dify-agent-uv sync --all-extras --all-groups-```--Only the `server` extra is required to run the API server, but installing all-extras and groups gives you the local test, docs, and server dependencies in one-environment.--## Start Redis--Skip this step if you already have a reachable Redis instance.--```bash-docker run -d \- --name dify-agent-redis \- -p 6379:6379 \- redis:7-alpine-```--## Configure the server--Create or update `.env` in the `dify-agent` directory:--```bash-cat > .env <<'EOF'-DIFY_AGENT_REDIS_URL=redis://localhost:6379/0-DIFY_AGENT_REDIS_PREFIX=dify-agent--DIFY_AGENT_PLUGIN_DAEMON_URL=http://localhost:5002-DIFY_AGENT_PLUGIN_DAEMON_API_KEY=replace-with-plugin-daemon-server-key--DIFY_AGENT_INNER_API_URL=http://localhost:5001-DIFY_AGENT_INNER_API_KEY=replace-with-dify-inner-api-key-for-plugin-EOF-```--The minimum settings are:--- `DIFY_AGENT_REDIS_URL`: Redis connection URL used for run records and event- streams.-- `DIFY_AGENT_REDIS_PREFIX`: Redis key prefix for this server.-- `DIFY_AGENT_PLUGIN_DAEMON_URL`: base URL for the Dify plugin daemon.-- `DIFY_AGENT_PLUGIN_DAEMON_API_KEY`: API key sent by the server to the plugin- daemon. In a Dify Docker setup this is usually the value previously configured- as `PLUGIN_DAEMON_KEY`.-- `DIFY_AGENT_INNER_API_URL`: Dify API service root for `/inner/api/...` calls.-- `DIFY_AGENT_INNER_API_KEY`: API key sent to Dify API inner plugin endpoints.- In Docker this should match `PLUGIN_DIFY_INNER_API_KEY`, which maps to Dify- API `INNER_API_KEY_FOR_PLUGIN`.--See `.example.env` for the full server settings template.--If you plan to run `dify.shell`, select a coherent Home Snapshot and Execution-Binding backend. A standalone Local server normally uses:--```env-DIFY_AGENT_RUNTIME_BACKEND=local-DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT=http://127.0.0.1:5004-DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN=-# Optional when shellctl runs directly on a host without /home/dify:-# DIFY_AGENT_LOCAL_SANDBOX_MATERIALIZED_HOME_ROOT=/tmp/dify-agent/materialized-homes-# DIFY_AGENT_LOCAL_SANDBOX_WORKSPACE_ROOT=/tmp/dify-agent/workspaces-# DIFY_AGENT_LOCAL_SANDBOX_HOME_SNAPSHOT_ROOT=/tmp/dify-agent/home-snapshots-```--E2B requires `DIFY_AGENT_E2B_API_KEY` and defaults to the prepared-`difys-default-team/dify-agent-local-sandbox` template. The E2B active timeout-pauses the physical resource behind a Binding; it is not a retention TTL.-Enterprise supports Bindings created from its deployment-default Home.-Immutable Home Snapshot creation and materialization remain unsupported there.--A shell-enabled request includes Execution Context, `dify.runtime`, and-`dify.shell`. Dify API creates or resolves the specific persistent Binding for-the request's product context;-`DifyRuntimeLayerConfig.backend_binding_ref` carries only that opaque ref and-opens a new operation-scoped `RuntimeLease` for the run. When shell jobs need to-call back with the `dify-agent` command, also set-`DIFY_AGENT_STUB_API_BASE_URL` and the Sandbox-reachable Dify API base-`DIFY_AGENT_SANDBOX_FILES_BASE_URL`. The supplied default configs include a-development `DIFY_AGENT_SERVER_SECRET_KEY`, but production deployments should-override it with a unique 32-byte base64url value as documented in-`.example.env`.--See [Runtime resources](../concepts/runtime-resources/index.md) for the layer-graph and state ownership, and the [Operations Guide](../guide/index.md) for-backend-specific configuration and validation commands.--## Start the Dify Agent server--For a normal local server process:--```bash-make serve-```--For development with uvicorn reload:--```bash-make dev-```--Both commands serve the API at:--```text-http://127.0.0.1:8000-```--The equivalent development command is:--```bash-uv run --extra server uvicorn dify_agent.server.app:app \- --host 127.0.0.1 \- --port 8000 \- --reload-```--`ServerSettings` reads `.env` from the current `dify-agent` directory, or from-`dify-agent/.env` when the command is run from the repository root.--## Create a Python client example--In another shell, keep working from the `dify-agent` directory. Create-`run_dify_agent_client.py` with the example below, then replace the placeholder-tenant, user, app, provider, and model values.--```python {test="skip" lint="skip"}-import asyncio-import json-import sys--from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig-from dify_agent.client import Client-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig-from dify_agent.layers.dify_plugin import (- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,- DifyPluginLLMLayerConfig,-)-from dify_agent.protocol import DIFY_AGENT_MODEL_LAYER_ID, CreateRunRequest, RunComposition, RunLayerSpec---API_BASE_URL = "http://127.0.0.1:8000"--TENANT_ID = "replace-with-tenant-id"-PLUGIN_ID = "langgenius/openai"-USER_ID = "replace-with-user-id"-APP_ID = "replace-with-app-id"--# Keep these aligned with DIFY_AGENT_PROVIDER and DIFY_AGENT_MODEL_NAME in dify-agent/.env.-MODEL_PROVIDER = "replace-with-provider-from-dify-agent-env"-MODEL_NAME = "replace-with-model-from-dify-agent-env"--SYSTEM_PROMPT = "You are a concise assistant."-USER_PROMPT = "用一句话介绍 Dify Agent。"---def build_request() -> CreateRunRequest:- return CreateRunRequest(- composition=RunComposition(- layers=[- RunLayerSpec(- name="prompt",- type=PLAIN_PROMPT_LAYER_TYPE_ID,- config=PromptLayerConfig(prefix=SYSTEM_PROMPT, user=USER_PROMPT),- ),- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id=TENANT_ID,- user_id=USER_ID,- user_from="account",- app_id=APP_ID,- agent_mode="single_step",- invoke_from="debugger",- ),- ),- RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id=PLUGIN_ID,- model_provider=MODEL_PROVIDER,- model=MODEL_NAME,- ),- ),- ],- ),- )---async def main() -> int:- async with Client(base_url=API_BASE_URL, stream_timeout=None) as client:- run = await client.create_run(build_request())- print(f"created run: {run.run_id}, status={run.status}")-- async for event in client.stream_events(run.run_id):- print(event.model_dump_json(indent=2))-- if event.type == "run_succeeded":- print("final output:")- print(json.dumps(event.data.output, ensure_ascii=False, indent=2))- return 0-- if event.type == "run_failed":- print(f"run failed: {event.data.error}", file=sys.stderr)- return 2-- return 0---if __name__ == "__main__":- raise SystemExit(asyncio.run(main()))-```--## Run the client example--The server-side `.env` controls how Dify Agent reaches Dify API and the plugin-daemon. The client example selects the tenant/user/app/plugin/provider/model;-Dify API resolves model credentials at invocation time.--Run the example from the `dify-agent` directory:--```bash-uv run python ./run_dify_agent_client.py-```--Set `MODEL_PROVIDER` and `MODEL_NAME` to the same values as-`DIFY_AGENT_PROVIDER` and `DIFY_AGENT_MODEL_NAME` in `dify-agent/.env`.--## Troubleshooting--If the run fails, check these items first:--1. Redis is running and reachable from the Dify Agent server.-2. The Dify Agent server is listening on `127.0.0.1:8000`.-3. `DIFY_AGENT_INNER_API_URL` points to the Dify API used by this environment.-4. `DIFY_AGENT_INNER_API_KEY` matches Dify API's configured inner API key.-5. `PLUGIN_ID`, `MODEL_PROVIDER`, and `MODEL_NAME` in the client example match- a model provider configured for the selected tenant in Dify API.+# Get started++Create a run with `POST /runs`; poll `/runs/{run_id}` or consume its event stream.+The composition schema version is 2. Each entry contains a registered `name` and+current JSON `config`. Module identity comes from the server registry; there are+no graph type/dependency fields or generic per-module exit policy.++```json+{+ "composition": {+ "schema_version": 2,+ "layers": [+ {"name": "execution_context", "config": {"tenant_id": "tenant", "agent_mode": "agent_app", "invoke_from": "service-api"}},+ {"name": "prompt", "config": {"prefix": "Be helpful", "user": "Hello"}},+ {"name": "history", "config": {}},+ {"name": "llm", "config": {"execution_context": "execution_context", "plugin_id": "langgenius/openai", "model_provider": "openai", "model": "gpt-4o-mini"}}+ ]+ }+}+```++Resume by including the previous terminal `session_snapshot` and submitting the+current composition. `llm` is required, `history` and `output` are optional.+Resource cleanup always happens at exit. Cancellation is a separate operation;+its terminal event is published only after the owner run has cleaned up.diff --git a/dify-agent/docs/dify-agent/guide/index.md b/dify-agent/docs/dify-agent/guide/index.mdindex 6be5b103f4b..f7bf9b8fc61 100644--- a/dify-agent/docs/dify-agent/guide/index.md+++ b/dify-agent/docs/dify-agent/guide/index.md@@ -345,12 +345,14 @@ Each run explicitly limits Pydantic AI to 500 model-request steps. Tool calls donot have a separate count limit, but every model request used to continue thetool loop consumes one of those steps.-`DIFY_AGENT_RUN_TIMEOUT_SECONDS` additionally applies a wall-clock deadline only-around Pydantic AI's `agent.run(...)`, including its model/tool loop and event-handler. It does not include compositor entry, RuntimeLease acquisition, tool-preparation, session snapshot generation, or resource exit. Expiry cancels the-active run task, allows the compositor to release resources, and finalizes the-run as failed with `error_type: "agent_run_limit_exceeded"`.+`DIFY_AGENT_RUN_TIMEOUT_SECONDS` additionally applies a wall-clock deadline around+native Pydantic AI's `agent.run(...)`. This includes capability entry, RuntimeLease+acquisition, dynamic tool preparation, the model/tool loop, and the event handler.+Request validation and agent assembly happen before this deadline. Expiry cancels+the native run; capability scopes unwind and release resources before the runner+generates the session snapshot and finalizes the run as failed with+`error_type: "agent_run_limit_exceeded"`. History persistence, snapshot generation,+and terminal finalization occur after native execution.During FastAPI shutdown the scheduler rejects new runs, waits up to`DIFY_AGENT_SHUTDOWN_GRACE_SECONDS` for active tasks, then cancels remaining tasks@@ -387,33 +389,29 @@ terminal event type.## Run inputs and session snapshots-The API does not accept a top-level `user_prompt`. Submit a `RunComposition`-whose Agenton layers provide user input. With the MVP provider set, use-`plain.prompt` and its `config.user` field:+Submit a `RunComposition` with registered module names and JSON Config. The+`llm` model module is required and references an `execution_context` module.+Prompt modules contribute instructions and `config.user` input:```json{"composition": {- "schema_version": 1,+ "schema_version": 2,"layers": [- {- "name": "prompt",- "type": "plain.prompt",- "config": {- "prefix": "You are concise.",- "user": "Summarize the current state."- }- }+ {"name": "prompt", "config": {"prefix": "You are concise.", "user": "Summarize the current state."}},+ {"name": "execution_context", "config": {"tenant_id": "tenant-id", "agent_mode": "agent_app", "invoke_from": "web-app"}},+ {"name": "llm", "config": {"plugin_id": "langgenius/openai", "model_provider": "openai", "model": "gpt-4o-mini"}}]}}````config.user` can be a string or a list of strings. Empty or whitespace-only-effective prompts are rejected during create-run validation before the run is-persisted or scheduled.+effective prompts and module configuration are validated by the runner before+resource acquisition or model I/O. HTTP create-run parses the wire shape, persists+the run and schedules execution; configuration errors produce `run_failed`.-Agent App callers can use the `dify.user_prompt` layer to send text and images+Agent App callers can use the `agent_app_user_prompt` module to send text and imagesin the same model turn. Each image must provide exactly one transport: anHTTP(S) `url` or unprefixed Base64 data in `base64_data`. The image is passed asstructured multimodal content; it is not interpolated into `config.text`.@@ -421,7 +419,6 @@ structured multimodal content; it is not interpolated into `config.text`.```json{"name": "agent_app_user_prompt",- "type": "dify.user_prompt","config": {"text": "Describe this image.","files": [@@ -451,17 +448,23 @@ is presented, independently of its file `type` (`image`, `document`, `audio`,`transfer_method: "remote_url"` with `url`, or a `local_file`, `tool_file`, or`datasource_file` transfer method with a canonical `reference`.-The layer appends sandbox file-download instructions for download attachments+The module appends sandbox file-download instructions for download attachmentsand adds multimodal attachments as structured model content. Callers keep`config.text` as the original user text. Omitting `config.files` is equivalentto an empty list.-The optional Pydantic AI history layer uses the reserved name `history` and-persists captured messages in session snapshots for later resume. Resume from a-terminal event's `session_snapshot` using the same layer composition, names, and-order. Success always contains a snapshot. Failure and cancellation contain one-only when compositor entry succeeded and layer exit completed; otherwise callers-should retain their previous snapshot.+The optional history module uses the reserved name `history`. It persists captured+messages, including failure and cancellation history, with current instructions+removed. Snapshots have `schema_version: 2` and a `layers` JSON dict containing only+State. Submit current Config on each turn along with the previous snapshot. Modules+can be added or removed between turns; retained state is matched by name.++Known v1 snapshots are converted once at read time without restoring legacy+instances or lifecycle. Native resource scopes always release leases and clear+tracked shell jobs at run exit. Success always contains the resulting snapshot;+failure and cancellation contain one when validated run data was available and+cleanup produced a snapshot. Callers retain the previous snapshot when none is+returned. Product Workspace retirement remains owned by the API.## Observing runs@@ -493,12 +496,10 @@ end with `run_cancelled`. Each run can append at most one of these terminalevents. Event envelopes retain `id`, `run_id`, `type`, `data`, and `created_at`;`data` is typed per event type,including Pydantic AI's `AgentStreamEvent` payload for `pydantic_ai_event` and a-terminal event may contain a `CompositorSessionSnapshot` for resumption.+terminal event may contain a `SessionSnapshot` for resumption.`run_succeeded` always contains it; `run_failed` and `run_cancelled` contain it-only when compositor entry succeeded, layer exit completed, and a post-exit-snapshot was actually produced. A successful run has exactly one active result branch: JSON-safe-`output` for final answers, or `deferred_tool_call` when a layer such as-`dify.ask_human` ends the current agent run with an external deferred tool call.+when the runner produced State after native capability cleanup. A successful run+contains JSON-safe `output`, which may be null.Failed event payloads contain the diagnostic `error`, optional source-specific`reason`, optional stable `error_type`, and optional `session_snapshot`.Cancelled payloads likewise may contain `session_snapshot`. Pydantic AI request/step budget@@ -520,5 +521,5 @@ The repository includes simple consumers that print observed output/events:- `dify-agent/examples/dify_agent/dify_agent_examples/run_server_sse_consumer.py`consumes raw SSE frames for an existing run id.-The create-run examples submit Dify plugin model layers, so they require Redis,+The create-run examples submit Dify plugin model modules, so they require Redis,the Agent server, Dify API gateway settings, and a configured model provider in Dify.diff --git a/dify-agent/docs/dify-agent/index.md b/dify-agent/docs/dify-agent/index.mdindex 2683fa78bd8..9e21843877d 100644--- a/dify-agent/docs/dify-agent/index.md+++ b/dify-agent/docs/dify-agent/index.md@@ -1,7 +1,39 @@# Dify Agent runtime-Dify Agent hosts Agenton-composed Pydantic AI runs behind a FastAPI API. Its-source code stays under `src/dify_agent`, while framework-neutral Agenton code-stays under `src/agenton` and `src/agenton_collections`.+Dify Agent hosts native Pydantic AI runs behind FastAPI. Implementations remain+under `src/dify_agent`; there is no separate agent composition framework.-See the [operations guide](guide/index.md) for local server behavior.+Each module declares Pydantic `Config`, `State`, and exactly one native+`Capability` or `Toolset`. The server registry maps a name to a module. Names+identify configuration, state and instances; aliases can use the same module+with independent state. New instances are created for every run.++`ctx.deps.layers[name]` contains JSON `config` and `state`. Config is read-only+within a run and comes from the current request. State belongs to its module;+validated models are copies, so mutations require explicit+`entry["state"] = state.model_dump(mode="json")` writeback. Stateful tools that+read and modify across awaits execute sequentially.++`deps.services` borrows lifespan clients and server settings. `deps.resources`+holds only operation leases, shell sessions and temporary credentials. The+capability that acquires a resource releases it in `wrap_run` using `finally`,+including failures and cancellation. The API owns durable Binding/Workspace+retirement and saves snapshots in the owning session.++Registered production names are `agent_soul_prompt`, `workflow_node_job_prompt`,+`workflow_user_prompt`, `agent_app_user_prompt`, `execution_context`, `runtime`,+`shell`, `config`, `history`, `llm`, `tools`, `core_tools`, `knowledge`, `output`,+plus `prompt` and `user_prompt` convenience names. HTTP input cannot supply an+import path. Cross-module references live in Config, for example+`execution_context`, `runtime`, and `shell`; the loader validates their targets+before I/O. Instruction ordering is unspecified. Native capability ordering+preserves Runtime → Shell → Config resource scopes.++Model, output type, current user content and initial history use explicit runner+assembly and native Agent arguments. Knowledge eager results stay in the user+role through a native model-request hook. Tool dispatch, instructions and+capability hooks use native Pydantic AI interfaces.++See [run lifecycle](concepts/run-lifecycle/index.md),+[resources](concepts/runtime-resources/index.md), and the+[operations guide](guide/index.md).diff --git a/dify-agent/docs/dify-agent/user-manual/ask-human-layer/index.md b/dify-agent/docs/dify-agent/user-manual/ask-human-layer/index.mddeleted file mode 100644index fc00b58aef5..00000000000--- a/dify-agent/docs/dify-agent/user-manual/ask-human-layer/index.md+++ /dev/null@@ -1,287 +0,0 @@-# Ask human layer--The ask human layer exposes one model-visible tool that lets an agent end the-current run with a structured request for human input. This page is for Dify-Agent clients that build `CreateRunRequest` payloads and then interpret terminal-run events.--The layer type id is `dify.ask_human`. It does not deliver forms, choose-recipients, enforce authorization, or wait inside the agent run. It only gives-the model a safe way to ask for human input and returns that request as a-deferred tool call.--## Layer contract--| Property | Value |-| --- | --- |-| Type id | `dify.ask_human` |-| Common layer name | `ask_human` |-| Config DTO | `DifyAskHumanLayerConfig` |-| Model-visible tool | `ask_human` by default, configurable with `tool_name` |-| Tool kind | pydantic-ai `external` deferred tool |-| Terminal event | `run_succeeded` |-| Terminal payload branch | `run_succeeded.data.deferred_tool_call` |--The agent run does not enter a paused status. When the model calls the ask-human-tool, the current run succeeds with a `deferred_tool_call` instead of normal-`output`. The client is responsible for turning that deferred call into its own-human-facing workflow, collecting a result, and starting another run with-`deferred_tool_results`.--## Basic usage--Add the ask human layer to the same composition as the prompt, history, LLM, and-optional structured-output layers:--```python {test="skip" lint="skip"}-from agenton_collections.layers.plain import PromptLayerConfig-from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID-from dify_agent.layers.ask_human import DIFY_ASK_HUMAN_LAYER_TYPE_ID, DifyAskHumanLayerConfig-from dify_agent.layers.dify_plugin import DifyPluginLLMLayerConfig-from dify_agent.layers.execution_context import (- DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- DifyExecutionContextLayerConfig,-)-from dify_agent.protocol import DIFY_AGENT_HISTORY_LAYER_ID, DIFY_AGENT_MODEL_LAYER_ID-from dify_agent.protocol.schemas import CreateRunRequest, RunComposition, RunLayerSpec---request = CreateRunRequest(- composition=RunComposition(- layers=[- RunLayerSpec(- name="prompt",- type="plain.prompt",- config=PromptLayerConfig(- prefix="You can ask a human only when the missing decision is required to continue.",- user="Review the deployment plan and proceed only after getting the required approval.",- ),- ),- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="replace-with-tenant-id",- user_id="replace-with-user-id",- user_from="account",- app_id="replace-with-app-id",- agent_mode="single_step",- invoke_from="debugger",- ),- ),- RunLayerSpec(- name=DIFY_AGENT_HISTORY_LAYER_ID,- type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,- ),- RunLayerSpec(- name="ask_human",- type=DIFY_ASK_HUMAN_LAYER_TYPE_ID,- config=DifyAskHumanLayerConfig(- max_fields=4,- max_actions=2,- allowed_field_types=["paragraph", "select"],- allow_file_fields=False,- ),- ),- RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type="dify.plugin.llm",- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id="langgenius/openai",- model_provider="openai",- model="gpt-5.2",- ),- ),- ]- )-)-```--Include a [history layer](../history-layer/index.md) whenever you expect to-resume after a human answer. The pending tool call is stored in pydantic-ai-message history, so the resumed run needs both the returned `session_snapshot`-and the same logical composition with the history layer still present.--## Config fields--`DifyAskHumanLayerConfig` controls the model-facing tool identity and guardrails.-It intentionally does not contain delivery settings.--| Field | Type | Default | Meaning |-| --- | --- | --- | --- |-| `enabled` | `bool` | `True` | When false, the layer exposes neither the tool nor the prompt guidance. |-| `tool_name` | `str` | `"ask_human"` | Model-visible tool name. Must be a valid identifier. |-| `tool_description` | `str \| None` | default description | Optional model-visible tool description. |-| `max_fields` | `int` | `8` | Maximum number of fields the model may request. Use `0` for action-only requests. |-| `max_actions` | `int` | `4` | Maximum number of human actions the model may request. |-| `allowed_field_types` | `list["paragraph" \| "select" \| "file" \| "file-list"]` | `["paragraph", "select"]` | Field types accepted by runtime validation. |-| `allow_file_fields` | `bool` | `False` | File field types are rejected unless this is true and the type is listed in `allowed_field_types`. |-| `max_markdown_chars` | `int` | `8000` | Maximum length for the optional `markdown` body. |-| `max_question_chars` | `int` | `1000` | Maximum length for the required `question`. |-| `max_field_label_chars` | `int` | `120` | Maximum label length for each field. |-| `max_action_label_chars` | `int` | `80` | Maximum label length for each action. |--Configured limits are also capped by server hard limits. If a config exceeds a-hard cap, request validation fails before the run can execute.--The layer converts these limits into a prompt hint automatically. Clients do not-need to write a separate system prompt listing the limits, although they may add-business-specific guidance such as when human input is appropriate.--## What the model can request--When enabled, the layer exposes an external deferred tool whose argument shape is-`AskHumanToolArgs`:--| Field | Type | Meaning |-| --- | --- | --- |-| `title` | `str \| None` | Optional short title for the human request. |-| `question` | `str` | Required question/instruction for the human. |-| `markdown` | `str \| None` | Optional longer Markdown body. Treat it as untrusted user-visible content. |-| `fields` | `list[AskHumanField]` | Optional structured fields for the human to fill. |-| `actions` | `list[AskHumanAction]` | Optional action buttons. If omitted, Dify Agent normalizes to a single primary `Submit` action. |-| `urgency` | `"normal" \| "high"` | Hint for downstream systems; it is not a delivery policy. |--Supported field variants:--- `paragraph`: free-text input.-- `select`: single-choice input with unique option values.-- `file`: single-file input, only when file fields are allowed.-- `file-list`: multi-file input, only when file fields are allowed.--Tool arguments are validated again after the model calls the tool. Invalid calls-produce a model retry before a terminal success is emitted.--## Handling a deferred human request--Stream or poll run events as usual. A successful final answer has-`event.data.output`. A successful human request has `event.data.deferred_tool_call`.-Exactly one branch is set.--```python {test="skip" lint="skip"}-deferred_call = None-snapshot = None--async for event in client.stream_events(run_id):- if event.type != "run_succeeded":- continue- snapshot = event.data.session_snapshot- if event.data.deferred_tool_call is not None:- deferred_call = event.data.deferred_tool_call- else:- final_output = event.data.output- break--if deferred_call is not None:- # Render your own human-facing form, enqueue notification, pause an outer- # workflow, or store the request for later. Dify Agent does not do that part.- print(deferred_call.tool_call_id, deferred_call.args)-```--A typical deferred payload looks like this:--```json-{- "tool_call_id": "call_01H...",- "tool_name": "ask_human",- "args": {- "title": "Deployment approval",- "question": "Can we deploy version 2026.06.10 to production now?",- "fields": [- {- "type": "paragraph",- "name": "comment",- "label": "Approval comment",- "required": false- }- ],- "actions": [- {"id": "approve", "label": "Approve", "style": "primary"},- {"id": "reject", "label": "Reject", "style": "destructive"}- ],- "urgency": "normal"- },- "metadata": {- "layer_type": "dify.ask_human",- "tool_name": "ask_human",- "schema_version": 1- }-}-```--The `args` object is model-generated content. Validate and sanitize it before-rendering it to end users.--## Resume with a human result--After your client collects a human answer, create a new run with:--- the previous `session_snapshot`;-- a matching composition that still includes the history and ask-human layers;-- `deferred_tool_results.calls[tool_call_id]` containing the human result.--```python {test="skip" lint="skip"}-from dify_agent.layers.ask_human import AskHumanToolResult-from dify_agent.protocol import DeferredToolResultsPayload---human_result = AskHumanToolResult(- status="submitted",- action={"id": "approve", "label": "Approve"},- values={"comment": "Approved for the planned window."},- message="The human approved the deployment.",-)--resume_request = CreateRunRequest(- composition=composition_with_same_layer_names_and_order,- session_snapshot=snapshot,- deferred_tool_results=DeferredToolResultsPayload(- calls={deferred_call.tool_call_id: human_result.model_dump(mode="json")},- ),-)-```--Dify Agent passes the supplied result back to pydantic-ai as the return value of-the original external tool call, then the model continues. The resumed run may-produce a final `output`, or it may produce another `deferred_tool_call` if the-agent needs another human turn.--Timeouts and unavailable humans should also be sent as tool results instead of-being treated as agent-run failures:--```json-{- "status": "timeout",- "action": {"id": "__timeout", "label": "Timeout"},- "values": {},- "message": "The human did not respond before the workflow timeout."-}-```--## Client responsibilities--The ask human layer deliberately leaves product decisions to the caller. Clients-must decide how to:--- persist the deferred call and correlate it with a human-facing task;-- render and sanitize the requested fields/actions;-- choose recipients, channels, and timeout policy;-- authorize who may answer;-- transform the human submission into `AskHumanToolResult`;-- resume with the returned `session_snapshot` and matching composition.--Do not put recipient emails, workspace member ids, public URLs, auth tokens, or-timeout policy in the tool arguments. The model-facing request is untrusted and-should not control delivery or authorization.--## Troubleshooting--| Symptom | What to check |-| --- | --- |-| Run fails with `Deferred tool results require a 'history' layer` | Add the `history` layer and resume with the prior snapshot. |-| Run fails with `pending tool call can be resumed` | Keep the history layer active for the initial deferred run. |-| Run fails with `exactly one deferred call` | The MVP supports one ask-human call per run. Ask the model to ask one question at a time. |-| Run fails with `tool name must be ...` | Use the configured `tool_name`; do not rename it only in downstream form code. |-| File fields are rejected | Set `allow_file_fields=True` and include `file` or `file-list` in `allowed_field_types`. |-| `run_succeeded.data.output` is absent | Check `run_succeeded.data.deferred_tool_call`; this is a human-request success, not a failed run. |diff --git a/dify-agent/docs/dify-agent/user-manual/execution-context-layer/index.md b/dify-agent/docs/dify-agent/user-manual/execution-context-layer/index.mdindex 582d7fac155..c17b4626a19 100644--- a/dify-agent/docs/dify-agent/user-manual/execution-context-layer/index.md+++ b/dify-agent/docs/dify-agent/user-manual/execution-context-layer/index.md@@ -1,92 +1,7 @@-# Execution context layer+# Execution context module-The execution-context layer carries shared Dify run identifiers plus the tenant-and optional user context needed for plugin-daemon calls. Server settings still-provide the plugin daemon URL and API key.--Use it together with a [plugin LLM layer](../plugin-llm-layer/index.md) and,-when the caller wants Dify tools exposed to the model, a-[plugin tool layer](../plugin-tool-layer/index.md). Both business layers depend-on this layer to reach the plugin daemon.--## Config fields--| Field | Type | Meaning |-| --- | --- | --- |-| `tenant_id` | `str` | Dify tenant/workspace id used when calling the plugin daemon. |-| `user_id` | `str \| None` | Optional end-user id passed through to the plugin daemon. |-| `invoke_from` | `Literal[...]` | Dify caller category recorded for observability and correlation. |-| `app_id` / `workflow_id` / `workflow_run_id` / `node_id` / `node_execution_id` / `conversation_id` / `agent_id` / `agent_config_version_id` / `trace_id` | `str \| None` | Optional Dify-owned execution identifiers forwarded with the run. |--## Trajectory span attributes--When Agent trajectory export is enabled, this layer's fields are attached to every-trajectory span of the run. The names follow the Dify Enterprise Data Push-dictionary so a trajectory span joins the platform's own workflow and node signals-on the same keys. Fields you leave unset are omitted, so an Agent App turn carries-`dify.conversation.id` while a workflow Agent node carries the workflow keys.--| Config field | Span attribute |-| --- | --- |-| `tenant_id` | `dify.tenant_id` |-| `app_id` | `dify.app_id` |-| `agent_id` | `dify.agent_id` |-| `user_id` | `gen_ai.user.id` |-| `invoke_from` | `dify.invoke_from` |-| `conversation_id` | `dify.conversation.id` |-| `workflow_id` | `dify.workflow.id` |-| `workflow_run_id` | `dify.workflow.run_id` |-| `node_id` | `dify.node.id` |-| `node_execution_id` | `dify.node.execution_id` |-| `trace_id` | `dify.trace_id` |--`app_id` is the app the run was invoked through, so a workflow Agent node reports-the workflow's own app rather than the Agent's.--The execution-context layer type id is `dify.execution_context`.--## Basic usage--```python {test="skip" lint="skip"}-from dify_agent.layers.execution_context import (- DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- DifyExecutionContextLayerConfig,-)-from dify_agent.protocol import RunLayerSpec---execution_context_layer = RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="replace-with-tenant-id",- user_id="replace-with-user-id",- invoke_from="workflow_run",- ),-)-```--If you do not need a user id, omit `user_id` or pass `None`. Most optional-execution identifiers may also be omitted when they are not available.--## Server-side settings--The execution-context layer config does not include daemon transport settings.-Configure these on the Dify Agent server instead:--```env-DIFY_AGENT_PLUGIN_DAEMON_URL=http://localhost:5002-DIFY_AGENT_PLUGIN_DAEMON_API_KEY=replace-with-plugin-daemon-server-key-```--This keeps server credentials out of client-submitted layer config and out of-session snapshots.--## Notes--- The execution-context layer does not open, cache, close, or snapshot HTTP clients.-- Concrete `plugin_id` values belong to the business layer that invokes the- daemon: the plugin LLM layer for model calls and each plugin tool config for- tool calls.-- The conventional layer name is `execution_context`. If you use another name,- point the LLM and tool layer dependencies at that name.+`dify_agent.layers.execution_context.layer` declares Config, empty State and+Capability. Config carries tenant/user/app/invoke identity and correlation IDs.+Other modules refer to its registered name in their Config. Server-only daemon+settings and clients are borrowed from Deps.services. Knowledge retrieval+requires its complete caller identity before any external request.diff --git a/dify-agent/docs/dify-agent/user-manual/history-layer/index.md b/dify-agent/docs/dify-agent/user-manual/history-layer/index.mdindex 473035fda3e..1da5eea2088 100644--- a/dify-agent/docs/dify-agent/user-manual/history-layer/index.md+++ b/dify-agent/docs/dify-agent/user-manual/history-layer/index.md@@ -1,140 +1,8 @@-# History layer--The history layer stores pydantic-ai conversation history in the Agenton session-snapshot. Add it when a later run should resume the previous conversation.--The history layer is state-only: it contributes no prompt text, user prompt, or-tools, and it owns no live resources.--## Layer contract--| Property | Value |-| --- | --- |-| Reserved layer name | `history` |-| Type id | `pydantic_ai.history` |-| Config | none |-| Dependencies | none |--Use at most one history layer. It must be named `history` and must not declare-dependencies.--## Basic usage--```python {test="skip" lint="skip"}-from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID-from dify_agent.protocol import DIFY_AGENT_HISTORY_LAYER_ID, RunLayerSpec---history_layer = RunLayerSpec(- name=DIFY_AGENT_HISTORY_LAYER_ID,- type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,-)-```--Include this layer in the same composition as your prompt, plugin, and LLM-layers.--## Compaction and persistence--When the LLM layer supplies `context_window_tokens`, Dify Agent sets the Harness-target to `min(floor(window * 0.8), window - max_tokens)` for a positive-`model_settings.max_tokens`; otherwise it uses `floor(window * 0.8)`. A target-that is not positive rejects the run before model invocation.--Harness estimates and, when needed, rewrites history immediately before model-requests. It clears older tool results first, retaining the latest three-tool-call/result pairs and their inputs. If the history is still over target, the-same current model incrementally summarizes older messages while retaining the-latest twenty messages and the first user message.--With a history layer, once pydantic-ai binds and builds messages in the run-capture, the captured, possibly rewritten history replaces the stored messages-in the terminal session snapshot. This applies to successful, failed, and-cancelled runs. A failure or cancellation before the capture contains any-messages preserves the previously restored history. An interrupted capture can-include a partial response or tool-return request marked `state="interrupted"`;-pydantic-ai repairs that state when the snapshot is used by a later independent-run. A run cancelled after the model returned tool calls but before any of them-ran is also stored with that marker, so the calls it never executed do not block-the next user prompt. Without this layer, compaction and interrupted messages affect only the-current run.--## Resume a conversation--Successful runs return a terminal event with both final output and a resumable-session snapshot. Failed and cancelled terminal events can also carry a session-snapshot that checkpoints current history, but they do not change the interrupted-run's terminal status into success.--```python {test="skip" lint="skip"}-accepted = await client.create_run(request)--async for event in client.stream_events(accepted.run_id):- if event.type == "run_succeeded":- output = event.data.output- snapshot = event.data.session_snapshot- break-```--Pass `snapshot` to the next request and keep the same layer names and order:--```python {test="skip" lint="skip"}-next_request = CreateRunRequest(- composition=composition_with_the_same_layer_names_and_order,- session_snapshot=snapshot,-)-```--`CreateRunRequest.on_exit` defaults to suspending layers, which makes the-terminal snapshot resumable. Keep that default for normal memory flows.--## What gets stored--Dify Agent handles memory conservatively:--1. Current system prompts are passed as run-level pydantic-ai instructions.-2. Stored history is sent to the model before the current user prompt.-3. When the LLM layer includes `context_window_tokens`, Harness may rewrite- over-target history immediately before a model request as described above.-4. Once pydantic-ai binds and builds messages in the run capture, the complete- captured and possibly compacted history is written back to the layer on- success, failure, timeout, or cancellation.-5. If failure or cancellation occurs before the capture contains any messages,- the previously restored history remains unchanged.-6. Run-level system instructions are removed before history is persisted.-7. Interrupted partial messages retain pydantic-ai's `state="interrupted"` marker- so a later independent run can repair and continue from the checkpoint. A- trailing response whose tool calls the interrupted run never executed is- stored with the same marker; a run that ends in a deferred tool request keeps- its open call so the next run can answer it.-8. Failed and cancelled runs keep their terminal status; their snapshot is a- checkpoint, not a successful continuation of the interrupted run.--## Persist snapshots outside the client process--Session snapshots are Pydantic models and can be saved as JSON:--```python {test="skip" lint="skip"}-from pathlib import Path--from agenton.compositor import CompositorSessionSnapshot---snapshot_path = Path("session_snapshot.json")-snapshot_path.write_text(snapshot.model_dump_json(), encoding="utf-8")--restored_snapshot = CompositorSessionSnapshot.model_validate_json(- snapshot_path.read_text(encoding="utf-8")-)-```--Always restore snapshots with the same layer names and order that produced them.--## Troubleshooting--| Symptom | What to check |-| --- | --- |-| `must use reserved layer name 'history'` | Rename the layer to `history`. |-| `does not support dependencies` | Remove `deps` from the history layer. |-| Resume fails with snapshot lifecycle errors | Use a terminal snapshot whose layers were suspended, and keep layer names/order unchanged. |-| System prompts appear missing from saved memory | This is expected; current system prompts are temporary and are not persisted. |+# History module++`dify_agent.layers.history` declares Config, State and Capability. Config is+empty. State contains `messages`, encoded as JSON using Pydantic AI message+schemas. The runner explicitly loads initial message_history and writes the+captured history on every terminal outcome, preserving compaction and partial+responses. Current instructions are removed and unmatched trailing calls are+marked interrupted on failure or cancellation. The reserved name is `history`.diff --git a/dify-agent/docs/dify-agent/user-manual/plugin-llm-layer/index.md b/dify-agent/docs/dify-agent/user-manual/plugin-llm-layer/index.mdindex 8b8c970e9e8..8c98f71abd8 100644--- a/dify-agent/docs/dify-agent/user-manual/plugin-llm-layer/index.md+++ b/dify-agent/docs/dify-agent/user-manual/plugin-llm-layer/index.md@@ -1,142 +1,7 @@-# Plugin LLM layer+# Model module-The plugin LLM layer selects the plugin package, model provider, model name,-and optional model settings for the current run. Dify Agent reads the model-from the reserved layer name `llm`; Dify API resolves model credentials.--It must depend on an [execution context layer](../execution-context-layer/index.md),-because that layer supplies the caller identity required by the API gateway.--## Config fields--| Field | Type | Meaning |-| --- | --- | --- |-| `plugin_id` | `str` | Plugin package id, for example `langgenius/openai`. |-| `model_provider` | `str` | Provider name inside `plugin_id`. Use the value of `DIFY_AGENT_PROVIDER` from `dify-agent/.env`. |-| `model` | `str` | Model name. Use the value of `DIFY_AGENT_MODEL_NAME` from `dify-agent/.env`. |-| `model_settings` | `ModelSettings \| None` | Optional pydantic-ai model settings. |-| `context_window_tokens` | `int \| None` | Positive effective context-window capability metadata. Enables window-based compaction when present; omission disables it. |--The plugin LLM layer type id is `dify.plugin.llm`.--## Basic usage--```python {test="skip" lint="skip"}-from dify_agent.layers.dify_plugin import DIFY_PLUGIN_LLM_LAYER_TYPE_ID, DifyPluginLLMLayerConfig-from dify_agent.protocol import DIFY_AGENT_MODEL_LAYER_ID, RunLayerSpec---MODEL_PROVIDER = "replace-with-provider-from-dify-agent-env"-MODEL_NAME = "replace-with-model-from-dify-agent-env"-PLUGIN_ID = "langgenius/openai"--llm_layer = RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id=PLUGIN_ID,- model_provider=MODEL_PROVIDER,- model=MODEL_NAME,- ),-)-```--`deps={"execution_context": "execution_context"}` means: bind the LLM layer's-dependency field named `execution_context` to the composition layer named-`execution_context`.--Set `MODEL_PROVIDER` and `MODEL_NAME` to the same values as-`DIFY_AGENT_PROVIDER` and `DIFY_AGENT_MODEL_NAME` in `dify-agent/.env`.--## Context compaction--Dify product request builders resolve `context_window_tokens` from the selected-model plugin schema using the current tenant and user credentials. A client that-constructs `DifyPluginLLMLayerConfig` directly is responsible for supplying an-accurate positive value. The field is model capability metadata: Dify Agent does-not forward it as a Provider parameter or merge it into `model_settings`.--For a known window, Dify Agent computes the Harness compaction target as:--```text-min(floor(context_window_tokens * 0.8), context_window_tokens - max_tokens)-```--The second term applies only when `model_settings.max_tokens` is positive. A-non-positive target rejects the run before model invocation. Immediately before-model requests, Harness estimates the message history and rewrites it when it is-over target: it first clears old tool results while retaining the three most-recent tool-call/result pairs and their inputs; if still over target, the current-model incrementally summarizes older history while retaining the latest twenty-messages and the first user message.--Compaction affects later runs only when the composition has a-[history layer](../history-layer/index.md). Once pydantic-ai binds and builds-messages in the run capture, successful, failed, timed-out, and cancelled runs-write the captured rewritten history into their terminal session snapshot. A-failure or cancellation before the capture contains any messages preserves the-previously restored history. Interrupted partial messages may be included and-repaired when that checkpoint is used by a later independent run; the interrupted-run's terminal status remains unchanged.--## Complete minimal model composition--Most runs include a prompt, execution-context layer, and LLM layer:--```python {test="skip" lint="skip"}-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig-from dify_agent.layers.dify_plugin import (- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,- DifyPluginLLMLayerConfig,-)-from dify_agent.protocol import DIFY_AGENT_MODEL_LAYER_ID, RunComposition, RunLayerSpec---MODEL_PROVIDER = "replace-with-provider-from-dify-agent-env"-MODEL_NAME = "replace-with-model-from-dify-agent-env"-PLUGIN_ID = "langgenius/openai"--composition = RunComposition(- layers=[- RunLayerSpec(- name="prompt",- type=PLAIN_PROMPT_LAYER_TYPE_ID,- config=PromptLayerConfig(prefix="You are concise.", user="Say hello."),- ),- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="replace-with-tenant-id",- user_id="replace-with-user-id",- user_from="account",- app_id="replace-with-app-id",- agent_mode="single_step",- invoke_from="debugger",- ),- ),- RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id=PLUGIN_ID,- model_provider=MODEL_PROVIDER,- model=MODEL_NAME,- ),- ),- ]-)-```--## Notes--- The model layer must use the reserved name `llm` (`DIFY_AGENT_MODEL_LAYER_ID`).-- `plugin_id` belongs here because model calls are plugin-specific business- calls. The shared execution-context layer carries the Dify caller context.-- Model credentials are never accepted from the Agent request. Dify API resolves- the tenant's current provider configuration and owns quota accounting.-- Omitting `context_window_tokens` disables window-based compaction. It does not- limit or otherwise change the Provider's own context-window enforcement.+`dify_agent.layers.dify_plugin.llm_layer` declares Config, State and Capability.+The reserved `llm` name selects model assembly. Public Config contains plugin,+provider, model, model settings, context window and an `execution_context` name.+The runtime builds a model through the Dify API metered gateway with borrowed+lifespan HTTP services. Credentials stay API-owned; no model/client is persisted.diff --git a/dify-agent/docs/dify-agent/user-manual/plugin-tool-layer/index.md b/dify-agent/docs/dify-agent/user-manual/plugin-tool-layer/index.mdindex a7618462c92..ecd604a6619 100644--- a/dify-agent/docs/dify-agent/user-manual/plugin-tool-layer/index.md+++ b/dify-agent/docs/dify-agent/user-manual/plugin-tool-layer/index.md@@ -1,130 +1,9 @@-# Plugin tool layer--The plugin tool layer exposes Dify plugin tools to the model. It is designed for-Dify API to build after it has resolved a user's tool selections, plugin daemon-declarations, credentials, and manual/runtime inputs.--Unlike the plugin LLM layer, this layer may contain tools from multiple plugin-packages. Each tool config carries its own `plugin_id`, while the shared-[execution context layer](../execution-context-layer/index.md) still carries-only tenant/user daemon context.--## Responsibilities--Dify API prepares the tool config before submitting the run request:--- resolve the selected provider and tool name;-- merge declared parameters with runtime parameters;-- produce the model-visible JSON schema;-- provide hidden/manual `runtime_parameters` and credentials;-- choose the daemon `credential_type` for invocation.--Dify Agent consumes that prepared config. At run time it validates required-hidden inputs, applies defaults, casts invocation values, calls plugin daemon,-and turns tool responses into model observations.--## Config fields--The plugin tools layer type id is `dify.plugin.tools`.--`DifyPluginToolsLayerConfig` contains a list of `DifyPluginToolConfig` objects:--| Field | Type | Meaning |-| --- | --- | --- |-| `tools` | `list[DifyPluginToolConfig]` | Prepared plugin tools to expose to the model. |--Each tool config has these fields:--| Field | Type | Meaning |-| --- | --- | --- |-| `plugin_id` | `str` | Plugin package id for this tool, for example `langgenius/wikipedia`. |-| `provider` | `str` | Tool provider name inside the plugin. |-| `tool_name` | `str` | Daemon tool name to invoke. |-| `credential_type` | `"api-key" \| "oauth2" \| "unauthorized"` | Credential mode sent to plugin daemon. |-| `name` | `str \| None` | Optional model-visible tool name. Defaults to `tool_name`. |-| `description` | `str \| None` | Optional model-visible description. Defaults to the tool name. |-| `credentials` | `dict[str, str \| int \| float \| bool \| None]` | Provider-specific tool credentials. |-| `runtime_parameters` | `dict[str, JsonValue]` | Hidden/manual values merged into daemon invocation but omitted from the model schema. |-| `parameters` | `list[DifyPluginToolParameter]` | API-prepared effective parameter declarations used for validation, defaults, and casting. |-| `parameters_json_schema` | `dict[str, JsonValue]` | API-prepared JSON schema shown to the model. |--## Example: Dify API prepared Wikipedia tool--```python {test="skip" lint="skip"}-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig-from dify_agent.layers.dify_plugin import (- DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,- DifyPluginToolConfig,- DifyPluginToolParameter,- DifyPluginToolsLayerConfig,-)-from dify_agent.protocol import RunComposition, RunLayerSpec---# Dify API side: resolve the selected tool into the API-side Tool runtime first,-# for example with ToolManager.get_agent_tool_runtime(...). Then adapt its-# effective ToolParameter objects at the protocol boundary. Dify Agent accepts-# both ToolParameter attribute objects and ToolParameter.model_dump(mode="json")-# dictionaries, ignoring API-only fields such as label and human_description.-tool_runtime = ToolManager.get_agent_tool_runtime(...)-effective_parameters = tool_runtime.get_merged_runtime_parameters()-prepared_parameters = [- DifyPluginToolParameter.model_validate(parameter)- # If the API serializes first, use:- # DifyPluginToolParameter.model_validate(parameter.model_dump(mode="json"))- for parameter in effective_parameters-]-parameters_json_schema = tool_runtime.get_llm_parameters_json_schema()--composition = RunComposition(- layers=[- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="replace-with-tenant-id",- user_id="replace-with-user-id",- invoke_from="workflow_run",- ),- ),- RunLayerSpec(- name="tools",- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,- deps={"execution_context": "execution_context"},- config=DifyPluginToolsLayerConfig(- tools=[- DifyPluginToolConfig(- plugin_id="langgenius/wikipedia",- provider="wikipedia",- tool_name="wikipedia_search",- credential_type="unauthorized",- name="wikipedia_search",- description="Search Wikipedia for relevant pages.",- parameters=prepared_parameters,- runtime_parameters={"language": "en"},- parameters_json_schema=parameters_json_schema,- )- ]- ),- ),- ]-)-```--`deps={"execution_context": "execution_context"}` means: bind the tool layer's-dependency field named `execution_context` to the composition layer named-`execution_context`.--## Notes for Dify API callers--- Do not ask Dify Agent to discover tool declarations. Resolve and prepare them- in API before creating the run.-- `parameters` should include all effective parameters, including hidden/manual- ones needed for validation and default application.-- `parameters_json_schema` should include only model-visible parameters. Omit- hidden/manual parameters and file/system-file parameters unless they are truly- intended for model input.-- `runtime_parameters` should contain hidden/manual values selected by the user- or derived from workflow variables.-- Put each tool's `plugin_id` on the tool config. The shared execution-context- layer has no package-specific identity.+# Plugin tool module++`dify_agent.layers.dify_plugin.tools_layer` declares Config, State and native+Toolset. The `tools` registry name accepts API-prepared declarations, parameters,+runtime values and model-facing schema, plus `execution_context` and optional+`shell` Config references. Hidden/default parameter merging, loose schemas and+observation mapping preserve the API-prepared contract. Sandbox paths use the+referenced live shell session to upload files; file mappings resolve signed URLs+through the borrowed Dify API client. Config and credentials are never snapshotted.diff --git a/dify-agent/docs/dify-agent/user-manual/prompt-layer/index.md b/dify-agent/docs/dify-agent/user-manual/prompt-layer/index.mdindex f31b2e41fca..c34c4d46925 100644--- a/dify-agent/docs/dify-agent/user-manual/prompt-layer/index.md+++ b/dify-agent/docs/dify-agent/user-manual/prompt-layer/index.md@@ -1,71 +1,7 @@-# Prompt layer+# Prompt module-The prompt layer provides the current run's system and user prompt fragments. In-Dify Agent request bodies it is a regular `RunLayerSpec` with type id-`plain.prompt`.--Use it for:--- system instructions that should be sent on this run-- the current user input-- optional suffix system instructions--## Config fields--| Field | Type | Meaning |-| --- | --- | --- |-| `prefix` | `str` or `list[str]` | System prompt fragments collected before other prompt content. |-| `user` | `str` or `list[str]` | Current user-message fragments for the run. |-| `suffix` | `str` or `list[str]` | System prompt fragments collected after prefix content. |--All fields default to an empty list. Dify Agent rejects a create-run request when-the effective user prompt is empty or whitespace-only.--## Basic usage--```python {test="skip" lint="skip"}-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig-from dify_agent.protocol import RunLayerSpec---prompt_layer = RunLayerSpec(- name="prompt",- type=PLAIN_PROMPT_LAYER_TYPE_ID,- config=PromptLayerConfig(- prefix="You are a concise assistant.",- user="Summarize the incident in one paragraph.",- ),-)-```--## Multiple prompt fragments--Use lists when the caller wants to keep fragments separate while still sending one-run:--```python {test="skip" lint="skip"}-prompt_layer = RunLayerSpec(- name="prompt",- type=PLAIN_PROMPT_LAYER_TYPE_ID,- config=PromptLayerConfig(- prefix=[- "You are an incident response assistant.",- "Prefer concrete mitigation steps.",- ],- user=[- "Database latency is elevated.",- "Return the likely severity and next actions.",- ],- suffix="Do not invent metrics that are not provided.",- ),-)-```--## Notes--- The run API does not accept a top-level `user_prompt`; submit user input through- a prompt layer.-- Prompt layer names are not reserved by the runtime, but `prompt` is the- recommended conventional name.-- When a [history layer](../history-layer/index.md) is present, current system- prompts are passed as run-level instructions and are not saved into memory.+`dify_agent.layers.prompt` declares Config, State and native Toolset. Config+accepts `prefix`, `suffix` and `user` string fragments or lists. Prefix/suffix+become dynamic instructions; `user` contributes current user content. State is+empty. Instruction order is unspecified. Product names `agent_soul_prompt`,+`workflow_node_job_prompt`, and `workflow_user_prompt` map to this module.diff --git a/dify-agent/docs/dify-agent/user-manual/shell-layer/index.md b/dify-agent/docs/dify-agent/user-manual/shell-layer/index.mdindex d6c5011637e..170d6be5220 100644--- a/dify-agent/docs/dify-agent/user-manual/shell-layer/index.md+++ b/dify-agent/docs/dify-agent/user-manual/shell-layer/index.md@@ -1,282 +1,14 @@-# Shell layer--The `dify.shell` layer exposes shellctl-backed commands to an Agent.-It does not select a backend or own persistent Home, Workspace, or Binding-resources. It consumes the operation-scoped `RuntimeLease` opened by a sibling-`dify.runtime` layer.--## Public configuration--```python-from dify_agent.layers.shell import (- DIFY_SHELL_LAYER_TYPE_ID,- DifyShellEnvVarConfig,- DifyShellLayerConfig,-)-from dify_agent.protocol import RunLayerSpec--RunLayerSpec(- name="shell",- type=DIFY_SHELL_LAYER_TYPE_ID,- deps={"execution_context": "execution_context", "runtime": "runtime"},- config=DifyShellLayerConfig(- env=[DifyShellEnvVarConfig(name="REPORT_FORMAT", value="markdown")],- redact_patterns=["private-[A-Za-z0-9]+"],- ),-)-```--| Config field | Meaning |-| --- | --- |-| `cli_tools` | CLI bootstrap declarations with install commands and scoped environment metadata. |-| `env` | Normal environment variables exported to Shell commands. |-| `secret_refs` | Names of secret environment variables supplied by the backend environment. |-| `redact_patterns` | Request-level regex patterns removed from Shell output shown to the model. |--Endpoints, credentials, Home/Workspace paths, resource refs, timeouts, and-network policy are not Shell config. Backend selection is server-private, and-the opaque Binding ref belongs to `DifyRuntimeLayerConfig`.--## Runtime requirements--The server constructs one coherent runtime backend profile. Local, E2B, and-OpenShell implement Home Snapshot and Execution Binding operations. Enterprise-implements default-Home Binding creation, acquisition, and coupled destruction,-while immutable Home Snapshot operations fail fast; there is no compatibility-fallback to the retired Sandbox protocol.--```python-from dify_agent.runtime.compositor_factory import create_default_layer_providers-from dify_agent.runtime_backend.profile import RuntimeBackendSettings, create_runtime_backend_profile--runtime_backend_profile = create_runtime_backend_profile(- RuntimeBackendSettings(- runtime_backend="local",- local_sandbox_endpoint="http://127.0.0.1:5004",- local_sandbox_auth_token="replace-with-shellctl-token",- )-)--layer_providers = create_default_layer_providers(- plugin_daemon_url="http://localhost:5002",- plugin_daemon_api_key="replace-with-plugin-daemon-key",- runtime_backend_profile=runtime_backend_profile,-)-```--Equivalent standalone environment settings are:--```env-DIFY_AGENT_RUNTIME_BACKEND=local-DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT=http://127.0.0.1:5004-DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN=replace-with-shellctl-token-# Optional when shellctl runs directly on a host without /home/dify:-# DIFY_AGENT_LOCAL_SANDBOX_MATERIALIZED_HOME_ROOT=/tmp/dify-agent/materialized-homes-# DIFY_AGENT_LOCAL_SANDBOX_WORKSPACE_ROOT=/tmp/dify-agent/workspaces-# DIFY_AGENT_LOCAL_SANDBOX_HOME_SNAPSHOT_ROOT=/tmp/dify-agent/home-snapshots-```--The auth token may be empty when shellctl authentication is disabled. Dify-created-E2B Sandboxes disable public traffic at creation and access shellctl through the-E2B port proxy with its `traffic_access_token`. Acquiring a RuntimeLease fails if-E2B does not provide a non-empty token. This policy applies only to newly created-Sandboxes and does not retrofit existing ones.--To let shell jobs call the Agent Stub with `dify-agent ...`, configure a-Sandbox-reachable Agent Stub URL and a unique production secret. Remote-deployments normally use a public Agent ingress. Local Compose uses-`http://agent_backend:5050/agent-stub`, reached through the existing-`agent_ssrf_proxy`; this configuration does not change the Compose network-topology.--```env-DIFY_AGENT_STUB_API_BASE_URL=https://agent.example.com/agent-stub-DIFY_AGENT_SANDBOX_FILES_BASE_URL=https://dify.example.com-DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT=50-DIFY_AGENT_SERVER_SECRET_KEY=replace-with-unpadded-base64url-for-32-random-bytes-```--HTTP URLs may be either the service root or the explicit `/agent-stub` root.-The server normalizes a service root and rejects unrelated paths. The separate-Sandbox file base must point to the Dify API ingress serving `/files/*`; it is-used for CLI upload/download bytes, including Config file and skill pulls.-`DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT` belongs to the Agent service, is in-MiB, and defaults to `50`. The Agent service converts it to the signed upload-URL's byte limit. Any ingress or proxy in front of `/files/*` must allow that-file limit plus multipart framing and header overhead; its request-body limit-does not need to be numerically identical.--After `dify-agent file upload <path>` succeeds, the CLI prints JSON such as:--```json-{- "transfer_method": "tool_file",- "reference": "dify-file-ref:...",- "public_download_url": "https://dify.example.com/files/tools/..."-}-```--`reference` is the persistent canonical file identity and should be stored in-structured output. `public_download_url` is a short-lived frontend presentation-address: it is an absolute URL when Dify API `FILES_URL` has a public origin,-or a same-origin `/files/...` relative URI when `FILES_URL` is empty. The CLI-does not access this field. The former ambiguous `download_url` upload-output-key is now named `public_download_url`.--Server-side Binding downloads use-`dify-agent file upload --no-download-link <path>`. This additive mode performs-the same streaming ToolFile upload but skips the download-request step and-prints only `transfer_method` plus the canonical `reference`. The regular-`file upload` command keeps the link-producing behavior shown above.--If the upload succeeds but creating the public URL fails, the command still-prints the canonical mapping and exits with an error containing an exact-`dify-agent file public-url <reference>` retry command. Run that command from a-new shell tool call to create the public URL without uploading the file again.-On success, `file public-url` prints the complete JSON mapping containing-`transfer_method`, `reference`, and `public_download_url`.--The Agent Stub authorization injected into a shell job is valid for five-minutes. It does not refresh inside an already-running process. If a command-reports that the authorization expired, start a new shell tool call and retry-the command (or its reported `file public-url` recovery command).--The injected JWE is masked as `***` in model-facing `shell_run`, `shell_wait`,-and `shell_input` observations. Raw shellctl output and files referenced by-`output_path` remain unchanged.--## Request graph--A shell-enabled run contains Execution Context, Runtime, and Shell layers:--```mermaid-flowchart LR- EC["execution_context"] --> SH["shell"]- RT["runtime<br/>backend_binding_ref"] --> SH-```--`DifyRuntimeLayer` acquires the Binding when the run's resource context opens-and releases it when that operation exits. `DifyShellLayer` uses the active-lease's commands, Home path, and Workspace path. It performs only-best-effort cleanup of shell jobs; the persistent Binding lifecycle remains in-Dify API.--## Example request--The Binding must already have been resolved or created by Dify API. Its backend-ref is opaque to the request builder:--```python {test="skip" lint="skip"}-from agenton_collections.layers.plain import PromptLayerConfig-from dify_agent.layers.dify_plugin.configs import DifyPluginLLMLayerConfig-from dify_agent.layers.execution_context import (- DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- DifyExecutionContextLayerConfig,-)-from dify_agent.layers.runtime import DIFY_RUNTIME_LAYER_TYPE_ID, DifyRuntimeLayerConfig-from dify_agent.layers.shell import DIFY_SHELL_LAYER_TYPE_ID, DifyShellLayerConfig-from dify_agent.protocol import DIFY_AGENT_MODEL_LAYER_ID-from dify_agent.protocol.schemas import CreateRunRequest, RunComposition, RunLayerSpec---request = CreateRunRequest(- composition=RunComposition(- layers=[- RunLayerSpec(- name="prompt",- type="plain.prompt",- config=PromptLayerConfig(- prefix="Use the workspace when local computation helps.",- user="Create report.txt containing the current UTC timestamp, then summarize it.",- ),- ),- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="92cca973-2d6f-45e0-906e-0b7eda5f2ccf",- user_id="replace-with-user-id",- user_from="account",- app_id="replace-with-app-id",- agent_id="8d542564-159d-4168-985c-dde8d8ff6092",- agent_config_version_id="931a4cee-4434-4c1c-8fbd-0a3c7591095d",- agent_config_version_kind="snapshot",- agent_mode="workflow_run",- invoke_from="debugger",- ),- ),- RunLayerSpec(- name="runtime",- type=DIFY_RUNTIME_LAYER_TYPE_ID,- config=DifyRuntimeLayerConfig(backend_binding_ref="opaque-backend-binding-ref"),- ),- RunLayerSpec(- name="shell",- type=DIFY_SHELL_LAYER_TYPE_ID,- deps={"execution_context": "execution_context", "runtime": "runtime"},- config=DifyShellLayerConfig(),- ),- RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type="dify.plugin.llm",- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id="langgenius/gemini",- model_provider="google",- model="gemini-2.5-flash",- ),- ),- ]- )-)-```--The resource part serializes as:--```json-{- "layers": [- {- "name": "runtime",- "type": "dify.runtime",- "config": {"backend_binding_ref": "opaque-backend-binding-ref"}- },- {- "name": "shell",- "type": "dify.shell",- "deps": {"execution_context": "execution_context", "runtime": "runtime"},- "config": {}- }- ]-}-```--## Paths and persistence--`RuntimeLease.layout.home_dir` and `workspace_dir` are absolute paths inside the-backend execution namespace. They are not host filesystem paths and are not-sent in the run request. Shell commands start in `workspace_dir`, while `HOME`-is forced to `home_dir`; `~` therefore resolves to the current Binding's-materialized Home. The runner also sets `TMPDIR`, `TMP`, and `TEMP` directly to-`workspace_dir`, making the active Workspace both the default `cwd` and the-temporary working space.--Workspace content persists with the Workspace until Dify API retires and-collects it. Releasing a RuntimeLease ends only the current operation. Dify API can later-browse the Binding filesystem through Dify Agent's private-`/execution-bindings/files/list`, `/execution-bindings/files/read`, and-`/execution-bindings/files/download` routes, each of which acquires a fresh-lease. Relative paths start in the Workspace, while `~` starts in the Binding's-Home. Download uses the installed CLI to stream a ToolFile upload and returns-only its canonical reference to Dify API.--On Local, multiple Bindings may share a Workspace while each receives a-separate materialized Home. Those directories may be siblings in one shellctl-namespace; path isolation restricts a lease to its Home and Workspace. On E2B-and OpenShell, one physical sandbox currently represents both Binding and-Workspace, so shared Workspace attachment is unsupported.--See [Runtime resources](../../concepts/runtime-resources/index.md) for the-ledger and lifecycle contract. The [Operations Guide](../../guide/index.md)-covers Local and E2B validation; the [OpenShell guide](../../guide/openshell.md)-covers OpenShell configuration and validation.+# Shell module++`dify_agent.layers.shell.layer` declares Config, State and Capability. Config+contains CLI tools, environment values, secret names, redaction patterns and+`runtime` / optional `execution_context` references. Native ordering ensures an+active lease exists before shell bootstrap and config eager pulls.++The Capability exposes shell_run, shell_wait, shell_input and shell_interrupt+through a native sequential Toolset. JSON State holds initialized, job_ids and+job_offsets; live tokens remain in the run-scoped ShellSession. Bootstrap marks+initialized only on success. Exit cleanup removes tracked jobs and clears IDs,+offsets and credentials before Runtime releases the lease, including cancellation.+The API owns Workspace/Binding retirement. HOME is reusable system space; cwd+and TMPDIR/TMP/TEMP refer to the active Workspace.diff --git a/dify-agent/docs/dify-agent/user-manual/structured-output-layer/index.md b/dify-agent/docs/dify-agent/user-manual/structured-output-layer/index.mdindex 049351d1fd6..2b958d314f0 100644--- a/dify-agent/docs/dify-agent/user-manual/structured-output-layer/index.md+++ b/dify-agent/docs/dify-agent/user-manual/structured-output-layer/index.md@@ -1,101 +1,9 @@-# Structured output layer--The structured output layer makes the final answer follow a caller-provided JSON-Schema. Add it when the client needs a JSON object instead of plain text.--When present, Dify Agent exposes the schema to the model as a structured-output-tool and validates the model response against the same schema.--## Layer contract--| Property | Value |-| --- | --- |-| Reserved layer name | `output` |-| Type id | `dify.output` |-| Config | `DifyOutputLayerConfig` |-| Dependencies | none |--Use at most one structured output layer. It must be named `output`.--## Config fields--| Field | Type | Meaning |-| --- | --- | --- |-| `json_schema` | `dict[str, JsonValue]` | Top-level object JSON Schema for the final answer. |-| `description` | `str \| None` | Optional model-facing tool description. |-| `strict` | `bool \| None` | Optional strictness flag passed to the output tool. |--The structured-output tool name is fixed to `final_output`.--## Basic usage--```python {test="skip" lint="skip"}-from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig-from dify_agent.protocol import DIFY_AGENT_OUTPUT_LAYER_ID, RunLayerSpec---output_layer = RunLayerSpec(- name=DIFY_AGENT_OUTPUT_LAYER_ID,- type=DIFY_OUTPUT_LAYER_TYPE_ID,- config=DifyOutputLayerConfig(- description="Structured incident summary returned by the agent.",- strict=True,- json_schema={- "type": "object",- "properties": {- "title": {"type": "string"},- "severity": {"type": "string", "enum": ["low", "medium", "high"]},- "actions": {"type": "array", "items": {"type": "string"}},- },- "required": ["title", "severity", "actions"],- "additionalProperties": False,- },- ),-)-```--On success, the terminal event contains the validated JSON-safe object:--```python {test="skip" lint="skip"}-async for event in client.stream_events(run_id):- if event.type == "run_succeeded":- structured_output = event.data.output-```--If the `output` layer is omitted, Dify Agent keeps the default plain text output-contract.--## Schema limits--The first structured-output version supports a practical subset of JSON Schema:--- the top-level schema must be an object (`"type": "object"`)-- the model-facing structured-output tool name is always `final_output`-- remote `$ref` values are not supported-- local refs are supported only under `#/$defs/...`-- recursive `$defs` refs are not supported-- `$ref` values inside ordinary literal keywords such as `const`, `enum`,- `example`, and `examples` are treated as data, not schema refs--## Validation and retry behavior--The runtime builds a pydantic-ai output contract from the layer config. The same-contract exposes the model-facing schema and validates the returned object.--If the model returns an invalid object, pydantic-ai's normal output-validation-retry behavior applies. If retries are exhausted, the run ends with `run_failed`.--## Resuming runs with structured output--Session snapshots store layer runtime state, not output-layer config. If you-resume a run that uses structured output, include the same `output` layer again so-the runtime can rebuild the output contract.--## Troubleshooting--| Symptom | What to check |-| --- | --- |-| `must use reserved layer name 'output'` | Rename the layer to `output`. |-| Structured output falls back to text | Confirm the `output` layer is present and has type `dify.output`. |-| Run fails before model resolution | Validate the JSON Schema and `$ref` usage. |-| Resume loses structured output | Resubmit the same output layer; snapshots do not store the schema. |+# Structured output module++`dify_agent.layers.output.output_layer` declares Config, empty State and+Capability. The reserved `output` name accepts a top-level object JSON Schema,+optional description and strictness. The runner resolves native output_type+before running the agent. A fresh dynamic type exposes the schema and performs+JSON Schema validation in Pydantic AI's retry pipeline. The model-facing tool+name is final_output. Local `#/$defs/` references are supported; remote or+recursive references are rejected before I/O. Resume resubmits current Config.diff --git a/dify-agent/docs/index.md b/dify-agent/docs/index.mdindex 0fd13b6cb66..a38dc88ff2c 100644--- a/dify-agent/docs/index.md+++ b/dify-agent/docs/index.md@@ -1,11 +1,5 @@# Dify Agent-This documentation is split by ownership boundary:--- [Agenton](agenton/index.md) covers the framework-neutral layer compositor and reusable- collection layers.-- [Dify Agent](dify-agent/index.md) covers the Dify runtime, HTTP API, Redis-backed run- storage, and server examples.--The split mirrors the source tree so Agenton documentation and examples can be-moved together if Agenton is published separately later.+[Runtime modules](dify-agent/index.md) compose native Pydantic AI capabilities+and toolsets. [Getting started](dify-agent/get-started/index.md) covers the HTTP+protocol; [operations](dify-agent/guide/index.md) covers deployment.diff --git a/dify-agent/examples/agenton/agenton_examples/__init__.py b/dify-agent/examples/agenton/agenton_examples/__init__.pydeleted file mode 100644index 048f5b8e02e..00000000000--- a/dify-agent/examples/agenton/agenton_examples/__init__.py+++ /dev/null@@ -1 +0,0 @@-"""Runnable Agenton examples kept separate from Dify Agent runtime examples."""diff --git a/dify-agent/examples/agenton/agenton_examples/__main__.py b/dify-agent/examples/agenton/agenton_examples/__main__.pydeleted file mode 100644index d0794fc2f08..00000000000--- a/dify-agent/examples/agenton/agenton_examples/__main__.py+++ /dev/null@@ -1,50 +0,0 @@-"""Small CLI for listing or copying Agenton examples."""--from __future__ import annotations--import argparse-import shutil-import sys-from pathlib import Path--EXAMPLE_MODULES = (- "basics",- "pydantic_ai_bridge",- "session_snapshot",-)---def cli() -> None:- parser = argparse.ArgumentParser(- prog="agenton_examples",- description="List or copy Agenton examples.",- )- parser.add_argument("--copy-to", metavar="DEST", help="Copy example files to a new directory")- args = parser.parse_args()-- examples_dir = Path(__file__).parent- if args.copy_to:- copy_to(examples_dir, Path(args.copy_to))- return-- for module_name in EXAMPLE_MODULES:- print(f"python -m agenton_examples.{module_name}")---def copy_to(examples_dir: Path, destination: Path) -> None:- if destination.exists():- print(f'Error: destination path "{destination}" already exists', file=sys.stderr)- sys.exit(1)-- destination.mkdir(parents=True)- copied = 0- for source in examples_dir.glob("*.py"):- if source.name == "__init__.py":- continue- shutil.copy2(source, destination / source.name)- copied += 1- print(f'Copied {copied} Agenton example files to "{destination}"')---if __name__ == "__main__":- cli()diff --git a/dify-agent/examples/agenton/agenton_examples/basics.py b/dify-agent/examples/agenton/agenton_examples/basics.pydeleted file mode 100644index 81a3daeb18d..00000000000--- a/dify-agent/examples/agenton/agenton_examples/basics.py+++ /dev/null@@ -1,142 +0,0 @@-"""Run with: uv run --project dify-agent python -m agenton_examples.basics."""--from __future__ import annotations--import asyncio-from dataclasses import dataclass, field-from inspect import signature-from typing import cast--from typing_extensions import override--from agenton.compositor import Compositor, LayerNode, LayerProvider-from agenton.layers import LayerDeps, NoLayerDeps, PlainLayer, PlainToolType-from agenton_collections.layers.plain import DynamicToolsLayer, ObjectLayer, PromptLayer, ToolsLayer, with_object-from agenton_collections.layers.plain.basic import PromptLayerConfig---@dataclass(frozen=True, slots=True)-class AgentProfile:- name: str- audience: str- tone: str---class ProfilePromptDeps(LayerDeps):- profile: ObjectLayer[AgentProfile] # pyright: ignore[reportUninitializedInstanceVariable]---@dataclass(slots=True)-class ProfilePromptLayer(PlainLayer[ProfilePromptDeps]):- @property- @override- def prefix_prompts(self) -> list[str]:- profile = self.deps.profile.value- return [- f"You are {profile.name}, writing for {profile.audience}.",- f"Keep the tone {profile.tone}.",- ]---@dataclass(slots=True)-class TraceLayer(PlainLayer[NoLayerDeps]):- events: list[str] = field(default_factory=list)-- @override- async def on_context_create(self) -> None:- self.events.append("create")-- @override- async def on_context_suspend(self) -> None:- self.events.append("suspend")-- @override- async def on_context_resume(self) -> None:- self.events.append("resume")-- @override- async def on_context_delete(self) -> None:- self.events.append("delete")---def count_words(text: str) -> int:- return len(text.split())---@with_object(AgentProfile)-def write_tagline(profile: AgentProfile, topic: str) -> str:- return f"{profile.name}: {topic} for {profile.audience}, in a {profile.tone} voice."---async def main() -> None:- profile = AgentProfile(- name="Agenton Assistant",- audience="engineers composing agent capabilities",- tone="precise and friendly",- )- trace_events: list[str] = []- compositor = Compositor(- [- LayerNode("base_prompt", PromptLayer),- LayerNode("extra_prompt", PromptLayer),- LayerNode(- "profile",- LayerProvider.from_factory(- layer_type=ObjectLayer,- create=lambda _config: ObjectLayer[AgentProfile](profile),- ),- ),- LayerNode("profile_prompt", ProfilePromptLayer, deps={"profile": "profile"}),- LayerNode(- "tools",- LayerProvider.from_factory(- layer_type=ToolsLayer,- create=lambda _config: ToolsLayer(tool_entries=(count_words,)),- ),- ),- LayerNode(- "dynamic_tools",- LayerProvider.from_factory(- layer_type=DynamicToolsLayer,- create=lambda _config: DynamicToolsLayer[AgentProfile](tool_entries=(write_tagline,)),- ),- deps={"object_layer": "profile"},- ),- LayerNode(- "trace",- LayerProvider.from_factory(layer_type=TraceLayer, create=lambda _config: TraceLayer(trace_events)),- ),- ]- )- configs = {- "base_prompt": PromptLayerConfig(- prefix="Use config dicts for serializable layers.",- user="Explain how the composed agent should use its layers.",- suffix="Before finalizing, make the result easy to scan.",- ),- "extra_prompt": PromptLayerConfig(prefix="Use constructed instances for objects, local code, and callables."),- }-- async with compositor.enter(configs=configs) as run:- print("Prompts:")- for prompt in run.prompts:- print(f"- {prompt.value}")-- print("\nUser prompts:")- for prompt in run.user_prompts:- print(f"- {prompt.value}")-- print("\nTools:")- plain_tools = [cast(PlainToolType, tool) for tool in run.tools]- for tool in plain_tools:- print(f"- {tool.value.__name__}{signature(tool.value)}")- print([tool.value("layer composition") for tool in plain_tools])- run.suspend_on_exit()-- async with compositor.enter(configs=configs, session_snapshot=run.session_snapshot):- pass- print("\nLifecycle:", trace_events)---if __name__ == "__main__":- asyncio.run(main())diff --git a/dify-agent/examples/agenton/agenton_examples/pydantic_ai_bridge.py b/dify-agent/examples/agenton/agenton_examples/pydantic_ai_bridge.pydeleted file mode 100644index 490e54100b9..00000000000--- a/dify-agent/examples/agenton/agenton_examples/pydantic_ai_bridge.py+++ /dev/null@@ -1,119 +0,0 @@-"""Pydantic AI bridge example for use from a source checkout.--`agenton_examples` is not part of the published package, so run this module from-the repository root with:-- PYTHONPATH=dify-agent/src:dify-agent/examples/agenton \- uv run --project dify-agent python -m agenton_examples.pydantic_ai_bridge-"""--from __future__ import annotations--import asyncio-import os-from dataclasses import dataclass--from pydantic_ai import Agent, RunContext-from pydantic_ai.models.openai import OpenAIChatModel # pyright: ignore[reportDeprecated]-from pydantic_ai.models.test import TestModel--from agenton.compositor import Compositor, LayerNode, LayerProvider-from agenton_collections.layers.plain import ObjectLayer, PromptLayer, PromptLayerConfig, ToolsLayer-from agenton_collections.layers.pydantic_ai import PydanticAIBridgeLayer-from agenton_collections.transformers.pydantic_ai import PYDANTIC_AI_TRANSFORMERS---@dataclass(frozen=True, slots=True)-class AgentProfile:- name: str- audience: str- tone: str---def count_words(text: str) -> int:- return len(text.split())---def profile_prompt(ctx: RunContext[AgentProfile]) -> str:- profile = ctx.deps- return f"You are {profile.name}, helping {profile.audience}."---def tone_prompt(ctx: RunContext[AgentProfile]) -> str:- return f"Keep responses {ctx.deps.tone}."---def write_tagline(ctx: RunContext[AgentProfile], topic: str) -> str:- profile = ctx.deps- return f"{profile.name}: {topic} for {profile.audience}, in a {profile.tone} voice."---async def main() -> None:- profile = AgentProfile(- name="Agenton Assistant",- audience="engineers composing agent capabilities",- tone="precise and friendly",- )- compositor = Compositor(- [- LayerNode("base_prompt", PromptLayer),- LayerNode(- "profile",- LayerProvider.from_factory(- layer_type=ObjectLayer,- create=lambda _config: ObjectLayer[AgentProfile](profile),- ),- ),- LayerNode(- "plain_tools",- LayerProvider.from_factory(- layer_type=ToolsLayer,- create=lambda _config: ToolsLayer(tool_entries=(count_words,)),- ),- ),- LayerNode(- "pydantic_ai_bridge",- LayerProvider.from_factory(- layer_type=PydanticAIBridgeLayer,- create=lambda _config: PydanticAIBridgeLayer[AgentProfile](- prefix=("Prefer concrete details.", profile_prompt, tone_prompt),- user="Use the tools for 'layer composition'.",- tool_entries=(write_tagline,),- ),- ),- deps={"object_layer": "profile"},- ),- ],- **PYDANTIC_AI_TRANSFORMERS,- )-- async with compositor.enter(- configs={- "base_prompt": PromptLayerConfig(- prefix="Use the available tools before answering.",- suffix="Return concise, inspectable output.",- )- }- ) as run:- model = (- OpenAIChatModel("gpt-5.5") # pyright: ignore[reportDeprecated]- if os.getenv("OPENAI_API_KEY")- else TestModel()- )- agent = Agent[AgentProfile](- model=model,- deps_type=AgentProfile,- tools=run.tools,- )- for prompt in run.prompts:- _ = agent.system_prompt(prompt)-- bridge_layer = run.get_layer("pydantic_ai_bridge", PydanticAIBridgeLayer)- result = await agent.run(run.user_prompts, deps=bridge_layer.run_deps)-- for message in result.all_messages():- print(message)---if __name__ == "__main__":- asyncio.run(main())diff --git a/dify-agent/examples/agenton/agenton_examples/session_snapshot.py b/dify-agent/examples/agenton/agenton_examples/session_snapshot.pydeleted file mode 100644index 4e5a9c3b9fb..00000000000--- a/dify-agent/examples/agenton/agenton_examples/session_snapshot.py+++ /dev/null@@ -1,50 +0,0 @@-"""Run with: uv run --project dify-agent python -m agenton_examples.session_snapshot."""--from __future__ import annotations--import asyncio-from dataclasses import dataclass-from typing import ClassVar--from pydantic import BaseModel, ConfigDict--from agenton.compositor import Compositor, LayerNode-from agenton.layers import EmptyLayerConfig, NoLayerDeps, PlainLayer---class ConnectionState(BaseModel):- connection_id: str = "demo-connection"-- model_config = ConfigDict(extra="forbid", validate_assignment=True)---class ConnectionHandle:- def __init__(self, connection_id: str) -> None:- self.connection_id = connection_id---@dataclass(slots=True)-class ConnectionLayer(PlainLayer[NoLayerDeps, EmptyLayerConfig, ConnectionState]):- runtime_state_type: ClassVar[type[BaseModel]] = ConnectionState---async def main() -> None:- compositor = Compositor([LayerNode("connection", ConnectionLayer)])- async with compositor.enter() as run:- layer = run.get_layer("connection", ConnectionLayer)- connection = ConnectionHandle(layer.runtime_state.connection_id)- print("Active external handle:", connection.connection_id)- run.suspend_on_exit()-- snapshot = run.session_snapshot- assert snapshot is not None- print("Snapshot:", snapshot.model_dump(mode="json"))-- async with compositor.enter(session_snapshot=snapshot) as restored_run:- layer = restored_run.get_layer("connection", ConnectionLayer)- restored_connection = ConnectionHandle(f"restored:{layer.runtime_state.connection_id}")- print("Rehydrated external handle:", restored_connection.connection_id)---if __name__ == "__main__":- asyncio.run(main())diff --git a/dify-agent/examples/dify_agent/dify_agent_examples/__init__.py b/dify-agent/examples/dify_agent/dify_agent_examples/__init__.pyindex 629dd853683..e3c5c15e2d3 100644--- a/dify-agent/examples/dify_agent/dify_agent_examples/__init__.py+++ b/dify-agent/examples/dify_agent/dify_agent_examples/__init__.py@@ -1 +1 @@-"""Runnable Dify Agent runtime examples kept separate from Agenton examples."""+"""Runnable Dify Agent client examples."""diff --git a/dify-agent/examples/dify_agent/dify_agent_examples/run_server_consumer.py b/dify-agent/examples/dify_agent/dify_agent_examples/run_server_consumer.pyindex 25c9081c1d4..c42d0b4ae32 100644--- a/dify-agent/examples/dify_agent/dify_agent_examples/run_server_consumer.py+++ b/dify-agent/examples/dify_agent/dify_agent_examples/run_server_consumer.py@@ -7,7 +7,7 @@ example:uv run --project dify-agent uvicorn dify_agent.server.app:app --reload-The request carries Dify plugin model configuration in Agenton layers. This+The request carries Dify plugin model configuration in registered modules. Thisscript prints the created run and every event observed through cursor polling.``Client.create_run`` performs one POST attempt only; use polling or SSE replay torecover after client-side uncertainty.@@ -15,11 +15,10 @@ recover after client-side uncertainty.import asyncio-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig+from dify_agent.layers.prompt import Config as PromptConfigfrom dify_agent.client import Client-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig+from dify_agent.layers.execution_context import DifyExecutionContextLayerConfigfrom dify_agent.layers.dify_plugin import (- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,DifyPluginLLMLayerConfig,)from dify_agent.protocol import DIFY_AGENT_MODEL_LAYER_ID, CreateRunRequest, RunComposition, RunLayerSpec@@ -42,33 +41,33 @@ async def main() -> None:layers=[RunLayerSpec(name="prompt",- type=PLAIN_PROMPT_LAYER_TYPE_ID,- config=PromptLayerConfig(- prefix="You are a concise assistant.",- user="Say hello from the Dify Agent API server example.",- ),+ config=(+ PromptConfig(+ prefix="You are a concise assistant.",+ user="Say hello from the Dify Agent API server example.",+ )+ ).model_dump(mode="json"),),RunLayerSpec(name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id=TENANT_ID,- user_id=USER_ID,- user_from="account",- app_id=APP_ID,- agent_mode="workflow_run",- invoke_from="service-api",- ),+ config=(+ DifyExecutionContextLayerConfig(+ tenant_id=TENANT_ID,+ user_id=USER_ID,+ user_from="account",+ app_id=APP_ID,+ agent_mode="workflow_run",+ invoke_from="service-api",+ )+ ).model_dump(mode="json"),),RunLayerSpec(name=DIFY_AGENT_MODEL_LAYER_ID,- type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id=PLUGIN_ID,- model_provider=PLUGIN_PROVIDER,- model=MODEL_NAME,- ),+ config=(+ DifyPluginLLMLayerConfig(+ plugin_id=PLUGIN_ID, model_provider=PLUGIN_PROVIDER, model=MODEL_NAME+ )+ ).model_dump(mode="json"),),# Minimal plugin-tools example. API callers should pass# prepared parameters + JSON schema instead of relying on@@ -82,9 +81,8 @@ async def main() -> None:# )# RunLayerSpec(# name="tools",- # type="dify.plugin.tools",- # deps={"execution_context": "execution_context"},# config=DifyPluginToolsLayerConfig(+ # execution_context="execution_context",# tools=[# DifyPluginToolConfig(# plugin_id="langgenius/search",@@ -111,7 +109,7 @@ async def main() -> None:# },# )# ]- # ),+ # ).model_dump(mode="json"),# ),],),diff --git a/dify-agent/examples/dify_agent/dify_agent_examples/run_server_sync_client.py b/dify-agent/examples/dify_agent/dify_agent_examples/run_server_sync_client.pyindex 7887329b666..76f4d5ac441 100644--- a/dify-agent/examples/dify_agent/dify_agent_examples/run_server_sync_client.py+++ b/dify-agent/examples/dify_agent/dify_agent_examples/run_server_sync_client.py@@ -8,11 +8,10 @@ timeout occurs, inspect server state or create a new run explicitly rather thanassuming the original request was not accepted."""-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig+from dify_agent.layers.prompt import Config as PromptConfigfrom dify_agent.client import Client-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig+from dify_agent.layers.execution_context import DifyExecutionContextLayerConfigfrom dify_agent.layers.dify_plugin import (- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,DifyPluginLLMLayerConfig,)from dify_agent.protocol import DIFY_AGENT_MODEL_LAYER_ID, CreateRunRequest, RunComposition, RunLayerSpec@@ -35,33 +34,33 @@ def main() -> None:layers=[RunLayerSpec(name="prompt",- type=PLAIN_PROMPT_LAYER_TYPE_ID,- config=PromptLayerConfig(- prefix="You are a concise assistant.",- user="Say hello from the synchronous Dify Agent client example.",- ),+ config=(+ PromptConfig(+ prefix="You are a concise assistant.",+ user="Say hello from the synchronous Dify Agent client example.",+ )+ ).model_dump(mode="json"),),RunLayerSpec(name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id=TENANT_ID,- user_id=USER_ID,- user_from="account",- app_id=APP_ID,- agent_mode="workflow_run",- invoke_from="service-api",- ),+ config=(+ DifyExecutionContextLayerConfig(+ tenant_id=TENANT_ID,+ user_id=USER_ID,+ user_from="account",+ app_id=APP_ID,+ agent_mode="workflow_run",+ invoke_from="service-api",+ )+ ).model_dump(mode="json"),),RunLayerSpec(name=DIFY_AGENT_MODEL_LAYER_ID,- type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id=PLUGIN_ID,- model_provider=PLUGIN_PROVIDER,- model=MODEL_NAME,- ),+ config=(+ DifyPluginLLMLayerConfig(+ plugin_id=PLUGIN_ID, model_provider=PLUGIN_PROVIDER, model=MODEL_NAME+ )+ ).model_dump(mode="json"),),# Minimal plugin-tools example. API callers should pass# prepared parameters + JSON schema instead of relying on@@ -75,9 +74,8 @@ def main() -> None:# )# RunLayerSpec(# name="tools",- # type="dify.plugin.tools",- # deps={"execution_context": "execution_context"},# config=DifyPluginToolsLayerConfig(+ # execution_context="execution_context",# tools=[# DifyPluginToolConfig(# plugin_id="langgenius/search",@@ -104,7 +102,7 @@ def main() -> None:# },# )# ]- # ),+ # ).model_dump(mode="json"),# ),],),diff --git a/dify-agent/mkdocs.yml b/dify-agent/mkdocs.ymlindex 5842702d8d3..ac3bf216585 100644--- a/dify-agent/mkdocs.yml+++ b/dify-agent/mkdocs.yml@@ -1,5 +1,5 @@site_name: Dify Agent-site_description: Agent runtime and Agenton composition framework documentation+site_description: Native Pydantic AI agent runtime documentationstrict: truerepo_name: langgenius/dify@@ -8,10 +8,6 @@ edit_uri: edit/main/dify-agent/docs/nav:- Home: index.md- - Agenton:- - Overview: agenton/index.md- - Guide: agenton/guide/index.md- - Examples: agenton/examples/index.md- Dify Agent:- Overview: dify-agent/index.md- Concepts:@@ -19,14 +15,13 @@ nav:- Runtime Resources: dify-agent/concepts/runtime-resources/index.md- User Manual:- Get Started: dify-agent/get-started/index.md- - Prompt Layer: dify-agent/user-manual/prompt-layer/index.md- - Execution Context Layer: dify-agent/user-manual/execution-context-layer/index.md- - Shell Layer: dify-agent/user-manual/shell-layer/index.md- - Ask Human Layer: dify-agent/user-manual/ask-human-layer/index.md- - Plugin LLM Layer: dify-agent/user-manual/plugin-llm-layer/index.md- - Plugin Tool Layer: dify-agent/user-manual/plugin-tool-layer/index.md- - History Layer: dify-agent/user-manual/history-layer/index.md- - Structured Output Layer: dify-agent/user-manual/structured-output-layer/index.md+ - Prompt Module: dify-agent/user-manual/prompt-layer/index.md+ - Execution Context Module: dify-agent/user-manual/execution-context-layer/index.md+ - Shell Module: dify-agent/user-manual/shell-layer/index.md+ - Plugin LLM Module: dify-agent/user-manual/plugin-llm-layer/index.md+ - Plugin Tool Module: dify-agent/user-manual/plugin-tool-layer/index.md+ - History Module: dify-agent/user-manual/history-layer/index.md+ - Structured Output Module: dify-agent/user-manual/structured-output-layer/index.md- Operations Guide:- Overview: dify-agent/guide/index.md- OpenShell Runtime Backend: dify-agent/guide/openshell.mddiff --git a/dify-agent/pyproject.toml b/dify-agent/pyproject.tomlindex a6549f7fcbc..1c29370e03c 100644--- a/dify-agent/pyproject.toml+++ b/dify-agent/pyproject.toml@@ -9,7 +9,7 @@ dependencies = ["httpx2>=2.5.0,<3.0.0","pydantic>=2.12.5,<2.13","pydantic-ai-harness>=0.20.0,<0.21.0",- "pydantic-ai-slim>=2.30.0,<3.0.0",+ "pydantic-ai-slim==2.31.0","typing-extensions>=4.12.2,<5.0.0",]@@ -29,7 +29,7 @@ server = ["jwcrypto>=1.5.6,<2","logfire[fastapi,httpx,redis]>=4.37.0,<5.0.0","openshell>=0.0.106,<0.1.0",- "pydantic-ai-slim[anthropic,google,openai]>=2.30.0,<3.0.0",+ "pydantic-ai-slim[anthropic,google,openai]==2.31.0","pydantic-settings>=2.12.0,<3.0.0","redis>=7.4.0,<8.0.0","uvicorn[standard]==0.46.0",@@ -37,7 +37,7 @@ server = [[tool.setuptools.packages.find]where = ["src"]-include = ["agenton*", "agenton_collections*", "dify_agent*", "shellctl*"]+include = ["dify_agent*", "shellctl*"][tool.setuptools.package-data]"dify_agent.layers" = ["_agent_cli_help.json"]@@ -45,9 +45,10 @@ include = ["agenton*", "agenton_collections*", "dify_agent*", "shellctl*"][tool.pyrefly]project-includes = ["src", "examples"]project-excludes = [".venv", "tests/"]-search-path = ["src", "examples/agenton", "examples/dify_agent"]+search-path = ["src", "examples/dify_agent"]python-platform = "linux"python-version = "3.13.0"+errors = { missing-override-decorator = "error" }[tool.pytest.ini_options]# Several test modules share a basename across directories (test_layer.py,diff --git a/dify-agent/src/agenton/__init__.py b/dify-agent/src/agenton/__init__.pydeleted file mode 100644index 13f624c6bcd..00000000000--- a/dify-agent/src/agenton/__init__.py+++ /dev/null@@ -1,19 +0,0 @@-"""Agenton state-only core.--Agenton core composes reusable stateless layer graph plans, creates a fresh-``CompositorRun`` for each invocation, hydrates and advances serializable layer-``runtime_state`` through run slots, enters each layer's active-scope-``resource_context()``, and emits session snapshots. It intentionally never-serializes resources, handles, clients, cleanup callbacks, or any other-non-serializable runtime object.--Each ``Compositor`` stores only graph nodes and layer providers. Every enter call-creates new layer instances, binds direct dependencies for that run, and writes-the next cross-call state to ``run.session_snapshot`` after exit. To resume a-suspended call, reuse the same compositor plan and pass the prior snapshot to a-new enter call.--``LifecycleState.ACTIVE`` is internal-only while an entry is running. External-session snapshots and hydrated input must contain only non-active lifecycle-states; ``runtime_state`` is the only mutable layer data captured by snapshots.-"""diff --git a/dify-agent/src/agenton/compositor/__init__.py b/dify-agent/src/agenton/compositor/__init__.pydeleted file mode 100644index 17829fe3e41..00000000000--- a/dify-agent/src/agenton/compositor/__init__.py+++ /dev/null@@ -1,56 +0,0 @@-"""Stateless layer graph composition facade for the Agenton core.--``agenton.compositor`` remains the stable import surface for reusable graph-composition. ``core.py`` defines the state-only ``Compositor`` graph plan and-``LayerNode`` orchestration, ``providers.py`` owns reusable construction plans-and fresh-instance validation, ``run.py`` owns active invocation lifecycle plus-prompt/tool aggregation, ``schemas.py`` owns serializable graph/snapshot DTOs-and boundary revalidation, and ``types.py`` holds shared generic transformer-types.--``Compositor`` itself stores no live layer instances, run lifecycle state,-session state, resources, or handles. Each ``enter(...)`` call creates a fresh-``CompositorRun`` with new layer instances, direct dependency binding, optional-snapshot hydration, entered per-layer ``resource_context()`` scopes, and the-next ``session_snapshot`` after exit.-``LifecycleState.ACTIVE`` remains internal-only and session snapshots contain-only ordered layer lifecycle state plus serializable ``runtime_state``.--The facade also keeps true module-level aliases for ``LayerConfigInput`` and-``LayerProviderInput`` so existing typed direct imports remain supported-without expanding ``__all__``.-"""--from .core import Compositor, LayerNode-from .providers import LayerConfigInput as _LayerConfigInput-from .providers import LayerFactory, LayerProvider, LayerProviderInput as _LayerProviderInput-from .run import CompositorRun, LayerRunSlot-from .schemas import (- CompositorConfig,- CompositorConfigValue,- CompositorSessionSnapshot,- CompositorSessionSnapshotValue,- LayerNodeConfig,- LayerSessionSnapshot,-)-from .types import CompositorTransformer, CompositorTransformerKwargs--type LayerConfigInput = _LayerConfigInput-type LayerProviderInput = _LayerProviderInput--__all__ = [- "Compositor",- "CompositorConfig",- "CompositorConfigValue",- "CompositorRun",- "CompositorSessionSnapshot",- "CompositorSessionSnapshotValue",- "CompositorTransformer",- "CompositorTransformerKwargs",- "LayerFactory",- "LayerNode",- "LayerNodeConfig",- "LayerProvider",- "LayerRunSlot",- "LayerSessionSnapshot",-]diff --git a/dify-agent/src/agenton/compositor/core.py b/dify-agent/src/agenton/compositor/core.pydeleted file mode 100644index eb3763b2f76..00000000000--- a/dify-agent/src/agenton/compositor/core.py+++ /dev/null@@ -1,331 +0,0 @@-"""Stateless compositor graph plans and run construction.--``Compositor`` stores only reusable graph nodes and optional aggregation-transformers. Each ``enter(...)`` call validates node-name keyed configs before-any provider factory runs, optionally validates and hydrates a session snapshot,-creates fresh layer instances, binds direct dependencies, and returns a new-``CompositorRun`` for that invocation only. Dependency targets must point to-preceding graph nodes so resource scopes can nest in dependency order.--``Compositor.from_config(...)`` resolves serializable provider type ids rather-than import paths. Named ``node_providers`` override type-id providers for the-same graph node without passing graph node data into factories. Session-snapshots must list layer names in compositor order so runtime state can be-hydrated deterministically.-"""--from collections import OrderedDict-from collections.abc import AsyncGenerator, Mapping, Sequence-from contextlib import asynccontextmanager-from dataclasses import dataclass-from typing import Any, Generic, Self, cast--from pydantic import JsonValue--from agenton.layers.base import Layer, LayerConfig, LifecycleState--from .providers import LayerConfigInput, LayerProvider, LayerProviderInput, _as_layer_provider-from .run import CompositorRun, LayerRunSlot-from .schemas import (- CompositorConfigValue,- CompositorSessionSnapshot,- CompositorSessionSnapshotValue,- _validate_compositor_config_input,- _validate_config_model_input,-)-from .types import (- CompositorTransformer,- LayerPromptT,- LayerToolT,- LayerUserPromptT,- PromptT,- ToolT,- UserPromptT,-)---@dataclass(frozen=True, slots=True, init=False)-class LayerNode:- """Stateless graph node plan for one named layer provider.-- ``implementation`` may be a layer class or an explicit ``LayerProvider``.- ``deps`` maps dependency field names on this node's layer class to other- preceding compositor node names. ``metadata`` is graph description data- only; it is not passed to provider factories and is never included in- session snapshots.- """-- name: str- provider: LayerProvider[Any]- deps: Mapping[str, str]- metadata: Mapping[str, JsonValue]-- def __init__(- self,- name: str,- implementation: LayerProviderInput,- *,- deps: Mapping[str, str] | None = None,- metadata: Mapping[str, JsonValue] | None = None,- ) -> None:- if not name:- raise ValueError("Layer node name must not be empty.")- object.__setattr__(self, "name", name)- object.__setattr__(self, "provider", _as_layer_provider(implementation))- object.__setattr__(self, "deps", dict(deps or {}))- object.__setattr__(self, "metadata", dict(metadata or {}))---class Compositor(Generic[PromptT, ToolT, LayerPromptT, LayerToolT, UserPromptT, LayerUserPromptT]):- """Reusable, framework-neutral ordered layer graph plan.-- A compositor stores only immutable graph nodes and provider construction- plans. It is safe to enter repeatedly or concurrently because every entry- creates a separate ``CompositorRun`` with fresh layer instances, run slots,- dependency bindings, and optional hydrated runtime state. Session- continuity is explicit: pass the previous ``CompositorSessionSnapshot`` to- the next ``enter`` call and read the next one from ``run.session_snapshot``- after exit.-- ``prompt_transformer``, ``user_prompt_transformer``, and- ``tool_transformer`` are post-aggregation hooks on each run. Use two type- arguments for identity aggregation, four when prompt/tool layer item types- differ from exposed item types, or all six when user prompt item types also- differ. Graph order is meaningful for lifecycle nesting, so dependency edges- must point only to earlier nodes.- """-- __slots__ = ("_nodes", "prompt_transformer", "tool_transformer", "user_prompt_transformer")-- _nodes: tuple[LayerNode, ...]- prompt_transformer: CompositorTransformer[LayerPromptT, PromptT] | None- user_prompt_transformer: CompositorTransformer[LayerUserPromptT, UserPromptT] | None- tool_transformer: CompositorTransformer[LayerToolT, ToolT] | None-- def __init__(- self,- nodes: Sequence[LayerNode],- *,- prompt_transformer: CompositorTransformer[LayerPromptT, PromptT] | None = None,- user_prompt_transformer: CompositorTransformer[LayerUserPromptT, UserPromptT] | None = None,- tool_transformer: CompositorTransformer[LayerToolT, ToolT] | None = None,- ) -> None:- self._nodes = tuple(nodes)- self.prompt_transformer = prompt_transformer- self.user_prompt_transformer = user_prompt_transformer- self.tool_transformer = tool_transformer- self._validate_nodes()-- @property- def nodes(self) -> tuple[LayerNode, ...]:- """Return the stateless graph plan nodes in compositor order."""- return self._nodes-- @classmethod- def from_config(- cls,- conf: CompositorConfigValue,- *,- providers: Sequence[LayerProviderInput],- node_providers: Mapping[str, LayerProviderInput] | None = None,- prompt_transformer: CompositorTransformer[LayerPromptT, PromptT] | None = None,- user_prompt_transformer: CompositorTransformer[LayerUserPromptT, UserPromptT] | None = None,- tool_transformer: CompositorTransformer[LayerToolT, ToolT] | None = None,- ) -> Self:- """Create a reusable compositor plan from serializable graph config.-- ``providers`` resolve graph node ``type`` ids. ``node_providers`` are- keyed by graph node name and take precedence over the type-id provider,- allowing node-specific construction without passing node data to factory- callables.- """- graph_config = _validate_compositor_config_input(conf)- if graph_config.schema_version != 1:- raise ValueError(f"Unsupported compositor config schema_version: {graph_config.schema_version}.")-- provider_by_type = _build_provider_type_map(providers)- provider_by_node = {name: _as_layer_provider(provider) for name, provider in (node_providers or {}).items()}- graph_node_names = {node.name for node in graph_config.layers}- unknown_node_providers = provider_by_node.keys() - graph_node_names- if unknown_node_providers:- names = ", ".join(sorted(unknown_node_providers))- raise ValueError(f"node_providers contains unknown layer node names: {names}.")-- nodes: list[LayerNode] = []- for node_config in graph_config.layers:- provider = provider_by_node.get(node_config.name)- if provider is None:- try:- provider = provider_by_type[node_config.type]- except KeyError as e:- raise KeyError(f"Layer type id '{node_config.type}' is not registered.") from e- nodes.append(- LayerNode(- node_config.name,- provider,- deps=node_config.deps,- metadata=node_config.metadata,- )- )-- return cls(- nodes,- prompt_transformer=prompt_transformer,- user_prompt_transformer=user_prompt_transformer,- tool_transformer=tool_transformer,- )-- @asynccontextmanager- async def enter(- self,- *,- configs: Mapping[str, LayerConfigInput] | None = None,- session_snapshot: CompositorSessionSnapshotValue | None = None,- ) -> AsyncGenerator[CompositorRun[PromptT, ToolT, LayerPromptT, LayerToolT, UserPromptT, LayerUserPromptT]]:- """Create a fresh run, enter layers in graph order, and yield it.-- Configs are keyed by layer node name and validated before factories run.- The optional session snapshot is validated and hydrated before any hook- runs. Layers exit in reverse graph order, and ``run.session_snapshot``- is populated after exit with the next non-active lifecycle states.- """- run = self._create_run(configs=configs, session_snapshot=session_snapshot)- await run._enter_layers()- body_error: BaseException | None = None- try:- yield run- except BaseException as exc:- body_error = exc- raise- finally:- await run._exit_layers(body_error)-- def _create_run(- self,- *,- configs: Mapping[str, LayerConfigInput] | None,- session_snapshot: CompositorSessionSnapshotValue | None,- ) -> CompositorRun[PromptT, ToolT, LayerPromptT, LayerToolT, UserPromptT, LayerUserPromptT]:- config_by_name = self._validate_run_configs(configs)- typed_config_by_name = self._validate_layer_configs(config_by_name)- snapshot = self._validate_session_snapshot(session_snapshot) if session_snapshot is not None else None- layer_by_name = self._create_layers(typed_config_by_name)-- snapshot_by_name = (- {layer_snapshot.name: layer_snapshot for layer_snapshot in snapshot.layers} if snapshot else {}- )- lifecycle_by_name: dict[str, LifecycleState] = {}- for node in self._nodes:- layer = layer_by_name[node.name]- layer_snapshot = snapshot_by_name.get(node.name)- if layer_snapshot is None:- lifecycle_by_name[node.name] = LifecycleState.NEW- continue- layer.runtime_state = cast(Any, layer.runtime_state_type.model_validate(layer_snapshot.runtime_state))- lifecycle_by_name[node.name] = layer_snapshot.lifecycle_state-- self._bind_deps(layer_by_name)- return CompositorRun(- slots=OrderedDict(- (node.name, LayerRunSlot(layer=layer_by_name[node.name], lifecycle_state=lifecycle_by_name[node.name]))- for node in self._nodes- ),- prompt_transformer=self.prompt_transformer,- user_prompt_transformer=self.user_prompt_transformer,- tool_transformer=self.tool_transformer,- )-- def _create_layers(- self,- config_by_name: Mapping[str, LayerConfig],- ) -> OrderedDict[str, Layer[Any, Any, Any, Any, Any, Any]]:- return OrderedDict(- (node.name, node.provider.create_layer_from_config(config_by_name[node.name])) for node in self._nodes- )-- def _validate_layer_configs(self, config_by_name: Mapping[str, LayerConfigInput]) -> dict[str, LayerConfig]:- """Validate every node config before any provider factory is invoked."""- return {node.name: node.provider.validate_config(config_by_name.get(node.name)) for node in self._nodes}-- def _bind_deps(self, layer_by_name: Mapping[str, Layer[Any, Any, Any, Any, Any, Any]]) -> None:- """Resolve dependency-name mappings and bind direct layer dependencies."""- for node in self._nodes:- layer = layer_by_name[node.name]- resolved_deps = {dep_name: layer_by_name[target_name] for dep_name, target_name in node.deps.items()}- layer.bind_deps(resolved_deps)-- def _validate_nodes(self) -> None:- layer_names: set[str] = set()- for node in self._nodes:- if node.name in layer_names:- raise ValueError(f"Duplicate layer name '{node.name}'.")- layer_names.add(node.name)-- layer_index_by_name = {node.name: index for index, node in enumerate(self._nodes)}-- for node in self._nodes:- declared_deps = node.provider.layer_type.dependency_names()- unknown_dep_keys = set(node.deps) - declared_deps- if unknown_dep_keys:- names = ", ".join(sorted(unknown_dep_keys))- raise ValueError(f"Layer '{node.name}' declares unknown dependency keys: {names}.")- missing_targets = set(node.deps.values()) - layer_names- if missing_targets:- names = ", ".join(sorted(missing_targets))- raise ValueError(f"Layer '{node.name}' depends on undefined layer names: {names}.")-- non_preceding_targets = {- dep_name: target_name- for dep_name, target_name in node.deps.items()- if layer_index_by_name[target_name] >= layer_index_by_name[node.name]- }- if non_preceding_targets:- targets = ", ".join(- f"{dep_name}->{target_name}" for dep_name, target_name in sorted(non_preceding_targets.items())- )- raise ValueError(- f"Layer '{node.name}' dependencies must target preceding layer nodes in compositor order: "- f"{targets}."- )-- def _validate_run_configs(self, configs: Mapping[str, LayerConfigInput] | None) -> dict[str, LayerConfigInput]:- config_by_name = dict(configs or {})- known_names = {node.name for node in self._nodes}- unknown_names = config_by_name.keys() - known_names- if unknown_names:- names = ", ".join(sorted(unknown_names))- raise ValueError(f"Layer configs contain unknown layer node names: {names}.")- return config_by_name-- def _validate_session_snapshot(- self,- snapshot: CompositorSessionSnapshotValue,- ) -> CompositorSessionSnapshot:- resolved_snapshot = _validate_config_model_input(CompositorSessionSnapshot, snapshot)- if resolved_snapshot.schema_version != 1:- raise ValueError(- f"Unsupported compositor session snapshot schema_version: {resolved_snapshot.schema_version}."- )- expected_layer_names = tuple(node.name for node in self._nodes)- actual_layer_names = tuple(layer.name for layer in resolved_snapshot.layers)- if actual_layer_names != expected_layer_names:- expected = ", ".join(expected_layer_names)- actual = ", ".join(actual_layer_names)- raise ValueError(- "CompositorSessionSnapshot layer names must match compositor layers in order. "- f"Expected [{expected}], got [{actual}]."- )- return resolved_snapshot---def _build_provider_type_map(providers: Sequence[LayerProviderInput]) -> dict[str, LayerProvider[Any]]:- provider_by_type: dict[str, LayerProvider[Any]] = {}- for provider_input in providers:- provider = _as_layer_provider(provider_input)- type_id = provider.type_id- if type_id is None or not type_id:- raise ValueError(f"Layer provider for '{provider.layer_type.__qualname__}' must declare a type_id.")- if type_id in provider_by_type:- raise ValueError(f"Layer type id '{type_id}' is already registered.")- provider_by_type[type_id] = provider- return provider_by_typediff --git a/dify-agent/src/agenton/compositor/providers.py b/dify-agent/src/agenton/compositor/providers.pydeleted file mode 100644index 7f176cec908..00000000000--- a/dify-agent/src/agenton/compositor/providers.py+++ /dev/null@@ -1,138 +0,0 @@-"""Reusable layer providers and fresh-instance validation.--Providers are construction plans, not live runtime owners. They validate raw-per-enter config into a layer's declared ``config_type`` and then construct a-fresh layer instance for one invocation. Provider factories receive only typed-config, never graph node data; node-specific construction belongs in named-``node_providers`` overrides on ``Compositor.from_config(...)``.--Fresh-instance enforcement is global by weak reference so ``Compositor`` can-stay stateless while still rejecting reused layer instances before dependency-binding or lifecycle hooks run.-"""--from collections.abc import Callable, Mapping-from typing import Any, Generic, cast-import weakref--from agenton.layers.base import Layer, LayerConfig, LayerConfigValue--from .schemas import _validate_config_model_input-from .types import LayerT--type LayerConfigInput = LayerConfigValue | Mapping[str, object] | str | bytes | None-type LayerFactory = Callable[[LayerConfig], Layer[Any, Any, Any, Any, Any, Any]]-type LayerProviderInput = type[Layer[Any, Any, Any, Any, Any, Any]] | "LayerProvider[Any]"---_USED_LAYER_INSTANCE_REFS: dict[int, weakref.ReferenceType[Layer[Any, Any, Any, Any, Any, Any]]] = {}---def _claim_fresh_layer_instance(layer: Layer[Any, Any, Any, Any, Any, Any]) -> None:- """Reject provider factories that return a layer object used before.-- The registry stores weak references, not live resources or run state. It is- intentionally global to keep ``Compositor`` stateless while still enforcing- the fresh-instance boundary before dependencies are bound or hooks run.- """- layer_identity = id(layer)- existing_ref = _USED_LAYER_INSTANCE_REFS.get(layer_identity)- if existing_ref is not None:- existing_layer = existing_ref()- if existing_layer is not None:- raise ValueError(- "LayerProvider factories must return a fresh layer instance for each invocation; "- f"got reused instance of '{type(layer).__name__}'."- )- _USED_LAYER_INSTANCE_REFS.pop(layer_identity, None)-- def remove_ref(ref: weakref.ReferenceType[Layer[Any, Any, Any, Any, Any, Any]]) -> None:- if _USED_LAYER_INSTANCE_REFS.get(layer_identity) is ref:- _USED_LAYER_INSTANCE_REFS.pop(layer_identity, None)-- _USED_LAYER_INSTANCE_REFS[layer_identity] = weakref.ref(layer, remove_ref)---class LayerProvider(Generic[LayerT]):- """Validated layer factory for one concrete ``Layer`` class.-- Providers are reusable construction plans. They validate per-call config- with ``layer_type.config_type`` before invoking either- ``layer_type.from_config`` or a custom factory. The factory receives only- typed config, never graph node data, and must return a fresh ``layer_type``- instance; reused instances are rejected before dependencies are bound or- hooks run.- """-- __slots__ = ("_create", "layer_type")-- layer_type: type[LayerT]- _create: Callable[[LayerConfig], LayerT]-- def __init__(self, *, layer_type: type[LayerT], create: Callable[[LayerConfig], LayerT]) -> None:- self.layer_type = layer_type- self._create = create-- @classmethod- def from_layer_type(cls, layer_type: type[LayerT]) -> "LayerProvider[LayerT]":- """Create a provider that constructs layers via ``layer_type.from_config``."""-- def create(config: LayerConfig) -> LayerT:- return layer_type.from_config(cast(Any, config))-- return cls(layer_type=layer_type, create=create)-- @classmethod- def from_factory(- cls,- *,- layer_type: type[LayerT],- create: Callable[[Any], LayerT],- ) -> "LayerProvider[LayerT]":- """Create a provider from a custom typed-config factory.-- ``create`` receives the validated instance of ``layer_type.config_type``.- It does not receive the graph node; node-specific construction should use- a dedicated provider in ``Compositor.from_config(node_providers=...)``.- """- return cls(layer_type=layer_type, create=cast(Callable[[LayerConfig], LayerT], create))-- @property- def type_id(self) -> str | None:- """Return the serializable registry type id declared by ``layer_type``."""- return self.layer_type.type_id-- def create_layer(self, config: LayerConfigInput = None) -> LayerT:- """Validate config, call the factory, and return a fresh layer instance."""- typed_config = self.validate_config(config)- return self.create_layer_from_config(typed_config)-- def validate_config(self, config: LayerConfigInput = None) -> LayerConfig:- """Return typed config without invoking the layer factory.-- ``Compositor.enter`` calls this for every node before creating any layer- so a later invalid node config cannot leave earlier factory side effects.- """- raw_config: LayerConfigValue | Mapping[str, object] | str | bytes = {} if config is None else config- return _validate_config_model_input(self.layer_type.config_type, raw_config)-- def create_layer_from_config(self, config: LayerConfig) -> LayerT:- """Call the factory with validated config and enforce fresh instances."""- typed_config = self.validate_config(config)- layer = self._create(typed_config)- if not isinstance(layer, self.layer_type):- raise TypeError(- f"LayerProvider for '{self.layer_type.__name__}' returned '{type(layer).__name__}', "- f"expected '{self.layer_type.__name__}'."- )- _claim_fresh_layer_instance(layer)- layer.config = cast(Any, typed_config)- return layer---def _as_layer_provider(implementation: LayerProviderInput) -> LayerProvider[Any]:- if isinstance(implementation, LayerProvider):- return implementation- if isinstance(implementation, type) and issubclass(implementation, Layer):- return LayerProvider.from_layer_type(implementation)- raise TypeError("LayerNode implementation must be a Layer subclass or LayerProvider.")diff --git a/dify-agent/src/agenton/compositor/run.py b/dify-agent/src/agenton/compositor/run.pydeleted file mode 100644index 95fa3451595..00000000000--- a/dify-agent/src/agenton/compositor/run.py+++ /dev/null@@ -1,278 +0,0 @@-"""Active compositor run lifecycle, snapshots, and aggregation.--``CompositorRun`` is the only compositor object that exposes live layer-instances. It owns invocation-local lifecycle state, per-layer exit intent,-entered layer resource scopes, and the next ``session_snapshot`` after exit.-Layers enter in graph order and exit in reverse graph order. A layer's-``resource_context()`` wraps that layer's enter hook, the active run body while-the layer remains active, and the layer's exit hook. Prompt aggregation-preserves graph ordering: prefix prompts first-to-last, suffix prompts-last-to-first, user prompts first-to-last, and tools in graph order.--Enter hooks transition a slot to ``LifecycleState.ACTIVE`` only after returning-successfully. If ``on_context_create`` or ``on_context_resume`` raises, the run-still exits any already-entered resource contexts, but it does not call the-layer's normal suspend/delete hook for that failed enter attempt.--Prompt, user prompt, and tool transformers run only after layer-level wrapping-and run-level aggregation. When no transformer is installed, the wrapped items-are returned unchanged.-"""--from collections import OrderedDict-from collections.abc import Sequence-from contextlib import AbstractAsyncContextManager-from dataclasses import dataclass-from typing import Any, Generic, cast, overload--from pydantic import JsonValue--from agenton.layers.base import ExitIntent, Layer, LifecycleState--from .schemas import CompositorSessionSnapshot, LayerSessionSnapshot-from .types import (- CompositorTransformer,- LayerPromptT,- LayerT,- LayerToolT,- LayerUserPromptT,- PromptT,- ToolT,- UserPromptT,-)---@dataclass(slots=True)-class LayerRunSlot:- """Invocation-local lifecycle, resource scope, and exit state for one layer."""-- layer: Layer[Any, Any, Any, Any, Any, Any]- lifecycle_state: LifecycleState- exit_intent: ExitIntent = ExitIntent.DELETE- active_resource_context: AbstractAsyncContextManager[None] | None = None---@dataclass(slots=True)-class CompositorRun(Generic[PromptT, ToolT, LayerPromptT, LayerToolT, UserPromptT, LayerUserPromptT]):- """Single-invocation runtime object created by ``Compositor.enter``.-- The run owns ordered ``LayerRunSlot`` objects and the fresh layers inside- them. It is the only object that exposes live layers, lifecycle state, exit- intent, and prompt/user-prompt/tool aggregation for an active invocation.- After context exit, ``session_snapshot`` contains the next cross-call state.- """-- slots: OrderedDict[str, LayerRunSlot]- prompt_transformer: CompositorTransformer[LayerPromptT, PromptT] | None = None- user_prompt_transformer: CompositorTransformer[LayerUserPromptT, UserPromptT] | None = None- tool_transformer: CompositorTransformer[LayerToolT, ToolT] | None = None- session_snapshot: CompositorSessionSnapshot | None = None-- @overload- def get_layer(self, name: str) -> Layer[Any, Any, Any, Any, Any, Any]: ...-- @overload- def get_layer(self, name: str, layer_type: type[LayerT]) -> LayerT: ...-- def get_layer(- self,- name: str,- layer_type: type[LayerT] | None = None,- ) -> Layer[Any, Any, Any, Any, Any, Any] | LayerT:- """Return a live layer by node name and optionally validate its type."""- try:- layer = self.slots[name].layer- except KeyError as e:- raise KeyError(f"Layer '{name}' is not defined in this compositor run.") from e-- if layer_type is not None and not isinstance(layer, layer_type):- raise TypeError(f"Layer '{name}' must be {layer_type.__name__}, got {type(layer).__name__}.")- return layer-- def suspend_on_exit(self) -> None:- """Request suspend behavior for every active layer when the run exits."""- for name in self.slots:- self.suspend_layer_on_exit(name)-- def delete_on_exit(self) -> None:- """Request delete behavior for every active layer when the run exits."""- for name in self.slots:- self.delete_layer_on_exit(name)-- def suspend_layer_on_exit(self, name: str) -> None:- """Request suspend behavior for one active layer when the run exits."""- self._set_layer_exit_intent(name, ExitIntent.SUSPEND)-- def delete_layer_on_exit(self, name: str) -> None:- """Request delete behavior for one active layer when the run exits."""- self._set_layer_exit_intent(name, ExitIntent.DELETE)-- def snapshot_session(self) -> CompositorSessionSnapshot:- """Snapshot non-active layer lifecycle state and runtime state from this run."""- active_layers = [name for name, slot in self.slots.items() if slot.lifecycle_state is LifecycleState.ACTIVE]- if active_layers:- names = ", ".join(active_layers)- raise RuntimeError(f"Cannot snapshot active compositor run layers: {names}.")- return CompositorSessionSnapshot(- layers=[- LayerSessionSnapshot(- name=name,- lifecycle_state=slot.lifecycle_state,- runtime_state=cast(dict[str, JsonValue], slot.layer.runtime_state.model_dump(mode="json")),- )- for name, slot in self.slots.items()- ]- )-- async def _enter_layers(self) -> None:- self._ensure_layers_can_enter()- entered_slots: list[LayerRunSlot] = []- try:- for slot in self.slots.values():- await self._enter_slot(slot)- entered_slots.append(slot)- except BaseException as enter_error:- hook_error = await self._exit_slots_reversed(entered_slots, wrapped_error=enter_error)- self.session_snapshot = self.snapshot_session()- if hook_error is not None:- raise hook_error from enter_error- raise-- async def _exit_layers(self, wrapped_error: BaseException | None = None) -> None:- hook_error = await self._exit_slots_reversed(list(self.slots.values()), wrapped_error=wrapped_error)- self.session_snapshot = self.snapshot_session()- if hook_error is not None:- raise hook_error-- async def _enter_slot(self, slot: LayerRunSlot) -> None:- resource_context = slot.layer.resource_context()- await resource_context.__aenter__()- slot.active_resource_context = resource_context- try:- if slot.lifecycle_state is LifecycleState.NEW:- slot.exit_intent = ExitIntent.DELETE- await slot.layer.on_context_create()- slot.lifecycle_state = LifecycleState.ACTIVE- return- if slot.lifecycle_state is LifecycleState.SUSPENDED:- slot.exit_intent = ExitIntent.DELETE- await slot.layer.on_context_resume()- slot.lifecycle_state = LifecycleState.ACTIVE- return- raise RuntimeError(f"Cannot enter layer from lifecycle state '{slot.lifecycle_state}'.")- except BaseException as enter_error:- resource_error = await self._exit_resource_context(slot, wrapped_error=enter_error)- if resource_error is not None:- raise resource_error from enter_error- raise-- async def _exit_slots_reversed(- self,- slots: Sequence[LayerRunSlot],- *,- wrapped_error: BaseException | None = None,- ) -> BaseException | None:- hook_error: BaseException | None = None- propagating_error = wrapped_error- for slot in reversed(slots):- if slot.lifecycle_state is not LifecycleState.ACTIVE:- continue- slot_error: BaseException | None = None- if slot.exit_intent is ExitIntent.SUSPEND:- try:- await slot.layer.on_context_suspend()- except BaseException as exc:- slot_error = exc- hook_error = hook_error or exc- finally:- slot.lifecycle_state = LifecycleState.SUSPENDED- else:- try:- await slot.layer.on_context_delete()- except BaseException as exc:- slot_error = exc- hook_error = hook_error or exc- finally:- slot.lifecycle_state = LifecycleState.CLOSED-- slot_scope_error = slot_error or propagating_error- resource_error = await self._exit_resource_context(slot, wrapped_error=slot_scope_error)- if resource_error is not None:- hook_error = hook_error or resource_error- propagating_error = resource_error- continue- propagating_error = slot_scope_error-- return hook_error-- async def _exit_resource_context(- self,- slot: LayerRunSlot,- *,- wrapped_error: BaseException | None,- ) -> BaseException | None:- resource_context = slot.active_resource_context- if resource_context is None:- return None-- slot.active_resource_context = None- exc_type = type(wrapped_error) if wrapped_error is not None else None- exc_traceback = wrapped_error.__traceback__ if wrapped_error is not None else None- try:- # Resource scopes exist for deterministic live-resource cleanup. They- # should observe the exception leaving the wrapped scope, but Agenton- # still preserves its own hook/body error propagation rules.- await resource_context.__aexit__(exc_type, wrapped_error, exc_traceback)- except BaseException as exc:- return exc- return None-- def _set_layer_exit_intent(self, name: str, intent: ExitIntent) -> None:- try:- slot = self.slots[name]- except KeyError as e:- raise KeyError(f"Layer '{name}' is not defined in this compositor run.") from e- if slot.lifecycle_state is not LifecycleState.ACTIVE:- raise RuntimeError("Layer exit intent can only be changed while the run slot is active.")- slot.exit_intent = intent-- def _ensure_layers_can_enter(self) -> None:- """Reject invalid external lifecycle states before any layer side effects."""- for name, slot in self.slots.items():- if slot.lifecycle_state is LifecycleState.ACTIVE:- raise RuntimeError(f"Layer '{name}' is already active; ACTIVE snapshots are not allowed.")- if slot.lifecycle_state is LifecycleState.CLOSED:- raise RuntimeError(f"Layer '{name}' is closed; CLOSED snapshots cannot be entered.")-- @property- def prompts(self) -> list[PromptT]:- result: list[LayerPromptT] = []- for slot in self.slots.values():- layer = slot.layer- result.extend(cast(LayerPromptT, layer.wrap_prompt(prompt)) for prompt in layer.prefix_prompts)- for slot in reversed(self.slots.values()):- layer = slot.layer- result.extend(cast(LayerPromptT, layer.wrap_prompt(prompt)) for prompt in layer.suffix_prompts)- if self.prompt_transformer is None:- return cast(list[PromptT], result)- return list(self.prompt_transformer(result))-- @property- def user_prompts(self) -> list[UserPromptT]:- result: list[LayerUserPromptT] = []- for slot in self.slots.values():- layer = slot.layer- result.extend(cast(LayerUserPromptT, layer.wrap_user_prompt(prompt)) for prompt in layer.user_prompts)- if self.user_prompt_transformer is None:- return cast(list[UserPromptT], result)- return list(self.user_prompt_transformer(result))-- @property- def tools(self) -> list[ToolT]:- result: list[LayerToolT] = []- for slot in self.slots.values():- layer = slot.layer- result.extend(cast(LayerToolT, layer.wrap_tool(tool)) for tool in layer.tools)- if self.tool_transformer is None:- return cast(list[ToolT], result)- return list(self.tool_transformer(result))diff --git a/dify-agent/src/agenton/compositor/schemas.py b/dify-agent/src/agenton/compositor/schemas.pydeleted file mode 100644index 9bf7c7da922..00000000000--- a/dify-agent/src/agenton/compositor/schemas.py+++ /dev/null@@ -1,115 +0,0 @@-"""Serializable compositor DTOs and external boundary validation.--Graph config and session snapshots are separate boundaries on purpose. Graph-config describes only reusable composition state: schema version, ordered node-names, provider type ids, dependency mappings, and metadata. Session snapshots-carry only ordered layer lifecycle state plus serializable ``runtime_state``.-Live resources acquired inside ``Layer.resource_context()`` are active-scope-only and can never appear in these DTOs.--External DTOs are revalidated even when callers pass an already-constructed-Pydantic model instance. These models are mutable, so dumping and validating-again prevents post-construction mutations from bypassing compositor entry-validators. ``LifecycleState.ACTIVE`` remains internal-only and is rejected in-external session snapshots.-"""--from collections.abc import Mapping--from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator--from agenton.layers.base import LifecycleState--type _ConfigModelValue[ModelT: BaseModel] = ModelT | JsonValue | str | bytes---def _validate_config_model_input[ModelT: BaseModel](- model_type: type[ModelT],- value: _ConfigModelValue[ModelT] | Mapping[str, object],-) -> ModelT:- """Validate an external DTO boundary, including existing model instances.-- Pydantic models in this package are generally mutable and do not all enable- assignment validation. Revalidating existing instances through their dumped- data prevents post-construction mutations from bypassing config or snapshot- validators at compositor entry boundaries.- """- if isinstance(value, BaseModel):- return model_type.model_validate(value.model_dump(mode="python", warnings=False))- if isinstance(value, str | bytes):- return model_type.model_validate_json(value)-- return model_type.model_validate(value)---class LayerNodeConfig(BaseModel):- """Serializable config for one provider-backed layer graph node.-- Nodes intentionally contain no runtime state and no per-call layer config.- Runtime state belongs to session snapshots; layer config belongs to- ``Compositor.enter(configs=...)`` keyed by node name.- """-- name: str- type: str- deps: Mapping[str, str] = Field(default_factory=dict)- metadata: Mapping[str, JsonValue] = Field(default_factory=dict)-- model_config = ConfigDict(extra="forbid")---class CompositorConfig(BaseModel):- """Serializable config for constructing a reusable compositor graph plan."""-- schema_version: int = 1- layers: list[LayerNodeConfig]-- model_config = ConfigDict(extra="forbid")---type CompositorConfigValue = _ConfigModelValue[CompositorConfig] | Mapping[str, object]---def _validate_compositor_config_input(value: CompositorConfigValue) -> CompositorConfig:- """Validate external graph config input for ``Compositor.from_config``."""- return _validate_config_model_input(CompositorConfig, value)---class LayerSessionSnapshot(BaseModel):- """Serializable snapshot for one layer's state-only invocation data.-- ``runtime_state`` is the only snapshotted mutable layer data. ``ACTIVE`` is- rejected here because a running layer cannot be represented safely outside- the active compositor entry.- """-- name: str- lifecycle_state: LifecycleState- runtime_state: dict[str, JsonValue]-- model_config = ConfigDict(extra="forbid")-- @field_validator("lifecycle_state")- @classmethod- def _reject_active_lifecycle(cls, value: LifecycleState) -> LifecycleState:- if value is LifecycleState.ACTIVE:- raise ValueError("LifecycleState.ACTIVE is internal-only and cannot appear in session snapshots.")- return value---class CompositorSessionSnapshot(BaseModel):- """Serializable compositor session snapshot.-- Snapshots include ordered layer lifecycle state and serializable runtime- state only. Live resources from ``Layer.resource_context()``, handles,- dependencies, prompts, tools, and config are outside Agenton snapshots and- are never captured here.- """-- schema_version: int = 1- layers: list[LayerSessionSnapshot]-- model_config = ConfigDict(extra="forbid")---type CompositorSessionSnapshotValue = _ConfigModelValue[CompositorSessionSnapshot] | Mapping[str, object]diff --git a/dify-agent/src/agenton/compositor/types.py b/dify-agent/src/agenton/compositor/types.pydeleted file mode 100644index 984dc2014ea..00000000000--- a/dify-agent/src/agenton/compositor/types.py+++ /dev/null@@ -1,46 +0,0 @@-"""Shared generic compositor types.--This module contains the generic prompt/tool type variables and transformer-contracts shared by compositor runtime and orchestration modules. It depends-only on layer base/types modules so higher-level compositor modules can import-it without creating cycles.-"""--from collections.abc import Callable, Sequence-from typing import Any, TypedDict--from typing_extensions import TypeVar--from agenton.layers.base import Layer-from agenton.layers.types import AllPromptTypes, AllToolTypes, AllUserPromptTypes--PromptT = TypeVar("PromptT", default=AllPromptTypes)-ToolT = TypeVar("ToolT", default=AllToolTypes)-LayerPromptT = TypeVar("LayerPromptT", default=AllPromptTypes)-LayerToolT = TypeVar("LayerToolT", default=AllToolTypes)-UserPromptT = TypeVar("UserPromptT", default=AllUserPromptTypes)-LayerUserPromptT = TypeVar("LayerUserPromptT", default=AllUserPromptTypes)-LayerT = TypeVar("LayerT", bound=Layer[Any, Any, Any, Any, Any, Any])---type CompositorTransformer[InputT, OutputT] = Callable[[Sequence[InputT]], Sequence[OutputT]]---class CompositorTransformerKwargs[- PromptT,- ToolT,- LayerPromptT,- LayerToolT,- UserPromptT,- LayerUserPromptT,-](TypedDict):- """Keyword arguments that install prompt, user prompt, and tool transformers.-- The required keys intentionally mirror the keyword-only transformer- parameters exposed by ``Compositor.__init__`` and- ``Compositor.from_config(...)``.- """-- prompt_transformer: CompositorTransformer[LayerPromptT, PromptT]- user_prompt_transformer: CompositorTransformer[LayerUserPromptT, UserPromptT]- tool_transformer: CompositorTransformer[LayerToolT, ToolT]diff --git a/dify-agent/src/agenton/layers/__init__.py b/dify-agent/src/agenton/layers/__init__.pydeleted file mode 100644index bc02a13f0cb..00000000000--- a/dify-agent/src/agenton/layers/__init__.py+++ /dev/null@@ -1,66 +0,0 @@-"""Layer base classes and typed layer families.--``agenton.layers.base`` owns the framework-neutral ``Layer`` abstraction.-``agenton.layers.types`` binds the prompt/tool generic slots to specific layer-families while keeping concrete reusable layers in ``agenton_collections``.-"""--from agenton.layers.base import (- EmptyLayerConfig,- EmptyRuntimeState,- ExitIntent,- Layer,- LayerConfig,- LayerConfigValue,- LayerDeps,- LifecycleState,- NoLayerDeps,-)-from agenton.layers.types import (- AllPromptTypes,- AllToolTypes,- AllUserPromptTypes,- PlainLayer,- PlainPrompt,- PlainPromptType,- PlainTool,- PlainToolType,- PlainUserPrompt,- PlainUserPromptType,- PydanticAILayer,- PydanticAIPrompt,- PydanticAIPromptType,- PydanticAITool,- PydanticAIToolType,- PydanticAIUserPrompt,- PydanticAIUserPromptType,-)--__all__ = [- "AllPromptTypes",- "AllToolTypes",- "AllUserPromptTypes",- "Layer",- "LayerConfig",- "LayerConfigValue",- "LayerDeps",- "LifecycleState",- "ExitIntent",- "EmptyLayerConfig",- "EmptyRuntimeState",- "NoLayerDeps",- "PlainLayer",- "PlainPrompt",- "PlainPromptType",- "PlainUserPrompt",- "PlainUserPromptType",- "PlainTool",- "PlainToolType",- "PydanticAILayer",- "PydanticAIPrompt",- "PydanticAIPromptType",- "PydanticAIUserPrompt",- "PydanticAIUserPromptType",- "PydanticAITool",- "PydanticAIToolType",-]diff --git a/dify-agent/src/agenton/layers/base.py b/dify-agent/src/agenton/layers/base.pydeleted file mode 100644index d8f8035c1cd..00000000000--- a/dify-agent/src/agenton/layers/base.py+++ /dev/null@@ -1,562 +0,0 @@-"""Invocation-scoped core layer abstractions and typed dependency binding.--Agenton core deliberately manages four concerns: stateless layer graph-composition, serializable ``runtime_state`` lifecycle, per-active-invocation-resource scopes, and session snapshots. Live resources remain layer-owned:-Agenton may enter ``Layer.resource_context()`` for the active scope, but it-never serializes or snapshots clients, process handles, cleanup stacks, or any-other non-serializable runtime object.--Layers declare their dependency shape with-``Layer[DepsT, PromptT, UserPromptT, ToolT, ConfigT, RuntimeStateT]``.-``DepsT`` must be a ``LayerDeps`` subclass whose annotated members are concrete-``Layer`` subclasses or modern optional dependencies such as ``SomeLayer | None``.-Dependencies are direct layer instance relationships bound onto ``self.deps``-for one compositor invocation; there is no dependency-control lookup API in the-core.--``LayerConfig`` is the DTO base for config schemas accepted by layer providers.-The provider validates raw node-name keyed configs with a layer's-``config_type`` before constructing the layer and assigning ``self.config``.-``runtime_state_type`` is the only mutable schema managed by Agenton and the only-per-layer data included in session snapshots. The base class infers-``deps_type``, ``config_type``, and ``runtime_state_type`` from generic bases-when possible, while still allowing subclasses to set them explicitly for-unusual inheritance patterns.--``Layer`` is an invocation-scoped business object. It owns ``config``, direct-``deps``, serializable ``runtime_state``, prompt/tool authoring surfaces, and-any live resource fields managed by ``resource_context()``. It does not own-lifecycle state, exit intent, graph owner tokens, or entry stacks.-``CompositorRun`` owns lifecycle state and exit intent for one entry and-orchestrates entering and exiting each layer's resource scope. ``SessionSnapshot``-objects are the only supported cross-call state carrier.--Lifecycle hooks are no-argument business hooks on the layer instance:-``on_context_create/resume/suspend/delete(self)``. They should read dependencies-from ``self.deps`` and read or mutate serializable invocation state through-``self.runtime_state``. ``resource_context(self)`` is the symmetric active-scope-API for live resources. Agenton enters it before ``on_context_create`` or-``on_context_resume`` and exits it after ``on_context_suspend`` or-``on_context_delete``. Create-versus-resume differences stay in the business-hooks; ``resource_context`` should manage only live resource setup and cleanup.-Agenton marks a slot ``ACTIVE`` only after ``on_context_create`` or-``on_context_resume`` returns successfully. If either enter hook raises, normal-``on_context_suspend``/``on_context_delete`` hooks do not run for that failed-attempt. Enter hooks therefore own any business compensation or idempotency for-partial side effects, while Agenton guarantees only ``resource_context()``-cleanup, not hook rollback.--``Layer`` is framework-neutral over system prompt, user prompt, and tool item-types. The native ``prefix_prompts``, ``suffix_prompts``, ``user_prompts``, and-``tools`` properties are the layer authoring surface. ``wrap_prompt``,-``wrap_user_prompt``, and ``wrap_tool`` are the compositor aggregation surface;-typed families such as ``agenton.layers.types.PlainLayer`` implement them to tag-native values without changing layer implementations.-"""--from abc import ABC, abstractmethod-from collections.abc import Mapping, Sequence-from contextlib import asynccontextmanager-from dataclasses import dataclass-from enum import StrEnum-from types import UnionType-from typing import (- Any,- AsyncIterator,- ClassVar,- Generic,- Union,- cast,- get_args,- get_origin,- get_type_hints,-)--from pydantic import BaseModel, ConfigDict, JsonValue, SerializeAsAny-from typing_extensions import Self, TypeVar---_DepsT = TypeVar("_DepsT", bound="LayerDeps")-_PromptT = TypeVar("_PromptT")-_UserPromptT = TypeVar("_UserPromptT")-_ToolT = TypeVar("_ToolT")---class LayerConfig(BaseModel):- """Base DTO for serializable layer configuration.-- Layer providers validate raw config values with concrete ``LayerConfig``- subclasses before constructing a layer for one invocation. Serializable- compositor graph config references layer type ids and node metadata only;- per-call config travels through ``Compositor.enter(configs=...)``.- """-- model_config = ConfigDict(extra="forbid")---type LayerConfigValue = JsonValue | SerializeAsAny[LayerConfig]---_ConfigT = TypeVar("_ConfigT", bound=LayerConfig, default="EmptyLayerConfig")-_RuntimeStateT = TypeVar("_RuntimeStateT", bound=BaseModel, default="EmptyRuntimeState")---class LayerDeps:- """Typed dependency container for a layer.-- Subclasses declare dependency members with annotations. Every annotated- member must be a Layer subclass or ``LayerSubclass | None``. Optional deps- are always assigned as attributes; missing optional values become ``None``.- """-- def __init__(self, **deps: "Layer[Any, Any, Any, Any, Any, Any] | None") -> None:- dep_specs = _get_dep_specs(type(self))- missing_names = {name for name, spec in dep_specs.items() if not spec.optional} - deps.keys()- if missing_names:- names = ", ".join(sorted(missing_names))- raise ValueError(f"Missing layer dependencies: {names}.")-- unknown_names = deps.keys() - dep_specs.keys()- if unknown_names:- names = ", ".join(sorted(unknown_names))- raise ValueError(f"Unknown layer dependencies: {names}.")-- for name, spec in dep_specs.items():- value = deps.get(name)- if value is None:- if spec.optional:- setattr(self, name, None)- continue- raise ValueError(f"Dependency '{name}' is required but not provided.")-- if not isinstance(value, spec.layer_type):- raise TypeError(- f"Dependency '{name}' should be of type '{spec.layer_type.__name__}', "- f"but got type '{type(value).__name__}'."- )- setattr(self, name, value)---class NoLayerDeps(LayerDeps):- """Dependency container for layers that do not require other layers."""---class EmptyLayerConfig(LayerConfig):- """Default serializable config schema for layers without config."""-- model_config = ConfigDict(extra="forbid")---class EmptyRuntimeState(BaseModel):- """Default serializable invocation runtime state schema."""-- model_config = ConfigDict(extra="forbid", validate_assignment=True)---class LifecycleState(StrEnum):- """Lifecycle state for one run slot.-- ``ACTIVE`` is internal-only. It is used while an invocation is running and- must never appear in external session snapshots or hydrated input.- """-- NEW = "new"- ACTIVE = "active"- SUSPENDED = "suspended"- CLOSED = "closed"---class ExitIntent(StrEnum):- """Run-slot exit behavior requested during active invocation."""-- DELETE = "delete"- SUSPEND = "suspend"---@dataclass(frozen=True, slots=True)-class LayerDepSpec:- """Runtime dependency specification derived from a deps annotation."""-- layer_type: type["Layer[Any, Any, Any, Any, Any, Any]"]- optional: bool = False---class Layer(- ABC,- Generic[_DepsT, _PromptT, _UserPromptT, _ToolT, _ConfigT, _RuntimeStateT],-):- """Framework-neutral base class for prompt/tool layers.-- A layer instance is invocation-scoped mutable business state, not a reusable- cross-session definition. ``CompositorRun`` creates fresh instances through- layer providers, assigns validated ``config``, binds direct dependency layer- instances to ``deps``, hydrates ``runtime_state`` from an optional session- snapshot, and then runs no-argument lifecycle hooks. The run owns lifecycle- state and exit intent; layers never expose a public entry context manager.-- ``runtime_state`` is the only mutable data Agenton snapshots across calls.- Live resources belong on the layer instance itself and should be acquired in- ``resource_context()``. Agenton keeps that resource scope active while the- corresponding enter hook, run body, and exit hook execute, then tears it- down deterministically even when later hooks or the body fail.- """-- deps_type: type[_DepsT]- config: _ConfigT- deps: _DepsT- runtime_state: _RuntimeStateT- type_id: ClassVar[str | None] = None- config_type: ClassVar[type[LayerConfig]] = EmptyLayerConfig- runtime_state_type: ClassVar[type[BaseModel]] = EmptyRuntimeState-- def __new__(cls, *args: object, **kwargs: object) -> Self:- instance = cast(Self, super().__new__(cls))- runtime_state_type = getattr(cls, "runtime_state_type", None)- if isinstance(runtime_state_type, type) and issubclass(runtime_state_type, BaseModel):- instance.runtime_state = cast(Any, runtime_state_type.model_validate({}))- return instance-- def __init_subclass__(cls) -> None:- super().__init_subclass__()- is_generic_template = _is_generic_layer_template(cls)- deps_type = cls.__dict__.get("deps_type")- if deps_type is None:- deps_type = _infer_deps_type(cls) or getattr(cls, "deps_type", None)- if deps_type is None and is_generic_template:- return- if deps_type is not None:- cls.deps_type = cast(type[_DepsT], deps_type)- if deps_type is None:- raise TypeError(f"{cls.__name__} must define deps_type or inherit from Layer[DepsT].")- if not isinstance(deps_type, type) or not issubclass(deps_type, LayerDeps):- raise TypeError(f"{cls.__name__}.deps_type must be a LayerDeps subclass.")- _get_dep_specs(deps_type)- _init_config_type(cls, _infer_config_type(cls))- _init_schema_type(- cls,- "runtime_state_type",- _infer_schema_type(cls, 5, "runtime_state_type"),- EmptyRuntimeState,- )-- @classmethod- def from_config(cls: type[Self], config: _ConfigT) -> Self:- """Create a layer from schema-validated serialized config.-- ``LayerProvider.from_layer_type`` validates raw config with- ``config_type`` before calling this method. Layers without config use the- default no-argument construction path. Layers with a concrete config- schema should override this method and consume the typed Pydantic model.- """- if cls.config_type is not EmptyLayerConfig:- raise TypeError(f"{cls.__name__} cannot be created from config; override from_config or use a provider.")- EmptyLayerConfig.model_validate(config)- try:- return cast(Self, cls())- except TypeError as e:- raise TypeError(f"{cls.__name__} cannot be created from empty config; use a custom provider.") from e-- @classmethod- def dependency_names(cls) -> frozenset[str]:- """Return dependency field names declared by this layer's deps schema."""- return frozenset(_get_dep_specs(cls.deps_type))-- def bind_deps(self, deps: Mapping[str, "Layer[Any, Any, Any, Any, Any, Any] | None"]) -> None:- """Bind this layer's declared dependencies from a name-to-layer mapping.-- The mapping may include more layers than the declared dependency fields.- Only names declared by ``deps_type`` are selected and validated. Missing- optional deps are bound as ``None``. Bound values are direct layer- instances for this invocation graph.- """- resolved_deps: dict[str, Layer[Any, Any, Any, Any, Any, Any] | None] = {}- for name, spec in _get_dep_specs(self.deps_type).items():- if name not in deps:- if spec.optional:- resolved_deps[name] = None- continue- raise ValueError(f"Dependency '{name}' is required for layer '{type(self).__name__}' but not provided.")- resolved_deps[name] = deps[name]- self.deps = self.deps_type(**resolved_deps)-- @asynccontextmanager- async def resource_context(self) -> AsyncIterator[None]:- """Wrap one active invocation with live non-serializable resources.-- Agenton enters this no-argument context before ``on_context_create`` or- ``on_context_resume`` and exits it after ``on_context_suspend`` or- ``on_context_delete``. Use it for live clients, process handles, or- other non-serializable objects stored on ``self``. Keep create-versus-- resume business differences in the corresponding lifecycle hooks.- """- yield-- async def on_context_create(self) -> None:- """Run when the run slot enters from ``LifecycleState.NEW``.-- ``resource_context()`` is already active for this layer when this hook- runs. If this hook raises, the layer never becomes ``ACTIVE`` and no- normal ``on_context_delete()`` hook runs for that failed enter attempt.- """-- async def on_context_delete(self) -> None:- """Run when the run slot exits with ``ExitIntent.DELETE``.-- ``resource_context()`` remains active while this hook runs.- """-- async def on_context_suspend(self) -> None:- """Run when the run slot exits with ``ExitIntent.SUSPEND``.-- ``resource_context()`` remains active while this hook runs.- """-- async def on_context_resume(self) -> None:- """Run when the run slot enters from ``LifecycleState.SUSPENDED``.-- ``resource_context()`` is already active for this layer when this hook- runs. If this hook raises, the layer never becomes ``ACTIVE`` and no- normal ``on_context_suspend()`` or ``on_context_delete()`` hook runs for- that failed resume attempt.- """-- @property- def prefix_prompts(self) -> Sequence[_PromptT]:- return []-- @property- def suffix_prompts(self) -> Sequence[_PromptT]:- return []-- @property- def user_prompts(self) -> Sequence[_UserPromptT]:- return []-- @property- def tools(self) -> Sequence[_ToolT]:- return []-- @abstractmethod- def wrap_prompt(self, prompt: _PromptT) -> object:- """Wrap a native prompt item for run-level aggregation."""- raise NotImplementedError-- @abstractmethod- def wrap_user_prompt(self, prompt: _UserPromptT) -> object:- """Wrap a native user prompt item for run-level aggregation."""- raise NotImplementedError-- @abstractmethod- def wrap_tool(self, tool: _ToolT) -> object:- """Wrap a native tool item for run-level aggregation."""- raise NotImplementedError---def _get_dep_specs(deps_type: type[LayerDeps]) -> dict[str, LayerDepSpec]:- dep_specs: dict[str, LayerDepSpec] = {}- for name, annotation in get_type_hints(deps_type).items():- spec = _as_dep_spec(annotation)- if spec is None:- raise TypeError(- f"{deps_type.__name__}.{name} must be annotated with a Layer subclass or Layer subclass | None."- )- dep_specs[name] = spec- return dep_specs---def _as_dep_spec(annotation: object) -> LayerDepSpec | None:- origin = get_origin(annotation)- args = get_args(annotation)- if origin in (UnionType, Union) and len(args) == 2 and type(None) in args:- layer_annotation = args[0] if args[1] is type(None) else args[1]- layer_type = _as_layer_type(layer_annotation)- if layer_type is None:- return None- return LayerDepSpec(layer_type=layer_type, optional=True)-- layer_type = _as_layer_type(annotation)- if layer_type is None:- return None- return LayerDepSpec(layer_type=layer_type)---def _as_layer_type(annotation: object) -> type[Layer[Any, Any, Any, Any, Any, Any]] | None:- runtime_type = get_origin(annotation) or annotation- if isinstance(runtime_type, type) and issubclass(runtime_type, Layer):- return cast(type[Layer[Any, Any, Any, Any, Any, Any]], runtime_type)- return None---def _infer_deps_type(layer_type: type[Layer[Any, Any, Any, Any, Any, Any]]) -> type[LayerDeps] | None:- inferred = _infer_layer_generic_arg(layer_type, 0, {})- if inferred is None:- return None- return _as_deps_type(inferred)---def _infer_schema_type(- layer_type: type[Layer[Any, Any, Any, Any, Any, Any]],- index: int,- attr_name: str,-) -> type[BaseModel] | None:- inferred = _infer_schema_generic_arg(layer_type, attr_name, {}) or _infer_layer_generic_arg(layer_type, index, {})- if inferred is None:- return None- schema_type = _as_model_type(inferred)- if schema_type is None:- raise TypeError(f"{layer_type.__name__}.{attr_name} must be a Pydantic BaseModel subclass.")- return schema_type---def _infer_config_type(layer_type: type[Layer[Any, Any, Any, Any, Any, Any]]) -> type[LayerConfig] | None:- inferred = _infer_schema_generic_arg(layer_type, "config_type", {}) or _infer_layer_generic_arg(layer_type, 4, {})- if inferred is None:- return None- config_type = _as_config_type(inferred)- if config_type is None:- raise TypeError(f"{layer_type.__name__}.config_type must be a LayerConfig subclass.")- return config_type---def _infer_schema_generic_arg(- layer_type: type[Layer[Any, Any, Any, Any, Any, Any]],- attr_name: str,- substitutions: Mapping[object, object],-) -> object | None:- """Infer schema type arguments exposed by typed layer family bases."""- expected_names = {- "config_type": {"ConfigT", "_ConfigT"},- "runtime_state_type": {"RuntimeStateT", "_RuntimeStateT"},- }[attr_name]- for base in getattr(layer_type, "__orig_bases__", ()):- origin = get_origin(base) or base- args = tuple(_substitute_type(arg, substitutions) for arg in get_args(base))- if not isinstance(origin, type) or not issubclass(origin, Layer):- continue-- params = _generic_params(origin)- for param, arg in zip(params, args):- if getattr(param, "__name__", None) in expected_names:- return arg-- next_substitutions = dict(substitutions)- next_substitutions.update(_generic_arg_substitutions(origin, args))- inferred = _infer_schema_generic_arg(origin, attr_name, next_substitutions)- if inferred is not None:- return inferred- return None---def _infer_layer_generic_arg(- layer_type: type[Layer[Any, Any, Any, Any, Any, Any]],- index: int,- substitutions: Mapping[object, object],-) -> object | None:- """Infer one concrete ``Layer`` generic argument through inheritance.-- This walks through intermediate generic base classes so subclasses can omit- explicit class attributes in common cases such as ``class X(Base[YDeps])``.- """- for base in getattr(layer_type, "__orig_bases__", ()):- origin = get_origin(base) or base- args = tuple(_substitute_type(arg, substitutions) for arg in get_args(base))- if origin is Layer:- if len(args) <= index:- continue- return args[index]-- if not isinstance(origin, type) or not issubclass(origin, Layer):- continue-- next_substitutions = dict(substitutions)- next_substitutions.update(_generic_arg_substitutions(origin, args))- inferred = _infer_layer_generic_arg(origin, index, next_substitutions)- if inferred is not None:- return inferred- return None---def _init_schema_type(- layer_type: type[Layer[Any, Any, Any, Any, Any, Any]],- attr_name: str,- inferred_schema_type: type[BaseModel] | None,- default_schema_type: type[BaseModel],-) -> None:- schema_type = layer_type.__dict__.get(attr_name)- if schema_type is None:- schema_type = inferred_schema_type or getattr(layer_type, attr_name, default_schema_type)- setattr(layer_type, attr_name, schema_type)- if not isinstance(schema_type, type) or not issubclass(schema_type, BaseModel):- raise TypeError(f"{layer_type.__name__}.{attr_name} must be a Pydantic BaseModel subclass.")---def _init_config_type(- layer_type: type[Layer[Any, Any, Any, Any, Any, Any]],- inferred_config_type: type[LayerConfig] | None,-) -> None:- config_type = layer_type.__dict__.get("config_type")- if config_type is None:- config_type = inferred_config_type or getattr(layer_type, "config_type", EmptyLayerConfig)- setattr(layer_type, "config_type", config_type)- if not isinstance(config_type, type) or not issubclass(config_type, LayerConfig):- raise TypeError(f"{layer_type.__name__}.config_type must be a LayerConfig subclass.")---def _substitute_type(value: object, substitutions: Mapping[object, object]) -> object:- if value in substitutions:- return substitutions[value]-- origin = get_origin(value)- if origin is None:- return value-- args = get_args(value)- if not args:- return value-- substituted_args = tuple(_substitute_type(arg, substitutions) for arg in args)- if substituted_args == args:- return value-- try:- return origin[substituted_args]- except TypeError:- return value---def _generic_arg_substitutions(origin: type[Any], args: Sequence[object]) -> dict[object, object]:- params = _generic_params(origin)- return dict(zip(params, args))---def _generic_params(origin: type[Any]) -> Sequence[object]:- params = getattr(origin, "__type_params__", ())- if not params:- params = getattr(origin, "__parameters__", ())- return params---def _as_deps_type(value: object) -> type[LayerDeps] | None:- runtime_type = get_origin(value) or value- if isinstance(runtime_type, type) and issubclass(runtime_type, LayerDeps):- return runtime_type- return None---def _as_model_type(value: object) -> type[BaseModel] | None:- runtime_type = get_origin(value) or value- if isinstance(runtime_type, type) and issubclass(runtime_type, BaseModel):- return runtime_type- return None---def _as_config_type(value: object) -> type[LayerConfig] | None:- runtime_type = get_origin(value) or value- if isinstance(runtime_type, type) and issubclass(runtime_type, LayerConfig):- return runtime_type- return None---def _is_generic_layer_template(layer_type: type[Layer[Any, Any, Any, Any, Any, Any]]) -> bool:- return bool(getattr(layer_type, "__type_params__", ())) or bool(getattr(layer_type, "__parameters__", ()))diff --git a/dify-agent/src/agenton/layers/types.py b/dify-agent/src/agenton/layers/types.pydeleted file mode 100644index e6133dcd55f..00000000000--- a/dify-agent/src/agenton/layers/types.py+++ /dev/null@@ -1,184 +0,0 @@-"""Typed layer family definitions.--``Layer`` itself is framework-neutral. This module defines typed layer families-that bind its system prompt, user prompt, and tool generic slots to concrete-contracts, such as ordinary strings with plain callable tools or pydantic-ai-prompt/tool shapes. The families keep the trailing schema generic slots open so-concrete layers can have ``config_type`` and ``runtime_state_type`` inferred from-type arguments instead of repeated class attributes. Config schemas use-``LayerConfig`` so they can also be embedded as-typed DTOs in serializable compositor config. Agenton core is state-only:-typed layer families do not expose runtime handle schemas or resource ownership.-Tagged aggregate aliases cover code paths that can accept any supported-prompt/tool family without changing the plain and pydantic-ai layer contracts.-Pydantic-ai names are imported for static analysis only, so ``agenton`` can be-imported without loading that optional integration at runtime.-Concrete reusable layers live under ``agenton_collections``.-"""--from __future__ import annotations--from collections.abc import Callable-from dataclasses import dataclass, field-from typing import TYPE_CHECKING, Any, Generic, Literal--from typing_extensions import TypeVar, final, override--if TYPE_CHECKING:- from pydantic_ai import Tool- from pydantic_ai.messages import UserContent- from pydantic_ai.tools import SystemPromptFunc--from pydantic import BaseModel--from agenton.layers.base import EmptyLayerConfig, EmptyRuntimeState, Layer, LayerConfig, LayerDeps--type PlainPrompt = str-type PlainUserPrompt = str-type PlainTool = Callable[..., Any]---type PydanticAIPrompt[AgentDepsT] = SystemPromptFunc[AgentDepsT]-type PydanticAIUserPrompt = UserContent-type PydanticAITool[AgentDepsT] = Tool[AgentDepsT]---@dataclass(frozen=True, slots=True)-class PlainPromptType:- """Tagged plain prompt item for aggregate prompt transformations."""-- value: PlainPrompt- kind: Literal["plain"] = field(default="plain", init=False)---@dataclass(frozen=True, slots=True)-class PlainToolType:- """Tagged plain tool item for aggregate tool transformations."""-- value: PlainTool- kind: Literal["plain"] = field(default="plain", init=False)---@dataclass(frozen=True, slots=True)-class PlainUserPromptType:- """Tagged plain user prompt item for aggregate user prompt transformations."""-- value: PlainUserPrompt- kind: Literal["plain"] = field(default="plain", init=False)---@dataclass(frozen=True, slots=True)-class PydanticAIPromptType[AgentDepsT]:- """Tagged pydantic-ai prompt item for aggregate prompt transformations."""-- value: PydanticAIPrompt[AgentDepsT]- kind: Literal["pydantic_ai"] = field(default="pydantic_ai", init=False)---@dataclass(frozen=True, slots=True)-class PydanticAIUserPromptType:- """Tagged pydantic-ai user prompt item for aggregate user prompts."""-- value: PydanticAIUserPrompt- kind: Literal["pydantic_ai"] = field(default="pydantic_ai", init=False)---@dataclass(frozen=True, slots=True)-class PydanticAIToolType[AgentDepsT]:- """Tagged pydantic-ai tool item for aggregate tool transformations."""-- value: PydanticAITool[AgentDepsT]- kind: Literal["pydantic_ai"] = field(default="pydantic_ai", init=False)---type AllPromptTypes = PlainPromptType | PydanticAIPromptType[Any]-type AllUserPromptTypes = PlainUserPromptType | PydanticAIUserPromptType-type AllToolTypes = PlainToolType | PydanticAIToolType[Any]---_DepsT = TypeVar("_DepsT", bound=LayerDeps)-_ConfigT = TypeVar("_ConfigT", bound=LayerConfig, default=EmptyLayerConfig)-_RuntimeStateT = TypeVar("_RuntimeStateT", bound=BaseModel, default=EmptyRuntimeState)-_AgentDepsT = TypeVar("_AgentDepsT")---class PlainLayer(- Generic[_DepsT, _ConfigT, _RuntimeStateT],- Layer[- _DepsT,- PlainPrompt,- PlainUserPrompt,- PlainTool,- _ConfigT,- _RuntimeStateT,- ],-):- """Layer base for ordinary string prompts and plain-callable tools."""-- @final- @override- def wrap_prompt(self, prompt: PlainPrompt) -> PlainPromptType:- return PlainPromptType(prompt)-- @final- @override- def wrap_user_prompt(self, prompt: PlainUserPrompt) -> PlainUserPromptType:- return PlainUserPromptType(prompt)-- @final- @override- def wrap_tool(self, tool: PlainTool) -> PlainToolType:- return PlainToolType(tool)---class PydanticAILayer(- Generic[_DepsT, _AgentDepsT, _ConfigT, _RuntimeStateT],- Layer[- _DepsT,- PydanticAIPrompt[_AgentDepsT],- PydanticAIUserPrompt,- PydanticAITool[_AgentDepsT],- _ConfigT,- _RuntimeStateT,- ],-):- """Layer base for pydantic-ai prompt and tool adapters."""-- @final- @override- def wrap_prompt(- self,- prompt: PydanticAIPrompt[_AgentDepsT],- ) -> PydanticAIPromptType[_AgentDepsT]:- return PydanticAIPromptType(prompt)-- @final- @override- def wrap_user_prompt(self, prompt: PydanticAIUserPrompt) -> PydanticAIUserPromptType:- return PydanticAIUserPromptType(prompt)-- @final- @override- def wrap_tool(self, tool: PydanticAITool[_AgentDepsT]) -> PydanticAIToolType[_AgentDepsT]:- return PydanticAIToolType(tool)---__all__ = [- "AllPromptTypes",- "AllUserPromptTypes",- "AllToolTypes",- "PlainLayer",- "PlainPrompt",- "PlainPromptType",- "PlainUserPrompt",- "PlainUserPromptType",- "PlainTool",- "PlainToolType",- "PydanticAILayer",- "PydanticAIPrompt",- "PydanticAIPromptType",- "PydanticAIUserPrompt",- "PydanticAIUserPromptType",- "PydanticAITool",- "PydanticAIToolType",-]diff --git a/dify-agent/src/agenton_collections/__init__.py b/dify-agent/src/agenton_collections/__init__.pydeleted file mode 100644index b4b52de993b..00000000000--- a/dify-agent/src/agenton_collections/__init__.py+++ /dev/null@@ -1,52 +0,0 @@-"""Convenience exports for reusable layer implementations.--Concrete collection layers live in family subpackages such as-``agenton_collections.layers.plain`` and-``agenton_collections.layers.pydantic_ai``. The package root keeps short-client-safe imports for common plain layers while requiring explicit submodule-imports for pydantic-ai bridge implementations.-"""--from agenton.layers.types import (- AllPromptTypes,- AllToolTypes,- PlainLayer,- PlainPrompt,- PlainPromptType,- PlainTool,- PlainToolType,- PydanticAILayer,- PydanticAIPrompt,- PydanticAIPromptType,- PydanticAITool,- PydanticAIToolType,-)-from agenton_collections.layers.plain import (- DynamicToolsLayer,- DynamicToolsLayerDeps,- ObjectLayer,- PromptLayer,- ToolsLayer,- with_object,-)--__all__ = [- "AllPromptTypes",- "AllToolTypes",- "DynamicToolsLayer",- "DynamicToolsLayerDeps",- "ObjectLayer",- "PlainLayer",- "PlainPrompt",- "PlainPromptType",- "PlainTool",- "PlainToolType",- "PromptLayer",- "PydanticAILayer",- "PydanticAIPrompt",- "PydanticAIPromptType",- "PydanticAITool",- "PydanticAIToolType",- "ToolsLayer",- "with_object",-]diff --git a/dify-agent/src/agenton_collections/layers/plain/__init__.py b/dify-agent/src/agenton_collections/layers/plain/__init__.pydeleted file mode 100644index a3e20cc204f..00000000000--- a/dify-agent/src/agenton_collections/layers/plain/__init__.py+++ /dev/null@@ -1,25 +0,0 @@-"""Reusable collection layers for the plain layer family."""--from agenton_collections.layers.plain.basic import (- PLAIN_PROMPT_LAYER_TYPE_ID,- ObjectLayer,- PromptLayer,- PromptLayerConfig,- ToolsLayer,-)-from agenton_collections.layers.plain.dynamic_tools import (- DynamicToolsLayer,- DynamicToolsLayerDeps,- with_object,-)--__all__ = [- "DynamicToolsLayer",- "DynamicToolsLayerDeps",- "ObjectLayer",- "PLAIN_PROMPT_LAYER_TYPE_ID",- "PromptLayer",- "PromptLayerConfig",- "ToolsLayer",- "with_object",-]diff --git a/dify-agent/src/agenton_collections/layers/plain/basic.py b/dify-agent/src/agenton_collections/layers/plain/basic.pydeleted file mode 100644index aeefd1abf8f..00000000000--- a/dify-agent/src/agenton_collections/layers/plain/basic.py+++ /dev/null@@ -1,103 +0,0 @@-"""Basic ready-to-compose layers for common plain use cases.--These layers are small concrete implementations built on-``agenton.layers.types``. They intentionally stay free of compositor graph-construction so they can be reused from config, examples, and higher-level-dynamic layers.-"""--from collections.abc import Callable, Sequence-from dataclasses import dataclass, field-from typing import Any, Final--from pydantic import ConfigDict, Field-from typing_extensions import Self, override--from agenton.layers.base import LayerConfig, NoLayerDeps-from agenton.layers.types import PlainLayer---PLAIN_PROMPT_LAYER_TYPE_ID: Final[str] = "plain.prompt"---class PromptLayerConfig(LayerConfig):- """Serializable config schema for ``PromptLayer``."""-- prefix: list[str] | str = Field(default_factory=list)- user: list[str] | str = Field(default_factory=list)- suffix: list[str] | str = Field(default_factory=list)-- model_config = ConfigDict(extra="forbid")---@dataclass-class ObjectLayer[ObjectT](PlainLayer[NoLayerDeps]):- """Layer that stores one typed object for downstream dependencies.-- Object layers are instance-only because arbitrary Python objects are not- serializable graph config. Add them with a custom ``LayerProvider`` factory- that creates a fresh object layer for each compositor run.- """-- value: ObjectT---@dataclass-class PromptLayer(PlainLayer[NoLayerDeps, PromptLayerConfig]):- """Layer that contributes configured system and user prompt fragments."""-- type_id = PLAIN_PROMPT_LAYER_TYPE_ID-- prefix: list[str] | str = field(default_factory=list)- user: list[str] | str = field(default_factory=list)- suffix: list[str] | str = field(default_factory=list)-- @classmethod- @override- def from_config(cls, config: PromptLayerConfig) -> Self:- """Create a prompt layer from validated prompt config."""- validated_config = PromptLayerConfig.model_validate(config)- return cls(prefix=validated_config.prefix, user=validated_config.user, suffix=validated_config.suffix)-- @property- def prefix_prompts(self) -> list[str]:- if isinstance(self.prefix, str):- return [self.prefix]- return self.prefix-- @property- def suffix_prompts(self) -> list[str]:- if isinstance(self.suffix, str):- return [self.suffix]- return self.suffix-- @property- def user_prompts(self) -> list[str]:- if isinstance(self.user, str):- return [self.user]- return self.user---@dataclass-class ToolsLayer(PlainLayer[NoLayerDeps]):- """Layer that contributes configured plain-callable tools.-- Tool layers are instance-only because Python callables are live objects. Add- them with a custom ``LayerProvider`` factory that returns a fresh layer for- each compositor run.- """-- tool_entries: Sequence[Callable[..., Any]] = ()-- @property- def tools(self) -> list[Callable[..., Any]]:- return list(self.tool_entries)---__all__ = [- "ObjectLayer",- "PLAIN_PROMPT_LAYER_TYPE_ID",- "PromptLayerConfig",- "PromptLayer",- "ToolsLayer",-]diff --git a/dify-agent/src/agenton_collections/layers/plain/dynamic_tools.py b/dify-agent/src/agenton_collections/layers/plain/dynamic_tools.pydeleted file mode 100644index 12c78990a35..00000000000--- a/dify-agent/src/agenton_collections/layers/plain/dynamic_tools.py+++ /dev/null@@ -1,232 +0,0 @@-"""Dynamic plain-tool layer with object-bound tool entries.--This module builds on ``ObjectLayer`` from ``agenton_collections.plain.basic``.-Plain callables are exposed unchanged, while entries wrapped with-``with_object`` bind the current object value into the first callable argument-and expose the remaining parameters as the public tool signature.-"""--from collections.abc import Callable, Sequence-from dataclasses import dataclass-from functools import wraps-from inspect import Parameter, Signature, iscoroutinefunction, signature-from types import UnionType-from typing import (- Annotated,- Any,- Concatenate,- Union,- get_args,- get_origin,- get_type_hints,-)--from agenton.layers.base import LayerDeps-from agenton.layers.types import PlainLayer-from agenton_collections.layers.plain.basic import ObjectLayer--type _ObjectToolCallable[ObjectT] = Callable[Concatenate[ObjectT, ...], Any]---@dataclass(frozen=True, slots=True)-class _ObjectToolEntry[ObjectT]:- """Tool entry whose first argument should be filled from ``ObjectLayer``."""-- tool_entry: _ObjectToolCallable[ObjectT]- object_type: type[ObjectT] | None = None---type _DynamicToolEntry[ObjectT] = Callable[..., Any] | _ObjectToolEntry[ObjectT]---def with_object[ObjectT](- object_type: type[ObjectT],- /,-) -> Callable[[_ObjectToolCallable[ObjectT]], _ObjectToolEntry[ObjectT]]:- """Mark a tool as requiring the bound object value as its first argument."""-- def decorator(tool_entry: _ObjectToolCallable[ObjectT]) -> _ObjectToolEntry[ObjectT]:- _validate_object_tool_annotation(tool_entry, object_type)- return _ObjectToolEntry(tool_entry=tool_entry, object_type=object_type)-- return decorator---class DynamicToolsLayerDeps[ObjectT](LayerDeps):- """Dependencies required by ``DynamicToolsLayer``."""-- object_layer: ObjectLayer[ObjectT] # pyright: ignore[reportUninitializedInstanceVariable]---@dataclass-class DynamicToolsLayer[ObjectT](PlainLayer[DynamicToolsLayerDeps[ObjectT]]):- """Layer that exposes plain tools and object-bound tools."""-- tool_entries: Sequence[_DynamicToolEntry[ObjectT]] = ()-- @property- def tools(self) -> list[Callable[..., Any]]:- object_value = self.deps.object_layer.value- return [- _bind_object_argument(tool_entry.tool_entry, object_value, tool_entry.object_type)- if isinstance(tool_entry, _ObjectToolEntry)- else tool_entry- for tool_entry in self.tool_entries- ]---def _bind_object_argument[ObjectT](- tool_entry: _ObjectToolCallable[ObjectT],- object_value: ObjectT,- object_type: type[ObjectT] | None,-) -> Callable[..., Any]:- _validate_object_value(tool_entry, object_value, object_type)- if iscoroutinefunction(tool_entry):- wrapped = _async_object_wrapper(tool_entry, object_value)- else:- wrapped = _sync_object_wrapper(tool_entry, object_value)-- public_signature = _public_tool_signature(tool_entry)- if public_signature is not None:- setattr(wrapped, "__signature__", public_signature)- _set_public_annotations(wrapped, tool_entry)- return wrapped---def _validate_object_tool_annotation[ObjectT](- tool_entry: _ObjectToolCallable[ObjectT],- object_type: type[ObjectT],-) -> None:- parameter = _first_object_parameter(tool_entry)- if parameter is None:- return-- annotation = _parameter_annotation(tool_entry, parameter)- if annotation is Parameter.empty:- return- if _annotation_accepts_object_type(annotation, object_type):- return-- raise TypeError(- f"Object-bound tool '{_tool_name(tool_entry)}' first parameter should accept '{_type_name(object_type)}'."- )---def _first_object_parameter(tool_entry: Callable[..., Any]) -> Parameter | None:- try:- tool_signature = signature(tool_entry)- except (TypeError, ValueError):- return None-- parameters = list(tool_signature.parameters.values())- if not parameters:- raise ValueError("Dynamic tools must accept the object dependency as their first parameter.")- return parameters[0]---def _parameter_annotation(tool_entry: Callable[..., Any], parameter: Parameter) -> object:- try:- type_hints = get_type_hints(tool_entry, include_extras=True)- except (AttributeError, NameError, TypeError):- return parameter.annotation- return type_hints.get(parameter.name, parameter.annotation)---def _annotation_accepts_object_type(annotation: object, object_type: type[Any]) -> bool:- if annotation is Any or annotation is Parameter.empty:- return True-- origin = get_origin(annotation)- if origin is Annotated:- args = get_args(annotation)- return True if not args else _annotation_accepts_object_type(args[0], object_type)- if origin in (UnionType, Union):- return any(- arg is type(None) or _annotation_accepts_object_type(arg, object_type) for arg in get_args(annotation)- )-- runtime_type = origin or annotation- if not isinstance(runtime_type, type):- return True- try:- return issubclass(object_type, runtime_type)- except TypeError:- return True---def _validate_object_value[ObjectT](- tool_entry: _ObjectToolCallable[ObjectT],- object_value: ObjectT,- object_type: type[ObjectT] | None,-) -> None:- if object_type is None or isinstance(object_value, object_type):- return- raise TypeError(- f"Object-bound tool '{_tool_name(tool_entry)}' expected object dependency "- f"of type '{_type_name(object_type)}', but got '{type(object_value).__qualname__}'."- )---def _tool_name(tool_entry: Callable[..., Any]) -> str:- return getattr(tool_entry, "__qualname__", getattr(tool_entry, "__name__", repr(tool_entry)))---def _type_name(object_type: type[Any]) -> str:- return object_type.__qualname__---def _sync_object_wrapper[ObjectT](- tool_entry: _ObjectToolCallable[ObjectT],- object_value: ObjectT,-) -> Callable[..., Any]:- @wraps(tool_entry)- def wrapped(*args: Any, **kwargs: Any) -> Any:- return tool_entry(object_value, *args, **kwargs)-- return wrapped---def _async_object_wrapper[ObjectT](- tool_entry: _ObjectToolCallable[ObjectT],- object_value: ObjectT,-) -> Callable[..., Any]:- @wraps(tool_entry)- async def wrapped(*args: Any, **kwargs: Any) -> Any:- return await tool_entry(object_value, *args, **kwargs)-- return wrapped---def _public_tool_signature(tool_entry: Callable[..., Any]) -> Signature | None:- try:- tool_signature = signature(tool_entry)- except (TypeError, ValueError):- return None-- parameters = list(tool_signature.parameters.values())- if not parameters:- raise ValueError("Dynamic tools must accept the object dependency as their first parameter.")- return tool_signature.replace(parameters=parameters[1:])---def _set_public_annotations(wrapper: Callable[..., Any], tool_entry: Callable[..., Any]) -> None:- annotations = getattr(tool_entry, "__annotations__", None)- if not isinstance(annotations, dict):- return-- try:- parameters = list(signature(tool_entry).parameters)- except (TypeError, ValueError):- parameters = []-- public_annotations = dict(annotations)- if parameters:- public_annotations.pop(parameters[0], None)- wrapper.__annotations__ = public_annotations---__all__ = [- "DynamicToolsLayer",- "DynamicToolsLayerDeps",- "with_object",-]diff --git a/dify-agent/src/agenton_collections/layers/pydantic_ai/__init__.py b/dify-agent/src/agenton_collections/layers/pydantic_ai/__init__.pydeleted file mode 100644index 67f8869d0fd..00000000000--- a/dify-agent/src/agenton_collections/layers/pydantic_ai/__init__.py+++ /dev/null@@ -1,19 +0,0 @@-"""Reusable collection layers for the pydantic-ai layer family."""--from agenton_collections.layers.pydantic_ai.bridge import (- PydanticAIBridgeLayer,- PydanticAIBridgeLayerDeps,-)-from agenton_collections.layers.pydantic_ai.history import (- PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,- PydanticAIHistoryLayer,- PydanticAIHistoryRuntimeState,-)--__all__ = [- "PydanticAIBridgeLayer",- "PydanticAIBridgeLayerDeps",- "PYDANTIC_AI_HISTORY_LAYER_TYPE_ID",- "PydanticAIHistoryLayer",- "PydanticAIHistoryRuntimeState",-]diff --git a/dify-agent/src/agenton_collections/layers/pydantic_ai/bridge.py b/dify-agent/src/agenton_collections/layers/pydantic_ai/bridge.pydeleted file mode 100644index c2f9c668db2..00000000000--- a/dify-agent/src/agenton_collections/layers/pydantic_ai/bridge.py+++ /dev/null@@ -1,106 +0,0 @@-"""Pydantic AI bridge prompt and tool layer.--This module keeps pydantic-ai's callable shapes intact through-``PydanticAILayer``. The bridge layer depends on ``ObjectLayer`` so callers have-one explicit graph node that provides the object used as-``RunContext[ObjectT].deps`` in pydantic-ai prompt and tool callables.-Bridge construction accepts pydantic-ai's ergonomic input forms and normalizes-them at the layer boundary: string system prompts become zero-arg system prompt-functions, user prompts stay as pydantic-ai ``UserContent`` values, and bare-tool functions become ``Tool`` instances.-"""--from collections.abc import Sequence-from dataclasses import dataclass--from pydantic_ai import Tool-from pydantic_ai.messages import UserContent-from pydantic_ai.tools import ToolFuncEither-from typing_extensions import override--from agenton.layers.base import LayerDeps-from agenton.layers.types import PydanticAILayer, PydanticAIPrompt, PydanticAITool, PydanticAIUserPrompt-from agenton_collections.layers.plain.basic import ObjectLayer---class PydanticAIBridgeLayerDeps[ObjectT](LayerDeps):- """Dependencies required by ``PydanticAIBridgeLayer``."""-- object_layer: ObjectLayer[ObjectT] # pyright: ignore[reportUninitializedInstanceVariable]---@dataclass-class PydanticAIBridgeLayer[ObjectT](PydanticAILayer[PydanticAIBridgeLayerDeps[ObjectT], ObjectT]):- """Bridge layer for pydantic-ai prompts and tools using one object deps."""-- prefix: str | PydanticAIPrompt[ObjectT] | Sequence[str | PydanticAIPrompt[ObjectT]] = ()- user: UserContent | Sequence[UserContent] = ()- suffix: str | PydanticAIPrompt[ObjectT] | Sequence[str | PydanticAIPrompt[ObjectT]] = ()- tool_entries: Sequence[PydanticAITool[ObjectT] | ToolFuncEither[ObjectT, ...]] = ()-- @property- def run_deps(self) -> ObjectT:- """Object to pass as pydantic-ai run deps for this layer."""- return self.deps.object_layer.value-- @property- @override- def prefix_prompts(self) -> list[PydanticAIPrompt[ObjectT]]:- return _normalize_prompts(self.prefix)-- @property- @override- def suffix_prompts(self) -> list[PydanticAIPrompt[ObjectT]]:- return _normalize_prompts(self.suffix)-- @property- @override- def user_prompts(self) -> list[PydanticAIUserPrompt]:- return _normalize_user_prompts(self.user)-- @property- @override- def tools(self) -> list[PydanticAITool[ObjectT]]:- return [_normalize_tool(tool_entry) for tool_entry in self.tool_entries]---def _normalize_prompts[ObjectT](- prompts: str | PydanticAIPrompt[ObjectT] | Sequence[str | PydanticAIPrompt[ObjectT]],-) -> list[PydanticAIPrompt[ObjectT]]:- if isinstance(prompts, str):- return [_normalize_prompt(prompts)]- if isinstance(prompts, Sequence):- return [_normalize_prompt(prompt) for prompt in prompts]- return [prompts]---def _normalize_prompt[ObjectT](- prompt: str | PydanticAIPrompt[ObjectT],-) -> PydanticAIPrompt[ObjectT]:- if isinstance(prompt, str):- return (lambda value: lambda: value)(prompt)- return prompt---def _normalize_user_prompts(- prompts: UserContent | Sequence[UserContent],-) -> list[PydanticAIUserPrompt]:- if isinstance(prompts, str):- return [prompts]- if isinstance(prompts, Sequence):- return list(prompts)- return [prompts]---def _normalize_tool[ObjectT](- tool_entry: PydanticAITool[ObjectT] | ToolFuncEither[ObjectT, ...],-) -> PydanticAITool[ObjectT]:- if isinstance(tool_entry, Tool):- return tool_entry- return Tool(tool_entry)---__all__ = [- "PydanticAIBridgeLayer",- "PydanticAIBridgeLayerDeps",-]diff --git a/dify-agent/src/agenton_collections/layers/pydantic_ai/history.py b/dify-agent/src/agenton_collections/layers/pydantic_ai/history.pydeleted file mode 100644index ac91e4006a2..00000000000--- a/dify-agent/src/agenton_collections/layers/pydantic_ai/history.py+++ /dev/null@@ -1,66 +0,0 @@-"""Serializable pydantic-ai conversation history layer.--This layer keeps pydantic-ai ``ModelMessage`` history inside Agenton's-serializable ``runtime_state`` so compositor session snapshots can persist and-restore typed messages without any separate storage protocol. The layer is-intentionally state-only: it contributes no system prompts, user prompts, or-tools, and it owns no live resources. Integrations should read-``message_history`` before ``Agent.run(message_history=...)`` and then write-back only the history shape they intend to persist after success, for example-replacing with ``result.all_messages()`` or appending only-``result.new_messages()`` when temporary prompt prefixes must stay ephemeral.-"""--from collections.abc import Sequence-from typing import ClassVar, Final--from pydantic import BaseModel, ConfigDict, Field-from pydantic_ai.messages import ModelMessage--from agenton.layers import EmptyLayerConfig, NoLayerDeps, PydanticAILayer---PYDANTIC_AI_HISTORY_LAYER_TYPE_ID: Final[str] = "pydantic_ai.history"---class PydanticAIHistoryRuntimeState(BaseModel):- """Serializable history state stored in Agenton session snapshots."""-- messages: list[ModelMessage] = Field(default_factory=list)-- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", validate_assignment=True)---class PydanticAIHistoryLayer(PydanticAILayer[NoLayerDeps, object, EmptyLayerConfig, PydanticAIHistoryRuntimeState]):- """State-only layer that stores pydantic-ai message history.-- The mutable history lives only in ``runtime_state.messages``. Helper methods- always assign fresh lists instead of mutating the stored list in place so- Pydantic assignment validation continues to guard the serialized state.- """-- type_id: ClassVar[str | None] = PYDANTIC_AI_HISTORY_LAYER_TYPE_ID-- @property- def message_history(self) -> list[ModelMessage]:- """Return a shallow copy of the stored message history."""- return list(self.runtime_state.messages)-- def replace_messages(self, messages: Sequence[ModelMessage]) -> None:- """Replace the stored history with a validated copy of ``messages``."""- self.runtime_state.messages = list(messages)-- def append_messages(self, messages: Sequence[ModelMessage]) -> None:- """Append ``messages`` while keeping assignment validation on write."""- self.runtime_state.messages = [*self.runtime_state.messages, *messages]-- def clear(self) -> None:- """Remove all stored history messages."""- self.runtime_state.messages = []---__all__ = [- "PYDANTIC_AI_HISTORY_LAYER_TYPE_ID",- "PydanticAIHistoryLayer",- "PydanticAIHistoryRuntimeState",-]diff --git a/dify-agent/src/agenton_collections/transformers/__init__.py b/dify-agent/src/agenton_collections/transformers/__init__.pydeleted file mode 100644index 9767d57fc3a..00000000000--- a/dify-agent/src/agenton_collections/transformers/__init__.py+++ /dev/null@@ -1,8 +0,0 @@-"""Transformer package marker for collection integrations.--Import pydantic-ai transformer presets from-``agenton_collections.transformers.pydantic_ai`` explicitly so default imports do-not pull runtime bridge implementations into client-safe environments.-"""--__all__: list[str] = []diff --git a/dify-agent/src/agenton_collections/transformers/pydantic_ai.py b/dify-agent/src/agenton_collections/transformers/pydantic_ai.pydeleted file mode 100644index 81b5393a8c7..00000000000--- a/dify-agent/src/agenton_collections/transformers/pydantic_ai.py+++ /dev/null@@ -1,85 +0,0 @@-"""Pydantic AI compositor transformer presets.--This module owns the pydantic-ai runtime dependency for transforming tagged-agenton system prompt, user prompt, and tool items into pydantic-ai-compatible-items.-"""--from collections.abc import Sequence-from typing import Final--from pydantic_ai import Tool--from agenton.compositor import CompositorTransformerKwargs-from agenton.layers.types import (- AllPromptTypes,- AllToolTypes,- AllUserPromptTypes,- PydanticAIPrompt,- PydanticAITool,- PydanticAIUserPrompt,-)--type PydanticAICompositorTransformerKwargs = CompositorTransformerKwargs[- PydanticAIPrompt[object],- PydanticAITool[object],- AllPromptTypes,- AllToolTypes,- PydanticAIUserPrompt,- AllUserPromptTypes,-]---def _pydantic_ai_prompt_transformer(- prompts: Sequence[AllPromptTypes],-) -> list[PydanticAIPrompt[object]]:- result: list[PydanticAIPrompt[object]] = []- for prompt in prompts:- if prompt.kind == "plain":- result.append((lambda value: lambda: value)(prompt.value))- elif prompt.kind == "pydantic_ai":- result.append(prompt.value)- else:- raise NotImplementedError(f"Unsupported prompt type: {type(prompt).__qualname__}.")- return result---def _pydantic_ai_user_prompt_transformer(- prompts: Sequence[AllUserPromptTypes],-) -> list[PydanticAIUserPrompt]:- result: list[PydanticAIUserPrompt] = []- for prompt in prompts:- if prompt.kind == "plain":- result.append(prompt.value)- elif prompt.kind == "pydantic_ai":- result.append(prompt.value)- else:- raise NotImplementedError(f"Unsupported user prompt type: {type(prompt).__qualname__}.")- return result---def _pydantic_ai_tool_transformer(- tools: Sequence[AllToolTypes],-) -> list[PydanticAITool[object]]:- result: list[PydanticAITool[object]] = []- for tool in tools:- if tool.kind == "plain":- result.append(Tool(tool.value))- elif tool.kind == "pydantic_ai":- result.append(tool.value)- else:- raise NotImplementedError(f"Unsupported tool type: {type(tool).__qualname__}.")- return result---PYDANTIC_AI_TRANSFORMERS: Final[PydanticAICompositorTransformerKwargs] = {- "prompt_transformer": _pydantic_ai_prompt_transformer,- "user_prompt_transformer": _pydantic_ai_user_prompt_transformer,- "tool_transformer": _pydantic_ai_tool_transformer,-}---__all__ = [- "PYDANTIC_AI_TRANSFORMERS",- "PydanticAICompositorTransformerKwargs",-]diff --git a/dify-agent/src/dify_agent/adapters/shell/shellctl.py b/dify-agent/src/dify_agent/adapters/shell/shellctl.pyindex 5af4e20afea..0b617549035 100644--- a/dify-agent/src/dify_agent/adapters/shell/shellctl.py+++ b/dify-agent/src/dify_agent/adapters/shell/shellctl.py@@ -10,7 +10,7 @@ from __future__ import annotationsimport posixpathfrom collections.abc import Awaitable, Callablefrom dataclasses import dataclass-from typing import Protocol, TypeVar, cast+from typing import Protocol, TypeVar, cast, overrideimport httpx2 as httpxfrom shellctl.client import ShellctlClientError@@ -109,6 +109,7 @@ class ShellctlCommands(ShellCommandProtocol):home_dir: str | None = Noneworkspace_dir: str | None = None+ @overrideasync def run(self,script: str,@@ -136,6 +137,7 @@ class ShellctlCommands(ShellCommandProtocol):))+ @overrideasync def wait(self,job_id: str,@@ -145,6 +147,7 @@ class ShellctlCommands(ShellCommandProtocol):) -> ShellCommandResult:return _from_job_result(await _run_client_call(self.client.wait(job_id, offset=offset, timeout=timeout)))+ @overrideasync def read_output(self,job_id: str,@@ -155,6 +158,7 @@ class ShellctlCommands(ShellCommandProtocol):await _run_client_call(self.client.wait(job_id, offset=offset, timeout=_READ_OUTPUT_TIMEOUT_SECONDS)))+ @overrideasync def input(self,job_id: str,@@ -165,6 +169,7 @@ class ShellctlCommands(ShellCommandProtocol):) -> ShellCommandResult:return _from_job_result(await _run_client_call(self.client.input(job_id, text, offset=offset, timeout=timeout)))+ @overrideasync def interrupt(self,job_id: str,@@ -173,9 +178,11 @@ class ShellctlCommands(ShellCommandProtocol):) -> ShellCommandStatus:return _from_job_status(await _run_client_call(self.client.terminate(job_id, grace_seconds=grace_seconds)))+ @overrideasync def tail(self, job_id: str) -> ShellCommandResult:return _from_job_result(await _run_client_call(self.client.tail(job_id)))+ @overrideasync def delete(self,job_id: str,diff --git a/dify-agent/src/dify_agent/layers/__init__.py b/dify-agent/src/dify_agent/layers/__init__.pyindex 518fbf9bd93..c42cd002d25 100644--- a/dify-agent/src/dify_agent/layers/__init__.py+++ b/dify-agent/src/dify_agent/layers/__init__.py@@ -1,3 +1,3 @@-"""Dify-owned Agenton layer packages."""+"""Dify modules and client-safe configuration DTOs."""__all__: list[str] = []diff --git a/dify-agent/src/dify_agent/layers/ask_human/__init__.py b/dify-agent/src/dify_agent/layers/ask_human/__init__.pydeleted file mode 100644index 0138d7daf62..00000000000--- a/dify-agent/src/dify_agent/layers/ask_human/__init__.py+++ /dev/null@@ -1,48 +0,0 @@-"""Client-safe exports for Dify ask-human layer DTOs and schema types.--The runtime layer implementation lives in ``layer.py`` and imports server-side- execution helpers. Keep this package root import-safe for client code that only- needs to build run requests or understand deferred payload shapes.-"""--from dify_agent.layers.ask_human.configs import (- DEFAULT_ASK_HUMAN_TOOL_DESCRIPTION,- DIFY_ASK_HUMAN_LAYER_TYPE_ID,- DifyAskHumanLayerConfig,-)-from dify_agent.layers.ask_human.schema import (- AskHumanAction,- AskHumanActionStyle,- AskHumanField,- AskHumanFieldType,- AskHumanFileField,- AskHumanFileListField,- AskHumanParagraphField,- AskHumanResultStatus,- AskHumanSelectField,- AskHumanSelectOption,- AskHumanSelectedAction,- AskHumanToolArgs,- AskHumanToolResult,- AskHumanUrgency,-)--__all__ = [- "AskHumanAction",- "AskHumanActionStyle",- "AskHumanField",- "AskHumanFieldType",- "AskHumanFileField",- "AskHumanFileListField",- "AskHumanParagraphField",- "AskHumanResultStatus",- "AskHumanSelectField",- "AskHumanSelectOption",- "AskHumanSelectedAction",- "AskHumanToolArgs",- "AskHumanToolResult",- "AskHumanUrgency",- "DEFAULT_ASK_HUMAN_TOOL_DESCRIPTION",- "DIFY_ASK_HUMAN_LAYER_TYPE_ID",- "DifyAskHumanLayerConfig",-]diff --git a/dify-agent/src/dify_agent/layers/ask_human/configs.py b/dify-agent/src/dify_agent/layers/ask_human/configs.pydeleted file mode 100644index 87fd1a4af0b..00000000000--- a/dify-agent/src/dify_agent/layers/ask_human/configs.py+++ /dev/null@@ -1,140 +0,0 @@-"""Client-safe DTOs for the Dify ask-human layer.--The public config controls only stable model-facing tool identity and guardrails.-Delivery, recipient selection, timeout policy, and other operational behavior are-intentionally out of scope for this layer and must stay outside the model-facing-tool contract. Setting ``enabled=False`` disables both ask-human tool exposure-and the prompt guidance that tells the model about these limits. Caller-provided-limits are additionally capped by small server hard limits so one composition-cannot widen the public deferred-tool surface arbitrarily. File field variants-are part of the schema vocabulary for forward compatibility, but they remain-invalid unless ``allow_file_fields=True`` and the allowed field-type list also-permits them.-"""--from __future__ import annotations--import re-from typing import ClassVar, Final--from pydantic import ConfigDict, Field, field_validator, model_validator--from agenton.layers import LayerConfig-from dify_agent.layers.ask_human.schema import AskHumanFieldType---DIFY_ASK_HUMAN_LAYER_TYPE_ID: Final[str] = "dify.ask_human"-DEFAULT_ASK_HUMAN_TOOL_DESCRIPTION: Final[str] = (- "Ask a human for missing information or a decision that is required to continue. "- "Use this only when the answer cannot be inferred from the conversation, available tools, or current context. "- "Provide concise instructions, structured fields, and clear actions for the human."-)--_TOOL_NAME_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")-_HARD_MAX_FIELDS = 16-_HARD_MAX_ACTIONS = 8-_HARD_MAX_MARKDOWN_CHARS = 20_000-_HARD_MAX_QUESTION_CHARS = 4_000-_HARD_MAX_FIELD_LABEL_CHARS = 200-_HARD_MAX_ACTION_LABEL_CHARS = 120-_FILE_FIELD_TYPES: Final[frozenset[AskHumanFieldType]] = frozenset({"file", "file-list"})---def _default_allowed_field_types() -> list[AskHumanFieldType]:- return ["paragraph", "select"]---class DifyAskHumanLayerConfig(LayerConfig):- """Public config for the optional ask-human deferred tool layer.-- This DTO describes the exact model-facing guardrail surface that the runtime- will both validate and surface back to the model through prompt guidance.- ``enabled=False`` means callers keep the layer in composition data without- exposing either the tool or its instructions for that run. Numeric limits are- caller-configurable only within the server's hard caps, and file field types- are rejected unless callers opt in with ``allow_file_fields=True``.- """-- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")-- enabled: bool = True- tool_name: str = "ask_human"- tool_description: str | None = None- max_fields: int = Field(default=8, ge=0)- max_actions: int = Field(default=4, ge=1)- allowed_field_types: list[AskHumanFieldType] = Field(default_factory=_default_allowed_field_types)- allow_file_fields: bool = False- max_markdown_chars: int = Field(default=8_000, ge=0)- max_question_chars: int = Field(default=1_000, ge=1)- max_field_label_chars: int = Field(default=120, ge=1)- max_action_label_chars: int = Field(default=80, ge=1)-- @property- def effective_tool_description(self) -> str:- """Return the configured description or the proposal default text."""- return self.tool_description or DEFAULT_ASK_HUMAN_TOOL_DESCRIPTION-- @field_validator("tool_name")- @classmethod- def _validate_tool_name(cls, value: str) -> str:- if not _TOOL_NAME_PATTERN.fullmatch(value):- raise ValueError("tool_name must be a valid tool identifier")- return value-- @field_validator("tool_description")- @classmethod- def _normalize_tool_description(cls, value: str | None) -> str | None:- if value is None:- return None- stripped = value.strip()- return stripped or None-- @field_validator("allowed_field_types")- @classmethod- def _validate_allowed_field_types(cls, value: list[AskHumanFieldType]) -> list[AskHumanFieldType]:- if len(set(value)) != len(value):- raise ValueError("allowed_field_types must not contain duplicates")- return value-- @field_validator(- "max_fields",- "max_actions",- "max_markdown_chars",- "max_question_chars",- "max_field_label_chars",- "max_action_label_chars",- mode="after",- )- @classmethod- def _validate_hard_limits(cls, value: int, info: object) -> int:- field_name = getattr(info, "field_name", "value")- hard_limits = {- "max_fields": _HARD_MAX_FIELDS,- "max_actions": _HARD_MAX_ACTIONS,- "max_markdown_chars": _HARD_MAX_MARKDOWN_CHARS,- "max_question_chars": _HARD_MAX_QUESTION_CHARS,- "max_field_label_chars": _HARD_MAX_FIELD_LABEL_CHARS,- "max_action_label_chars": _HARD_MAX_ACTION_LABEL_CHARS,- }- hard_limit = hard_limits[field_name]- if value > hard_limit:- raise ValueError(f"{field_name} must be <= {hard_limit}")- return value-- @model_validator(mode="after")- def _validate_file_field_policy(self) -> DifyAskHumanLayerConfig:- if not self.allow_file_fields:- forbidden = [field_type for field_type in self.allowed_field_types if field_type in _FILE_FIELD_TYPES]- if forbidden:- joined = ", ".join(forbidden)- raise ValueError(- f"allowed_field_types cannot include file field types when allow_file_fields is false: {joined}"- )- return self---__all__ = [- "DEFAULT_ASK_HUMAN_TOOL_DESCRIPTION",- "DIFY_ASK_HUMAN_LAYER_TYPE_ID",- "DifyAskHumanLayerConfig",-]diff --git a/dify-agent/src/dify_agent/layers/ask_human/layer.py b/dify-agent/src/dify_agent/layers/ask_human/layer.pydeleted file mode 100644index 399f28ab063..00000000000--- a/dify-agent/src/dify_agent/layers/ask_human/layer.py+++ /dev/null@@ -1,275 +0,0 @@-"""Runtime ask-human layer built on pydantic-ai external deferred tools.--The layer contributes one optional external tool plus one prompt hint. The tool-never executes Python during the initial run; instead the model emits an-external deferred tool call that Dify Agent returns through ``run_succeeded`` as-``deferred_tool_call``. Guardrails are enforced in two places:--* prompt/tool-definition guidance nudges the model toward valid requests, and-* runtime validation normalizes default actions and rejects out-of-policy calls.--The layer stays product-neutral: downstream systems decide delivery, recipients,-timeouts, and authorization for the human request.-"""--from __future__ import annotations--from dataclasses import dataclass-from typing import Any, ClassVar, cast--from pydantic import JsonValue, ValidationError-from pydantic_ai import Tool-from pydantic_ai.exceptions import ModelRetry-from pydantic_ai.tools import ArgsValidatorFunc, DeferredToolRequests, RunContext, ToolDefinition-from typing_extensions import Self, override--from agenton.layers import EmptyRuntimeState, NoLayerDeps, PydanticAILayer, PydanticAIPrompt, PydanticAITool-from dify_agent.layers.ask_human.configs import DIFY_ASK_HUMAN_LAYER_TYPE_ID, DifyAskHumanLayerConfig-from dify_agent.layers.ask_human.schema import (- AskHumanAction,- AskHumanField,- AskHumanToolArgs,-)-from dify_agent.protocol.schemas import DeferredToolCallPayload, RunComposition---_ASK_HUMAN_DEFERRED_SCHEMA_VERSION = 1-_DEFAULT_SUBMIT_ACTION = AskHumanAction(id="submit", label="Submit", style="primary")---@dataclass(slots=True)-class DifyAskHumanLayer(PydanticAILayer[NoLayerDeps, object, DifyAskHumanLayerConfig, EmptyRuntimeState]):- """State-free pydantic-ai layer that exposes the ask-human deferred tool."""-- type_id: ClassVar[str | None] = DIFY_ASK_HUMAN_LAYER_TYPE_ID-- config: DifyAskHumanLayerConfig-- @classmethod- @override- def from_config(cls, config: DifyAskHumanLayerConfig) -> Self:- """Create the layer from validated public config."""- return cls(config=DifyAskHumanLayerConfig.model_validate(config))-- @property- @override- def prefix_prompts(self) -> list[PydanticAIPrompt[object]]:- if not self.config.enabled:- return []- return [self.build_prompt_hint]-- @property- @override- def tools(self) -> list[PydanticAITool[object]]:- if not self.config.enabled:- return []- return [- Tool(- self._never_executed_tool,- takes_ctx=True,- name=self.config.tool_name,- description=self.config.effective_tool_description,- prepare=self._prepare_tool_definition,- args_validator=cast(ArgsValidatorFunc[object, ...], self._validate_tool_args),- sequential=True,- )- ]-- def build_prompt_hint(self) -> str:- """Return the model-facing instruction text for ask-human guardrails."""- allowed_field_types = ", ".join(self.config.allowed_field_types) if self.config.allowed_field_types else "none"- file_field_status = "enabled" if self.config.allow_file_fields else "disabled"- if self.config.max_fields == 0:- field_count_hint = "Do not add any fields."- else:- field_count_hint = f"Use at most {self.config.max_fields} field(s)."- return (- f"You may call the external tool '{self.config.tool_name}' only when human input is required to continue. "- "Do not ask a human for information that can be inferred from the conversation, current context, or other tools.\n\n"- f"Ask-human guardrails:\n"- f"- Allowed field types: {allowed_field_types}.\n"- f"- File upload fields are {file_field_status}.\n"- f"- {field_count_hint}\n"- f"- Use at most {self.config.max_actions} action(s).\n"- f"- Keep 'question' under {self.config.max_question_chars} characters.\n"- f"- Keep 'markdown' under {self.config.max_markdown_chars} characters.\n"- f"- Keep each field label under {self.config.max_field_label_chars} characters.\n"- f"- Keep each action label under {self.config.max_action_label_chars} characters.\n"- "- If you omit actions, the system will add one primary action: Submit.\n"- "Prefer concise, structured requests that stay comfortably within these limits."- )-- def build_deferred_tool_call_payload(self, requests: DeferredToolRequests) -> DeferredToolCallPayload:- """Validate and normalize the single supported deferred ask-human call."""- if requests.approvals:- raise ValueError("ask_human does not support approval requests; use external deferred calls only")-- call_count = len(requests.calls)- if call_count != 1:- raise ValueError(f"ask_human supports exactly one deferred call per run in this version; got {call_count}.")-- call = requests.calls[0]- if call.tool_name != self.config.tool_name:- raise ValueError(f"ask_human deferred tool name must be '{self.config.tool_name}', got '{call.tool_name}'.")-- args = self._validate_and_normalize_tool_args(- title=None,- question="",- markdown=None,- fields=[],- actions=[],- urgency="normal",- raw_args=call.args,- )- return DeferredToolCallPayload(- tool_call_id=call.tool_call_id,- tool_name=call.tool_name,- args=cast(JsonValue, args.model_dump(mode="json")),- metadata={- "layer_type": self.type_id,- "tool_name": self.config.tool_name,- "schema_version": _ASK_HUMAN_DEFERRED_SCHEMA_VERSION,- },- )-- def _prepare_tool_definition(self, _ctx: RunContext[object], tool_def: ToolDefinition) -> ToolDefinition:- """Convert the ask-human tool into a pydantic-ai external deferred tool."""- del tool_def- return ToolDefinition(- name=self.config.tool_name,- description=self.config.effective_tool_description,- parameters_json_schema=cast(dict[str, Any], AskHumanToolArgs.model_json_schema()),- strict=False,- sequential=True,- kind="external",- )-- async def _never_executed_tool(- self,- _ctx: RunContext[object],- *,- title: str | None = None,- question: str,- markdown: str | None = None,- fields: list[AskHumanField] | None = None,- actions: list[AskHumanAction] | None = None,- urgency: str = "normal",- ) -> str:- del title, question, markdown, fields, actions, urgency- raise RuntimeError("ask_human is an external deferred tool and should not execute during the initial run")-- def _validate_tool_args(- self,- _ctx: RunContext[object],- *,- title: str | None = None,- question: str,- markdown: str | None = None,- fields: list[AskHumanField] | None = None,- actions: list[AskHumanAction] | None = None,- urgency: str = "normal",- ) -> None:- try:- _ = self._validate_and_normalize_tool_args(- title=title,- question=question,- markdown=markdown,- fields=fields or [],- actions=actions or [],- urgency=urgency,- )- except (ValidationError, ValueError) as exc:- raise ModelRetry(str(exc)) from exc-- def _validate_and_normalize_tool_args(- self,- *,- title: str | None,- question: str,- markdown: str | None,- fields: list[AskHumanField],- actions: list[AskHumanAction],- urgency: str,- raw_args: str | dict[str, Any] | None = None,- ) -> AskHumanToolArgs:- if raw_args is not None:- args = _validate_tool_args_payload(raw_args)- else:- args = AskHumanToolArgs(- title=title,- question=question,- markdown=markdown,- fields=fields,- actions=actions,- urgency=cast(Any, urgency),- )-- if len(args.fields) > self.config.max_fields:- raise ValueError(f"ask_human fields must contain at most {self.config.max_fields} item(s)")-- normalized_actions = list(args.actions)- if not normalized_actions:- normalized_actions = [_DEFAULT_SUBMIT_ACTION.model_copy()]- if len(normalized_actions) > self.config.max_actions:- raise ValueError(f"ask_human actions must contain at most {self.config.max_actions} item(s)")-- if len(args.question) > self.config.max_question_chars:- raise ValueError(f"ask_human question must be <= {self.config.max_question_chars} characters")- if args.markdown is not None and len(args.markdown) > self.config.max_markdown_chars:- raise ValueError(f"ask_human markdown must be <= {self.config.max_markdown_chars} characters")-- allowed_field_types = set(self.config.allowed_field_types)- for field in args.fields:- if field.type not in allowed_field_types:- raise ValueError(f"ask_human field type '{field.type}' is not allowed by this layer config")- if len(field.label) > self.config.max_field_label_chars:- raise ValueError(- f"ask_human field label '{field.label}' must be <= {self.config.max_field_label_chars} characters"- )- if not self.config.allow_file_fields and field.type in {"file", "file-list"}:- raise ValueError("ask_human file fields are disabled by this layer config")-- for action in normalized_actions:- if len(action.label) > self.config.max_action_label_chars:- raise ValueError(- f"ask_human action label '{action.label}' must be <= {self.config.max_action_label_chars} characters"- )-- return args.model_copy(update={"actions": normalized_actions})---def validate_ask_human_layer_composition(composition: RunComposition) -> None:- """Reject unsupported public ask-human layer graph shapes."""- ask_human_layers = [layer.name for layer in composition.layers if layer.type == DIFY_ASK_HUMAN_LAYER_TYPE_ID]- if len(ask_human_layers) > 1:- names = ", ".join(ask_human_layers)- raise ValueError(f"Only one '{DIFY_ASK_HUMAN_LAYER_TYPE_ID}' layer is supported. Found layers: {names}.")---def get_ask_human_layer(run: Any) -> DifyAskHumanLayer | None:- """Return the active ask-human layer when one is present and enabled."""- matched: list[DifyAskHumanLayer] = []- for slot in run.slots.values():- layer = slot.layer- if isinstance(layer, DifyAskHumanLayer):- matched.append(layer)- if not matched:- return None- if len(matched) > 1:- raise ValueError(f"Only one '{DIFY_ASK_HUMAN_LAYER_TYPE_ID}' layer is supported per run.")-- layer = matched[0]- return layer if layer.config.enabled else None---def _validate_tool_args_payload(raw_args: str | dict[str, Any]) -> AskHumanToolArgs:- if isinstance(raw_args, str):- return AskHumanToolArgs.model_validate_json(raw_args or "{}")- return AskHumanToolArgs.model_validate(raw_args or {})---__all__ = [- "DifyAskHumanLayer",- "get_ask_human_layer",- "validate_ask_human_layer_composition",-]diff --git a/dify-agent/src/dify_agent/layers/ask_human/schema.py b/dify-agent/src/dify_agent/layers/ask_human/schema.pydeleted file mode 100644index 59fb9d3fc70..00000000000--- a/dify-agent/src/dify_agent/layers/ask_human/schema.py+++ /dev/null@@ -1,234 +0,0 @@-"""Product-neutral schemas for the Dify ask-human deferred tool contract.--These models describe the model-facing tool arguments and the later human result-payload expected by resumed runs. Config-specific guardrails such as maximum-counts, allowed field types, or per-install length limits are enforced by-``dify_agent.layers.ask_human.layer`` so this module stays import-safe for-client code that only needs the stable wire/schema shapes.-"""--from __future__ import annotations--import re-from typing import Annotated, ClassVar, Literal--from pydantic import BaseModel, ConfigDict, Field, JsonValue, ValidationInfo, field_validator, model_validator---_IDENTIFIER_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")--type AskHumanFieldType = Literal["paragraph", "select", "file", "file-list"]-type AskHumanActionStyle = Literal["default", "primary", "destructive"]-type AskHumanUrgency = Literal["normal", "high"]-type AskHumanResultStatus = Literal["submitted", "timeout", "cancelled", "unavailable"]---def is_valid_identifier(value: str) -> bool:- """Return whether ``value`` matches the stable ask-human identifier rules."""- return bool(_IDENTIFIER_PATTERN.fullmatch(value))---def _require_non_blank(value: str, *, label: str) -> str:- if not value.strip():- raise ValueError(f"{label} must not be blank")- return value---class AskHumanSelectOption(BaseModel):- """One selectable option for an ask-human select field."""-- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")-- value: str = Field(min_length=1)- label: str = Field(min_length=1)-- @field_validator("value", "label")- @classmethod- def _validate_non_blank(cls, value: str, info: ValidationInfo) -> str:- return _require_non_blank(value, label=f"select option {info.field_name}")---class AskHumanFieldBase(BaseModel):- """Shared field properties for ask-human form fields."""-- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")-- name: str = Field(min_length=1)- label: str = Field(min_length=1)- required: bool = False-- @field_validator("name")- @classmethod- def _validate_name(cls, value: str) -> str:- if not is_valid_identifier(value):- raise ValueError("field name must be a valid identifier")- return value-- @field_validator("label")- @classmethod- def _validate_label(cls, value: str) -> str:- return _require_non_blank(value, label="field label")---class AskHumanParagraphField(AskHumanFieldBase):- """Free-text paragraph field."""-- type: Literal["paragraph"] = "paragraph"- placeholder: str | None = None- default: str | None = None---class AskHumanSelectField(AskHumanFieldBase):- """Single-choice select field."""-- type: Literal["select"] = "select"- options: list[AskHumanSelectOption] = Field(default_factory=list)- default: str | None = None-- @model_validator(mode="after")- def _validate_options(self) -> AskHumanSelectField:- if not self.options:- raise ValueError("select fields must define at least one option")-- seen_values: set[str] = set()- for option in self.options:- if option.value in seen_values:- raise ValueError(f"select field '{self.name}' contains duplicate option value '{option.value}'")- seen_values.add(option.value)-- if self.default is not None and self.default not in seen_values:- raise ValueError(f"select field '{self.name}' default must match one of its option values")- return self---class AskHumanFileField(AskHumanFieldBase):- """Single-file upload field."""-- type: Literal["file"] = "file"---class AskHumanFileListField(AskHumanFieldBase):- """Multi-file upload field."""-- type: Literal["file-list"] = "file-list"- max_files: int | None = Field(default=None, ge=1)---type AskHumanField = Annotated[- AskHumanParagraphField | AskHumanSelectField | AskHumanFileField | AskHumanFileListField,- Field(discriminator="type"),-]---class AskHumanAction(BaseModel):- """One human-visible action rendered with an ask-human request."""-- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")-- id: str = Field(min_length=1)- label: str = Field(min_length=1)- style: AskHumanActionStyle = "default"-- @field_validator("id")- @classmethod- def _validate_id(cls, value: str) -> str:- if not is_valid_identifier(value):- raise ValueError("action id must be a valid identifier")- return value-- @field_validator("label")- @classmethod- def _validate_label(cls, value: str) -> str:- return _require_non_blank(value, label="action label")---class AskHumanSelectedAction(BaseModel):- """Action metadata returned with a human-submitted result."""-- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")-- id: str = Field(min_length=1)- label: str = Field(min_length=1)-- @field_validator("id")- @classmethod- def _validate_id(cls, value: str) -> str:- if not is_valid_identifier(value):- raise ValueError("selected action id must be a valid identifier")- return value-- @field_validator("label")- @classmethod- def _validate_label(cls, value: str) -> str:- return _require_non_blank(value, label="selected action label")---class AskHumanToolArgs(BaseModel):- """Arguments accepted by the ask-human external deferred tool."""-- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")-- title: str | None = None- question: str = Field(min_length=1)- markdown: str | None = None- fields: list[AskHumanField] = Field(default_factory=list)- actions: list[AskHumanAction] = Field(default_factory=list)- urgency: AskHumanUrgency = "normal"-- @field_validator("question")- @classmethod- def _validate_question(cls, value: str) -> str:- return _require_non_blank(value, label="question")-- @field_validator("title")- @classmethod- def _validate_title(cls, value: str | None) -> str | None:- if value is None:- return None- return _require_non_blank(value, label="title")-- @model_validator(mode="after")- def _validate_unique_ids(self) -> AskHumanToolArgs:- field_names: set[str] = set()- for field in self.fields:- if field.name in field_names:- raise ValueError(f"field name '{field.name}' must be unique")- field_names.add(field.name)-- action_ids: set[str] = set()- for action in self.actions:- if action.id in action_ids:- raise ValueError(f"action id '{action.id}' must be unique")- action_ids.add(action.id)- return self---class AskHumanToolResult(BaseModel):- """Expected value shape for a later deferred ask-human tool result."""-- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")-- status: AskHumanResultStatus- action: AskHumanSelectedAction | None = None- values: dict[str, JsonValue] = Field(default_factory=dict)- message: str | None = None- rendered_content: str | None = None---__all__ = [- "AskHumanAction",- "AskHumanActionStyle",- "AskHumanField",- "AskHumanFieldType",- "AskHumanFileField",- "AskHumanFileListField",- "AskHumanParagraphField",- "AskHumanResultStatus",- "AskHumanSelectField",- "AskHumanSelectOption",- "AskHumanSelectedAction",- "AskHumanToolArgs",- "AskHumanToolResult",- "AskHumanUrgency",- "is_valid_identifier",-]diff --git a/dify-agent/src/dify_agent/layers/config/__init__.py b/dify-agent/src/dify_agent/layers/config/__init__.pyindex f5c3d0c4b3a..c5fea5d92a5 100644--- a/dify-agent/src/dify_agent/layers/config/__init__.py+++ b/dify-agent/src/dify_agent/layers/config/__init__.py@@ -1,7 +1,6 @@"""Client-safe exports for the Dify config runtime catalog DTOs."""from dify_agent.layers.config.configs import (- DIFY_CONFIG_LAYER_TYPE_ID,DifyConfigFileConfig,DifyConfigLayerConfig,DifyConfigRuntimeState,@@ -10,7 +9,6 @@ from dify_agent.layers.config.configs import ()__all__ = [- "DIFY_CONFIG_LAYER_TYPE_ID","DifyConfigFileConfig","DifyConfigLayerConfig","DifyConfigRuntimeState",diff --git a/dify-agent/src/dify_agent/layers/config/configs.py b/dify-agent/src/dify_agent/layers/config/configs.pyindex 5f8eae360eb..664b14083b4 100644--- a/dify-agent/src/dify_agent/layers/config/configs.py+++ b/dify-agent/src/dify_agent/layers/config/configs.py@@ -1,14 +1,9 @@"""Client-safe DTOs for the Dify config declaration layer."""-from typing import ClassVar, Final, Literal+from typing import ClassVar, Literalfrom pydantic import BaseModel, ConfigDict, Field-from agenton.layers import LayerConfig---DIFY_CONFIG_LAYER_TYPE_ID: Final[str] = "dify.config"-class DifyConfigVersionConfig(BaseModel):"""Agent config version metadata visible to the runtime prompt."""@@ -41,9 +36,11 @@ class DifyConfigFileConfig(BaseModel):model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")-class DifyConfigLayerConfig(LayerConfig):+class DifyConfigLayerConfig(BaseModel):"""Agent Soul config context plus eager-pull instructions for prompt mentions."""+ shell: str = "shell"+agent_id: str | None = Noneconfig_version: DifyConfigVersionConfig | None = Noneskills: list[DifyConfigSkillConfig] = Field(default_factory=list)@@ -57,30 +54,15 @@ class DifyConfigLayerConfig(LayerConfig):class DifyConfigRuntimeState(BaseModel):- """Serializable config-layer values computed once during context entry.-- ``config_cli_help`` stores pre-rendered shell-visible ``dify-agent`` help snippets- for config commands and file upload/download commands.-- The ``push_spec_*`` fields are compatibility leftovers from the removed root- JSON-spec config mutation workflow. This change keeps them in the runtime-state- schema to avoid snapshot churn, but new code should treat them as inert- compatibility fields rather than active prompt data.- """+ """Persisted outputs of completed shell-backed config pulls."""pulled_skill_outputs: dict[str, str] = Field(default_factory=dict)pulled_file_outputs: dict[str, str] = Field(default_factory=dict)- config_context_json: str = ""- config_cli_help: dict[str, str] = Field(default_factory=dict)- push_spec_semantics: str = ""- push_spec_json_schema: str = ""- push_spec_example: str = ""model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", validate_assignment=True)__all__ = [- "DIFY_CONFIG_LAYER_TYPE_ID","DifyConfigFileConfig","DifyConfigLayerConfig","DifyConfigRuntimeState",diff --git a/dify-agent/src/dify_agent/layers/config/layer.py b/dify-agent/src/dify_agent/layers/config/layer.pyindex 730cdc6b15c..08060a4dea0 100644--- a/dify-agent/src/dify_agent/layers/config/layer.py+++ b/dify-agent/src/dify_agent/layers/config/layer.py@@ -1,23 +1,29 @@-"""Runtime Dify config layer with shell-backed eager pulls."""+"""Shell-backed config pulls with instructions derived from current Config.++Only pull results and successful initialization persist. The manifest and CLI+help are rendered from current configuration and the installed CLI reference.+"""from __future__ import annotationsimport jsonimport shlexfrom dataclasses import dataclass-from typing import ClassVar+from typing import override-from typing_extensions import Self, override-from agenton.layers import LayerDeps, PlainLayer+from pydantic_ai import RunContext+from pydantic_ai.capabilities import AbstractCapability, CapabilityOrdering+from pydantic_ai.capabilities.abstract import WrapRunHandler+from pydantic_ai.run import AgentRunResult+from dify_agent.runtime.context import Depsfrom dify_agent.layers._agent_cli_help import render_agent_stub_cli_helpfrom dify_agent.layers._agent_file_cli_help import AGENT_FILE_UPLOAD_REPLY_HINT as _AGENT_FILE_UPLOAD_REPLY_HINTfrom dify_agent.layers.config.configs import (- DIFY_CONFIG_LAYER_TYPE_ID,DifyConfigLayerConfig,DifyConfigRuntimeState,)-from dify_agent.layers.shell.layer import DifyShellLayer+from dify_agent.layers.shell.layer import Capability as ShellCapability, ShellSession_CONFIG_CONTEXT_HEADING = "Current Agent config manifest for this run:"_CONFIG_CONTEXT_COMMAND = "dify-agent config manifest"@@ -52,64 +58,65 @@ _AGENT_FILE_CLI_HELP_COMMANDS: dict[str, tuple[str, ...]] = {"dify-agent file public-url --help": ("file", "public-url"),"dify-agent file download --help": ("file", "download"),}-_CONFIG_CONTEXT_EXCLUDE = {"mentioned_skill_names": True, "mentioned_file_names": True}+_CONFIG_CONTEXT_EXCLUDE = {"mentioned_skill_names": True, "mentioned_file_names": True, "shell": True}class DifyConfigLayerError(RuntimeError):"""Raised when one eager-pull config operation fails."""-class DifyConfigDeps(LayerDeps):- shell: DifyShellLayer # pyright: ignore[reportUninitializedInstanceVariable]+class Config(DifyConfigLayerConfig):+ pass-@dataclass(slots=True)-class DifyConfigLayer(PlainLayer[DifyConfigDeps, DifyConfigLayerConfig, DifyConfigRuntimeState]):- """Config runtime layer that materializes prompt-mentioned targets via shell."""+class State(DifyConfigRuntimeState):+ initialized: bool = False- type_id: ClassVar[str | None] = DIFY_CONFIG_LAYER_TYPE_ID- config: DifyConfigLayerConfig+class Capability(AbstractCapability[Deps]):+ """First-run eager pulls with explicit JSON writeback and native ordering."""- @classmethod- @override- def from_config(cls, config: DifyConfigLayerConfig) -> Self:- return cls(config=DifyConfigLayerConfig.model_validate(config))+ def __init__(self, name: str):+ self.id = name+ self.name = name- @property@override- def prefix_prompts(self) -> list[str]:- return [self.build_prompt_context()]+ def get_ordering(self) -> CapabilityOrdering:+ return CapabilityOrdering(wrapped_by=[ShellCapability], requires=[ShellCapability])- @property@override- def suffix_prompts(self) -> list[str]:- return [self.build_suffix_prompt()]+ def get_instructions(self):+ return self._instructions- @override- async def on_context_create(self) -> None:- await self._initialize_context()+ def _instructions(self, ctx: RunContext[Deps]) -> str:+ context = self._context(ctx.deps)+ return f"{context.build_prompt_context()}\n\n{context.build_suffix_prompt()}"++ def _context(self, deps: Deps) -> _ConfigContext:+ config = Config.model_validate(deps.layers[self.name]["config"])+ return _ConfigContext(+ config, State.model_validate(deps.layers[self.name]["state"]), deps.resources.shells[config.shell]+ )@override- async def on_context_resume(self) -> None:- return None+ async def wrap_run(self, ctx: RunContext[Deps], *, handler: WrapRunHandler) -> AgentRunResult:+ context = self._context(ctx.deps)+ try:+ if not context.runtime_state.initialized:+ await context._pull_mentioned_targets()+ context.runtime_state.initialized = True+ finally:+ ctx.deps.layers[self.name]["state"] = context.runtime_state.model_dump(mode="json")+ return await handler()- async def _initialize_context(self) -> None:- self._initialize_runtime_prompt_state()- await self._pull_mentioned_targets()- def _initialize_runtime_prompt_state(self) -> None:- command_paths = dict(_CONFIG_CLI_HELP_COMMANDS)- if self._config_writable:- command_paths.update(_CONFIG_CLI_MUTATION_HELP_COMMANDS)- command_paths.update(_AGENT_FILE_CLI_HELP_COMMANDS)- self.runtime_state.config_context_json = self._format_config_context_json()- self.runtime_state.config_cli_help = {- command: render_agent_stub_cli_help(args) for command, args in command_paths.items()- }- self.runtime_state.push_spec_semantics = ""- self.runtime_state.push_spec_json_schema = ""- self.runtime_state.push_spec_example = ""+@dataclass+class _ConfigContext:+ """Short-lived validated data for prompt rendering or an eager-pull operation."""++ config: Config+ runtime_state: State+ shell: ShellSessiondef build_prompt_context(self) -> str:sections: list[str] = []@@ -141,17 +148,11 @@ class DifyConfigLayer(PlainLayer[DifyConfigDeps, DifyConfigLayerConfig, DifyConfreturn "\n\n".join(section for section in sections if section)def build_suffix_prompt(self) -> str:- sections: list[str] = []- if self.runtime_state.config_context_json:- sections.append(- f"{_CONFIG_CONTEXT_HEADING}\n"- f"{_format_command_output(_CONFIG_CONTEXT_COMMAND, self.runtime_state.config_context_json)}"- )- usage_lines = [_CONFIG_CLI_USAGE_PROMPT]- if cli_help := self._format_config_cli_help():- usage_lines.append(cli_help)- if file_cli_help := self._format_agent_file_cli_help():- usage_lines.append(file_cli_help)+ sections = [+ f"{_CONFIG_CONTEXT_HEADING}\n"+ f"{_format_command_output(_CONFIG_CONTEXT_COMMAND, self._format_config_context_json())}"+ ]+ usage_lines = [_CONFIG_CLI_USAGE_PROMPT, self._format_config_cli_help(), self._format_agent_file_cli_help()]sections.append("\n".join(usage_lines))return "\n\n".join(section for section in sections if section)@@ -160,26 +161,19 @@ class DifyConfigLayer(PlainLayer[DifyConfigDeps, DifyConfigLayerConfig, DifyConfreturn self.config.config_version is not None and self.config.config_version.writabledef _format_config_cli_help(self) -> str:- commands = list(_CONFIG_CLI_HELP_COMMANDS)+ commands = dict(_CONFIG_CLI_HELP_COMMANDS)if self._config_writable:- commands.extend(_CONFIG_CLI_MUTATION_HELP_COMMANDS)+ commands.update(_CONFIG_CLI_MUTATION_HELP_COMMANDS)command_sections = [- _format_command_output(command, self.runtime_state.config_cli_help[command])- for command in commands- if command in self.runtime_state.config_cli_help+ _format_command_output(command, render_agent_stub_cli_help(args)) for command, args in commands.items()]- if not command_sections:- return ""return "Agent config CLI reference for installed `dify-agent`:\n" + "\n\n".join(command_sections)def _format_agent_file_cli_help(self) -> str:command_sections = [- _format_command_output(command, self.runtime_state.config_cli_help[command])- for command in _AGENT_FILE_CLI_HELP_COMMANDS- if command in self.runtime_state.config_cli_help+ _format_command_output(command, render_agent_stub_cli_help(args))+ for command, args in _AGENT_FILE_CLI_HELP_COMMANDS.items()]- if not command_sections:- return ""return ("Agent file CLI reference for installed `dify-agent`:\n"+ "\n\n".join(command_sections)@@ -210,7 +204,7 @@ class DifyConfigLayer(PlainLayer[DifyConfigDeps, DifyConfigLayerConfig, DifyConfself.runtime_state.pulled_file_outputs = _parse_file_pull_outputs(output, names)async def _run_mentioned_pull(self, *, script: str, target_kind: str) -> str:- result = await self.deps.shell.run_remote_script(+ result = await self.shell.run_remote_script(script,inject_agent_stub_env=True,)@@ -296,4 +290,4 @@ def _format_command_output(command: str, output: str) -> str:return f"Command:\n$ {command}\nOutput:\n{output}"-__all__ = ["DifyConfigLayer", "DifyConfigLayerError"]+__all__ = ["Config", "State", "Capability", "DifyConfigLayerError"]diff --git a/dify-agent/src/dify_agent/layers/dify_core_tools/__init__.py b/dify-agent/src/dify_agent/layers/dify_core_tools/__init__.pyindex dd8b09574cf..24eaeb9a1dd 100644--- a/dify-agent/src/dify_agent/layers/dify_core_tools/__init__.py+++ b/dify-agent/src/dify_agent/layers/dify_core_tools/__init__.py@@ -1,14 +1,12 @@"""Client-safe exports for the Dify core-tools layer DTOs and type ids."""from dify_agent.layers.dify_core_tools.configs import (- DIFY_CORE_TOOLS_LAYER_TYPE_ID,DifyCoreToolConfig,DifyCoreToolProviderType,DifyCoreToolsLayerConfig,)__all__ = [- "DIFY_CORE_TOOLS_LAYER_TYPE_ID","DifyCoreToolConfig","DifyCoreToolProviderType","DifyCoreToolsLayerConfig",diff --git a/dify-agent/src/dify_agent/layers/dify_core_tools/configs.py b/dify-agent/src/dify_agent/layers/dify_core_tools/configs.pyindex 19a25898cf8..dc6ddb5f694 100644--- a/dify-agent/src/dify_agent/layers/dify_core_tools/configs.py+++ b/dify-agent/src/dify_agent/layers/dify_core_tools/configs.py@@ -1,4 +1,4 @@-"""Client-safe DTOs for the Dify core-tools Agenton layer.+"""Client-safe DTOs for the Dify core-tools layer.This layer exposes API-routed tool invocations for the Dify-owned providerfamilies that should execute inside the API service boundary: `plugin`,@@ -9,23 +9,20 @@ not need to inspect provider internals or storage state.from __future__ import annotations-from typing import ClassVar, Final, Literal+from typing import ClassVar, Literal-from pydantic import ConfigDict, Field, JsonValue+from pydantic import BaseModel, ConfigDict, Field, JsonValue-from agenton.layers import LayerConfigfrom dify_agent.layers.dify_plugin.configs import DifyPluginToolParametertype DifyCoreToolProviderType = Literal["plugin", "builtin", "api", "workflow", "mcp"]-DIFY_CORE_TOOLS_LAYER_TYPE_ID: Final[str] = "dify.core.tools"-def _default_parameters_json_schema() -> dict[str, JsonValue]:return {"type": "object", "properties": {}, "required": []}-class DifyCoreToolConfig(LayerConfig):+class DifyCoreToolConfig(BaseModel):"""Prepared API-routed tool declaration exposed to the model."""provider_type: DifyCoreToolProviderType@@ -41,9 +38,11 @@ class DifyCoreToolConfig(LayerConfig):model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", arbitrary_types_allowed=True)-class DifyCoreToolsLayerConfig(LayerConfig):+class DifyCoreToolsLayerConfig(BaseModel):"""Public config for the Dify core-tools layer."""+ execution_context: str = "execution_context"+tools: list[DifyCoreToolConfig] = Field(default_factory=list)model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", arbitrary_types_allowed=True)diff --git a/dify-agent/src/dify_agent/layers/dify_core_tools/layer.py b/dify-agent/src/dify_agent/layers/dify_core_tools/layer.pyindex fcd4e7eede4..0b8c5725e48 100644--- a/dify-agent/src/dify_agent/layers/dify_core_tools/layer.py+++ b/dify-agent/src/dify_agent/layers/dify_core_tools/layer.py@@ -10,89 +10,69 @@ provider-local state stay in the API process.from __future__ import annotationsfrom copy import deepcopy-from dataclasses import dataclass-from typing import ClassVar, cast+from dataclasses import replace+from typing import cast, override-import httpxfrom pydantic import JsonValuefrom pydantic_ai import RunContext, Toolfrom pydantic_ai.tools import ToolDefinition-from typing_extensions import Self, override-from agenton.layers import LayerDeps, PlainLayer+from pydantic import BaseModel, ConfigDict+from pydantic_ai.toolsets import FunctionToolset+from dify_agent.runtime.context import Depsfrom dify_agent.layers.dify_core_tools.client import (DifyCoreToolsClient,DifyCoreToolsClientConfigurationError,DifyCoreToolsClientError,)from dify_agent.layers.dify_core_tools.configs import (- DIFY_CORE_TOOLS_LAYER_TYPE_ID,DifyCoreToolConfig,DifyCoreToolsLayerConfig,)from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer+CORE_TOOL_STRICT = FalseTEMPORARY_UNAVAILABLE_OBSERVATION = "Tool is temporarily unavailable. Please continue without it if possible."-class DifyCoreToolsDeps(LayerDeps):- """Dependencies required by `DifyCoreToolsLayer`."""+class Config(DifyCoreToolsLayerConfig):+ pass- execution_context: DifyExecutionContextLayer # pyright: ignore[reportUninitializedInstanceVariable]+class State(BaseModel):+ model_config = ConfigDict(extra="forbid")-@dataclass(slots=True)-class DifyCoreToolsLayer(PlainLayer[DifyCoreToolsDeps, DifyCoreToolsLayerConfig]):- """Layer that resolves API-routed Dify tools into Pydantic AI tools."""- type_id: ClassVar[str | None] = DIFY_CORE_TOOLS_LAYER_TYPE_ID+class Toolset(FunctionToolset[Deps]):+ """Expose API-prepared schemas and borrow the lifespan API client."""- config: DifyCoreToolsLayerConfig- inner_api_url: str- inner_api_key: str+ def __init__(self, name: str):+ super().__init__(id=name)+ self.name = name+ self._loaded = False- @classmethod@override- def from_config(cls, config: DifyCoreToolsLayerConfig) -> Self:- del config- raise TypeError("DifyCoreToolsLayer requires server-side Dify API settings and must use a provider factory.")-- @classmethod- def from_config_with_settings(- cls,- config: DifyCoreToolsLayerConfig,- *,- inner_api_url: str,- inner_api_key: str,- ) -> Self:- return cls(- config=DifyCoreToolsLayerConfig.model_validate(config),- inner_api_url=inner_api_url,- inner_api_key=inner_api_key,- )-- async def get_tools(self, *, http_client: httpx.AsyncClient) -> list[Tool[object]]:- if http_client.is_closed:- raise RuntimeError("DifyCoreToolsLayer.get_tools() requires an open shared HTTP client.")-- execution_context = self.deps.execution_context.config- client = DifyCoreToolsClient(- base_url=self.inner_api_url,- api_key=self.inner_api_key,- http_client=http_client,- )- tools: list[Tool[object]] = []- for tool_config in self.config.tools:- tools.append(- self._build_tool(- client=client,- execution_context=execution_context,- tool_config=tool_config,- )+ async def get_tools(self, ctx: RunContext[Deps]):+ if not self._loaded:+ config = Config.model_validate(ctx.deps.layers[self.name]["config"])+ execution_context = DifyExecutionContextLayerConfig.model_validate(+ ctx.deps.layers[config.execution_context]["config"])- return tools+ http_client = ctx.deps.services.dify_api_http_client+ if http_client.is_closed:+ raise RuntimeError("Core tools require an open shared HTTP client.")+ client = DifyCoreToolsClient(+ base_url=ctx.deps.services.inner_api_url,+ api_key=ctx.deps.services.inner_api_key,+ http_client=http_client,+ )+ for tool_config in config.tools:+ self.add_tool(+ self._build_tool(client=client, execution_context=execution_context, tool_config=tool_config)+ )+ self._loaded = True+ return await super().get_tools(ctx)@staticmethoddef _build_tool(@@ -100,12 +80,12 @@ class DifyCoreToolsLayer(PlainLayer[DifyCoreToolsDeps, DifyCoreToolsLayerConfig]client: DifyCoreToolsClient,execution_context: DifyExecutionContextLayerConfig,tool_config: DifyCoreToolConfig,- ) -> Tool[object]:+ ) -> Tool[Deps]:tool_name = tool_config.name or tool_config.tool_nametool_description = tool_config.description or tool_nametool_schema = deepcopy(tool_config.parameters_json_schema)- async def invoke_tool(_ctx: RunContext[object], **tool_arguments: object) -> str:+ async def invoke_tool(_ctx: RunContext[Deps], **tool_arguments: object) -> str:try:response = await client.invoke(execution_context=execution_context,@@ -118,20 +98,8 @@ class DifyCoreToolsLayer(PlainLayer[DifyCoreToolsDeps, DifyCoreToolsLayerConfig]except DifyCoreToolsClientError as exc:return _tool_error_text(tool_name=tool_name, error=exc)- async def prepare_tool_definition(_ctx: RunContext[object], tool_def: ToolDefinition) -> ToolDefinition:- return ToolDefinition(- name=tool_def.name,- description=tool_def.description,- parameters_json_schema=tool_schema,- strict=CORE_TOOL_STRICT,- sequential=tool_def.sequential,- metadata=tool_def.metadata,- timeout=tool_def.timeout,- defer_loading=tool_def.defer_loading,- kind=tool_def.kind,- return_schema=tool_def.return_schema,- include_return_schema=tool_def.include_return_schema,- )+ async def prepare_tool_definition(_ctx: RunContext[Deps], tool_def: ToolDefinition) -> ToolDefinition:+ return replace(tool_def, parameters_json_schema=tool_schema, strict=CORE_TOOL_STRICT)return Tool(invoke_tool,@@ -161,4 +129,4 @@ def _tool_error_text(*, tool_name: str, error: DifyCoreToolsClientError) -> str:return f"tool invoke error: {error}"-__all__ = ["DifyCoreToolsDeps", "DifyCoreToolsLayer"]+__all__ = ["Config", "State", "Toolset"]diff --git a/dify-agent/src/dify_agent/layers/dify_plugin/__init__.py b/dify-agent/src/dify_agent/layers/dify_plugin/__init__.pyindex bd719cea8f5..138f0d78c21 100644--- a/dify-agent/src/dify_agent/layers/dify_plugin/__init__.py+++ b/dify-agent/src/dify_agent/layers/dify_plugin/__init__.py@@ -5,8 +5,6 @@ dependencies. Keep this package root import-safe for client-only installs."""from dify_agent.layers.dify_plugin.configs import (- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,- DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,DifyPluginCredentialValue,DifyPluginLLMLayerConfig,DifyPluginToolCredentialType,@@ -20,8 +18,6 @@ from dify_agent.layers.dify_plugin.configs import ()__all__ = [- "DIFY_PLUGIN_LLM_LAYER_TYPE_ID",- "DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID","DifyPluginCredentialValue","DifyPluginLLMLayerConfig","DifyPluginToolCredentialType",diff --git a/dify-agent/src/dify_agent/layers/dify_plugin/configs.py b/dify-agent/src/dify_agent/layers/dify_plugin/configs.pyindex ad289c055d8..8c81467ad07 100644--- a/dify-agent/src/dify_agent/layers/dify_plugin/configs.py+++ b/dify-agent/src/dify_agent/layers/dify_plugin/configs.py@@ -1,4 +1,4 @@-"""Client-safe DTOs for Dify plugin-backed Agenton business layers.+"""Client-safe DTOs for Dify plugin-backed business layers.This module intentionally contains only public config schemas and scalar typealiases plus stable plugin business-layer type identifiers. Runtime objects@@ -15,19 +15,15 @@ re-fetch and re-merge tool declarations at execution time."""from enum import StrEnum-from typing import ClassVar, Final, Literal, TypeAlias+from typing import ClassVar, Literal, TypeAliasfrom pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator, model_validatorfrom pydantic_ai.settings import ModelSettings-from agenton.layers import LayerConfig-DifyPluginCredentialValue: TypeAlias = str | int | float | bool | NoneDifyPluginToolCredentialType: TypeAlias = Literal["api-key", "oauth2", "unauthorized"]DifyPluginToolValue: TypeAlias = JsonValue-DIFY_PLUGIN_LLM_LAYER_TYPE_ID: Final[str] = "dify.plugin.llm"-DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID: Final[str] = "dify.plugin.tools"def _default_parameters_json_schema() -> dict[str, JsonValue]:@@ -106,9 +102,11 @@ class DifyPluginToolParameter(BaseModel):model_config: ClassVar[ConfigDict] = ConfigDict(extra="ignore", from_attributes=True)-class DifyPluginLLMLayerConfig(LayerConfig):+class DifyPluginLLMLayerConfig(BaseModel):"""Public config for selecting a plugin-backed business provider/model."""+ execution_context: str = "execution_context"+plugin_id: strmodel_provider: strmodel: str@@ -127,7 +125,7 @@ class DifyPluginLLMLayerConfig(LayerConfig):return value-class DifyPluginToolConfig(LayerConfig):+class DifyPluginToolConfig(BaseModel):"""Public config for exposing one plugin tool to the agent model.``credential_type`` is an explicit caller-supplied daemon transport choice,@@ -160,21 +158,22 @@ class DifyPluginToolConfig(LayerConfig):model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", arbitrary_types_allowed=True)-class DifyPluginToolsLayerConfig(LayerConfig):+class DifyPluginToolsLayerConfig(BaseModel):"""Public config for the Dify plugin tools layer.Callers configure the tools layer with this wrapper object and supply oneor more prepared ``DifyPluginToolConfig`` entries in ``tools``."""+ execution_context: str = "execution_context"+ shell: str | None = None+tools: list[DifyPluginToolConfig] = Field(default_factory=list)model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", arbitrary_types_allowed=True)__all__ = [- "DIFY_PLUGIN_LLM_LAYER_TYPE_ID",- "DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID","DifyPluginCredentialValue","DifyPluginLLMLayerConfig","DifyPluginToolCredentialType",diff --git a/dify-agent/src/dify_agent/layers/dify_plugin/llm_layer.py b/dify-agent/src/dify_agent/layers/dify_plugin/llm_layer.pyindex 71e26f22b9e..9ceb79839ef 100644--- a/dify-agent/src/dify_agent/layers/dify_plugin/llm_layer.py+++ b/dify-agent/src/dify_agent/layers/dify_plugin/llm_layer.py@@ -1,77 +1,42 @@-"""Dify plugin LLM model layer.+"""Construct the API-metered model from JSON config and borrowed services."""-This layer owns model capability resolution for Dify plugin-backed LLMs. It-depends on ``DifyExecutionContextLayer`` for shared request context through-Agenton's direct dependency binding and returns a Pydantic AI model adapter-configured from the public LLM layer DTO. Runtime code supplies the FastAPI-lifespan-owned shared HTTP client to ``get_model``; the layer does not own or-discover live resources. The API provider carries plugin transport identity,-while the DTO's ``model_provider`` is passed to the adapter as request-level-model identity.-"""+from pydantic import BaseModel, ConfigDict+from pydantic_ai.capabilities import AbstractCapability-from dataclasses import dataclass, field-from typing import ClassVar--import httpx-from typing_extensions import Self, override--from agenton.layers import LayerDeps, PlainLayerfrom dify_agent.adapters.llm import DifyApiLLMProvider, DifyLLMAdapterModel-from dify_agent.layers.dify_plugin.configs import DIFY_PLUGIN_LLM_LAYER_TYPE_ID, DifyPluginLLMLayerConfig-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer---class DifyPluginLLMDeps(LayerDeps):- """Dependencies required by ``DifyPluginLLMLayer``."""+from dify_agent.layers.dify_plugin.configs import DifyPluginLLMLayerConfig+from dify_agent.layers.execution_context.layer import Config as ExecutionContextConfig+from dify_agent.runtime.context import Deps- execution_context: DifyExecutionContextLayer # pyright: ignore[reportUninitializedInstanceVariable]+class Config(DifyPluginLLMLayerConfig):+ pass-@dataclass(slots=True)-class DifyPluginLLMLayer(PlainLayer[DifyPluginLLMDeps, DifyPluginLLMLayerConfig]):- """Layer that creates the Dify API-backed Pydantic AI model."""- type_id: ClassVar[str | None] = DIFY_PLUGIN_LLM_LAYER_TYPE_ID+class State(BaseModel):+ model_config = ConfigDict(extra="forbid")- config: DifyPluginLLMLayerConfig- inner_api_url: str = "http://localhost:5001"- inner_api_key: str = field(default="", repr=False)- @classmethod- @override- def from_config(cls, config: DifyPluginLLMLayerConfig) -> Self:- """Create the LLM layer from validated public config."""- return cls(config=config)+class Capability(AbstractCapability[Deps]):+ def __init__(self, name: str):+ self.id = name+ self.name = name- @classmethod- def from_config_with_settings(- cls,- config: DifyPluginLLMLayerConfig,- *,- inner_api_url: str,- inner_api_key: str,- ) -> Self:- return cls(config=config, inner_api_url=inner_api_url.rstrip("/"), inner_api_key=inner_api_key)-- def get_model(self, *, http_client: httpx.AsyncClient, agent_run_id: str) -> DifyLLMAdapterModel:- """Return the configured model through the API-owned metered gateway."""- if http_client.is_closed:- raise RuntimeError("DifyPluginLLMLayer.get_model() requires an open Dify API HTTP client.")+ def build_model(self, deps: Deps) -> DifyLLMAdapterModel:+ config = Config.model_validate(deps.layers[self.name]["config"])+ if deps.services.dify_api_http_client.is_closed:+ raise RuntimeError("Model execution requires an open Dify API HTTP client.")provider = DifyApiLLMProvider(- plugin_id=self.config.plugin_id,- inner_api_url=self.inner_api_url,- inner_api_key=self.inner_api_key,- execution_context=self.deps.execution_context.config,- agent_run_id=agent_run_id,- http_client=http_client,+ plugin_id=config.plugin_id,+ inner_api_url=deps.services.inner_api_url,+ inner_api_key=deps.services.inner_api_key,+ execution_context=ExecutionContextConfig.model_validate(deps.layers[config.execution_context]["config"]),+ agent_run_id=deps.run_id,+ http_client=deps.services.dify_api_http_client,)return DifyLLMAdapterModel(- model=self.config.model,+ model=config.model,dify_provider=provider,- model_provider=self.config.model_provider,- model_settings=self.config.model_settings,+ model_provider=config.model_provider,+ model_settings=config.model_settings,)---__all__ = ["DifyPluginLLMDeps", "DifyPluginLLMLayer"]diff --git a/dify-agent/src/dify_agent/layers/dify_plugin/tools_layer.py b/dify-agent/src/dify_agent/layers/dify_plugin/tools_layer.pyindex 6e43566e589..f48cc948114 100644--- a/dify-agent/src/dify_agent/layers/dify_plugin/tools_layer.py+++ b/dify-agent/src/dify_agent/layers/dify_plugin/tools_layer.py@@ -17,19 +17,18 @@ from copy import deepcopyimport jsonimport mimetypesfrom collections.abc import Mapping, Sequence-from dataclasses import dataclass, field-from typing import ClassVar+from dataclasses import dataclass, field, replace+from typing import ClassVar, overridefrom urllib.parse import urlparseimport httpxfrom pydantic import BaseModel, ConfigDict, JsonValue, ValidationErrorfrom pydantic_ai import RunContext, Toolfrom pydantic_ai.tools import ToolDefinition-from typing_extensions import Self, override-from agenton.layers import LayerDeps, PlainLayer+from pydantic_ai.toolsets import FunctionToolset+from dify_agent.runtime.context import Depsfrom dify_agent.layers.dify_plugin.configs import (- DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,DifyPluginToolConfig,DifyPluginToolParameter,DifyPluginToolParameterForm,@@ -42,8 +41,7 @@ from dify_agent.layers.dify_plugin.tool_client import (DifyPluginToolInvokeMessage,)from dify_agent.layers.execution_context.configs import DifyExecutionContextLayerConfig-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer-from dify_agent.layers.shell.layer import DifyShellLayer+from dify_agent.layers.execution_context.layer import Capability as ExecutionContextCapability# Plugin tools intentionally do not expose a per-tool strictness override in the@@ -58,13 +56,6 @@ _FILE_UPLOAD_TIMEOUT_SECONDS = 60.0_SUPPORTED_REMOTE_URL_PREFIXES = ("http://", "https://")-class DifyPluginToolsDeps(LayerDeps):- """Dependencies required by ``DifyPluginToolsLayer``."""-- execution_context: DifyExecutionContextLayer # pyright: ignore[reportUninitializedInstanceVariable]- shell: DifyShellLayer | None # pyright: ignore[reportUninitializedInstanceVariable]--class DifyPluginToolsClientConfigurationError(ValueError):"""Raised when local plugin-tool file conversion preconditions are missing."""@@ -154,81 +145,64 @@ class _DifyPluginToolFileClient:raise DifyPluginToolClientError("Invalid Dify API file download data.") from exc-@dataclass(slots=True)-class DifyPluginToolsLayer(PlainLayer[DifyPluginToolsDeps, DifyPluginToolsLayerConfig]):- """Layer that resolves Dify plugin tools into Pydantic AI tools."""+class Config(DifyPluginToolsLayerConfig):+ pass- type_id: ClassVar[str | None] = DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID- config: DifyPluginToolsLayerConfig- inner_api_url: str- inner_api_key: str+class State(BaseModel):+ model_config = ConfigDict(extra="forbid")- @classmethod- @override- def from_config(cls, config: DifyPluginToolsLayerConfig) -> Self:- """Reject construction without server-injected Dify API settings."""- del config- raise TypeError("DifyPluginToolsLayer requires server-side Dify API settings and must use a provider factory.")-- @classmethod- def from_config_with_settings(- cls,- config: DifyPluginToolsLayerConfig,- *,- inner_api_url: str,- inner_api_key: str,- ) -> Self:- return cls(- config=DifyPluginToolsLayerConfig.model_validate(config),- inner_api_url=inner_api_url,- inner_api_key=inner_api_key,- )- async def get_tools(- self,- *,- http_client: httpx.AsyncClient,- dify_api_http_client: httpx.AsyncClient,- ) -> list[Tool[object]]:- """Build Pydantic AI tool adapters from prepared plugin tool config."""- if dify_api_http_client.is_closed:- raise RuntimeError("DifyPluginToolsLayer.get_tools() requires an open shared Dify API HTTP client.")-- tool_clients: dict[str, DifyPluginDaemonToolClient] = {}- tools: list[Tool[object]] = []- file_client = _DifyPluginToolFileClient(- base_url=self.inner_api_url,- api_key=self.inner_api_key,- http_client=dify_api_http_client,- )- file_context = _PluginToolFileContext(- file_client=file_client,- execution_context=self.deps.execution_context.config,- shell=self.deps.shell,- )+class Toolset(FunctionToolset[Deps]):+ """Prepare native tools once per run; all clients and shell resources are borrowed."""- for tool_config in self.config.tools:- client = tool_clients.get(tool_config.plugin_id)- if client is None:- client = self.deps.execution_context.create_tool_client(- plugin_id=tool_config.plugin_id,- http_client=http_client,- )- tool_clients[tool_config.plugin_id] = client- effective_parameters = [parameter.model_copy(deep=True) for parameter in tool_config.parameters]- _validate_required_hidden_parameters(tool_config, effective_parameters)-- tools.append(- _build_pydantic_ai_tool(- client=client,- tool_config=tool_config,- effective_parameters=effective_parameters,- file_context=file_context,- )- )+ def __init__(self, name: str):+ super().__init__(id=name)+ self.name = name+ self._loaded = False- return tools+ @override+ async def get_tools(self, ctx: RunContext[Deps]):+ if not self._loaded:+ config = Config.model_validate(ctx.deps.layers[self.name]["config"])+ services = ctx.deps.services+ if services.dify_api_http_client.is_closed:+ raise RuntimeError("Plugin tools require an open shared Dify API HTTP client.")+ tool_clients: dict[str, DifyPluginDaemonToolClient] = {}+ file_context = _PluginToolFileContext(+ file_client=_DifyPluginToolFileClient(+ base_url=services.inner_api_url,+ api_key=services.inner_api_key,+ http_client=services.dify_api_http_client,+ ),+ execution_context=DifyExecutionContextLayerConfig.model_validate(+ ctx.deps.layers[config.execution_context]["config"]+ ),+ deps=ctx.deps,+ shell=config.shell,+ )+ for tool_config in config.tools:+ client = tool_clients.get(tool_config.plugin_id)+ if client is None:+ client = ExecutionContextCapability.create_tool_client(+ ctx.deps,+ config.execution_context,+ plugin_id=tool_config.plugin_id,+ http_client=services.plugin_daemon_http_client,+ )+ tool_clients[tool_config.plugin_id] = client+ effective_parameters = [parameter.model_copy(deep=True) for parameter in tool_config.parameters]+ _validate_required_hidden_parameters(tool_config, effective_parameters)+ self.add_tool(+ _build_pydantic_ai_tool(+ client=client,+ tool_config=tool_config,+ effective_parameters=effective_parameters,+ file_context=file_context,+ )+ )+ self._loaded = True+ return await super().get_tools(ctx)def _validate_required_hidden_parameters(@@ -254,12 +228,12 @@ def _build_pydantic_ai_tool(tool_config: DifyPluginToolConfig,effective_parameters: Sequence[DifyPluginToolParameter],file_context: "_PluginToolFileContext",-) -> Tool[object]:+) -> Tool[Deps]:tool_name = tool_config.name or tool_config.tool_nametool_description = tool_config.description or tool_nametool_schema = deepcopy(tool_config.parameters_json_schema)- async def invoke_tool(_ctx: RunContext[object], **tool_arguments: object) -> str:+ async def invoke_tool(_ctx: RunContext[Deps], **tool_arguments: object) -> str:try:merged_arguments = await _prepare_tool_arguments(effective_parameters,@@ -280,20 +254,8 @@ def _build_pydantic_ai_tool(except ValueError as exc:return f"tool parameters validation error: {exc}, please check your tool parameters"- async def prepare_tool_definition(_ctx: RunContext[object], tool_def: ToolDefinition) -> ToolDefinition:- return ToolDefinition(- name=tool_def.name,- description=tool_def.description,- parameters_json_schema=tool_schema,- strict=PLUGIN_TOOL_STRICT,- sequential=tool_def.sequential,- metadata=tool_def.metadata,- timeout=tool_def.timeout,- defer_loading=tool_def.defer_loading,- kind=tool_def.kind,- return_schema=tool_def.return_schema,- include_return_schema=tool_def.include_return_schema,- )+ async def prepare_tool_definition(_ctx: RunContext[Deps], tool_def: ToolDefinition) -> ToolDefinition:+ return replace(tool_def, parameters_json_schema=tool_schema, strict=PLUGIN_TOOL_STRICT)return Tool(invoke_tool,@@ -352,7 +314,8 @@ async def _prepare_tool_arguments(class _PluginToolFileContext:file_client: _DifyPluginToolFileClientexecution_context: DifyExecutionContextLayerConfig- shell: DifyShellLayer | None+ deps: Deps+ shell: str | Noneasync def to_plugin_file_parameter(self, value: object) -> dict[str, object]:if isinstance(value, str):@@ -389,7 +352,7 @@ class _PluginToolFileContext:f"print('{_FILE_UPLOAD_BEGIN}' + json.dumps(payload, separators=(',', ':')) + '{_FILE_UPLOAD_END}')\n""PY")- result = await self.shell.run_remote_script_complete(+ result = await self.deps.resources.shells[self.shell].run_remote_script_complete(script,timeout=_FILE_UPLOAD_TIMEOUT_SECONDS,inject_agent_stub_env=True,@@ -678,4 +641,4 @@ def _convert_tool_response_to_text(tool_response: Sequence[DifyPluginToolInvokeMreturn "".join(parts)-__all__ = ["DifyPluginToolsDeps", "DifyPluginToolsLayer"]+__all__ = ["Config", "State", "Toolset"]diff --git a/dify-agent/src/dify_agent/layers/execution_context/__init__.py b/dify-agent/src/dify_agent/layers/execution_context/__init__.pyindex 45575faf3e2..356653ae65c 100644--- a/dify-agent/src/dify_agent/layers/execution_context/__init__.py+++ b/dify-agent/src/dify_agent/layers/execution_context/__init__.py@@ -7,7 +7,6 @@ DTO, but that runtime implementation still lives in sibling modules."""from dify_agent.layers.execution_context.configs import (- DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,DifyExecutionContextAgentConfigVersionKind,DifyExecutionContextAgentMode,DifyExecutionContextInvokeFrom,@@ -16,7 +15,6 @@ from dify_agent.layers.execution_context.configs import ()__all__ = [- "DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID","DifyExecutionContextAgentConfigVersionKind","DifyExecutionContextAgentMode","DifyExecutionContextInvokeFrom",diff --git a/dify-agent/src/dify_agent/layers/execution_context/configs.py b/dify-agent/src/dify_agent/layers/execution_context/configs.pyindex afddd7b9344..1f8d1d51453 100644--- a/dify-agent/src/dify_agent/layers/execution_context/configs.py+++ b/dify-agent/src/dify_agent/layers/execution_context/configs.py@@ -1,4 +1,4 @@-"""Client-safe DTOs for the Dify execution-context Agenton layer.+"""Client-safe DTOs for the Dify execution-context layer.This layer carries both Dify product execution context (tenant, user, workflow,invoke source) and Agent backend runtime mode. The product-facing fields are@@ -7,18 +7,15 @@ need to reconstruct Dify API file-access scope without granting the sandbox anydirect inner-API credentials. Knowledge-base layers also read ``user_from`` fromthis shared config so the inner Dify API can distinguish platform-user andend-user searches without making that caller identity model-controlled.-Server-only plugin-daemon settings are injected by the runtime provider factory+Server-only plugin-daemon settings are injected by the runtime runtime servicesand therefore do not appear in this public schema."""-from typing import ClassVar, Final, Literal, TypeAlias+from typing import ClassVar, Literal, TypeAlias-from pydantic import ConfigDict+from pydantic import BaseModel, ConfigDict-from agenton.layers import LayerConfig--DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID: Final[str] = "dify.execution_context"DifyExecutionContextAgentMode: TypeAlias = Literal["workflow_run","single_step",@@ -40,7 +37,7 @@ DifyExecutionContextInvokeFrom: TypeAlias = Literal[]-class DifyExecutionContextLayerConfig(LayerConfig):+class DifyExecutionContextLayerConfig(BaseModel):"""Public config for Dify execution identity and daemon transport context."""tenant_id: str@@ -63,7 +60,6 @@ class DifyExecutionContextLayerConfig(LayerConfig):__all__ = [- "DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID","DifyExecutionContextAgentConfigVersionKind","DifyExecutionContextAgentMode","DifyExecutionContextInvokeFrom",diff --git a/dify-agent/src/dify_agent/layers/execution_context/layer.py b/dify-agent/src/dify_agent/layers/execution_context/layer.pyindex 2e4b726bcda..831ff1f3a89 100644--- a/dify-agent/src/dify_agent/layers/execution_context/layer.py+++ b/dify-agent/src/dify_agent/layers/execution_context/layer.py@@ -1,75 +1,39 @@-"""Runtime Dify execution-context layer.--The public config carries Dify-owned execution identifiers plus the tenant/user-daemon context needed by plugin-backed business layers and the caller identity-needed by knowledge-base layers. Server-only daemon URL-and API key are injected by the provider factory. The layer is intentionally-config/settings-only under Agenton's state-only core: it does not open, cache,-close, or snapshot HTTP clients, and its lifecycle hooks remain the inherited-no-op hooks. Runtime code passes the FastAPI lifespan-owned shared-``httpx.AsyncClient`` into ``create_tool_client`` for each tool invocation.-"""--from dataclasses import dataclass-from typing import ClassVar+"""Dify identity module; clients and transport settings remain lifespan-owned."""import httpx-from typing_extensions import Self, override+from pydantic import BaseModel, ConfigDict+from pydantic_ai.capabilities import AbstractCapability-from agenton.layers import EmptyRuntimeState, NoLayerDeps, PlainLayer+from dify_agent.layers.execution_context.configs import DifyExecutionContextLayerConfigfrom dify_agent.layers.dify_plugin.tool_client import DifyPluginDaemonToolClient-from dify_agent.layers.execution_context.configs import (- DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- DifyExecutionContextLayerConfig,-)-+from dify_agent.runtime.context import Deps-@dataclass(slots=True)-class DifyExecutionContextLayer(PlainLayer[NoLayerDeps, DifyExecutionContextLayerConfig, EmptyRuntimeState]):- """Layer that carries Dify execution context without owning live resources."""- type_id: ClassVar[str | None] = DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID+class Config(DifyExecutionContextLayerConfig):+ pass- config: DifyExecutionContextLayerConfig- daemon_url: str- daemon_api_key: str- @classmethod- @override- def from_config(cls, config: DifyExecutionContextLayerConfig) -> Self:- """Reject construction without server-injected daemon settings."""- del config- raise TypeError(- "DifyExecutionContextLayer requires server-side daemon settings and must use a provider factory."- )+class State(BaseModel):+ model_config = ConfigDict(extra="forbid")- @classmethod- def from_config_with_settings(- cls,- config: DifyExecutionContextLayerConfig,- *,- daemon_url: str,- daemon_api_key: str,- ) -> Self:- """Create the layer from public config plus server-only daemon settings."""- return cls(config=config, daemon_url=daemon_url, daemon_api_key=daemon_api_key)- def create_tool_client(self, *, plugin_id: str, http_client: httpx.AsyncClient) -> DifyPluginDaemonToolClient:- """Return a plugin-daemon tool client backed by the shared HTTP client.+class Capability(AbstractCapability[Deps]):+ def __init__(self, name: str):+ self.id = name+ self.name = name- Raises:- RuntimeError: if ``http_client`` has already been closed.- """+ @staticmethod+ def create_tool_client(+ deps: Deps, name: str, *, plugin_id: str, http_client: httpx.AsyncClient+ ) -> DifyPluginDaemonToolClient:if http_client.is_closed:- raise RuntimeError("DifyExecutionContextLayer.create_tool_client() requires an open shared HTTP client.")+ raise RuntimeError("Plugin tool invocation requires an open shared HTTP client.")+ config = Config.model_validate(deps.layers[name]["config"])return DifyPluginDaemonToolClient(- tenant_id=self.config.tenant_id,+ tenant_id=config.tenant_id,plugin_id=plugin_id,- plugin_daemon_url=self.daemon_url,- plugin_daemon_api_key=self.daemon_api_key,- user_id=self.config.user_id,+ plugin_daemon_url=deps.services.plugin_daemon_url,+ plugin_daemon_api_key=deps.services.plugin_daemon_api_key,+ user_id=config.user_id,http_client=http_client,)---__all__ = ["DifyExecutionContextLayer"]diff --git a/dify-agent/src/dify_agent/layers/history.py b/dify-agent/src/dify_agent/layers/history.pynew file mode 100644index 00000000000..5c7d09d6beb--- /dev/null+++ b/dify-agent/src/dify_agent/layers/history.py@@ -0,0 +1,41 @@+"""Conversation persistence in JSON state; run instructions remain transient."""++from collections.abc import Sequence+from dataclasses import replace++from pydantic import BaseModel, ConfigDict, Field+from pydantic_ai.capabilities import AbstractCapability+from pydantic_ai.messages import ModelMessage, ModelRequest, ModelResponse++from dify_agent.runtime.context import Deps+++class Config(BaseModel):+ model_config = ConfigDict(extra="forbid")+++class State(BaseModel):+ messages: list[ModelMessage] = Field(default_factory=list)+ model_config = ConfigDict(extra="forbid")+++class Capability(AbstractCapability[Deps]):+ def __init__(self, name: str):+ self.id = name+ self.name = name++ def load_messages(self, deps: Deps) -> list[ModelMessage]:+ return State.model_validate(deps.layers[self.name]["state"]).messages++ def save_messages(self, deps: Deps, messages: Sequence[ModelMessage], *, interrupted: bool = False) -> None:+ """Save captured history, closing unexecuted trailing calls on interruption.++ Pydantic AI closes unmatched tool calls on the next user turn when a response+ is marked interrupted, rather than complete.+ """+ persistent = [replace(m, instructions=None) if isinstance(m, ModelRequest) else m for m in messages]+ if interrupted and persistent:+ last = persistent[-1]+ if isinstance(last, ModelResponse) and last.state == "complete" and last.tool_calls:+ persistent[-1] = replace(last, state="interrupted")+ deps.layers[self.name]["state"] = State(messages=persistent).model_dump(mode="json")diff --git a/dify-agent/src/dify_agent/layers/knowledge/__init__.py b/dify-agent/src/dify_agent/layers/knowledge/__init__.pyindex 86a9405bce3..d25893606c1 100644--- a/dify-agent/src/dify_agent/layers/knowledge/__init__.py+++ b/dify-agent/src/dify_agent/layers/knowledge/__init__.py@@ -5,7 +5,6 @@ root stays import-safe for callers that only need to construct run requests."""from dify_agent.layers.knowledge.configs import (- DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID,DifyKnowledgeBaseLayerConfig,DifyKnowledgeDatasetConfig,DifyKnowledgeEagerResult,@@ -21,7 +20,6 @@ from dify_agent.layers.knowledge.configs import ()__all__ = [- "DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID","DifyKnowledgeBaseLayerConfig","DifyKnowledgeDatasetConfig","DifyKnowledgeEagerResult",diff --git a/dify-agent/src/dify_agent/layers/knowledge/configs.py b/dify-agent/src/dify_agent/layers/knowledge/configs.pyindex b7b71ab9c42..36386b50e5f 100644--- a/dify-agent/src/dify_agent/layers/knowledge/configs.py+++ b/dify-agent/src/dify_agent/layers/knowledge/configs.py@@ -1,4 +1,4 @@-"""Client-safe DTOs for the Dify knowledge-base Agenton layer.+"""Client-safe DTOs for the Dify knowledge-base layer.The public layer config carries one or more named knowledge sets. Each set ownsits dataset ids plus query, retrieval, and metadata-filtering policy. Generated-@@ -10,11 +10,10 @@ are kept only in JSON-safe ``runtime_state`` for session snapshots.from __future__ import annotations-from typing import ClassVar, Final, Literal+from typing import ClassVar, Literalfrom pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator, model_validator-from agenton.layers import LayerConfigtype DifyKnowledgeMetadataComparisonOperator = Literal["contains",@@ -37,8 +36,6 @@ type DifyKnowledgeMetadataComparisonOperator = Literal["after",]-DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID: Final[str] = "dify.knowledge_base"-class DifyKnowledgeModelConfig(BaseModel):"""Static model configuration forwarded to the inner retrieval API."""@@ -239,7 +236,7 @@ class DifyKnowledgeEagerResult(BaseModel):class DifyKnowledgeRuntimeState(BaseModel):- """Serializable eager-retrieval state stored in Agenton session snapshots."""+ """Serializable eager-retrieval state stored in session snapshots."""eager_config_fingerprint: str | None = Noneeager_results: list[DifyKnowledgeEagerResult] = Field(default_factory=list)@@ -247,7 +244,7 @@ class DifyKnowledgeRuntimeState(BaseModel):model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", validate_assignment=True)-class DifyKnowledgeBaseLayerConfig(LayerConfig):+class DifyKnowledgeBaseLayerConfig(BaseModel):"""Public config for one knowledge-base layer.The model-visible surface stays fixed to ``knowledge_base_search``. Set@@ -256,6 +253,8 @@ class DifyKnowledgeBaseLayerConfig(LayerConfig):concerns outside the tool schema."""+ execution_context: str = "execution_context"+sets: list[DifyKnowledgeSetConfig]max_result_content_chars: int = Field(default=2000, ge=1)max_observation_chars: int = Field(default=12000, ge=1)@@ -278,7 +277,6 @@ class DifyKnowledgeBaseLayerConfig(LayerConfig):__all__ = [- "DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID","DifyKnowledgeBaseLayerConfig","DifyKnowledgeDatasetConfig","DifyKnowledgeEagerResult",diff --git a/dify-agent/src/dify_agent/layers/knowledge/layer.py b/dify-agent/src/dify_agent/layers/knowledge/layer.pyindex ed1005e40ae..1bd6433ed80 100644--- a/dify-agent/src/dify_agent/layers/knowledge/layer.py+++ b/dify-agent/src/dify_agent/layers/knowledge/layer.py@@ -1,35 +1,39 @@"""Dify knowledge-base layer exposing set-aware retrieval.-The layer depends on ``DifyExecutionContextLayer`` for tenant/app/user/invoke+The layer depends on ``execution-context Config`` for tenant/app/user/invokeidentity. Generated-query sets become one stable model-visible``knowledge_base_search(set_name, query)`` tool, while user-query sets areretrieved eagerly during context entry and exposed as additional user promptcontent. Eager observations are persisted only as JSON-safe runtime state so-Agenton session snapshots can resume without repeating unchanged retrievals.+session snapshots can resume without repeating unchanged retrievals."""from __future__ import annotations-from dataclasses import dataclass+from dataclasses import dataclass, replaceimport hashlibimport jsonimport logging-from typing import ClassVar, cast+from typing import cast, overrideimport httpxfrom pydantic_ai import RunContext, Toolfrom pydantic_ai.tools import ToolDefinition-from typing_extensions import Self, override-from agenton.layers import LayerDeps, PlainLayer-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer+from pydantic_ai.capabilities import AbstractCapability+from pydantic_ai.capabilities.abstract import WrapRunHandler+from pydantic_ai.run import AgentRunResult+from pydantic_ai.toolsets import FunctionToolset+from pydantic_ai.models import ModelRequestContext+from pydantic_ai.messages import ModelRequest, UserPromptPart+from dify_agent.runtime.context import Deps+from dify_agent.layers.execution_context.layer import Config as ExecutionContextConfigfrom dify_agent.layers.knowledge.client import (DifyKnowledgeBaseClient,DifyKnowledgeBaseClientError,DifyKnowledgeRetrieveResponse,)from dify_agent.layers.knowledge.configs import (- DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID,DifyKnowledgeBaseLayerConfig,DifyKnowledgeEagerResult,DifyKnowledgeRuntimeState,@@ -52,49 +56,94 @@ TEMPORARY_UNAVAILABLE_OBSERVATION = ()-class DifyKnowledgeBaseDeps(LayerDeps):- """Dependencies required by ``DifyKnowledgeBaseLayer``."""+class Config(DifyKnowledgeBaseLayerConfig):+ pass- execution_context: DifyExecutionContextLayer # pyright: ignore[reportUninitializedInstanceVariable]+class State(DifyKnowledgeRuntimeState):+ pass-@dataclass(slots=True)-class DifyKnowledgeBaseLayer(- PlainLayer[DifyKnowledgeBaseDeps, DifyKnowledgeBaseLayerConfig, DifyKnowledgeRuntimeState]-):- """Layer that resolves set-scoped knowledge tools and eager user prompts."""- type_id: ClassVar[str | None] = DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID+class Capability(AbstractCapability[Deps]):+ """Eager retrieval and user-context injection plus generated-query tools."""- config: DifyKnowledgeBaseLayerConfig- inner_api_url: str- inner_api_key: str+ def __init__(self, name: str):+ self.id = name+ self.name = name+ self._injected = False- @classmethod@override- def from_config(cls, config: DifyKnowledgeBaseLayerConfig) -> Self:- """Reject construction without server-injected Dify API settings."""- del config- raise TypeError(- "DifyKnowledgeBaseLayer requires server-side Dify API settings and must use a provider factory."- )+ def get_toolset(self) -> FunctionToolset[Deps]:+ return _KnowledgeTools(self.name)- @classmethod- def from_config_with_settings(- cls,- config: DifyKnowledgeBaseLayerConfig,- *,- inner_api_url: str,- inner_api_key: str,- ) -> Self:- """Create the layer from public config plus server-only API settings."""- return cls(- config=DifyKnowledgeBaseLayerConfig.model_validate(config),- inner_api_url=inner_api_url,- inner_api_key=inner_api_key,- )+ def provides_user_content(self, deps: Deps) -> bool:+ """User-query retrieval supplies meaningful user input before the model."""+ config = Config.model_validate(deps.layers[self.name]["config"])+ return any(knowledge_set.query.mode == "user_query" for knowledge_set in config.sets)++ @override+ async def wrap_run(self, ctx: RunContext[Deps], *, handler: WrapRunHandler) -> AgentRunResult:+ await _KnowledgeOperations(self.name, ctx.deps)._refresh_eager_results_if_needed()+ return await handler()++ @override+ async def before_model_request(+ self, ctx: RunContext[Deps], request_context: ModelRequestContext+ ) -> ModelRequestContext:+ if not self._injected and ctx.prompt is not None:+ self._injected = True+ prompts = _KnowledgeOperations(self.name, ctx.deps).user_prompts+ if prompts:+ # Keep retrieval in the user role and in captured conversation history.+ request_context.messages.append(ModelRequest(parts=[UserPromptPart(content="\n\n".join(prompts))]))+ return request_context+++class _KnowledgeTools(FunctionToolset[Deps]):+ def __init__(self, name: str):+ super().__init__(id=name)+ self.name = name+ self._loaded = False- async def get_tools(self, *, http_client: httpx.AsyncClient) -> list[Tool[object]]:+ @override+ async def get_tools(self, ctx: RunContext[Deps]):+ if not self._loaded:+ for tool in await _KnowledgeOperations(self.name, ctx.deps).build_tools(+ http_client=ctx.deps.services.dify_api_http_client+ ):+ self.add_tool(tool)+ self._loaded = True+ return await super().get_tools(ctx)+++@dataclass+class _KnowledgeOperations:+ """Request-scoped retrieval operations; JSON holds all cached state."""++ name: str+ deps: Deps++ @property+ def config(self) -> Config:+ return Config.model_validate(self.deps.layers[self.name]["config"])++ @property+ def runtime_state(self) -> State:+ return State.model_validate(self.deps.layers[self.name]["state"])++ @property+ def execution_context(self) -> ExecutionContextConfig:+ return ExecutionContextConfig.model_validate(self.deps.layers[self.config.execution_context]["config"])++ @property+ def inner_api_url(self) -> str:+ return self.deps.services.inner_api_url++ @property+ def inner_api_key(self) -> str:+ return self.deps.services.inner_api_key++ async def build_tools(self, *, http_client: httpx.AsyncClient) -> list[Tool[Deps]]:"""Build the unified generated-query Pydantic AI tool, when needed.Knowledge tools depend on execution-context identity that is optional for@@ -115,7 +164,7 @@ class DifyKnowledgeBaseLayer(if http_client.is_closed:raise RuntimeError("DifyKnowledgeBaseLayer.get_tools() requires an open shared HTTP client.")- execution_context = self.deps.execution_context.config+ execution_context = self.execution_contextcaller = _build_caller_context(execution_context)client = DifyKnowledgeBaseClient(base_url=self.inner_api_url,@@ -124,7 +173,7 @@ class DifyKnowledgeBaseLayer()set_by_name = {knowledge_set.name: knowledge_set for knowledge_set in generated_sets}- async def knowledge_base_search(_ctx: RunContext[object], set_name: str, query: str) -> str:+ async def knowledge_base_search(_ctx: RunContext[Deps], set_name: str, query: str) -> str:knowledge_set = set_by_name.get(set_name)if knowledge_set is None:return f"unknown knowledge set: {set_name}"@@ -139,20 +188,8 @@ class DifyKnowledgeBaseLayer(retryable_observation=True,)- async def prepare_tool_definition(_ctx: RunContext[object], tool_def: ToolDefinition) -> ToolDefinition:- return ToolDefinition(- name=tool_def.name,- description=tool_def.description,- parameters_json_schema=_tool_schema(generated_sets),- strict=tool_def.strict,- sequential=tool_def.sequential,- metadata=tool_def.metadata,- timeout=tool_def.timeout,- defer_loading=tool_def.defer_loading,- kind=tool_def.kind,- return_schema=tool_def.return_schema,- include_return_schema=tool_def.include_return_schema,- )+ async def prepare_tool_definition(_ctx: RunContext[Deps], tool_def: ToolDefinition) -> ToolDefinition:+ return replace(tool_def, parameters_json_schema=_tool_schema(generated_sets))return [Tool(@@ -165,7 +202,6 @@ class DifyKnowledgeBaseLayer(]@property- @overridedef user_prompts(self) -> list[str]:"""Expose eager user-query results as an additional user prompt."""if not self.runtime_state.eager_results:@@ -185,14 +221,6 @@ class DifyKnowledgeBaseLayer()return ["Knowledge retrieval results:\n\n" + "\n\n".join(sections)]- @override- async def on_context_create(self) -> None:- await self._refresh_eager_results_if_needed()-- @override- async def on_context_resume(self) -> None:- await self._refresh_eager_results_if_needed()-def _generated_query_sets(self) -> list[DifyKnowledgeSetConfig]:return [knowledge_set for knowledge_set in self.config.sets if knowledge_set.query.mode == "generated_query"]@@ -202,63 +230,38 @@ class DifyKnowledgeBaseLayer(async def _refresh_eager_results_if_needed(self) -> None:user_query_sets = self._user_query_sets()if not user_query_sets:- self.runtime_state.eager_config_fingerprint = None- self.runtime_state.eager_results = []+ self.deps.layers[self.name]["state"] = State().model_dump(mode="json")returnfingerprint = _eager_config_fingerprint(user_query_sets)if self.runtime_state.eager_config_fingerprint == fingerprint:return- caller = _build_caller_context(self.deps.execution_context.config)- async with httpx.AsyncClient() as http_client:- client = DifyKnowledgeBaseClient(- base_url=self.inner_api_url,- api_key=self.inner_api_key,- http_client=http_client,- )- eager_results: list[DifyKnowledgeEagerResult] = []- for knowledge_set in user_query_sets:- query = (knowledge_set.query.value or "").strip()- try:- response = await client.retrieve(- tenant_id=caller["tenant_id"],- user_id=caller["user_id"],- app_id=caller["app_id"],- user_from=caller["user_from"],- invoke_from=caller["invoke_from"],- dataset_ids=knowledge_set.dataset_ids,- query=query,- retrieval=knowledge_set.retrieval,- metadata_filtering=knowledge_set.metadata_filtering,- )- except DifyKnowledgeBaseClientError as exc:- if exc.retryable:- logger.warning(- "eager knowledge retrieval temporarily unavailable",- extra={- "tenant_id": caller["tenant_id"],- "app_id": caller["app_id"],- "invoke_from": caller["invoke_from"],- "knowledge_set_id": knowledge_set.id,- "error_code": exc.error_code,- "status_code": exc.status_code,- "error_message": str(exc),- },- exc_info=True,- )- eager_results.append(- DifyKnowledgeEagerResult(- set_id=knowledge_set.id,- set_name=knowledge_set.name,- query=query,- observation=TEMPORARY_UNAVAILABLE_OBSERVATION,- status="temporarily_unavailable",- )- )- continue- logger.error(- "eager knowledge retrieval failed",+ caller = _build_caller_context(self.execution_context)+ client = DifyKnowledgeBaseClient(+ base_url=self.inner_api_url,+ api_key=self.inner_api_key,+ http_client=self.deps.services.dify_api_http_client,+ )+ eager_results: list[DifyKnowledgeEagerResult] = []+ for knowledge_set in user_query_sets:+ query = (knowledge_set.query.value or "").strip()+ try:+ response = await client.retrieve(+ tenant_id=caller["tenant_id"],+ user_id=caller["user_id"],+ app_id=caller["app_id"],+ user_from=caller["user_from"],+ invoke_from=caller["invoke_from"],+ dataset_ids=knowledge_set.dataset_ids,+ query=query,+ retrieval=knowledge_set.retrieval,+ metadata_filtering=knowledge_set.metadata_filtering,+ )+ except DifyKnowledgeBaseClientError as exc:+ if exc.retryable:+ logger.warning(+ "eager knowledge retrieval temporarily unavailable",extra={"tenant_id": caller["tenant_id"],"app_id": caller["app_id"],@@ -270,20 +273,44 @@ class DifyKnowledgeBaseLayer(},exc_info=True,)- raise-- eager_results.append(- DifyKnowledgeEagerResult(- set_id=knowledge_set.id,- set_name=knowledge_set.name,- query=query,- observation=_format_observation(response, self.config, include_heading=False),- status="success" if response.results else "empty",+ eager_results.append(+ DifyKnowledgeEagerResult(+ set_id=knowledge_set.id,+ set_name=knowledge_set.name,+ query=query,+ observation=TEMPORARY_UNAVAILABLE_OBSERVATION,+ status="temporarily_unavailable",+ ))+ continue+ logger.error(+ "eager knowledge retrieval failed",+ extra={+ "tenant_id": caller["tenant_id"],+ "app_id": caller["app_id"],+ "invoke_from": caller["invoke_from"],+ "knowledge_set_id": knowledge_set.id,+ "error_code": exc.error_code,+ "status_code": exc.status_code,+ "error_message": str(exc),+ },+ exc_info=True,+ )+ raise++ eager_results.append(+ DifyKnowledgeEagerResult(+ set_id=knowledge_set.id,+ set_name=knowledge_set.name,+ query=query,+ observation=_format_observation(response, self.config, include_heading=False),+ status="success" if response.results else "empty",)+ )- self.runtime_state.eager_results = eager_results- self.runtime_state.eager_config_fingerprint = fingerprint+ self.deps.layers[self.name]["state"] = State(+ eager_results=eager_results, eager_config_fingerprint=fingerprint+ ).model_dump(mode="json")async def _retrieve_for_set(self,@@ -478,8 +505,9 @@ def _truncate_text(text: str, max_chars: int) -> str:__all__ = ["BLANK_QUERY_OBSERVATION",- "DifyKnowledgeBaseDeps",- "DifyKnowledgeBaseLayer",+ "Config",+ "State",+ "Capability","NO_RESULTS_OBSERVATION","TEMPORARY_UNAVAILABLE_OBSERVATION",]diff --git a/dify-agent/src/dify_agent/layers/output/__init__.py b/dify-agent/src/dify_agent/layers/output/__init__.pyindex 076fd00b1aa..9a3404ff6ad 100644--- a/dify-agent/src/dify_agent/layers/output/__init__.py+++ b/dify-agent/src/dify_agent/layers/output/__init__.py@@ -5,6 +5,6 @@ server-side execution dependencies. Keep this package root import-safe forclient code that only needs to build run requests."""-from dify_agent.layers.output.configs import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig+from dify_agent.layers.output.configs import DifyOutputLayerConfig-__all__ = ["DIFY_OUTPUT_LAYER_TYPE_ID", "DifyOutputLayerConfig"]+__all__ = ["DifyOutputLayerConfig"]diff --git a/dify-agent/src/dify_agent/layers/output/configs.py b/dify-agent/src/dify_agent/layers/output/configs.pyindex 0d73ef5411f..f3b1baaf2d8 100644--- a/dify-agent/src/dify_agent/layers/output/configs.py+++ b/dify-agent/src/dify_agent/layers/output/configs.py@@ -8,17 +8,12 @@ imports do not pull in server execution code.from __future__ import annotations-from typing import ClassVar, Final+from typing import ClassVar-from pydantic import ConfigDict, JsonValue, field_validator+from pydantic import BaseModel, ConfigDict, JsonValue, field_validator-from agenton.layers import LayerConfig--DIFY_OUTPUT_LAYER_TYPE_ID: Final[str] = "dify.output"---class DifyOutputLayerConfig(LayerConfig):+class DifyOutputLayerConfig(BaseModel):"""Public config for the conventionally named structured output layer.The runtime only reads the layer named by@@ -48,4 +43,4 @@ class DifyOutputLayerConfig(LayerConfig):return value-__all__ = ["DIFY_OUTPUT_LAYER_TYPE_ID", "DifyOutputLayerConfig"]+__all__ = ["DifyOutputLayerConfig"]diff --git a/dify-agent/src/dify_agent/layers/output/output_layer.py b/dify-agent/src/dify_agent/layers/output/output_layer.pyindex 206f0cceb25..8e4cfb3ae38 100644--- a/dify-agent/src/dify_agent/layers/output/output_layer.py+++ b/dify-agent/src/dify_agent/layers/output/output_layer.py@@ -1,15 +1,7 @@-"""Runtime layer for Dify Agent structured final output contracts.--``DifyOutputLayer`` is intentionally state-free and does not participate in-prompt, user prompt, or tool aggregation. Instead, the scheduler and runner read-the conventionally named layer after ``Compositor.enter(...)`` and convert its-top-level object JSON Schema into a ``ToolOutput(...)`` whose inner dynamic type-both exposes the model-facing schema and validates runtime output. ``jsonschema``-performs the real content validation inside that custom Pydantic-compatible-dict-like type, so Pydantic AI's normal output validation flow can request-retries without a separate Dify-owned output-validator callback. Keeping both-steps here lets request validation and execution reuse the same schema checks-without teaching Agenton core about output aggregation.+"""Native structured output assembly with shared JSON Schema validation.++The runner resolves output_type before invoking Pydantic AI. Its dynamic type+exposes the schema and validates the result in Pydantic AI's retry pipeline."""from __future__ import annotations@@ -27,11 +19,13 @@ from pydantic import GetCoreSchemaHandler, GetJsonSchemaHandler, JsonValuefrom pydantic.json_schema import JsonSchemaValuefrom pydantic_ai.output import OutputSpec, ToolOutputfrom pydantic_core import PydanticCustomError, core_schema-from typing_extensions import Self, assert_never, override+from typing_extensions import assert_never-from agenton.layers import EmptyRuntimeState, NoLayerDeps, PlainLayer-from dify_agent.layers.output.configs import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig+from pydantic import BaseModel, ConfigDict+from pydantic_ai.capabilities import AbstractCapability+from dify_agent.runtime.context import Deps+from dify_agent.layers.output.configs import DifyOutputLayerConfig_FINAL_OUTPUT_TOOL_NAME: Final[str] = "final_output"@@ -52,21 +46,22 @@ class DifyOutputContract:output_type: OutputSpec[object]-@dataclass(slots=True)-class DifyOutputLayer(PlainLayer[NoLayerDeps, DifyOutputLayerConfig, EmptyRuntimeState]):- """State-free layer that stores the final structured output contract."""+class Config(DifyOutputLayerConfig):+ pass- type_id = DIFY_OUTPUT_LAYER_TYPE_ID- config: DifyOutputLayerConfig+class State(BaseModel):+ model_config = ConfigDict(extra="forbid")- @classmethod- @override- def from_config(cls, config: DifyOutputLayerConfig) -> Self:- """Create the output layer from validated public config."""- return cls(config=DifyOutputLayerConfig.model_validate(config))- def build_output_contract(self) -> DifyOutputContract:+class Capability(AbstractCapability[Deps]):+ """Explicit runner assembly for the native output_type parameter."""++ def __init__(self, name: str):+ self.id = name+ self.name = name++ def build_output_contract(self, deps: Deps) -> DifyOutputContract:"""Return the pydantic-ai output contract for this layer.The returned contract always keeps model-facing schema exposure plus@@ -82,11 +77,12 @@ class DifyOutputLayer(PlainLayer[NoLayerDeps, DifyOutputLayerConfig, EmptyRuntimreferences, or cannot be represented as a supported structuredoutput tool schema."""- user_schema = deepcopy(self.config.json_schema)+ config = Config.model_validate(deps.layers[self.name]["config"])+ user_schema = deepcopy(config.json_schema)_reject_non_local_refs(user_schema)validated_output_type = _build_validated_output_type(user_schema,- description=self.config.description,+ description=config.description,)return DifyOutputContract(@@ -95,7 +91,7 @@ class DifyOutputLayer(PlainLayer[NoLayerDeps, DifyOutputLayerConfig, EmptyRuntimToolOutput(validated_output_type,name=_FINAL_OUTPUT_TOOL_NAME,- strict=self.config.strict,+ strict=config.strict,),),)@@ -310,4 +306,4 @@ def _sort_error_path(path: Sequence[object]) -> tuple[str, ...]:return tuple(str(segment) for segment in path)-__all__ = ["DifyOutputContract", "DifyOutputLayer"]+__all__ = ["DifyOutputContract", "Config", "State", "Capability"]diff --git a/dify-agent/src/dify_agent/layers/prompt/__init__.py b/dify-agent/src/dify_agent/layers/prompt/__init__.pynew file mode 100644index 00000000000..2ec75f0f7dd--- /dev/null+++ b/dify-agent/src/dify_agent/layers/prompt/__init__.py@@ -0,0 +1,5 @@+"""Client-safe prompt configuration exports."""++from .configs import Config++__all__ = ["Config"]diff --git a/dify-agent/src/dify_agent/layers/prompt/configs.py b/dify-agent/src/dify_agent/layers/prompt/configs.pynew file mode 100644index 00000000000..c589c730dc2--- /dev/null+++ b/dify-agent/src/dify_agent/layers/prompt/configs.py@@ -0,0 +1,10 @@+"""Client-safe JSON configuration for the prompt module."""++from pydantic import BaseModel, ConfigDict, Field+++class Config(BaseModel):+ prefix: list[str] | str = Field(default_factory=list)+ user: list[str] | str = Field(default_factory=list)+ suffix: list[str] | str = Field(default_factory=list)+ model_config = ConfigDict(extra="forbid")diff --git a/dify-agent/src/dify_agent/layers/prompt/layer.py b/dify-agent/src/dify_agent/layers/prompt/layer.pynew file mode 100644index 00000000000..7b76e16e09c--- /dev/null+++ b/dify-agent/src/dify_agent/layers/prompt/layer.py@@ -0,0 +1,31 @@+"""Serializable prompt module; instruction ordering is deliberately unspecified."""++from pydantic import BaseModel, ConfigDict++from dify_agent.layers.prompt.configs import Config+from pydantic_ai import RunContext+from pydantic_ai.messages import UserContent+from pydantic_ai.toolsets import FunctionToolset++from dify_agent.runtime.context import Deps+++class State(BaseModel):+ model_config = ConfigDict(extra="forbid")+++class Toolset(FunctionToolset[Deps]):+ def __init__(self, name: str):+ self.name = name+ super().__init__(id=name, instructions=self._render_instructions)++ def _render_instructions(self, ctx: RunContext[Deps]) -> str:+ config = Config.model_validate(ctx.deps.layers[self.name]["config"])+ return "\n\n".join([*_fragments(config.prefix), *_fragments(config.suffix)])++ def build_user_content(self, deps: Deps) -> list[UserContent]:+ return list(_fragments(Config.model_validate(deps.layers[self.name]["config"]).user))+++def _fragments(value: list[str] | str) -> list[str]:+ return [value] if isinstance(value, str) else valuediff --git a/dify-agent/src/dify_agent/layers/runtime/__init__.py b/dify-agent/src/dify_agent/layers/runtime/__init__.pyindex 872ed9120c4..8761ed8a621 100644--- a/dify-agent/src/dify_agent/layers/runtime/__init__.py+++ b/dify-agent/src/dify_agent/layers/runtime/__init__.py@@ -1,4 +1,3 @@-from .configs import DIFY_RUNTIME_LAYER_TYPE_ID, DifyRuntimeLayerConfig-from .layer import DifyRuntimeLayer+from .configs import DifyRuntimeLayerConfig-__all__ = ["DIFY_RUNTIME_LAYER_TYPE_ID", "DifyRuntimeLayer", "DifyRuntimeLayerConfig"]+__all__ = ["DifyRuntimeLayerConfig"]diff --git a/dify-agent/src/dify_agent/layers/runtime/configs.py b/dify-agent/src/dify_agent/layers/runtime/configs.pyindex f7f3a576dbb..5761a486b8d 100644--- a/dify-agent/src/dify_agent/layers/runtime/configs.py+++ b/dify-agent/src/dify_agent/layers/runtime/configs.py@@ -1,17 +1,14 @@"""Client-safe config for operation-scoped RuntimeLease acquisition."""-from typing import ClassVar, Final+from typing import ClassVar-from agenton.layers import LayerConfig-from pydantic import ConfigDict, Field+from pydantic import BaseModel, ConfigDict, Field-DIFY_RUNTIME_LAYER_TYPE_ID: Final[str] = "dify.runtime"--class DifyRuntimeLayerConfig(LayerConfig):+class DifyRuntimeLayerConfig(BaseModel):backend_binding_ref: str = Field(min_length=1)model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")-__all__ = ["DIFY_RUNTIME_LAYER_TYPE_ID", "DifyRuntimeLayerConfig"]+__all__ = ["DifyRuntimeLayerConfig"]diff --git a/dify-agent/src/dify_agent/layers/runtime/layer.py b/dify-agent/src/dify_agent/layers/runtime/layer.pyindex e6fbaf70aff..b2889f07b72 100644--- a/dify-agent/src/dify_agent/layers/runtime/layer.py+++ b/dify-agent/src/dify_agent/layers/runtime/layer.py@@ -1,75 +1,40 @@-"""Agenton layer exposing one operation-scoped RuntimeLease."""+"""Acquire an operation lease without owning Binding or Workspace retirement."""-from collections.abc import AsyncGenerator-from contextlib import asynccontextmanager-from dataclasses import dataclass, field-from typing import ClassVar+from typing import override-from agenton.layers import EmptyRuntimeState, NoLayerDeps, PlainLayer-from typing_extensions import Self, override+from pydantic import BaseModel, ConfigDict+from pydantic_ai import RunContext+from pydantic_ai.capabilities import AbstractCapability+from pydantic_ai.capabilities.abstract import WrapRunHandler+from pydantic_ai.run import AgentRunResult-from dify_agent.layers.runtime.configs import DIFY_RUNTIME_LAYER_TYPE_ID, DifyRuntimeLayerConfig-from dify_agent.runtime_backend import ExecutionBindingBackend, RuntimeLease+from dify_agent.layers.runtime.configs import DifyRuntimeLayerConfig+from dify_agent.runtime.context import Depsfrom dify_agent.runtime_backend.leases import open_runtime_lease-@dataclass(slots=True)-class DifyRuntimeLayer(PlainLayer[NoLayerDeps, DifyRuntimeLayerConfig, EmptyRuntimeState]):- """Acquire/release a Binding without owning its product lifecycle."""+class Config(DifyRuntimeLayerConfig):+ pass- type_id: ClassVar[str | None] = DIFY_RUNTIME_LAYER_TYPE_ID- config: DifyRuntimeLayerConfig- backend: ExecutionBindingBackend- _lease: RuntimeLease | None = field(default=None, init=False)- @classmethod- @override- def from_config(cls, config: DifyRuntimeLayerConfig) -> Self:- del config- raise TypeError("DifyRuntimeLayer requires a server-injected ExecutionBindingBackend")+class State(BaseModel):+ model_config = ConfigDict(extra="forbid")- @classmethod- def from_config_with_backend(- cls,- config: DifyRuntimeLayerConfig,- *,- backend: ExecutionBindingBackend,- ) -> Self:- return cls(config=DifyRuntimeLayerConfig.model_validate(config), backend=backend)- @property- def lease(self) -> RuntimeLease:- if self._lease is None:- raise RuntimeError("DifyRuntimeLayer lease is only available inside resource_context()")- return self._lease+class Capability(AbstractCapability[Deps]):+ def __init__(self, name: str):+ self.id = name+ self.name = name@override- @asynccontextmanager- async def resource_context(self) -> AsyncGenerator[None]:- if self._lease is not None:- raise RuntimeError("DifyRuntimeLayer resource_context() is already active")- async with open_runtime_lease(self.backend, self.config.backend_binding_ref) as lease:- self._lease = lease+ async def wrap_run(self, ctx: RunContext[Deps], *, handler: WrapRunHandler) -> AgentRunResult:+ config = Config.model_validate(ctx.deps.layers[self.name]["config"])+ profile = ctx.deps.services.runtime_backend_profile+ if profile is None:+ raise ValueError("Runtime module requires a configured runtime backend.")+ async with open_runtime_lease(profile.execution_bindings, config.backend_binding_ref) as lease:+ ctx.deps.resources.leases[self.name] = leasetry:- yield+ return await handler()finally:- self._lease = None-- @override- async def on_context_create(self) -> None:- _ = self.lease-- @override- async def on_context_resume(self) -> None:- _ = self.lease-- @override- async def on_context_suspend(self) -> None:- _ = self.lease-- @override- async def on_context_delete(self) -> None:- _ = self.lease---__all__ = ["DifyRuntimeLayer"]+ del ctx.deps.resources.leases[self.name]diff --git a/dify-agent/src/dify_agent/layers/shell/__init__.py b/dify-agent/src/dify_agent/layers/shell/__init__.pyindex 34800d69471..5a6466e0f1f 100644--- a/dify-agent/src/dify_agent/layers/shell/__init__.py+++ b/dify-agent/src/dify_agent/layers/shell/__init__.py@@ -6,7 +6,6 @@ client code that only needs to build run requests."""from dify_agent.layers.shell.configs import (- DIFY_SHELL_LAYER_TYPE_ID,DifyShellCliToolConfig,DifyShellEnvVarConfig,DifyShellLayerConfig,@@ -14,7 +13,6 @@ from dify_agent.layers.shell.configs import ()__all__ = [- "DIFY_SHELL_LAYER_TYPE_ID","DifyShellCliToolConfig","DifyShellEnvVarConfig","DifyShellLayerConfig",diff --git a/dify-agent/src/dify_agent/layers/shell/configs.py b/dify-agent/src/dify_agent/layers/shell/configs.pyindex 77d7d05a3f7..e552405f1ef 100644--- a/dify-agent/src/dify_agent/layers/shell/configs.py+++ b/dify-agent/src/dify_agent/layers/shell/configs.py@@ -1,21 +1,18 @@-"""Client-safe DTOs for the Dify shell Agenton layer.+"""Client-safe DTOs for the Dify shell layer.Server-only Agent Stub and redaction settings are injected by the runtime-provider factory. The Sandbox dependency supplies the active shellctl data+runtime services. The Sandbox dependency supplies the active shellctl dataplane. Public config carries product-level Agent Soul settings that affect theworkspace itself: CLI tool bootstrap commands, normal environment variables,secret environment variable names. Sandbox selection is a deployment concern."""import re-from typing import ClassVar, Final+from typing import ClassVarfrom pydantic import BaseModel, ConfigDict, Field, field_validator-from agenton.layers import LayerConfig--DIFY_SHELL_LAYER_TYPE_ID: Final[str] = "dify.shell"_ENV_NAME_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")@@ -67,9 +64,12 @@ class DifyShellCliToolConfig(BaseModel):return [command for command in (item.strip() for item in value) if command]-class DifyShellLayerConfig(LayerConfig):+class DifyShellLayerConfig(BaseModel):"""Public product behavior for the Sandbox-backed Dify Shell layer."""+ runtime: str = "runtime"+ execution_context: str | None = "execution_context"+model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")cli_tools: list[DifyShellCliToolConfig] = Field(default_factory=list)@@ -79,7 +79,6 @@ class DifyShellLayerConfig(LayerConfig):__all__ = [- "DIFY_SHELL_LAYER_TYPE_ID","DifyShellCliToolConfig","DifyShellEnvVarConfig","DifyShellLayerConfig",diff --git a/dify-agent/src/dify_agent/layers/shell/layer.py b/dify-agent/src/dify_agent/layers/shell/layer.pyindex 354818d91f2..b923c3147c5 100644--- a/dify-agent/src/dify_agent/layers/shell/layer.py+++ b/dify-agent/src/dify_agent/layers/shell/layer.py@@ -7,21 +7,16 @@ import jsonimport loggingimport refrom dataclasses import dataclass, field-from typing import ClassVar, NotRequired, Protocol, TypedDict, runtime_checkable+from typing import ClassVar, NotRequired, Protocol, TypedDict, override, runtime_checkablefrom pydantic import BaseModel, ConfigDict, Field, NonNegativeInt, field_validator, model_validator-from pydantic_ai import Tool-from typing_extensions import Self, override--from agenton.layers import (- EmptyRuntimeState,- LayerDeps,- NoLayerDeps,- PlainLayer,- PydanticAILayer,- PydanticAIPrompt,- PydanticAITool,-)+from pydantic_ai import RunContext+from pydantic_ai.capabilities import AbstractCapability, CapabilityOrdering+from pydantic_ai.capabilities.abstract import WrapRunHandler+from pydantic_ai.run import AgentRunResult+from pydantic_ai.toolsets import FunctionToolset+from typing_extensions import Self+from dify_agent.adapters.shell.protocols import (CompleteShellCommandResult,ShellCommandProtocol,@@ -29,10 +24,11 @@ from dify_agent.adapters.shell.protocols import (ShellPromptObservation,)from dify_agent.agent_stub.protocol import AGENT_STUB_AUTH_JWE_ENV_VAR-from dify_agent.agent_stub.shell_env import ShellAgentStubTokenFactory, build_shell_agent_stub_env+from dify_agent.agent_stub.shell_env import build_shell_agent_stub_envfrom dify_agent.layers.execution_context import DifyExecutionContextLayerConfig-from dify_agent.layers.runtime.layer import DifyRuntimeLayer-from dify_agent.layers.shell.configs import DIFY_SHELL_LAYER_TYPE_ID, DifyShellLayerConfig+from dify_agent.layers.runtime.layer import Capability as RuntimeCapability+from dify_agent.runtime.context import Deps+from dify_agent.layers.shell.configs import DifyShellLayerConfigfrom dify_agent.layers.shell.output_text import normalized_output_text, utf8_prefix, utf8_suffixfrom dify_agent.runtime.command_runner import execute_complete_with_commandsfrom dify_agent.runtime_backend import RuntimeLease@@ -173,12 +169,12 @@ type ShellRunToolResult = str | ShellToolErrorObservationtype ShellInterruptToolResult = str | ShellToolErrorObservation-class DifyShellLayerDeps(LayerDeps):- execution_context: PlainLayer[NoLayerDeps, DifyExecutionContextLayerConfig, EmptyRuntimeState] | None # pyright: ignore[reportUninitializedInstanceVariable]- runtime: DifyRuntimeLayer # pyright: ignore[reportUninitializedInstanceVariable]+class Config(DifyShellLayerConfig):+ pass-class DifyShellRuntimeState(BaseModel):+class State(BaseModel):+ initialized: bool = Falsejob_ids: list[str] = Field(default_factory=list)job_offsets: dict[str, NonNegativeInt] = Field(default_factory=dict)@@ -203,102 +199,118 @@ class DifyShellRuntimeState(BaseModel):CompleteRemoteCommandResult = CompleteShellCommandResult-@dataclass(slots=True)-class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerConfig, DifyShellRuntimeState]):- """Expose Shell tools over the active RuntimeLease without owning it.-- Create optionally bootstraps configured CLI tools in the lease's Workspace.- Suspend and delete best-effort remove tracked shellctl jobs, then clear job- ids and offsets so they do not persist across requests. Commands, files,- Home, and cwd come only from ``DifyRuntimeLayer.lease``. Persistent Binding- and Workspace lifecycle remains exclusively owned by Dify API.- """+class Capability(AbstractCapability[Deps]):+ """Own one ShellSession, bootstrap once and clean jobs on every outcome."""- type_id: ClassVar[str | None] = DIFY_SHELL_LAYER_TYPE_ID+ def __init__(self, name: str):+ self.id = name+ self.name = name- config: DifyShellLayerConfig- shell_redact_patterns: list[str] = field(default_factory=list)- agent_stub_api_base_url: str | None = None- agent_stub_token_factory: ShellAgentStubTokenFactory | None = None- _job_agent_stub_tokens: dict[str, str] = field(default_factory=dict, init=False, repr=False)+ @override+ def get_ordering(self) -> CapabilityOrdering:+ return CapabilityOrdering(wrapped_by=[RuntimeCapability], requires=[RuntimeCapability])- @classmethod@override- def from_config(cls, config: DifyShellLayerConfig) -> Self:- del config- raise TypeError("DifyShellLayer requires server-injected settings and must use a provider factory.")+ def get_instructions(self):+ return self._instructions- @classmethod- def from_config_with_settings(- cls,- config: DifyShellLayerConfig,- *,- shell_redact_patterns: list[str] | None = None,- agent_stub_api_base_url: str | None = None,- agent_stub_token_factory: ShellAgentStubTokenFactory | None = None,- ) -> Self:- return cls(- config=config,- shell_redact_patterns=shell_redact_patterns or [],- agent_stub_api_base_url=agent_stub_api_base_url,- agent_stub_token_factory=agent_stub_token_factory,- )+ def _instructions(self, ctx: RunContext[Deps]) -> str:+ session = ctx.deps.resources.shells[self.name]+ return f"{session.build_prefix_prompt()}\n\n{_SHELL_LAYER_SUFFIX_PROMPT}"- @property@override- def prefix_prompts(self) -> Sequence[PydanticAIPrompt[object]]:- return [self._build_prefix_prompt]+ def get_toolset(self) -> FunctionToolset[Deps]:+ toolset = FunctionToolset[Deps](id=self.name, sequential=True)++ @toolset.tool(name="shell_run")+ async def shell_run(+ ctx: RunContext[Deps], script: str, timeout: float = DEFAULT_TIMEOUT_SECONDS+ ) -> ShellRunToolResult:+ """Start a shell job and return its output and status."""+ return await ctx.deps.resources.shells[self.name]._tool_run(script, timeout)++ @toolset.tool(name="shell_wait")+ async def shell_wait(+ ctx: RunContext[Deps], job_id: str, timeout: float = DEFAULT_TIMEOUT_SECONDS+ ) -> ShellRunToolResult:+ """Wait for output or completion from an existing shell job."""+ return await ctx.deps.resources.shells[self.name]._tool_wait(job_id, timeout)++ @toolset.tool(name="shell_input")+ async def shell_input(+ ctx: RunContext[Deps], job_id: str, text: str, timeout: float = DEFAULT_TIMEOUT_SECONDS+ ) -> ShellRunToolResult:+ """Send stdin to a shell job and wait for its next output."""+ return await ctx.deps.resources.shells[self.name]._tool_input(job_id, text, timeout)++ @toolset.tool(name="shell_interrupt")+ async def shell_interrupt(+ ctx: RunContext[Deps], job_id: str, grace_seconds: float = DEFAULT_TERMINATE_GRACE_SECONDS+ ) -> ShellInterruptToolResult:+ """Interrupt a running shell job and return its final status."""+ return await ctx.deps.resources.shells[self.name]._tool_interrupt(job_id, grace_seconds)++ return toolset- @property@override- def suffix_prompts(self) -> Sequence[PydanticAIPrompt[object]]:- return [_shell_layer_suffix_prompt]+ async def wrap_run(self, ctx: RunContext[Deps], *, handler: WrapRunHandler) -> AgentRunResult:+ session = ShellSession(self.name, ctx.deps)+ ctx.deps.resources.shells[self.name] = session+ try:+ state = session.runtime_state+ if not state.initialized:+ script = _workspace_bootstrap_script(session.config)+ if script:+ result = await session._run_internal_script_complete(script, cwd=session._require_workspace_cwd())+ if result.exit_code != 0 or not result.output_complete:+ raise RuntimeError(+ f"Failed to bootstrap shell workspace: {result.status} exit_code={result.exit_code}"+ )+ state.initialized = True+ session.save_state(state)+ return await handler()+ finally:+ try:+ await session._delete_tracked_jobs_best_effort(session.runtime_state.job_ids)+ finally:+ session._clear_tracked_jobs()+ del ctx.deps.resources.shells[self.name]- @property- @override- def tools(self) -> Sequence[PydanticAITool[object]]:- return [- Tool(self._tool_run, name="shell_run"),- Tool(self._tool_wait, name="shell_wait"),- Tool(self._tool_input, name="shell_input"),- Tool(self._tool_interrupt, name="shell_interrupt"),- ]-- def _build_prefix_prompt(self) -> str:- execution_context = self.deps.execution_context- is_build_draft = (- execution_context is not None and execution_context.config.agent_config_version_kind == "build_draft"- )- working_location_prompt = (- _BUILD_DRAFT_WORKING_LOCATION_PROMPT if is_build_draft else _DEFAULT_WORKING_LOCATION_PROMPT- )- return f"{_SHELL_LAYER_PREFIX_PROMPT}\n\n{working_location_prompt}"- @override- async def on_context_create(self) -> None:- bootstrap_script = _workspace_bootstrap_script(self.config)- if not bootstrap_script:- return- result = await self._run_internal_script_complete(bootstrap_script, cwd=self._require_workspace_cwd())- if result.exit_code != 0 or not result.output_complete:- raise RuntimeError(- f"Failed to bootstrap shell workspace {self._require_workspace_cwd()}: "- f"{result.status} exit_code={result.exit_code}"- )+@dataclass(slots=True)+class ShellSession:+ """Run-scoped shell operations over borrowed lease and canonical JSON state.- @override- async def on_context_resume(self) -> None:- _ = self._require_resource()+ Capabilities and tools share this live command adapter, never copied Config+ or State models. Shell tools run sequentially because offsets and tokens+ share one session. Binding and Workspace retirement remain API-owned.+ """- @override- async def on_context_suspend(self) -> None:- await self._delete_tracked_jobs_best_effort(self.runtime_state.job_ids)- self._clear_tracked_jobs()+ name: str+ deps: Deps+ _job_agent_stub_tokens: dict[str, str] = field(default_factory=dict, init=False, repr=False)- @override- async def on_context_delete(self) -> None:- await self._delete_tracked_jobs_best_effort(self.runtime_state.job_ids)- self._clear_tracked_jobs()+ @property+ def config(self) -> Config:+ return Config.model_validate(self.deps.layers[self.name]["config"])++ @property+ def runtime_state(self) -> State:+ return State.model_validate(self.deps.layers[self.name]["state"])++ def save_state(self, state: State) -> None:+ self.deps.layers[self.name]["state"] = state.model_dump(mode="json")++ def build_prefix_prompt(self) -> str:+ context_name = self.config.execution_context+ context = (+ DifyExecutionContextLayerConfig.model_validate(self.deps.layers[context_name]["config"])+ if context_name+ else None+ )+ is_build_draft = context is not None and context.agent_config_version_kind == "build_draft"+ working = _BUILD_DRAFT_WORKING_LOCATION_PROMPT if is_build_draft else _DEFAULT_WORKING_LOCATION_PROMPT+ return f"{_SHELL_LAYER_PREFIX_PROMPT}\n\n{working}"async def _tool_run(self, script: str, timeout: float = DEFAULT_TIMEOUT_SECONDS) -> ShellRunToolResult:"""Start a shell job in the current workspace and return its output and status."""@@ -312,12 +324,17 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerCenv=env,timeout=timeout,)+ # Register the remote job before observing output so cancellation during+ # a tail request still leaves cleanup with its job and redaction token.+ self._remember_job_id(result.job_id)+ self._remember_job_offset(result.job_id, 0)+ if agent_stub_token is not None and not result.done:+ self._job_agent_stub_tokens[result.job_id] = agent_stub_tokenobservation = await render_prompt_observation_from_result(self._require_resource().commands,result,edge_bytes=_SHELL_OUTPUT_PROMPT_EDGE_BYTES,)- self._remember_job_id(result.job_id)self._remember_job_offset(result.job_id, observation.offset)if agent_stub_token is not None and not result.done:self._job_agent_stub_tokens[result.job_id] = agent_stub_token@@ -502,7 +519,10 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC)def _require_resource(self) -> RuntimeLease:- return self.deps.runtime.lease+ lease = self.deps.resources.leases.get(self.config.runtime)+ if lease is None:+ raise RuntimeError("Shell requires an active Runtime lease.")+ return leasedef _require_workspace_cwd(self) -> str:return self._require_resource().layout.workspace_dir@@ -518,12 +538,14 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerCdef _remember_job_id(self, job_id: str) -> None:if job_id in self.runtime_state.job_ids:return- self.runtime_state.job_ids = [*self.runtime_state.job_ids, job_id]+ state = self.runtime_state+ state.job_ids = [*state.job_ids, job_id]+ self.save_state(state)def _remember_job_offset(self, job_id: str, offset: int) -> None:- job_offsets = dict(self.runtime_state.job_offsets)- job_offsets[job_id] = offset- self.runtime_state.job_offsets = job_offsets+ state = self.runtime_state+ state.job_offsets = {**state.job_offsets, job_id: offset}+ self.save_state(state)async def _delete_tracked_jobs_best_effort(self, job_ids: Sequence[str]) -> None:commands = self._require_resource().commands@@ -538,8 +560,10 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC)def _clear_tracked_jobs(self) -> None:- self.runtime_state.job_offsets = {}- self.runtime_state.job_ids = []+ state = self.runtime_state+ state.job_offsets = {}+ state.job_ids = []+ self.save_state(state)self._job_agent_stub_tokens.clear()def _build_shell_command_env(@@ -552,12 +576,16 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerCenv["HOME"] = self._require_resource().layout.home_dirif not include_agent_stub_env:return env- execution_context_layer = self.deps.execution_context- execution_context = execution_context_layer.config if execution_context_layer is not None else None+ context_name = self.config.execution_context+ execution_context = (+ DifyExecutionContextLayerConfig.model_validate(self.deps.layers[context_name]["config"])+ if context_name+ else None+ )agent_stub_env = build_shell_agent_stub_env(- agent_stub_api_base_url=self.agent_stub_api_base_url,+ agent_stub_api_base_url=self.deps.services.agent_stub_api_base_url,execution_context=execution_context,- token_factory=self.agent_stub_token_factory,+ token_factory=self.deps.services.agent_stub_token_factory,session_id=None,)if agent_stub_env is None:@@ -587,7 +615,7 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerCif value and len(value) > 8:text = text.replace(value, "***")# Server-level + per-agent regex patterns.- for pattern in (*self.shell_redact_patterns, *self.config.redact_patterns):+ for pattern in (*self.deps.services.shell_redact_patterns, *self.config.redact_patterns):text = re.sub(pattern, "***", text)return text@@ -623,10 +651,6 @@ async def render_prompt_observation_from_result(return ShellPromptObservation(text=text, output_path=output_path, offset=offset)-def _shell_layer_suffix_prompt() -> str:- return _SHELL_LAYER_SUFFIX_PROMPT--def _metadata_dict(*,job_id: str,@@ -738,10 +762,11 @@ def _tagged_shell_observation(metadata: dict[str, object], output: str) -> str:__all__ = [+ "Config",+ "State",+ "Capability",+ "ShellSession","CompleteRemoteCommandResult",- "DifyShellLayer",- "DifyShellLayerDeps",- "DifyShellRuntimeState","DEFAULT_TERMINATE_GRACE_SECONDS","DEFAULT_TIMEOUT_SECONDS","render_prompt_observation_from_result",diff --git a/dify-agent/src/dify_agent/layers/user_prompt/__init__.py b/dify-agent/src/dify_agent/layers/user_prompt/__init__.pyindex f675b1c0140..142c770ab52 100644--- a/dify-agent/src/dify_agent/layers/user_prompt/__init__.py+++ b/dify-agent/src/dify_agent/layers/user_prompt/__init__.py@@ -1,7 +1,6 @@"""Client-safe exports for the Agent App multimodal user prompt layer."""from dify_agent.layers.user_prompt.configs import (- DIFY_USER_PROMPT_LAYER_TYPE_ID,DifyUserPromptDownloadConfig,DifyUserPromptFileConfig,DifyUserPromptFileType,@@ -10,7 +9,6 @@ from dify_agent.layers.user_prompt.configs import ()__all__ = [- "DIFY_USER_PROMPT_LAYER_TYPE_ID","DifyUserPromptDownloadConfig","DifyUserPromptFileConfig","DifyUserPromptFileType",diff --git a/dify-agent/src/dify_agent/layers/user_prompt/configs.py b/dify-agent/src/dify_agent/layers/user_prompt/configs.pyindex fc9fa273e7d..f0f50ee6158 100644--- a/dify-agent/src/dify_agent/layers/user_prompt/configs.py+++ b/dify-agent/src/dify_agent/layers/user_prompt/configs.py@@ -4,18 +4,15 @@ from __future__ import annotationsimport base64import binascii-from typing import Annotated, ClassVar, Final, Literal, Self+from typing import Annotated, ClassVar, Literal, Self-from pydantic import ConfigDict, Field, model_validator+from pydantic import BaseModel, ConfigDict, Field, model_validator-from agenton.layers import LayerConfig--DIFY_USER_PROMPT_LAYER_TYPE_ID: Final[str] = "dify.user_prompt"type DifyUserPromptFileType = Literal["image", "document", "audio", "video", "custom"]-class DifyUserPromptImageConfig(LayerConfig):+class DifyUserPromptImageConfig(BaseModel):"""One image delivered directly to the configured vision model.Callers provide either an HTTP(S) URL or base64 bytes. Opaque Dify file@@ -47,7 +44,7 @@ class DifyUserPromptImageConfig(LayerConfig):return self-class DifyUserPromptDownloadConfig(LayerConfig):+class DifyUserPromptDownloadConfig(BaseModel):delivery: Literal["download"] = "download"type: DifyUserPromptFileTypetransfer_method: Literal["remote_url", "local_file", "tool_file", "datasource_file"]@@ -71,7 +68,7 @@ type DifyUserPromptFileConfig = Annotated[]-class DifyUserPromptLayerConfig(LayerConfig):+class DifyUserPromptLayerConfig(BaseModel):"""User text plus images that should be sent in the same model turn."""text: str = Field(min_length=1)@@ -81,7 +78,6 @@ class DifyUserPromptLayerConfig(LayerConfig):__all__ = [- "DIFY_USER_PROMPT_LAYER_TYPE_ID","DifyUserPromptDownloadConfig","DifyUserPromptFileConfig","DifyUserPromptFileType",diff --git a/dify-agent/src/dify_agent/layers/user_prompt/layer.py b/dify-agent/src/dify_agent/layers/user_prompt/layer.pyindex edcdf0a45bc..d677d82e651 100644--- a/dify-agent/src/dify_agent/layers/user_prompt/layer.py+++ b/dify-agent/src/dify_agent/layers/user_prompt/layer.py@@ -4,39 +4,40 @@ from __future__ import annotationsimport base64import json-from dataclasses import dataclass-from typing import ClassVar, assert_never+from typing import assert_neverfrom pydantic_ai.messages import BinaryContent, ImageUrl, UserContent-from typing_extensions import Self, override-from agenton.layers import EmptyRuntimeState, NoLayerDeps, PydanticAILayer+from pydantic import BaseModel, ConfigDict+from pydantic_ai.capabilities import AbstractCapability+from dify_agent.runtime.context import Depsfrom dify_agent.layers.user_prompt.configs import (- DIFY_USER_PROMPT_LAYER_TYPE_ID,DifyUserPromptDownloadConfig,DifyUserPromptImageConfig,DifyUserPromptLayerConfig,)-@dataclass(slots=True)-class DifyUserPromptLayer(PydanticAILayer[NoLayerDeps, object, DifyUserPromptLayerConfig, EmptyRuntimeState]):- """State-free layer for a text prompt and directly attached images."""+class Config(DifyUserPromptLayerConfig):+ pass- type_id: ClassVar[str | None] = DIFY_USER_PROMPT_LAYER_TYPE_ID- config: DifyUserPromptLayerConfig- @classmethod- @override- def from_config(cls, config: DifyUserPromptLayerConfig) -> Self:- return cls(config=DifyUserPromptLayerConfig.model_validate(config))+class State(BaseModel):+ model_config = ConfigDict(extra="forbid")- @property- @override- def user_prompts(self) -> list[UserContent]:++class Capability(AbstractCapability[Deps]):+ """Resolve current user content before calling Agent.run."""++ def __init__(self, name: str):+ self.id = name+ self.name = name++ def build_user_content(self, deps: Deps) -> list[UserContent]:+ config = Config.model_validate(deps.layers[self.name]["config"])images: list[UserContent] = []downloads: list[DifyUserPromptDownloadConfig] = []- for file in self.config.files:+ for file in config.files:match file.delivery:case "multimodal":images.append(_to_image_content(file))@@ -44,7 +45,7 @@ class DifyUserPromptLayer(PydanticAILayer[NoLayerDeps, object, DifyUserPromptLaydownloads.append(file)case _:assert_never(file)- return [_append_file_downloads(self.config.text, downloads), *images]+ return [_append_file_downloads(config.text, downloads), *images]def _append_file_downloads(text: str, files: list[DifyUserPromptDownloadConfig]) -> str:@@ -88,4 +89,4 @@ def _identifier_from_filename(filename: str, file_format: str) -> str:return filename-__all__ = ["DifyUserPromptLayer"]+__all__ = ["Config", "State", "Capability"]diff --git a/dify-agent/src/dify_agent/protocol/__init__.py b/dify-agent/src/dify_agent/protocol/__init__.pyindex 0eb18b57a36..11664536ce5 100644--- a/dify-agent/src/dify_agent/protocol/__init__.py+++ b/dify-agent/src/dify_agent/protocol/__init__.py@@ -15,10 +15,7 @@ from .schemas import (CancelRunResponse,CreateRunRequest,CreateRunResponse,- DeferredToolCallPayload,- DeferredToolResultsPayload,EmptyRunEventData,- LayerExitSignals,PydanticAIStreamRunEvent,RunCancelledEvent,RunCancelledEventData,@@ -30,12 +27,12 @@ from .schemas import (RunFailedEventData,RunFailureType,RunLayerSpec,+ SessionSnapshot,RunStartedEvent,RunStatus,RunStatusResponse,RunSucceededEvent,RunSucceededEventData,- normalize_composition,utc_now,)from .execution_binding import (@@ -76,14 +73,11 @@ __all__ = ["CreateExecutionBindingResponse","CreateHomeSnapshotFromBindingRequest","DeleteHomeSnapshotRequest",- "DeferredToolCallPayload",- "DeferredToolResultsPayload","DIFY_AGENT_HISTORY_LAYER_ID","DIFY_AGENT_MODEL_LAYER_ID","DIFY_AGENT_OUTPUT_LAYER_ID","DestroyExecutionBindingRequest","EmptyRunEventData",- "LayerExitSignals","HomeSnapshotResponse","PydanticAIStreamRunEvent","RUN_EVENT_ADAPTER",@@ -97,11 +91,11 @@ __all__ = ["RunFailedEventData","RunFailureType","RunLayerSpec",+ "SessionSnapshot","RunStartedEvent","RunStatus","RunStatusResponse","RunSucceededEvent","RunSucceededEventData",- "normalize_composition","utc_now",]diff --git a/dify-agent/src/dify_agent/protocol/schemas.py b/dify-agent/src/dify_agent/protocol/schemas.pyindex e0cb62c7f00..0318649c632 100644--- a/dify-agent/src/dify_agent/protocol/schemas.py+++ b/dify-agent/src/dify_agent/protocol/schemas.py@@ -1,36 +1,10 @@-"""Public HTTP protocol schemas for the Dify Agent run API.--This module is the shared wire contract for the FastAPI server, runtime event-producers, storage adapters, and Python client. Create-run requests expose a-Dify-friendly ``composition.layers[].config`` shape so callers can describe one-layer in one place; the server normalizes that public DTO into Agenton's-state-only ``CompositorConfig`` plus node-name keyed per-run configs before-calling ``Compositor.enter(configs=...)``. Session snapshots, deferred tool-results, and ``on_exit`` stay top-level because they are per-run resume state or-exit policy, not graph node definition.--The server still constructs layers only from explicit provider type ids, keeping-HTTP input data-only and preventing unsafe import-path construction. Run events-are append-only records; Redis stream ids (or in-memory equivalents in tests) are-the public cursors used by polling and SSE replay. Event envelopes keep the-public ``id``/``run_id``/``type``/``data``/``created_at`` shape, while each-``type`` has a typed ``data`` model so OpenAPI, Redis replay, and clients parse-the same payload contract. Model/provider selection is part of the submitted-composition, not a top-level run field; the runtime reads the model layer named-by ``DIFY_AGENT_MODEL_LAYER_ID``, the optional history layer named by-``DIFY_AGENT_HISTORY_LAYER_ID``, and the optional structured output layer named-by ``DIFY_AGENT_OUTPUT_LAYER_ID``. Request-level ``on_exit`` signals decide-whether each active layer is suspended or deleted when the run exits, with-suspend as the default so terminal events can include resumable snapshots.-Successful runs always publish the resumable Agenton session snapshot on the-terminal ``run_succeeded`` event; failed and cancelled runs publish it when the-compositor context was entered and exited. Success includes either the final JSON-safe-``output`` or a deferred external ``deferred_tool_call`` payload. Session-snapshots carry only layer lifecycle/runtime state in-compositor order; they do not persist output-layer config. Resumed-structured-output runs therefore must resubmit the same ``output`` layer in-``composition.layers[]`` so snapshot layer name/order still matches the-composition and the runtime can rebuild the same structured output contract.+"""Data-only HTTP protocol for native Pydantic AI module runs.++Composition names resolve through a server-owned registry. Each module receives+current JSON Config and restored JSON State through deps.layers[name]; Config+and live services are never persisted. Snapshot v2 is keyed by name and has no+ordering or generic lifecycle state. Terminal events include a state snapshot+after native capability cleanup on success, failure and cancellation."""from __future__ import annotations@@ -40,12 +14,10 @@ from decimal import Decimalfrom enum import StrEnumfrom typing import Annotated, ClassVar, Final, Literal, TypeAlias-from pydantic import BaseModel, ConfigDict, Field, JsonValue, TypeAdapter, model_serializer, model_validator+from pydantic import BaseModel, ConfigDict, Field, JsonValue, TypeAdapter, model_validatorfrom pydantic_ai.messages import AgentStreamEvent-from pydantic_ai.tools import DeferredToolResults-from agenton.compositor import CompositorConfig, CompositorSessionSnapshot, LayerConfigInput, LayerNodeConfig-from agenton.layers import ExitIntent+from dify_agent.protocol.snapshot import SessionSnapshotDIFY_AGENT_MODEL_LAYER_ID: Final[str] = "llm"@@ -64,8 +36,8 @@ RunEventType = Literal[class RunFailureType(StrEnum):"""Stable machine-readable categories for failed Dify Agent runs.- Run-limit failures cover execution budgets enforced by Dify Agent, not- provider, connection, or wall-clock timeouts.+ Run-limit failures cover Dify Agent's model-request budget and run wall-clock+ deadline. Provider and connection timeouts retain their own error categories."""AGENT_RUN_LIMIT_EXCEEDED = "agent_run_limit_exceeded"@@ -76,83 +48,35 @@ def utc_now() -> datetime:return datetime.now(timezone.utc)-class LayerExitSignals(BaseModel):- """Requested per-layer lifecycle behavior for the top-level ``on_exit`` field."""-- default: ExitIntent = ExitIntent.SUSPEND- layers: dict[str, ExitIntent] = Field(default_factory=dict)-- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")--class RunLayerSpec(BaseModel):- """Public graph node plus per-run layer config for one Dify Agent layer.-- ``name``/``type``/``deps``/``metadata`` are normalized into Agenton's- provider-backed graph config. ``config`` is kept separate at the Agenton- boundary and passed to ``Compositor.enter(configs=...)`` keyed by ``name``;- existing layer config DTO instances are preserved so client code can stay- DTO-first without being forced into raw dictionaries.- """-- name: str- type: str- deps: dict[str, str] = Field(default_factory=dict)- metadata: dict[str, JsonValue] = Field(default_factory=dict)- config: LayerConfigInput = None+ """One registered module and its current JSON configuration."""+ name: str = Field(min_length=1)+ config: dict[str, JsonValue] = Field(default_factory=dict)model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")class RunComposition(BaseModel):- """Public create-run composition DTO.+ """Module configuration; instruction order is not a public contract."""- The public shape intentionally differs from Agenton's internal- ``CompositorConfig`` by carrying each layer's per-run config next to its graph- node fields. Use ``normalize_composition`` at server/runtime boundaries before- constructing a ``Compositor``.- """-- schema_version: int = 1+ schema_version: Literal[2] = 2layers: list[RunLayerSpec]-model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")class CreateRunRequest(BaseModel):- """Request body for creating one async agent run.-- Model/provider configuration must be supplied through the composition layer- named by ``DIFY_AGENT_MODEL_LAYER_ID``. Optional persisted conversation- history may be supplied through the composition layer named by- ``DIFY_AGENT_HISTORY_LAYER_ID``. Structured output may be supplied through- the optional composition layer named by- ``DIFY_AGENT_OUTPUT_LAYER_ID``. ``on_exit`` defaults every active layer to- suspend so callers receive a resumable success snapshot unless they- explicitly request delete for one or more layers. Session snapshots do not- preserve output-layer config, so resume requests that rely on structured- output must include the same ``output`` layer in ``composition.layers[]`` to- keep snapshot compatibility and rebuild the output schema. Dify tenant,- user, and run-correlation identifiers must be submitted through a- ``dify.execution_context`` entry in ``composition.layers[]``; there is no- parallel top-level ``execution_context`` request field. External deferred- tool continuation input belongs in the top-level ``deferred_tool_results``- field rather than inside composition. Resume requests are therefore expected- to pair a prior ``session_snapshot`` with the same logical composition so- Agenton can rebuild the same layers and message history. For ask-human- continuation specifically, the matching pending tool call must still exist- in prior history state; callers should keep the history layer active across- runs so deferred tool results can be matched against the original model- response instead of starting a fresh user-prompt turn.+ """Create a run using current Config and an optional state-only snapshot.++ The model slot is named llm, history and output are optional reserved slots.+ Product+ binding/workspace lifecycle and state storage are owned by the API caller.+ Native capabilities always release operation resources at run exit."""composition: RunCompositionidempotency_key: str | None = Nonemetadata: dict[str, JsonValue] = Field(default_factory=dict)- session_snapshot: CompositorSessionSnapshot | None = None- deferred_tool_results: DeferredToolResultsPayload | None = None- on_exit: LayerExitSignals = Field(default_factory=LayerExitSignals)-+ session_snapshot: SessionSnapshot | None = Nonemodel_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")@@ -170,35 +94,6 @@ class CancelRunRequest(BaseModel):model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")-def normalize_composition(composition: RunComposition) -> tuple[CompositorConfig, dict[str, LayerConfigInput]]:- """Split public Dify composition into Agenton's graph config and layer configs.-- Returns:- A ``CompositorConfig`` containing only graph fields and a node-name keyed- config mapping suitable for ``Compositor.enter(configs=...)``.-- The helper is the stable public-to-Agenton boundary: it preserves concrete- ``LayerConfig`` DTO inputs where possible, does not accept legacy- ``LayerNodeConfig(config=...)`` payloads, and keeps session snapshots plus- exit signals out of graph normalization.- """-- graph_config = CompositorConfig(- schema_version=composition.schema_version,- layers=[- LayerNodeConfig(- name=layer.name,- type=layer.type,- deps=dict(layer.deps),- metadata=dict(layer.metadata),- )- for layer in composition.layers- ],- )- layer_configs = {layer.name: layer.config for layer in composition.layers}- return graph_config, layer_configs--class CreateRunResponse(BaseModel):"""Response returned after a run has been persisted and scheduled locally."""@@ -236,33 +131,6 @@ class EmptyRunEventData(BaseModel):model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")-class DeferredToolResultsPayload(BaseModel):- """Public JSON-safe DTO for deferred external tool results supplied on resume."""-- calls: dict[str, JsonValue] = Field(default_factory=dict)- metadata: dict[str, dict[str, JsonValue]] = Field(default_factory=dict)-- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")-- def to_pydantic_ai(self) -> DeferredToolResults:- """Convert the public DTO into pydantic-ai's resume input dataclass."""- return DeferredToolResults(- calls=dict(self.calls),- metadata={key: dict(value) for key, value in self.metadata.items()},- )---class DeferredToolCallPayload(BaseModel):- """Terminal success payload for one deferred external tool request."""-- tool_call_id: str- tool_name: str- args: JsonValue- metadata: dict[str, JsonValue] = Field(default_factory=dict)-- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")--class AgentRunUsage(BaseModel):"""Complete model usage reported for one Agent run.@@ -295,34 +163,13 @@ class AgentRunUsage(BaseModel):class RunSucceededEventData(BaseModel):- """Terminal success payload for final output or deferred tool continuation."""+ """Terminal final output and state captured after capability cleanup."""- output: JsonValue | None = None- deferred_tool_call: DeferredToolCallPayload | None = None- session_snapshot: CompositorSessionSnapshot+ output: JsonValue+ session_snapshot: SessionSnapshotusage: AgentRunUsage | None = None-model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")- @model_validator(mode="after")- def _validate_result_shape(self) -> RunSucceededEventData:- has_output = "output" in self.model_fields_set- has_deferred_tool_call = "deferred_tool_call" in self.model_fields_set- if has_output == has_deferred_tool_call:- raise ValueError("Exactly one of output or deferred_tool_call must be set")- return self-- @model_serializer(mode="plain")- def _serialize_active_result(self) -> dict[str, object]:- data: dict[str, object] = {"session_snapshot": self.session_snapshot}- if "output" in self.model_fields_set:- data["output"] = self.output- if "deferred_tool_call" in self.model_fields_set:- data["deferred_tool_call"] = self.deferred_tool_call- if self.usage is not None:- data["usage"] = self.usage- return data-class RunFailedEventData(BaseModel):"""Terminal failure payload shown to polling and SSE consumers."""@@ -330,7 +177,7 @@ class RunFailedEventData(BaseModel):error: strerror_type: RunFailureType | None = Nonereason: str | None = None- session_snapshot: CompositorSessionSnapshot | None = None+ session_snapshot: SessionSnapshot | None = Noneusage: AgentRunUsage | None = Nonemodel_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")@@ -341,7 +188,7 @@ class RunCancelledEventData(BaseModel):reason: str | None = Nonemessage: str | None = None- session_snapshot: CompositorSessionSnapshot | None = None+ session_snapshot: SessionSnapshot | None = Noneusage: AgentRunUsage | None = Nonemodel_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")@@ -417,13 +264,10 @@ __all__ = ["CancelRunResponse","CreateRunRequest","CreateRunResponse",- "DeferredToolCallPayload",- "DeferredToolResultsPayload","DIFY_AGENT_HISTORY_LAYER_ID","DIFY_AGENT_MODEL_LAYER_ID","DIFY_AGENT_OUTPUT_LAYER_ID","EmptyRunEventData",- "LayerExitSignals","PydanticAIStreamRunEvent","RUN_EVENT_ADAPTER","RunCancelledEvent",@@ -441,6 +285,6 @@ __all__ = ["RunSucceededEvent","RunSucceededEventData","RunLayerSpec",- "normalize_composition",+ "SessionSnapshot","utc_now",]diff --git a/dify-agent/src/dify_agent/protocol/snapshot.py b/dify-agent/src/dify_agent/protocol/snapshot.pynew file mode 100644index 00000000000..f6cbecfd400--- /dev/null+++ b/dify-agent/src/dify_agent/protocol/snapshot.py@@ -0,0 +1,126 @@+"""State-only session snapshots with version dispatch at model validation.++Configuration and live resources never belong to a snapshot. Module validators+check the data after it is paired with the current request configuration.+"""++from typing import ClassVar, Literal++from pydantic import BaseModel, ConfigDict, Field, JsonValue, model_validator+from pydantic_ai.messages import ModelMessagesTypeAdapter, ModelRequest, RetryPromptPart, ToolReturnPart+++_LEGACY_NAMES = frozenset(+ {+ "agent_soul_prompt",+ "workflow_node_job_prompt",+ "workflow_user_prompt",+ "agent_app_user_prompt",+ "execution_context",+ "runtime",+ "shell",+ "config",+ "history",+ "llm",+ "tools",+ "core_tools",+ "knowledge",+ "ask_human",+ "output",+ "prompt",+ "user_prompt",+ }+)+++def migrate_snapshot_v1_to_v2(snapshot: dict[str, object]) -> dict[str, object]:+ """Convert Agenton v1 list snapshots to state-only v2 JSON data.++ Legacy snapshots lack module types, so only known product slots can migrate.+ Removed slots have no resumable state; Config-derived fields are regenerated.+ Pending AskHuman calls are marked interrupted so native history repair can+ close them before the first new user turn.++ The input is not modified. Non-list shapes pass through for the current+ model's validation and defaults. This function performs no persistence I/O.+ """+ if set(snapshot) - {"schema_version", "layers"}:+ raise ValueError("Unknown legacy snapshot fields")+ layers = snapshot.get("layers")+ if not isinstance(layers, list):+ return snapshot+ states: dict[str, object] = {}+ seen: set[str] = set()+ for slot in layers:+ if not isinstance(slot, dict) or set(slot) != {"name", "lifecycle_state", "runtime_state"}:+ raise ValueError("Invalid legacy snapshot slot")+ name = slot["name"]+ if not isinstance(name, str) or name not in _LEGACY_NAMES:+ raise ValueError(f"Unknown legacy snapshot module: {name}")+ if name in seen:+ raise ValueError(f"Duplicate legacy snapshot module: {name}")+ seen.add(name)+ lifecycle = slot["lifecycle_state"]+ if lifecycle not in {"new", "suspended", "closed"}:+ raise ValueError(f"Invalid legacy lifecycle state: {lifecycle}")+ state = slot["runtime_state"]+ if not isinstance(state, dict):+ raise ValueError(f"Invalid legacy state for {name}")+ state = dict(state)+ if name == "ask_human":+ continue+ if lifecycle == "closed":+ state = {}+ elif name in {"shell", "config"}:+ state["initialized"] = lifecycle != "new"+ if name == "config":+ for key in (+ "config_context_json",+ "config_cli_help",+ "push_spec_semantics",+ "push_spec_json_schema",+ "push_spec_example",+ ):+ state.pop(key, None)+ states[name] = state+ history = states.get("history")+ if "ask_human" in seen and isinstance(history, dict):+ messages = ModelMessagesTypeAdapter.validate_python(history.get("messages", []))+ if messages and messages[-1].state == "complete":+ answered: set[str] = set()+ for message in reversed(messages):+ if isinstance(message, ModelRequest):+ answered.update(+ part.tool_call_id+ for part in message.parts+ if isinstance(part, (ToolReturnPart, RetryPromptPart))+ )+ else:+ if any(+ call.tool_name == "ask_human" and call.tool_call_id not in answered+ for call in message.tool_calls+ ):+ # Keep every other field/message; native PAI supplies the+ # interrupted return when a new prompt is submitted.+ raw_messages = history["messages"]+ history["messages"] = [+ *raw_messages[:-1],+ {**raw_messages[-1], "state": "interrupted"},+ ]+ break+ return {"schema_version": 2, "layers": states}+++class SessionSnapshot(BaseModel):+ """JSON state keyed by registered module name, independent of ordering."""++ schema_version: Literal[2] = 2+ layers: dict[str, dict[str, JsonValue]] = Field(default_factory=dict)+ model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")++ @model_validator(mode="before")+ @classmethod+ def migrate_snapshot(cls, value: object) -> object:+ if isinstance(value, dict) and value.get("schema_version", 1) == 1:+ return migrate_snapshot_v1_to_v2(value)+ return valuediff --git a/dify-agent/src/dify_agent/runtime/agent_factory.py b/dify-agent/src/dify_agent/runtime/agent_factory.pyindex 0161d4159fb..1bf1449c75c 100644--- a/dify-agent/src/dify_agent/runtime/agent_factory.py+++ b/dify-agent/src/dify_agent/runtime/agent_factory.py@@ -1,25 +1,16 @@-"""Pydantic AI agent construction for models supplied by Agenton layers.--The run request carries model/provider selection in the layer graph. This helper-keeps Agent construction details out of ``AgentRunRunner`` while accepting an-already resolved Pydantic AI model from the configured model layer. Tool values-arriving here are already transformed by Agenton's-``PYDANTIC_AI_TRANSFORMERS`` preset. The runner passes Dify system prompts as-run-level instructions and the context compaction capability directly to-``Agent.run``. The caller also passes the already resolved ``output_type`` so legacy text output and the-optional JSON Schema output layer share the same ``Agent`` construction path.-"""+"""Native Pydantic AI agent construction for one module run."""from collections.abc import Sequencefrom typing import Any, Final, castfrom pydantic_ai import Agent+from pydantic_ai.capabilities import AbstractCapabilityfrom pydantic_ai.messages import UserContentfrom pydantic_ai.models import Modelfrom pydantic_ai.output import OutputSpec+from pydantic_ai.toolsets import AbstractToolset-from agenton.layers.types import PydanticAITool-+from dify_agent.runtime.context import DepsDIFY_AGENT_RUN_NAME: Final[str] = "dify-agent"@@ -27,31 +18,27 @@ DIFY_AGENT_RUN_NAME: Final[str] = "dify-agent"def create_agent(model: Model[Any],*,- tools: Sequence[PydanticAITool[object]],+ toolsets: Sequence[AbstractToolset[Deps]],+ capabilities: Sequence[AbstractCapability[Deps]],output_type: OutputSpec[object] = str,-) -> Agent[None, object]:- """Create the pydantic-ai agent for one run.-- ``output_type`` is resolved by the runtime after entering the Agenton run so- validation and execution both honor the same optional structured output- contract. For structured output runs the type inside ``output_type`` already- carries the Pydantic hooks needed for schema exposure and runtime validation,- so agent construction does not need to register a separate validator.- """- # TODO: propagate roster name, so gen_ai.agent.name can pick that up+) -> Agent[Deps, object]:+ """Use native instructions, tool dispatch, ordering and capability hooks."""agent = cast(- Agent[None, object],- Agent(model, name=DIFY_AGENT_RUN_NAME, output_type=output_type, tools=tools),+ Agent[Deps, object],+ Agent(+ model,+ name=DIFY_AGENT_RUN_NAME,+ deps_type=Deps,+ output_type=output_type,+ toolsets=toolsets,+ capabilities=capabilities,+ ),)agent.instrument = Falsereturn agentdef normalize_user_input(user_prompts: Sequence[UserContent]) -> str | Sequence[UserContent]:- """Return the pydantic-ai run input while preserving multi-part prompts."""if len(user_prompts) == 1 and isinstance(user_prompts[0], str):return user_prompts[0]return list(user_prompts)---__all__ = ["DIFY_AGENT_RUN_NAME", "create_agent", "normalize_user_input"]diff --git a/dify-agent/src/dify_agent/runtime/agenton_validation.py b/dify-agent/src/dify_agent/runtime/agenton_validation.pydeleted file mode 100644index 3522e16b081..00000000000--- a/dify-agent/src/dify_agent/runtime/agenton_validation.py+++ /dev/null@@ -1,28 +0,0 @@-"""Shared validation helpers for Agenton-backed request boundaries.--Most bad Dify Agent inputs surface from Agenton as ``KeyError``, ``TypeError``,-or ``ValueError`` while graph config, per-run layer config, and session snapshot-DTOs are being validated. One smaller class of request-shaped failures appears a-bit later, during ``Compositor.enter(...)`` before the body of the entered run-executes: session snapshots may contain lifecycle states such as ``CLOSED`` that-are serializable but not enterable. Agenton reports those as ``RuntimeError``.--Dify Agent intentionally translates only these known enter-time runtime errors-into public request-validation errors. Other runtime failures still represent-execution bugs or infrastructure problems and must not be downgraded to client-input errors.-"""--_ENTER_VALIDATION_RUNTIME_ERROR_FRAGMENTS = (- "ACTIVE snapshots are not allowed.",- "CLOSED snapshots cannot be entered.",-)---def is_agenton_enter_validation_runtime_error(exc: RuntimeError) -> bool:- """Return whether ``exc`` is a known Agenton enter-time input failure."""- message = str(exc)- return any(fragment in message for fragment in _ENTER_VALIDATION_RUNTIME_ERROR_FRAGMENTS)---__all__ = ["is_agenton_enter_validation_runtime_error"]diff --git a/dify-agent/src/dify_agent/runtime/compaction.py b/dify-agent/src/dify_agent/runtime/compaction.pyindex b1e40e5f436..3df21baf21f 100644--- a/dify-agent/src/dify_agent/runtime/compaction.py+++ b/dify-agent/src/dify_agent/runtime/compaction.py@@ -8,6 +8,7 @@ unused ``max_tokens=1`` values below solely to satisfy that validation; they arenot one-token Dify policy thresholds."""+from dify_agent.runtime.context import Depsfrom pydantic_ai.settings import ModelSettingsfrom pydantic_ai_harness.compaction import ClearToolResults, SummarizingCompaction, TieredCompaction@@ -16,7 +17,7 @@ def build_compaction_capability(*,context_window_tokens: int | None,model_settings: ModelSettings | None,-) -> TieredCompaction[None] | None:+) -> TieredCompaction[Deps] | None:"""Build compaction for the effective model window, or disable it when unknown."""if context_window_tokens is None:return Nonediff --git a/dify-agent/src/dify_agent/runtime/compositor_factory.py b/dify-agent/src/dify_agent/runtime/compositor_factory.pydeleted file mode 100644index a22df749ea6..00000000000--- a/dify-agent/src/dify_agent/runtime/compositor_factory.py+++ /dev/null@@ -1,185 +0,0 @@-"""Safe Agenton compositor construction for API-submitted configs.--Only explicitly allowed provider type ids are constructible here. The default-provider set contains prompt layers, the optional pydantic-ai history layer, the-state-free Dify structured output layer, the optional Dify ask-human layer, the-Dify execution-context and runtime-resource layers, the stateful Dify shell-layer, and the Dify plugin/knowledge business-layer family:--- ``dify.config`` for Agent Soul-backed config assets + eager pull,-- ``dify.execution_context`` for shared tenant/user/run daemon context,-- ``dify.runtime`` for operation-scoped RuntimeLease acquisition,-- ``dify.shell`` for command/file capabilities from the active RuntimeLease,-- ``dify.user_prompt`` for structured text-plus-image user turns,-- ``dify.plugin.llm`` for plugin-backed model selection,-- ``dify.plugin.tools`` for prepared plugin tool exposure, and-- ``dify.core.tools`` for API-routed Dify tool exposure, and-- ``dify.knowledge_base`` for inner-API-backed knowledge search tools.--Public DTOs provide Dify context plus plugin/model/tool data, while server-only-plugin daemon settings and Dify API inner settings are injected through provider-factories. The deployment-selected runtime backend profile is injected only-into the Runtime layer. Shell receives Agent Stub settings and consumes the-active lease's data plane. The resulting ``Compositor``-remains Agenton state-only at the snapshot boundary: live resources such as-HTTP clients are injected by runtime-owned providers, may be held on active-layer instances inside ``resource_context()``, and never enter session-snapshots.-"""--from __future__ import annotations--from collections.abc import Mapping, Sequence-from typing import Any--from pydantic_ai.messages import UserContent--from agenton.compositor import Compositor, CompositorConfig, LayerProvider, LayerProviderInput-from agenton.layers.types import AllPromptTypes, AllToolTypes, AllUserPromptTypes, PydanticAIPrompt, PydanticAITool-from agenton_collections.layers.pydantic_ai import PydanticAIHistoryLayer-from agenton_collections.layers.plain.basic import PromptLayer-from agenton_collections.transformers.pydantic_ai import PYDANTIC_AI_TRANSFORMERS-from dify_agent.agent_stub.shell_env import ShellAgentStubTokenFactory-from dify_agent.layers.ask_human.layer import DifyAskHumanLayer-from dify_agent.layers.config.layer import DifyConfigLayer-from dify_agent.layers.dify_core_tools.configs import DifyCoreToolsLayerConfig-from dify_agent.layers.dify_core_tools.layer import DifyCoreToolsLayer-from dify_agent.layers.dify_plugin.configs import DifyPluginLLMLayerConfig, DifyPluginToolsLayerConfig-from dify_agent.layers.dify_plugin.llm_layer import DifyPluginLLMLayer-from dify_agent.layers.dify_plugin.tools_layer import DifyPluginToolsLayer-from dify_agent.layers.execution_context.configs import DifyExecutionContextLayerConfig-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer-from dify_agent.layers.knowledge.configs import DifyKnowledgeBaseLayerConfig-from dify_agent.layers.knowledge.layer import DifyKnowledgeBaseLayer-from dify_agent.layers.output.output_layer import DifyOutputLayer-from dify_agent.layers.runtime.configs import DifyRuntimeLayerConfig-from dify_agent.layers.runtime.layer import DifyRuntimeLayer-from dify_agent.layers.shell.configs import DifyShellLayerConfig-from dify_agent.layers.shell.layer import DifyShellLayer-from dify_agent.layers.user_prompt.layer import DifyUserPromptLayer-from dify_agent.runtime_backend import RuntimeBackendProfile--type DifyAgentLayerProvider = LayerProvider[Any]---def create_default_layer_providers(- *,- plugin_daemon_url: str = "http://localhost:5002",- plugin_daemon_api_key: str = "",- inner_api_url: str = "http://localhost:5001",- inner_api_key: str = "",- runtime_backend_profile: RuntimeBackendProfile | None = None,- shell_redact_patterns: list[str] | None = None,- agent_stub_api_base_url: str | None = None,- agent_stub_token_factory: ShellAgentStubTokenFactory | None = None,-) -> tuple[DifyAgentLayerProvider, ...]:- """Return the server provider set of safe config-constructible layers."""- providers: list[DifyAgentLayerProvider] = [- LayerProvider.from_layer_type(PromptLayer),- LayerProvider.from_layer_type(DifyUserPromptLayer),- LayerProvider.from_layer_type(PydanticAIHistoryLayer),- LayerProvider.from_layer_type(DifyOutputLayer),- LayerProvider.from_layer_type(DifyAskHumanLayer),- LayerProvider.from_layer_type(DifyConfigLayer),- LayerProvider.from_factory(- layer_type=DifyExecutionContextLayer,- create=lambda config: DifyExecutionContextLayer.from_config_with_settings(- DifyExecutionContextLayerConfig.model_validate(config),- daemon_url=plugin_daemon_url,- daemon_api_key=plugin_daemon_api_key,- ),- ),- LayerProvider.from_factory(- layer_type=DifyShellLayer,- create=lambda config: DifyShellLayer.from_config_with_settings(- DifyShellLayerConfig.model_validate(config),- shell_redact_patterns=shell_redact_patterns or [],- agent_stub_api_base_url=agent_stub_api_base_url,- agent_stub_token_factory=agent_stub_token_factory,- ),- ),- LayerProvider.from_factory(- layer_type=DifyPluginLLMLayer,- create=lambda config: DifyPluginLLMLayer.from_config_with_settings(- DifyPluginLLMLayerConfig.model_validate(config),- inner_api_url=inner_api_url,- inner_api_key=inner_api_key,- ),- ),- LayerProvider.from_factory(- layer_type=DifyPluginToolsLayer,- create=lambda config: DifyPluginToolsLayer.from_config_with_settings(- DifyPluginToolsLayerConfig.model_validate(config),- inner_api_url=inner_api_url,- inner_api_key=inner_api_key,- ),- ),- LayerProvider.from_factory(- layer_type=DifyCoreToolsLayer,- create=lambda config: DifyCoreToolsLayer.from_config_with_settings(- DifyCoreToolsLayerConfig.model_validate(config),- inner_api_url=inner_api_url,- inner_api_key=inner_api_key,- ),- ),- LayerProvider.from_factory(- layer_type=DifyKnowledgeBaseLayer,- create=lambda config: DifyKnowledgeBaseLayer.from_config_with_settings(- DifyKnowledgeBaseLayerConfig.model_validate(config),- inner_api_url=inner_api_url,- inner_api_key=inner_api_key,- ),- ),- ]- if runtime_backend_profile is not None:- providers.extend(- [- LayerProvider.from_factory(- layer_type=DifyRuntimeLayer,- create=lambda config: DifyRuntimeLayer.from_config_with_backend(- DifyRuntimeLayerConfig.model_validate(config),- backend=runtime_backend_profile.execution_bindings,- ),- ),- ]- )- return tuple(providers)---def build_pydantic_ai_compositor(- config: CompositorConfig,- *,- providers: Sequence[LayerProviderInput],- node_providers: Mapping[str, LayerProviderInput] | None = None,-) -> Compositor[- PydanticAIPrompt[object],- PydanticAITool[object],- AllPromptTypes,- AllToolTypes,- UserContent,- AllUserPromptTypes,-]:- """Build a Pydantic AI-ready compositor from a validated graph config.-- Prompt, user prompt, and tool conversion is delegated to Agenton's shared- pydantic-ai transformer preset so Dify Agent does not duplicate conversion- logic for plain and pydantic-ai layer families. Callers must pass the already- selected provider set explicitly so provider defaulting stays at outer runtime- boundaries rather than being duplicated here.- """- return Compositor[- PydanticAIPrompt[object],- PydanticAITool[object],- AllPromptTypes,- AllToolTypes,- UserContent,- AllUserPromptTypes,- ].from_config(- config,- providers=providers,- node_providers=node_providers,- **PYDANTIC_AI_TRANSFORMERS,- )---__all__ = ["DifyAgentLayerProvider", "build_pydantic_ai_compositor", "create_default_layer_providers"]diff --git a/dify-agent/src/dify_agent/runtime/context.py b/dify-agent/src/dify_agent/runtime/context.pynew file mode 100644index 00000000000..55a1c672324--- /dev/null+++ b/dify-agent/src/dify_agent/runtime/context.py@@ -0,0 +1,56 @@+"""Dependencies for native Pydantic AI modules.++``layers`` is the sole source of module config and persisted state. Models are+validated copies and state changes must be dumped back explicitly. Services are+borrowed from the server lifespan; resources exist only inside one native run+and are closed by the capability that acquired them.+"""++from __future__ import annotations++from dataclasses import dataclass, field+from typing import TYPE_CHECKING, TypedDict++import httpx+from pydantic import JsonValue++from dify_agent.agent_stub.shell_env import ShellAgentStubTokenFactory+from dify_agent.runtime_backend import RuntimeBackendProfile, RuntimeLease++if TYPE_CHECKING:+ from dify_agent.layers.shell.layer import ShellSession+++class LayerData(TypedDict):+ config: dict[str, JsonValue]+ state: dict[str, JsonValue]+++@dataclass+class Services:+ """Lifespan-owned infrastructure borrowed by every run."""++ plugin_daemon_http_client: httpx.AsyncClient+ dify_api_http_client: httpx.AsyncClient+ plugin_daemon_url: str = "http://localhost:5002"+ plugin_daemon_api_key: str = field(default="", repr=False)+ inner_api_url: str = "http://localhost:5001"+ inner_api_key: str = field(default="", repr=False)+ runtime_backend_profile: RuntimeBackendProfile | None = None+ shell_redact_patterns: list[str] = field(default_factory=list)+ agent_stub_api_base_url: str | None = None+ agent_stub_token_factory: ShellAgentStubTokenFactory | None = None+++@dataclass+class RunResources:+ leases: dict[str, RuntimeLease] = field(default_factory=dict)+ shells: dict[str, ShellSession] = field(default_factory=dict)+++@dataclass+class Deps:+ layers: dict[str, LayerData]+ services: Services+ run_id: str+ resources: RunResources = field(default_factory=RunResources)diff --git a/dify-agent/src/dify_agent/runtime/event_sink.py b/dify-agent/src/dify_agent/runtime/event_sink.pyindex 161e1a75fde..ea68a3e1948 100644--- a/dify-agent/src/dify_agent/runtime/event_sink.py+++ b/dify-agent/src/dify_agent/runtime/event_sink.py@@ -10,15 +10,14 @@ implements the same contract with Redis streams infrom collections import defaultdictfrom dataclasses import dataclass-from typing import Protocol, TypeAlias, cast+from typing import Protocol, TypeAliasfrom pydantic import JsonValuefrom pydantic_ai.messages import AgentStreamEvent-from agenton.compositor import CompositorSessionSnapshot+from dify_agent.protocol.snapshot import SessionSnapshotfrom dify_agent.protocol.schemas import (AgentRunUsage,- DeferredToolCallPayload,EmptyRunEventData,PydanticAIStreamRunEvent,RunEvent,@@ -33,7 +32,6 @@ from dify_agent.protocol.schemas import ()-_UNSET = object()TerminalRunEvent: TypeAlias = RunSucceededEvent | RunFailedEventNonTerminalRunEvent: TypeAlias = RunStartedEvent | PydanticAIStreamRunEvent@@ -146,26 +144,15 @@ async def emit_run_succeeded(sink: RunEventSink,*,run_id: str,- output: JsonValue | None | object = _UNSET,- deferred_tool_call: DeferredToolCallPayload | object = _UNSET,- session_snapshot: CompositorSessionSnapshot,+ output: JsonValue,+ session_snapshot: SessionSnapshot,usage: AgentRunUsage | None = None,) -> RunFinalizationResult:- """Finalize a run as succeeded with output or deferred continuation.-- Callers must activate exactly one result branch. ``_UNSET`` is used instead- of ``None`` to preserve the distinction between an omitted inactive branch- and an active ``output`` branch whose JSON value is explicitly ``null``.- Without that sentinel, ``output=None`` would be indistinguishable from- “output field absent”, which would break nullable-success payloads.- """- data: dict[str, JsonValue | DeferredToolCallPayload | CompositorSessionSnapshot | AgentRunUsage | None] = {+ """Finalize a successful run, including explicitly null output."""+ data: dict[str, JsonValue | SessionSnapshot | AgentRunUsage | None] = {"session_snapshot": session_snapshot,}- if output is not _UNSET:- data["output"] = cast(JsonValue | None, output)- if deferred_tool_call is not _UNSET:- data["deferred_tool_call"] = cast(DeferredToolCallPayload, deferred_tool_call)+ data["output"] = outputif usage is not None:data["usage"] = usage@@ -185,7 +172,7 @@ async def emit_run_failed(error: str,error_type: RunFailureType | None = None,reason: str | None = None,- session_snapshot: CompositorSessionSnapshot | None = None,+ session_snapshot: SessionSnapshot | None = None,usage: AgentRunUsage | None = None,) -> RunFinalizationResult:"""Finalize a run with a failed terminal event."""diff --git a/dify-agent/src/dify_agent/runtime/history.py b/dify-agent/src/dify_agent/runtime/history.pydeleted file mode 100644index fc61e9cf3cc..00000000000--- a/dify-agent/src/dify_agent/runtime/history.py+++ /dev/null@@ -1,117 +0,0 @@-"""Helpers for optional Dify Agent history-layer integration.--Dify Agent keeps pydantic-ai conversation history as an optional Agenton layer-named ``history``. Current system instructions belong to each run and are never-stored. Once Pydantic AI binds and builds messages in the run capture, its-complete captured history replaces the layer for every terminal outcome,-including interrupted runs. A failure or cancellation before the capture-contains messages preserves the previously restored history. When a run is-interrupted with tool calls the model returned but the run never executed, the-stored history records that the response was cut short so the next run can close-those calls out instead of refusing a new user prompt.-"""--from __future__ import annotations--from collections.abc import Sequence-from dataclasses import replace-from typing import Protocol--from pydantic_ai.messages import ModelMessage, ModelRequest, ModelResponse--from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID, PydanticAIHistoryLayer-from dify_agent.protocol import DIFY_AGENT_HISTORY_LAYER_ID-from dify_agent.protocol.schemas import RunComposition---class SupportsHistoryLayerLookup(Protocol):- """Minimal entered-run surface needed by the history helper."""-- def get_layer(self, name: str, layer_type: type[PydanticAIHistoryLayer]) -> PydanticAIHistoryLayer:- """Return a typed layer instance or raise lookup/type errors."""- ...---def validate_history_layer_composition(composition: RunComposition) -> None:- """Reject unsupported public history-layer graph shapes."""- history_layers = [layer for layer in composition.layers if layer.type == PYDANTIC_AI_HISTORY_LAYER_TYPE_ID]- if not history_layers:- return-- if len(history_layers) > 1:- names = ", ".join(layer.name for layer in history_layers)- raise ValueError(- f"Only one '{PYDANTIC_AI_HISTORY_LAYER_TYPE_ID}' layer is supported, named "- f"'{DIFY_AGENT_HISTORY_LAYER_ID}'. Found layers: {names}."- )-- history_layer = history_layers[0]- if history_layer.name != DIFY_AGENT_HISTORY_LAYER_ID:- raise ValueError(- f"Layer type '{PYDANTIC_AI_HISTORY_LAYER_TYPE_ID}' must use reserved layer name "- f"'{DIFY_AGENT_HISTORY_LAYER_ID}', got '{history_layer.name}'."- )-- if history_layer.deps:- dependency_names = ", ".join(sorted(history_layer.deps))- raise ValueError(- f"Layer type '{PYDANTIC_AI_HISTORY_LAYER_TYPE_ID}' does not support dependencies; "- f"got dependency keys: {dependency_names}."- )---def get_history_layer(run: SupportsHistoryLayerLookup) -> PydanticAIHistoryLayer | None:- """Return the active history layer when the reserved slot is present."""- try:- return run.get_layer(DIFY_AGENT_HISTORY_LAYER_ID, PydanticAIHistoryLayer)- except KeyError:- return None---def replace_run_history(- history_layer: PydanticAIHistoryLayer | None,- messages: Sequence[ModelMessage],- *,- interrupted: bool = False,-) -> None:- """Persist a run's captured history without transient instructions.-- Set ``interrupted`` when the run did not reach a terminal result, so tool calls the run- never got to execute are marked as such for the next run.- """- if history_layer is None:- return- persistent_messages: list[ModelMessage] = [- replace(message, instructions=None) if isinstance(message, ModelRequest) else message for message in messages- ]- if interrupted:- persistent_messages = _mark_trailing_tool_calls_interrupted(persistent_messages)- history_layer.replace_messages(persistent_messages)---def _mark_trailing_tool_calls_interrupted(messages: list[ModelMessage]) -> list[ModelMessage]:- """Record that a final response's tool calls were never executed.-- A run cancelled between the model returning tool calls and the first tool result leaves a- ``'complete'`` response whose calls have no matching result. Pydantic AI closes such calls- out with synthesized returns on the next run only when that tail is marked- ``'interrupted'``; otherwise it rejects the next user prompt and the conversation cannot- continue. A run that ends in ``DeferredToolRequests`` keeps its open calls, which is why- this is applied to interrupted runs only.- """- if not messages:- return messages- last_message = messages[-1]- if not isinstance(last_message, ModelResponse) or last_message.state != "complete":- return messages- if not last_message.tool_calls:- return messages- return [*messages[:-1], replace(last_message, state="interrupted")]---__all__ = [- "SupportsHistoryLayerLookup",- "get_history_layer",- "replace_run_history",- "validate_history_layer_composition",-]diff --git a/dify-agent/src/dify_agent/runtime/layer_exit_signals.py b/dify-agent/src/dify_agent/runtime/layer_exit_signals.pydeleted file mode 100644index 3636b898368..00000000000--- a/dify-agent/src/dify_agent/runtime/layer_exit_signals.py+++ /dev/null@@ -1,46 +0,0 @@-"""Validation and application of request-level Agenton layer exit signals.--HTTP requests carry data-only lifecycle intent in the top-level ``on_exit``-field. The runtime validates signal keys against the built compositor before a-run is persisted or entered, then applies the resolved intent to the active-``CompositorRun`` after entry because Agenton initializes each run slot with a-delete-on-exit intent.-"""--from typing import Any--from agenton.compositor import Compositor, CompositorRun-from agenton.layers import ExitIntent-from dify_agent.protocol.schemas import LayerExitSignals---def validate_layer_exit_signals(- compositor: Compositor[Any, Any, Any, Any, Any, Any],- signals: LayerExitSignals,-) -> None:- """Raise ``ValueError`` when ``signals`` mention layers absent from ``compositor``."""- known_layer_ids = {node.name for node in compositor.nodes}- unknown_layer_ids = set(signals.layers) - known_layer_ids- if not unknown_layer_ids:- return-- names = ", ".join(sorted(unknown_layer_ids))- raise ValueError(f"on_exit.layers references unknown layer ids: {names}.")---def apply_layer_exit_signals(- run: CompositorRun[Any, Any, Any, Any, Any, Any],- signals: LayerExitSignals,-) -> None:- """Apply ``signals`` to active run slots for the current compositor entry."""- for layer_id in run.slots:- intent = signals.layers.get(layer_id, signals.default)- if intent is ExitIntent.SUSPEND:- run.suspend_layer_on_exit(layer_id)- elif intent is ExitIntent.DELETE:- run.delete_layer_on_exit(layer_id)- else:- raise ValueError(f"Unsupported layer exit intent: {intent!r}.")---__all__ = ["apply_layer_exit_signals", "validate_layer_exit_signals"]diff --git a/dify-agent/src/dify_agent/runtime/modules.py b/dify-agent/src/dify_agent/runtime/modules.pynew file mode 100644index 00000000000..959572ab94b--- /dev/null+++ b/dify-agent/src/dify_agent/runtime/modules.py@@ -0,0 +1,139 @@+"""Allowlisted name-to-module registry and JSON state loading.++Modules export Config, State and exactly one native Capability or Toolset. All+configuration, state and references are checked before a run performs I/O. The+registry is server-owned; HTTP callers never supply import paths or live objects.+"""++from collections.abc import Mapping+from types import ModuleType+from typing import cast++from pydantic import BaseModel+from pydantic_ai.capabilities import AbstractCapability+from pydantic_ai.toolsets import AbstractToolset++from dify_agent.layers import history+from dify_agent.layers.prompt import layer as prompt+from dify_agent.layers.config import layer as config+from dify_agent.layers.dify_core_tools import layer as core_tools+from dify_agent.layers.dify_plugin import llm_layer as llm, tools_layer as plugin_tools+from dify_agent.layers.execution_context import layer as execution_context+from dify_agent.layers.knowledge import layer as knowledge+from dify_agent.layers.output import output_layer as output+from dify_agent.layers.runtime import layer as runtime+from dify_agent.layers.shell import layer as shell+from dify_agent.layers.user_prompt import layer as user_prompt+from dify_agent.protocol.schemas import CreateRunRequest+from dify_agent.protocol.snapshot import SessionSnapshot+from dify_agent.runtime.context import Deps, LayerData, Services+++REGISTRY: dict[str, ModuleType] = {+ "agent_soul_prompt": prompt,+ "workflow_node_job_prompt": prompt,+ "workflow_user_prompt": prompt,+ "agent_app_user_prompt": user_prompt,+ "prompt": prompt,+ "user_prompt": user_prompt,+ "execution_context": execution_context,+ "runtime": runtime,+ "shell": shell,+ "config": config,+ "history": history,+ "llm": llm,+ "tools": plugin_tools,+ "core_tools": core_tools,+ "knowledge": knowledge,+ "output": output,+}++_REFERENCES: dict[ModuleType, dict[str, ModuleType]] = {+ llm: {"execution_context": execution_context},+ plugin_tools: {"execution_context": execution_context, "shell": shell},+ core_tools: {"execution_context": execution_context},+ knowledge: {"execution_context": execution_context},+ shell: {"runtime": runtime, "execution_context": execution_context},+ config: {"shell": shell},+}+++def load_modules(+ request: CreateRunRequest, services: Services, run_id: str, *, registry: Mapping[str, ModuleType] = REGISTRY+) -> Deps:+ """Create independent validated JSON data using current Config and saved State.++ Optional modules may be added or removed between runs. Retained unknown state+ names are rejected, while known removed slots are omitted from the new+ snapshot. Legacy migration happens at the snapshot DTO boundary.+ """+ names = [spec.name for spec in request.composition.layers]+ if len(set(names)) != len(names):+ raise ValueError("Module names must be unique")+ if "llm" not in names:+ raise ValueError("Missing required 'llm' module")+ state = request.session_snapshot.layers if request.session_snapshot is not None else {}+ unknown = state.keys() - registry.keys()+ if unknown:+ raise ValueError(f"Unknown snapshot modules: {', '.join(sorted(unknown))}")+ layers: dict[str, LayerData] = {}+ configs: dict[str, BaseModel] = {}+ for spec in request.composition.layers:+ module = registry.get(spec.name)+ if module is None:+ raise ValueError(f"Unknown registered module: {spec.name}")+ config_type = cast(type[BaseModel], module.Config)+ state_type = cast(type[BaseModel], module.State)+ has_capability = hasattr(module, "Capability")+ has_toolset = hasattr(module, "Toolset")+ if has_capability == has_toolset:+ raise TypeError(f"Module {spec.name} must export exactly one Capability or Toolset")+ implementation = module.Capability if has_capability else module.Toolset+ expected = AbstractCapability if has_capability else AbstractToolset+ if not issubclass(implementation, expected):+ raise TypeError(f"Module {spec.name} must use native Pydantic AI components")+ cfg = config_type.model_validate(spec.config)+ restored = state_type.model_validate(state.get(spec.name, {}))+ configs[spec.name] = cfg+ layers[spec.name] = {"config": cfg.model_dump(mode="json"), "state": restored.model_dump(mode="json")}+ for name, cfg in configs.items():+ module = registry[name]+ for field, expected_module in _REFERENCES.get(module, {}).items():+ target = cast(str | None, layers[name]["config"][field])+ if target is None:+ continue+ if target not in layers or registry[target] is not expected_module:+ raise ValueError(+ f"Module {name} reference {field} must name a configured {expected_module.__name__} module"+ )+ if module is runtime and services.runtime_backend_profile is None:+ raise ValueError("Runtime module requires a configured runtime backend")+ if module is plugin_tools:+ for tool in cast(plugin_tools.Config, cfg).tools:+ plugin_tools._validate_required_hidden_parameters(tool, tool.parameters)+ if module is knowledge:+ target = cast(knowledge.Config, cfg).execution_context+ knowledge._build_caller_context(configs[target])+ return Deps(layers=layers, services=services, run_id=run_id)+++def create_modules(+ deps: Deps, *, registry: Mapping[str, ModuleType] = REGISTRY+) -> dict[str, AbstractCapability[Deps] | AbstractToolset[Deps]]:+ """Construct fresh native instances for this run; no instance is restored."""+ return {+ name: (+ registry[name].Capability(name) if hasattr(registry[name], "Capability") else registry[name].Toolset(name)+ )+ for name in deps.layers+ }+++def snapshot_modules(deps: Deps, *, registry: Mapping[str, ModuleType] = REGISTRY) -> SessionSnapshot:+ """Validate and copy final state after resource cleanup, excluding all Config."""+ return SessionSnapshot(+ layers={+ name: registry[name].State.model_validate(entry["state"]).model_dump(mode="json")+ for name, entry in deps.layers.items()+ }+ )diff --git a/dify-agent/src/dify_agent/runtime/observability.py b/dify-agent/src/dify_agent/runtime/observability.pyindex 8933dea279c..b7b4d0de3e6 100644--- a/dify-agent/src/dify_agent/runtime/observability.py+++ b/dify-agent/src/dify_agent/runtime/observability.py@@ -3,7 +3,7 @@ from __future__ import annotationsimport asynciofrom collections.abc import Sequencefrom dataclasses import dataclass-from typing import TYPE_CHECKING, Any, Final, Literal+from typing import TYPE_CHECKING, Any, Final, Literal, overridefrom opentelemetry.context import Contextfrom opentelemetry.sdk.trace import ReadableSpan@@ -63,6 +63,7 @@ class IsolatedTracerProvider(TracerProvider):client: Logfirepreserve_external_parent: bool = False+ @overridedef get_tracer(self,instrumenting_module_name: str,@@ -97,6 +98,7 @@ class _IsolatedTracer(Tracer):return contextreturn set_span_in_context(INVALID_SPAN, context)+ @overridedef start_span(self,name: str,@@ -119,6 +121,7 @@ class _IsolatedTracer(Tracer):set_status_on_exception=set_status_on_exception,)+ @overridedef start_as_current_span(self,name: str,@@ -151,6 +154,7 @@ class RunScopedTracerProvider(TracerProvider):delegate: TracerProviderattributes: tuple[tuple[str, str], ...]+ @overridedef get_tracer(self,instrumenting_module_name: str,@@ -175,6 +179,7 @@ class _RunScopedTracer(Tracer):def _run_attributes(self, attributes: Attributes) -> Attributes:return {**(attributes or {}), **dict(self.attributes)}+ @overridedef start_span(self,name: str,@@ -197,6 +202,7 @@ class _RunScopedTracer(Tracer):set_status_on_exception=set_status_on_exception,)+ @overridedef start_as_current_span(self,name: str,diff --git a/dify-agent/src/dify_agent/runtime/output_type.py b/dify-agent/src/dify_agent/runtime/output_type.pydeleted file mode 100644index a8e12cfd6ff..00000000000--- a/dify-agent/src/dify_agent/runtime/output_type.py+++ /dev/null@@ -1,92 +0,0 @@-"""Validate and resolve the optional structured output layer.--Dify Agent keeps structured output outside Agenton's prompt/tool aggregation.-That means the request boundary must validate the public composition shape-before entering Agenton, while the entered-run helper resolves a complete output-contract containing the model-facing output type. The type itself carries the-custom Pydantic hooks needed for schema exposure and runtime validation, so the-runtime does not need a separate validator callback. Missing output layers-preserve the legacy plain-text ``str`` output contract.-"""--from typing import Protocol--from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID-from dify_agent.layers.output.output_layer import DifyOutputContract, DifyOutputLayer-from dify_agent.protocol import DIFY_AGENT_OUTPUT_LAYER_ID-from dify_agent.protocol.schemas import RunComposition---class SupportsOutputLayerLookup(Protocol):- """Minimal run surface needed to resolve the optional output layer."""-- def get_layer(self, name: str, layer_type: type[DifyOutputLayer]) -> DifyOutputLayer:- """Return a typed layer instance or raise lookup/type errors."""- ...---def validate_output_layer_composition(composition: RunComposition) -> None:- """Reject unsupported public output-layer graph shapes.-- The proposal reserves the node name ``output`` for the single supported- ``dify.output`` layer. Validating this directly from- ``CreateRunRequest.composition.layers`` keeps bad requests from silently- falling back to text output after entering Agenton.-- Raises:- ValueError: If more than one ``dify.output`` layer is declared or if the- single ``dify.output`` layer does not use the reserved node name- ``output``.- """- output_layer_names = [layer.name for layer in composition.layers if layer.type == DIFY_OUTPUT_LAYER_TYPE_ID]- if not output_layer_names:- return-- if len(output_layer_names) > 1:- names = ", ".join(output_layer_names)- raise ValueError(- f"Only one '{DIFY_OUTPUT_LAYER_TYPE_ID}' layer is supported, named '{DIFY_AGENT_OUTPUT_LAYER_ID}'. "- f"Found layers: {names}."- )-- output_layer_name = output_layer_names[0]- if output_layer_name != DIFY_AGENT_OUTPUT_LAYER_ID:- raise ValueError(- f"Layer type '{DIFY_OUTPUT_LAYER_TYPE_ID}' must use reserved layer name "- f"'{DIFY_AGENT_OUTPUT_LAYER_ID}', got '{output_layer_name}'."- )---_TEXT_OUTPUT_CONTRACT = DifyOutputContract(output_type=str)---def resolve_run_output_contract(run: SupportsOutputLayerLookup) -> DifyOutputContract:- """Return the run's configured pydantic-ai output contract.-- When the conventionally named output layer is absent, the runtime keeps the- existing plain-text behavior by returning a contract whose ``output_type`` is- ``str``. This helper assumes the- public composition has already passed ``validate_output_layer_composition``;- its remaining responsibility is to type-check the reserved ``output`` slot- after compositor entry and build the validated output type from the layer- config.-- Raises:- TypeError: If a layer named ``output`` exists but is not a- ``DifyOutputLayer``.- ValueError: If the output layer exists but its JSON Schema cannot be- converted into a supported pydantic-ai structured output contract.- """- try:- output_layer = run.get_layer(DIFY_AGENT_OUTPUT_LAYER_ID, DifyOutputLayer)- except KeyError:- return _TEXT_OUTPUT_CONTRACT- return output_layer.build_output_contract()---__all__ = [- "DifyOutputContract",- "SupportsOutputLayerLookup",- "resolve_run_output_contract",- "validate_output_layer_composition",-]diff --git a/dify-agent/src/dify_agent/runtime/run_scheduler.py b/dify-agent/src/dify_agent/runtime/run_scheduler.pyindex db3592b3cd1..dfebfdadade 100644--- a/dify-agent/src/dify_agent/runtime/run_scheduler.py+++ b/dify-agent/src/dify_agent/runtime/run_scheduler.py@@ -8,7 +8,7 @@ handoff. If the process crashes, currently active runs are lost until an externaoperator marks or retries them.Create-run requests are accepted once the scheduler is not stopping and storagecan persist the run record. Request-shaped execution failures are left to-``AgentRunRunner`` so bad compositions, ``on_exit`` policies, prompts,+``AgentRunRunner`` so bad compositions, prompts,structured-output schemas, or session snapshots become asynchronous``run_failed`` outcomes instead of synchronous HTTP rejections."""@@ -18,12 +18,11 @@ import loggingfrom collections.abc import Callablefrom typing import Protocol-import httpx-from agenton.compositor import CompositorSessionSnapshot, LayerProviderInput+from dify_agent.protocol.snapshot import SessionSnapshot+from dify_agent.runtime.context import Servicesfrom dify_agent.protocol.schemas import AgentRunUsage, CancelRunRequest, CancelRunResponse, CreateRunRequest, RunStatusfrom dify_agent.runtime.cancellation import RunCancellationIntent-from dify_agent.runtime.compositor_factory import create_default_layer_providersfrom dify_agent.runtime.event_coalescer import (DEFAULT_TEXT_DELTA_FLUSH_INTERVAL_SECONDS,DEFAULT_TEXT_DELTA_MAX_CHARS,@@ -68,7 +67,7 @@ class RunStore(RunEventSink, Protocol):run_id: str,intent: RunCancellationIntent,*,- session_snapshot: CompositorSessionSnapshot | None = None,+ session_snapshot: SessionSnapshot | None = None,usage: AgentRunUsage | None = None,) -> RunFinalizationResult:"""Publish cancellation after the owner runner has exited."""@@ -79,7 +78,7 @@ class RunnableRun(Protocol):"""Executable unit for one scheduled run."""@property- def terminal_session_snapshot(self) -> CompositorSessionSnapshot | None:+ def terminal_session_snapshot(self) -> SessionSnapshot | None:"""Return the post-exit snapshot for the current invocation, if available."""...@@ -117,9 +116,7 @@ class RunScheduler:active_tasks: dict[str, asyncio.Task[None]]stopping: boolrunner_factory: RunRunnerFactory | None- layer_providers: tuple[LayerProviderInput, ...]- plugin_daemon_http_client: httpx.AsyncClient- dify_api_http_client: httpx.AsyncClient+ services: Servicesagent_observability: AgentObservability | None_lifecycle_lock: asyncio.Lock@@ -127,14 +124,12 @@ class RunScheduler:self,*,store: RunStore,- plugin_daemon_http_client: httpx.AsyncClient,- dify_api_http_client: httpx.AsyncClient,+ services: Services,shutdown_grace_seconds: float = 30,run_timeout_seconds: float = DEFAULT_AGENT_RUN_TIMEOUT_SECONDS,stream_text_delta_coalescing_enabled: bool = True,stream_text_delta_flush_interval_seconds: float = DEFAULT_TEXT_DELTA_FLUSH_INTERVAL_SECONDS,stream_text_delta_max_chars: int = DEFAULT_TEXT_DELTA_MAX_CHARS,- layer_providers: tuple[LayerProviderInput, ...] | None = None,runner_factory: RunRunnerFactory | None = None,agent_observability: AgentObservability | None = None,) -> None:@@ -146,9 +141,7 @@ class RunScheduler:self.stream_text_delta_max_chars = stream_text_delta_max_charsself.active_tasks = {}self.stopping = False- self.plugin_daemon_http_client = plugin_daemon_http_client- self.dify_api_http_client = dify_api_http_client- self.layer_providers = layer_providers if layer_providers is not None else create_default_layer_providers()+ self.services = servicesself.runner_factory = runner_factoryself.agent_observability = agent_observabilityself._lifecycle_lock = asyncio.Lock()@@ -316,9 +309,7 @@ class RunScheduler:sink=self.store,request=request,run_id=record.run_id,- plugin_daemon_http_client=self.plugin_daemon_http_client,- dify_api_http_client=self.dify_api_http_client,- layer_providers=self.layer_providers,+ services=self.services,is_cancelled=is_cancelled,run_timeout_seconds=self.run_timeout_seconds,stream_text_delta_coalescing_enabled=self.stream_text_delta_coalescing_enabled,@@ -341,7 +332,7 @@ class RunScheduler:self,run_id: str,*,- session_snapshot: CompositorSessionSnapshot | None = None,+ session_snapshot: SessionSnapshot | None = None,usage: AgentRunUsage | None = None,) -> RunFinalizationResult | None:"""Best-effort failure event/status for shutdown-cancelled runs."""diff --git a/dify-agent/src/dify_agent/runtime/runner.py b/dify-agent/src/dify_agent/runtime/runner.pyindex 71e367d0b33..8d5527264c8 100644--- a/dify-agent/src/dify_agent/runtime/runner.py+++ b/dify-agent/src/dify_agent/runtime/runner.py@@ -1,73 +1,44 @@-"""Runtime execution for one scheduled Dify Agent run.--The runner is storage-agnostic: it normalizes the public Dify composition into-Agenton's graph/config split and executes one model run after the ``on_exit``-policy is validated:--- model runs: enter a fresh ``CompositorRun`` (or resume one from a snapshot),- pass the current Dify system prompts as run-level instructions, run- pydantic-ai with either the current ``run.user_prompts`` or deferred external- tool results, emit stream events with bounded text-delta coalescing and- agent-message annotations, apply request-level ``on_exit`` signals, and publish- a terminal success or failure event;-The Pydantic AI model is resolved from the active Agenton layer named by-``DIFY_AGENT_MODEL_LAYER_ID``. An optional history layer contributes stored-message history only through session state. Once pydantic-ai binds and builds-messages in the run capture, every terminal outcome replaces that state with the-captured messages after transient instructions are cleared; a failure or-cancellation before the capture contains messages preserves the restored state.-An interrupted run also records that its trailing response was cut short, so tool-calls it never executed do not block the next user prompt.-This preserves compaction rewrites and interrupted partial messages without-saving current system prompts. An optional structured output layer named by-``DIFY_AGENT_OUTPUT_LAYER_ID`` is read after entry and resolved into an output-contract whose type both exposes the output schema to the model and performs-runtime JSON Schema validation through custom Pydantic hooks. When the ask-human-layer is active, the runtime also allows ``DeferredToolRequests`` output and-publishes that deferred request through the normal ``run_succeeded`` event as-``deferred_tool_call`` instead of a final ``output``. Invalid structured outputs-or invalid deferred-tool behavior still trigger normal retries/failures before-Dify Agent emits success. Layers still never own the FastAPI lifespan-owned-plugin daemon or Dify API inner HTTP clients. Successful terminal events contain-both the JSON-safe final output or deferred tool call and the session snapshot;-there are no separate output or snapshot events to correlate.+"""Storage-agnostic execution of native Pydantic AI module runs.++Validate all JSON data and references before I/O, create fresh native components,+and persist only State after capability cleanup. Captured history is saved in+finally, including interrupted tool responses; current instructions are never+stored. Live clients belong to the server lifespan and leases to native wrap_run+scopes. Workspace and Binding retirement remain API-owned."""import asynciofrom collections.abc import AsyncIterable, Callable, Mapping-from collections import Counterfrom dataclasses import dataclass-from typing import Any, Literal, Protocol, cast, runtime_checkable+from typing import Protocol, cast, runtime_checkable+from types import ModuleType-import httpxfrom graphon.model_runtime.entities.llm_entities import LLMUsagefrom pydantic import JsonValue, TypeAdapterfrom pydantic_ai import capture_run_messagesfrom pydantic_ai.exceptions import ModelHTTPError, UsageLimitExceededfrom pydantic_ai.messages import AgentStreamEvent, PartDeltaEvent, PartStartEvent, TextPart, TextPartDelta-from pydantic_ai.output import OutputSpec-from pydantic_ai.tools import DeferredToolRequests, DeferredToolResults-from pydantic_ai.usage import UsageLimits--from agenton.compositor import CompositorSessionSnapshot, LayerConfigInput, LayerProviderInput-from agenton.layers.types import PydanticAITool-from dify_agent.layers.ask_human.layer import get_ask_human_layer, validate_ask_human_layer_composition-from dify_agent.layers.dify_core_tools.layer import DifyCoreToolsLayer-from dify_agent.layers.dify_plugin.llm_layer import DifyPluginLLMLayer-from dify_agent.layers.dify_plugin.tools_layer import DifyPluginToolsLayer+from pydantic_ai.usage import RunUsage, UsageLimits++from dify_agent.protocol.snapshot import SessionSnapshot+from dify_agent.runtime.context import Services+from dify_agent.runtime.modules import REGISTRY, load_modules, create_modules, snapshot_modules+from pydantic_ai.capabilities import AbstractCapability+from pydantic_ai.toolsets import AbstractToolset+from dify_agent.layers import history as history_module+from dify_agent.layers.prompt import layer as prompt_module+from dify_agent.layers.dify_plugin import llm_layer as llm_module+from dify_agent.layers.output import output_layer as output_module+from dify_agent.layers.user_prompt import layer as user_prompt_module+from dify_agent.layers.knowledge import layer as knowledge_modulefrom dify_agent.layers.knowledge.client import DifyKnowledgeBaseClientError-from dify_agent.layers.knowledge.layer import DifyKnowledgeBaseLayerfrom dify_agent.protocol.schemas import (AgentRunUsage,CreateRunRequest,DIFY_AGENT_MODEL_LAYER_ID,- DeferredToolCallPayload,RunFailureType,- normalize_composition,)from dify_agent.runtime.agent_factory import create_agent, normalize_user_input-from dify_agent.runtime.agenton_validation import is_agenton_enter_validation_runtime_error-from dify_agent.runtime.compositor_factory import build_pydantic_ai_compositor, create_default_layer_providersfrom dify_agent.runtime.compaction import build_compaction_capabilityfrom dify_agent.runtime_backend import BindingLostErrorfrom dify_agent.runtime.event_coalescer import (@@ -83,13 +54,6 @@ from dify_agent.runtime.event_sink import (emit_run_succeeded,)from dify_agent.runtime.observability import AgentObservability-from dify_agent.runtime.history import (- get_history_layer,- replace_run_history,- validate_history_layer_composition,-)-from dify_agent.runtime.layer_exit_signals import apply_layer_exit_signals, validate_layer_exit_signals-from dify_agent.runtime.output_type import resolve_run_output_contract, validate_output_layer_compositionfrom dify_agent.runtime.user_prompt_validation import EMPTY_USER_PROMPTS_ERROR, has_non_blank_user_prompt@@ -98,26 +62,6 @@ _MAX_AGENT_STEPS_PER_RUN = 500DEFAULT_AGENT_RUN_TIMEOUT_SECONDS = 60 * 60-@runtime_checkable-class _HasUsage(Protocol):- usage: object---@runtime_checkable-class _HasInputTokens(Protocol):- input_tokens: int | None---@runtime_checkable-class _HasOutputTokens(Protocol):- output_tokens: int | None---@runtime_checkable-class _HasTotalTokens(Protocol):- total_tokens: int | None--@runtime_checkableclass _HasAccumulatedUsage(Protocol):@property@@ -159,11 +103,6 @@ def _run_failed_error_payload(exc: Exception) -> tuple[str, RunFailureType | Nonreturn message, None, reason-def _has_model_layer(request: CreateRunRequest) -> bool:- """Return whether the public composition includes the reserved model layer."""- return any(layer.name == DIFY_AGENT_MODEL_LAYER_ID for layer in request.composition.layers)--def _extract_agent_message_delta(event: AgentStreamEvent) -> str | None:"""Return agent-message text content from Pydantic AI stream events."""if isinstance(event, PartDeltaEvent) and isinstance(event.delta, TextPartDelta):@@ -177,10 +116,8 @@ def _extract_agent_message_delta(event: AgentStreamEvent) -> str | None:class RunSuccessOutcome:"""Normalized successful runner output before event emission."""- result_kind: Literal["output", "deferred_tool_call"]output: JsonValue | None- deferred_tool_call: DeferredToolCallPayload | None- session_snapshot: CompositorSessionSnapshot+ session_snapshot: SessionSnapshotusage: AgentRunUsage | None@@ -191,16 +128,15 @@ class AgentRunRunner:request: CreateRunRequestrun_id: str- layer_providers: tuple[LayerProviderInput, ...]- plugin_daemon_http_client: httpx.AsyncClient- dify_api_http_client: httpx.AsyncClient+ services: Services+ registry: Mapping[str, ModuleType]is_cancelled: Callable[[], bool]run_timeout_seconds: floatstream_text_delta_coalescing_enabled: boolstream_text_delta_flush_interval_seconds: floatstream_text_delta_max_chars: intagent_observability: AgentObservability | None- _terminal_session_snapshot: CompositorSessionSnapshot | None+ _terminal_session_snapshot: SessionSnapshot | None_terminal_usage: AgentRunUsage | Nonedef __init__(@@ -209,9 +145,8 @@ class AgentRunRunner:sink: RunEventSink,request: CreateRunRequest,run_id: str,- plugin_daemon_http_client: httpx.AsyncClient,- dify_api_http_client: httpx.AsyncClient,- layer_providers: tuple[LayerProviderInput, ...] | None = None,+ services: Services,+ registry: Mapping[str, ModuleType] = REGISTRY,is_cancelled: Callable[[], bool] | None = None,run_timeout_seconds: float = DEFAULT_AGENT_RUN_TIMEOUT_SECONDS,stream_text_delta_coalescing_enabled: bool = True,@@ -226,9 +161,8 @@ class AgentRunRunner:self.sink = sinkself.request = requestself.run_id = run_id- self.plugin_daemon_http_client = plugin_daemon_http_client- self.dify_api_http_client = dify_api_http_client- self.layer_providers = layer_providers if layer_providers is not None else create_default_layer_providers()+ self.services = services+ self.registry = registryself.is_cancelled = is_cancelled or (lambda: False)self.run_timeout_seconds = run_timeout_secondsself.stream_text_delta_coalescing_enabled = stream_text_delta_coalescing_enabled@@ -239,8 +173,8 @@ class AgentRunRunner:self._terminal_usage = None@property- def terminal_session_snapshot(self) -> CompositorSessionSnapshot | None:- """Return the snapshot captured after the current compositor context exited."""+ def terminal_session_snapshot(self) -> SessionSnapshot | None:+ """Return the snapshot captured after native capability cleanup."""return self._terminal_session_snapshot@property@@ -280,199 +214,115 @@ class AgentRunRunner:_ = await emit_run_succeeded(self.sink,run_id=self.run_id,- **(- {"output": outcome.output}- if outcome.result_kind == "output"- else {"deferred_tool_call": outcome.deferred_tool_call}- ),+ output=outcome.output,session_snapshot=outcome.session_snapshot,usage=outcome.usage,)async def _run_agent(self) -> RunSuccessOutcome:- """Run the normalized request through the model path.-- Known request-shaped Agenton enter-time failures are normalized to- ``AgentRunValidationError``. That includes the existing small class of- enter-time ``RuntimeError`` values reported by Agenton plus- layer-construction or snapshot-hydration ``ValueError`` failures that- arise before the run becomes active, such as missing shell settings for a- requested ``dify.shell`` layer or malformed serialized shell offsets.- Output/history-layer graph invariants are validated from the public- composition before entering Agenton so misnamed or extra reserved layers- never silently degrade. Later runtime failures still propagate as- execution errors so they become terminal failed runs rather than client- validation responses. Structured output uses a resolved contract whose- type itself encodes both the model-facing schema and the runtime- validation hooks, so invalid model outputs can be corrected before Dify- Agent emits success.- """try:- validate_output_layer_composition(self.request.composition)- validate_history_layer_composition(self.request.composition)- validate_ask_human_layer_composition(self.request.composition)- graph_config, layer_configs = normalize_composition(self.request.composition)- compositor = build_pydantic_ai_compositor(graph_config, providers=self.layer_providers)- validate_layer_exit_signals(compositor, self.request.on_exit)+ deps = load_modules(self.request, self.services, self.run_id, registry=self.registry)+ modules = create_modules(deps, registry=self.registry)+ model_module = modules[DIFY_AGENT_MODEL_LAYER_ID]+ if not isinstance(model_module, llm_module.Capability):+ raise ValueError("The llm module must provide native model assembly")+ model = model_module.build_model(deps)+ llm_config = llm_module.Config.model_validate(deps.layers[DIFY_AGENT_MODEL_LAYER_ID]["config"])+ history = modules.get("history")+ if history is not None and not isinstance(history, history_module.Capability):+ raise ValueError("The history slot must provide the history module")+ message_history = history.load_messages(deps) if isinstance(history, history_module.Capability) else None+ output = modules.get("output")+ if output is not None and not isinstance(output, output_module.Capability):+ raise ValueError("The output slot must provide the output module")+ output_type = (+ output.build_output_contract(deps).output_type if isinstance(output, output_module.Capability) else str+ )+ user_content = []+ for module in modules.values():+ if isinstance(module, (prompt_module.Toolset, user_prompt_module.Capability)):+ user_content.extend(module.build_user_content(deps))+ eager_user_content = any(+ isinstance(module, knowledge_module.Capability) and module.provides_user_content(deps)+ for module in modules.values()+ )+ if not has_non_blank_user_prompt(user_content) and not eager_user_content:+ raise ValueError(EMPTY_USER_PROMPTS_ERROR)+ capabilities = [module for module in modules.values() if isinstance(module, AbstractCapability)]+ compaction = build_compaction_capability(+ context_window_tokens=llm_config.context_window_tokens, model_settings=llm_config.model_settings+ )+ if compaction is not None:+ capabilities.append(compaction)+ agent = create_agent(+ model,+ toolsets=[module for module in modules.values() if isinstance(module, AbstractToolset)],+ capabilities=capabilities,+ output_type=output_type,+ )+ if self.agent_observability is not None:+ from dify_agent.layers.execution_context.configs import DifyExecutionContextLayerConfig++ self.agent_observability.instrument(+ agent,+ execution_context=DifyExecutionContextLayerConfig.model_validate(+ deps.layers[llm_config.execution_context]["config"]+ ),+ )except (KeyError, TypeError, ValueError) as exc:raise AgentRunValidationError(str(exc)) from exc- if not _has_model_layer(self.request):- raise AgentRunValidationError(f"Missing required '{DIFY_AGENT_MODEL_LAYER_ID}' layer.")- return await self._run_model(compositor=compositor, layer_configs=layer_configs)+ async def handle_events(_ctx: object, events: AsyncIterable[AgentStreamEvent]) -> None:+ published_events = coalesce_agent_stream_events(+ events,+ enabled=self.stream_text_delta_coalescing_enabled,+ flush_interval_seconds=self.stream_text_delta_flush_interval_seconds,+ max_chars=self.stream_text_delta_max_chars,+ )+ async for event in published_events:+ if self.is_cancelled():+ raise asyncio.CancelledError+ await emit_pydantic_ai_event(+ self.sink, run_id=self.run_id, data=event, agent_message_delta=_extract_agent_message_delta(event)+ )- async def _run_model(- self,- *,- compositor: Any,- layer_configs: dict[str, LayerConfigInput],- ) -> RunSuccessOutcome:- """Run the normal model/deferred-tool path inside an entered Agenton run."""- entered_run = False- output: JsonValue | None = None- deferred_tool_call: DeferredToolCallPayload | None = None- result_kind: Literal["output", "deferred_tool_call"] | None = None- usage: AgentRunUsage | None = None- model: Any = None- run = None+ timeout = asyncio.timeout(self.run_timeout_seconds)try:- async with compositor.enter(configs=layer_configs, session_snapshot=self.request.session_snapshot) as run:- entered_run = True- apply_layer_exit_signals(run, self.request.on_exit)- user_prompts = run.user_prompts- deferred_tool_results = _resolve_deferred_tool_results(self.request)- if deferred_tool_results is None and not has_non_blank_user_prompt(user_prompts):- raise AgentRunValidationError(EMPTY_USER_PROMPTS_ERROR)-- async def handle_events(_ctx: object, events: AsyncIterable[AgentStreamEvent]) -> None:- published_events = coalesce_agent_stream_events(- events,- enabled=self.stream_text_delta_coalescing_enabled,- flush_interval_seconds=self.stream_text_delta_flush_interval_seconds,- max_chars=self.stream_text_delta_max_chars,- )- async for event in published_events:- if self.is_cancelled():- raise asyncio.CancelledError- text_delta = _extract_agent_message_delta(event)- _ = await emit_pydantic_ai_event(- self.sink,- run_id=self.run_id,- data=event,- agent_message_delta=text_delta,- )-- try:- output_contract = resolve_run_output_contract(run)- history_layer = get_history_layer(run)- message_history = history_layer.message_history if history_layer is not None else None- ask_human_layer = get_ask_human_layer(run)- llm_layer = run.get_layer(DIFY_AGENT_MODEL_LAYER_ID, DifyPluginLLMLayer)- compaction = build_compaction_capability(- context_window_tokens=llm_layer.config.context_window_tokens,- model_settings=llm_layer.config.model_settings,- )- model = llm_layer.get_model(- http_client=self.dify_api_http_client,- agent_run_id=self.run_id,- )- tools = await _resolve_run_tools(- run,- plugin_daemon_http_client=self.plugin_daemon_http_client,- dify_api_http_client=self.dify_api_http_client,- )- except (KeyError, TypeError, RuntimeError, ValueError) as exc:- raise AgentRunValidationError(str(exc)) from exc-- if deferred_tool_results is not None and history_layer is None:- raise AgentRunValidationError(- "Deferred tool results require a 'history' layer with prior message history."- )-- agent = create_agent(- model,- tools=tools,- output_type=_resolve_agent_output_type(output_contract.output_type, ask_human_layer is not None),- )- if self.agent_observability is not None:- # The model layer's required execution-context dependency is the- # run's only carrier of Dify identity, and its node name is- # caller-chosen, so read it through the typed dependency.- self.agent_observability.instrument(- agent,- execution_context=llm_layer.deps.execution_context.config,- )- run_timeout = asyncio.timeout(self.run_timeout_seconds)+ with capture_run_messages() as messages:+ finished = Falsetry:- with capture_run_messages() as captured_messages:- agent_run_finished = False- try:- async with run_timeout:- result = await agent.run(- None if deferred_tool_results is not None else normalize_user_input(user_prompts),- message_history=message_history,- deferred_tool_results=deferred_tool_results,- event_stream_handler=handle_events,- instructions=run.prompts or None,- capabilities=[compaction] if compaction is not None else None,- usage_limits=UsageLimits(request_limit=_MAX_AGENT_STEPS_PER_RUN),- )- agent_run_finished = True- finally:- if captured_messages:- replace_run_history(- history_layer, captured_messages, interrupted=not agent_run_finished- )- except TimeoutError as exc:- if not run_timeout.expired():- raise- raise UsageLimitExceeded(- f"Agent run exceeded the configured limit of {self.run_timeout_seconds:g} seconds"- ) from exc- complete_usage = model.accumulated_usage if isinstance(model, _HasAccumulatedUsage) else None- usage = _serialize_agent_usage(complete_usage if complete_usage is not None else _result_usage(result))- self._terminal_usage = usage- if isinstance(result.output, DeferredToolRequests):- if ask_human_layer is None:- raise AgentRunValidationError(- "Deferred tool requests were returned, but no active ask_human layer is available for validation."+ async with timeout:+ result = await agent.run(+ normalize_user_input(user_content),+ deps=deps,+ message_history=message_history,+ event_stream_handler=handle_events,+ usage_limits=UsageLimits(request_limit=_MAX_AGENT_STEPS_PER_RUN),)- if history_layer is None:- raise AgentRunValidationError(- "ask_human deferred tool requests require a 'history' layer so the pending tool call can be resumed."- )- deferred_tool_call = ask_human_layer.build_deferred_tool_call_payload(result.output)- result_kind = "deferred_tool_call"- else:- output = _serialize_agent_output(result.output)- result_kind = "output"- except RuntimeError as exc:- if not entered_run and is_agenton_enter_validation_runtime_error(exc):- raise AgentRunValidationError(str(exc)) from exc- raise- except ValueError as exc:- if not entered_run:- raise AgentRunValidationError(str(exc)) from exc- raise+ finished = True+ finally:+ if messages and isinstance(history, history_module.Capability):+ history.save_messages(deps, messages, interrupted=not finished)+ complete_usage = model.accumulated_usage if isinstance(model, _HasAccumulatedUsage) else None+ self._terminal_usage = _serialize_agent_usage(+ complete_usage if complete_usage is not None else result.usage+ )+ final_output = _serialize_agent_output(result.output)+ except TimeoutError as exc:+ if not timeout.expired():+ raise+ raise UsageLimitExceeded(+ f"Agent run exceeded the configured limit of {self.run_timeout_seconds:g} seconds"+ ) from excfinally:- if entered_run and run is not None:- self._terminal_session_snapshot = run.session_snapshot+ # Native wrap_run scopes have exited, including cancellation cleanup.+ self._terminal_session_snapshot = snapshot_modules(deps, registry=self.registry)if isinstance(model, _HasAccumulatedUsage):- accumulated_usage = _serialize_agent_usage(model.accumulated_usage)- if accumulated_usage is not None:- self._terminal_usage = accumulated_usage-- if run is None or run.session_snapshot is None:- raise RuntimeError("Agenton run did not produce a session snapshot after exit.")- if result_kind is None:- raise RuntimeError("Agent run did not resolve either a final output or a deferred tool call.")-+ usage = _serialize_agent_usage(model.accumulated_usage)+ if usage is not None:+ self._terminal_usage = usagereturn RunSuccessOutcome(- result_kind=result_kind,- output=output,- deferred_tool_call=deferred_tool_call,- session_snapshot=run.session_snapshot,- usage=usage,+ output=final_output, session_snapshot=self._terminal_session_snapshot, usage=self._terminal_usage)@@ -481,81 +331,17 @@ def _serialize_agent_output(output: object) -> JsonValue:return cast(JsonValue, _AGENT_OUTPUT_ADAPTER.dump_python(output, mode="json"))-def _result_usage(result: object) -> object | None:- """Return pydantic-ai result usage across method/property API variants."""- if not isinstance(result, _HasUsage):- return None-- usage = result.usage- if isinstance(usage, _HasInputTokens) or isinstance(usage, _HasOutputTokens):- return usage- if callable(usage):- usage_getter = cast(Callable[[], object], usage)- return usage_getter()- return usage---def _serialize_agent_usage(usage: object | None) -> AgentRunUsage | None:+def _serialize_agent_usage(usage: LLMUsage | RunUsage | None) -> AgentRunUsage | None:"""Convert complete daemon or fallback pydantic-ai usage into the public shape."""if usage is None:return Noneif isinstance(usage, LLMUsage):return AgentRunUsage.model_validate(usage.model_dump(mode="python"))- input_tokens = int(usage.input_tokens or 0) if isinstance(usage, _HasInputTokens) else 0- output_tokens = int(usage.output_tokens or 0) if isinstance(usage, _HasOutputTokens) else 0- total_tokens = int(usage.total_tokens or 0) if isinstance(usage, _HasTotalTokens) else 0return AgentRunUsage(- prompt_tokens=input_tokens,- completion_tokens=output_tokens,- total_tokens=total_tokens,+ prompt_tokens=usage.input_tokens,+ completion_tokens=usage.output_tokens,+ total_tokens=usage.total_tokens,)-def _resolve_agent_output_type(output_type: OutputSpec[object], allow_deferred_tools: bool) -> OutputSpec[object]:- """Return the run output type, optionally augmented with deferred-tool support."""- if not allow_deferred_tools:- return output_type- return cast(OutputSpec[object], [output_type, DeferredToolRequests])---def _resolve_deferred_tool_results(request: CreateRunRequest) -> DeferredToolResults | None:- """Convert public deferred tool results into the pydantic-ai resume input."""- if request.deferred_tool_results is None:- return None- return request.deferred_tool_results.to_pydantic_ai()---async def _resolve_run_tools(- run: Any,- *,- plugin_daemon_http_client: httpx.AsyncClient,- dify_api_http_client: httpx.AsyncClient,-) -> list[PydanticAITool[object]]:- """Return the static compositor tools plus any Dify runtime tools."""- resolved_tools = list(cast(list[PydanticAITool[object]], run.tools))- for slot in run.slots.values():- layer = slot.layer- if isinstance(layer, DifyPluginToolsLayer):- resolved_tools.extend(- await layer.get_tools(- http_client=plugin_daemon_http_client,- dify_api_http_client=dify_api_http_client,- )- )- if isinstance(layer, DifyCoreToolsLayer):- resolved_tools.extend(await layer.get_tools(http_client=dify_api_http_client))- if isinstance(layer, DifyKnowledgeBaseLayer):- resolved_tools.extend(await layer.get_tools(http_client=dify_api_http_client))- _validate_unique_tool_names(resolved_tools)- return resolved_tools---def _validate_unique_tool_names(tools: list[PydanticAITool[object]]) -> None:- """Reject duplicate tool names across static and dynamic tool sources."""- duplicate_names = sorted(name for name, count in Counter(tool.name for tool in tools).items() if count > 1)- if duplicate_names:- names = ", ".join(duplicate_names)- raise ValueError(f"Agent run requires unique tool names across all layers, got duplicates: {names}.")--__all__ = ["AgentRunRunner", "AgentRunValidationError"]diff --git a/dify-agent/src/dify_agent/runtime/user_prompt_validation.py b/dify-agent/src/dify_agent/runtime/user_prompt_validation.pyindex c2cda83accc..b0287d34cd0 100644--- a/dify-agent/src/dify_agent/runtime/user_prompt_validation.py+++ b/dify-agent/src/dify_agent/runtime/user_prompt_validation.py@@ -1,7 +1,7 @@-"""Validation for effective user prompts produced by Agenton runs.+"""Validation for effective user input assembled from module configuration.-Validation happens after safe compositor construction and run entry so runtime-execution uses the same transformed prompts as the actual pydantic-ai input.+The runner validates assembled current prompt content before resource acquisition.+Knowledge user-query retrieval can also provide input through its native hook.Blank string fragments do not count as meaningful input; non-string``UserContent`` is treated as intentional content because rich media/messageparts do not have a universal whitespace representation.diff --git a/dify-agent/src/dify_agent/runtime_backend/e2b.py b/dify-agent/src/dify_agent/runtime_backend/e2b.pyindex 7f09cb5a9f3..398dd0e2f1e 100644--- a/dify-agent/src/dify_agent/runtime_backend/e2b.py+++ b/dify-agent/src/dify_agent/runtime_backend/e2b.py@@ -3,7 +3,7 @@Dify API persists only opaque Home Snapshot, Binding, and Workspace backendrefs. This adapter maps those refs to E2B resources internally. API keys,traffic tokens, SDK objects, shellctl clients, and ``RuntimeLease`` objects stay-operation-local and are never serialized into Agenton state.+operation-local and are never serialized into module JSON state."""from __future__ import annotationsdiff --git a/dify-agent/src/dify_agent/server/app.py b/dify-agent/src/dify_agent/server/app.pyindex 36219c9c6e5..abae36a5e0a 100644--- a/dify-agent/src/dify_agent/server/app.py+++ b/dify-agent/src/dify_agent/server/app.py@@ -7,10 +7,8 @@ rather than request handlers, so client disconnects do not cancel the agentruntime. Redis persists run records and per-run event streams with configuredretention. Optional provider accounting is exposed as a separate one-shot HTTPendpoint driven by Celery Beat; it starts no tasks during lifespan startup and-adds no reporting to business operations. Redis is not used as a run job queue. Agenton layers and providers-stay state-only: they borrow the lifespan-owned clients through the runner and-receive runtime-backend and Shell settings through provider construction rather-than reading environment variables themselves. The standard server mounts the+adds no reporting to business operations. Redis is not used as a run job queue. Modules borrow lifespan-owned services through run dependencies; their JSON+configuration and state never retain live infrastructure. The standard server mounts theHTTP Agent Stub router. Process-level platform Logfire instrumentation isconfigured at app construction time. Logfire-platform export is token-gated;standard OTLP export follows the SDK environment configuration, including@@ -29,7 +27,7 @@ from redis.asyncio import Redisfrom dify_agent.agent_stub.shell_env import ShellAgentStubTokenFactoryfrom dify_agent.agent_stub.server.router import create_agent_stub_routerfrom dify_agent.layers.execution_context import DifyExecutionContextLayerConfig-from dify_agent.runtime.compositor_factory import create_default_layer_providers+from dify_agent.runtime.context import Servicesfrom dify_agent.runtime.run_scheduler import RunSchedulerfrom dify_agent.server.auth import create_bearer_token_dependencyfrom dify_agent.server.observability import configure_agent_observability, configure_server_observability@@ -67,16 +65,6 @@ def create_app(settings: ServerSettings | None = None) -> FastAPI:agent_stub_file_request_handler = resolved_settings.create_agent_stub_file_request_handler()agent_stub_config_request_handler = resolved_settings.create_agent_stub_config_request_handler()runtime_backend_profile = resolved_settings.build_runtime_backend_profile()- layer_providers = create_default_layer_providers(- plugin_daemon_url=resolved_settings.plugin_daemon_url,- plugin_daemon_api_key=resolved_settings.plugin_daemon_api_key,- inner_api_url=resolved_settings.inner_api_url,- inner_api_key=resolved_settings.inner_api_key or "",- runtime_backend_profile=runtime_backend_profile,- shell_redact_patterns=resolved_settings.get_shell_redact_patterns(),- agent_stub_api_base_url=resolved_settings.agent_stub_api_base_url,- agent_stub_token_factory=agent_stub_token_factory,- )binding_file_service = (BindingFileService(execution_bindings=runtime_backend_profile.execution_bindings,@@ -117,14 +105,23 @@ def create_app(settings: ServerSettings | None = None) -> FastAPI:)scheduler = RunScheduler(store=store,- plugin_daemon_http_client=plugin_daemon_http_client,- dify_api_http_client=dify_api_inner_http_client,+ services=Services(+ plugin_daemon_http_client=plugin_daemon_http_client,+ dify_api_http_client=dify_api_inner_http_client,+ plugin_daemon_url=resolved_settings.plugin_daemon_url,+ plugin_daemon_api_key=resolved_settings.plugin_daemon_api_key,+ inner_api_url=resolved_settings.inner_api_url,+ inner_api_key=resolved_settings.inner_api_key or "",+ runtime_backend_profile=runtime_backend_profile,+ shell_redact_patterns=resolved_settings.get_shell_redact_patterns(),+ agent_stub_api_base_url=resolved_settings.agent_stub_api_base_url,+ agent_stub_token_factory=agent_stub_token_factory,+ ),shutdown_grace_seconds=resolved_settings.shutdown_grace_seconds,run_timeout_seconds=resolved_settings.run_timeout_seconds,stream_text_delta_coalescing_enabled=resolved_settings.stream_text_delta_coalescing_enabled,stream_text_delta_flush_interval_seconds=(resolved_settings.stream_text_delta_flush_interval_ms / 1000),stream_text_delta_max_chars=resolved_settings.stream_text_delta_max_chars,- layer_providers=layer_providers,agent_observability=agent_observability,)state["store"] = storediff --git a/dify-agent/src/dify_agent/server/settings.py b/dify-agent/src/dify_agent/server/settings.pyindex 207e14b7675..a5b5623a9ba 100644--- a/dify-agent/src/dify_agent/server/settings.py+++ b/dify-agent/src/dify_agent/server/settings.py@@ -2,7 +2,7 @@Outbound HTTP client settings describe the FastAPI lifespan-owned``httpx.AsyncClient`` instances shared by local run tasks for plugin-daemon and-Dify API inner calls. Layers and Agenton providers do not own those clients, so+Dify API inner calls. Native modules borrow those clients, sothese settings are process resource limits rather than per-run lifecycle knobs.Endpoint URLs and API keys stay service-specific. The Agent Stub also uses thissettings model directly: the public Agent Stub API base URL, server secret,@@ -12,7 +12,7 @@ and optional Dify inner API bridge settings live here under theimport httpx-from typing import ClassVar, Literal, cast+from typing import ClassVar, Literal, cast, overridefrom pydantic import AliasChoices, AnyHttpUrl, Field, SecretStr, TypeAdapter, field_validator, model_validatorfrom pydantic_settings import BaseSettings, SettingsConfigDict@@ -158,6 +158,7 @@ class ServerSettings(BaseSettings):)@classmethod+ @overridedef settings_customise_sources(cls,settings_cls: type[BaseSettings],diff --git a/dify-agent/src/dify_agent/storage/redis_run_store.py b/dify-agent/src/dify_agent/storage/redis_run_store.pyindex a2a61cd9231..98a4fa78257 100644--- a/dify-agent/src/dify_agent/storage/redis_run_store.py+++ b/dify-agent/src/dify_agent/storage/redis_run_store.py@@ -10,11 +10,11 @@ sensitive runtime configuration."""from collections.abc import AsyncIterator, Awaitable-from typing import cast+from typing import cast, overridefrom redis.asyncio import Redis-from agenton.compositor import CompositorSessionSnapshot+from dify_agent.protocol.snapshot import SessionSnapshotfrom dify_agent.protocol.schemas import (AgentRunUsage,RUN_EVENT_ADAPTER,@@ -198,6 +198,7 @@ class RedisRunStore(RunEventSink):value = value.decode()return RunRecord.model_validate_json(value)+ @overrideasync def append_event(self, event: NonTerminalRunEvent) -> str:"""Append a non-terminal event JSON payload with refreshed TTLs."""events_key = run_events_key(self.prefix, event.run_id)@@ -215,6 +216,7 @@ class RedisRunStore(RunEventSink):event_id = results[0]return event_id.decode() if isinstance(event_id, bytes) else str(event_id)+ @overrideasync def finalize_run(self, event: TerminalRunEvent) -> RunFinalizationResult:"""Atomically append the first success/failure event and update its run record."""status, error, error_type = terminal_event_status_fields(event)@@ -297,7 +299,7 @@ class RedisRunStore(RunEventSink):run_id: str,intent: RunCancellationIntent,*,- session_snapshot: CompositorSessionSnapshot | None = None,+ session_snapshot: SessionSnapshot | None = None,usage: AgentRunUsage | None = None,) -> RunFinalizationResult:"""Atomically publish cancellation after the owner runner has exited."""diff --git a/dify-agent/tests/docs/test_examples.py b/dify-agent/tests/docs/test_examples.pyindex 83280724b2d..253fb8e419a 100644--- a/dify-agent/tests/docs/test_examples.py+++ b/dify-agent/tests/docs/test_examples.py@@ -26,7 +26,6 @@ def find_doc_examples() -> Iterable[ParameterSet]:for example in find_examples(root_dir / "docs",root_dir / "src",- root_dir / "examples" / "agenton",root_dir / "examples" / "dify_agent",):path = example.path.relative_to(root_dir)@@ -47,7 +46,7 @@ def test_documentation_examples(example: CodeExample, eval_example: EvalExample)isort=True,upgrade=True,quotes="double",- known_first_party=["agenton", "agenton_collections", "dify_agent"],+ known_first_party=["dify_agent"],)if not opt_lint.startswith("skip"):diff --git a/dify-agent/tests/docs/test_snippets.py b/dify-agent/tests/docs/test_snippets.pyindex 89428323d08..9086cd50b92 100644--- a/dify-agent/tests/docs/test_snippets.py+++ b/dify-agent/tests/docs/test_snippets.py@@ -38,9 +38,9 @@ if __name__ == "__main__":parsed = parse_file_sections(source)assert "main" in parsed.sections- markdown = '```snippet {path="/examples/agenton/agenton_examples/session_snapshot.py"}\n```'+ markdown = '```snippet {path="/examples/dify_agent/dify_agent_examples/run_server_consumer.py"}\n```'rendered = inject_snippets(markdown, PROJECT_ROOT / "docs")- assert rendered.startswith('```py {title="examples/agenton/agenton_examples/session_snapshot.py"}')+ assert rendered.startswith('```py {title="examples/dify_agent/dify_agent_examples/run_server_consumer.py"}')assert "async def main() -> None:" in renderedassert "asyncio.run(main())" in rendereddiff --git a/dify-agent/tests/integration/dify_agent/storage/test_terminal_finalization.py b/dify-agent/tests/integration/dify_agent/storage/test_terminal_finalization.pyindex 5bf579bee03..1b1791adfca 100644--- a/dify-agent/tests/integration/dify_agent/storage/test_terminal_finalization.py+++ b/dify-agent/tests/integration/dify_agent/storage/test_terminal_finalization.py@@ -12,7 +12,7 @@ import httpximport pytestfrom redis.asyncio import Redis-from agenton.compositor import CompositorSessionSnapshot+from dify_agent.protocol.snapshot import SessionSnapshotfrom dify_agent.protocol.schemas import (CancelRunRequest,CreateRunRequest,@@ -25,6 +25,7 @@ from dify_agent.protocol.schemas import (RunSucceededEventData,utc_now,)+from dify_agent.runtime.context import Servicesfrom dify_agent.runtime.cancellation import RunCancellationIntentfrom dify_agent.runtime.run_scheduler import RunSchedulerfrom dify_agent.storage.redis_keys import run_cancel_intent_key, run_events_key, run_record_key@@ -40,7 +41,7 @@ def _success_or_failure_event(kind: str, run_id: str) -> RunSucceededEvent | Runrun_id=run_id,data=RunSucceededEventData(output="done",- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),)return RunFailedEvent(run_id=run_id, data=RunFailedEventData(error="model failed"))@@ -108,7 +109,7 @@ def test_success_and_cancel_intent_commit_exactly_one_matching_terminal(redis_urrun_id=record.run_id,data=RunSucceededEventData(output="done",- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),)@@ -175,7 +176,7 @@ def test_event_stream_is_trimmed_and_keeps_the_terminal_event(redis_url: str) ->run_id=record.run_id,data=RunSucceededEventData(output="done",- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),))@@ -263,7 +264,7 @@ def test_cancellation_intent_lifecycle_and_terminal_exclusion(redis_url: str) ->first_finalization = await store.finalize_cancellation(record.run_id,intent,- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),)repeated_finalization = await store.finalize_cancellation(record.run_id, intent)post_terminal_status = await store.request_cancellation(@@ -369,17 +370,12 @@ def test_non_owner_scheduler_cancellation_stops_owner_runner(redis_url: str) ->async with httpx.AsyncClient() as http_client:owner_scheduler = RunScheduler(store=owner_store,- plugin_daemon_http_client=http_client,- dify_api_http_client=http_client,- runner_factory=lambda _record, _request: BlockingRunner(- started=runner_started,- stopped=runner_stopped,- ),+ runner_factory=lambda _record, _request: BlockingRunner(started=runner_started, stopped=runner_stopped),+ services=Services(plugin_daemon_http_client=http_client, dify_api_http_client=http_client),)remote_scheduler = RunScheduler(store=remote_store,- plugin_daemon_http_client=http_client,- dify_api_http_client=http_client,+ services=Services(plugin_daemon_http_client=http_client, dify_api_http_client=http_client),)try:record = await owner_scheduler.create_run(CreateRunRequest(composition=RunComposition(layers=[])))diff --git a/dify-agent/tests/local/agenton/__init__.py b/dify-agent/tests/local/agenton/__init__.pydeleted file mode 100644index 8b137891791..00000000000--- a/dify-agent/tests/local/agenton/__init__.py+++ /dev/null@@ -1 +0,0 @@-diff --git a/dify-agent/tests/local/agenton/compositor/__init__.py b/dify-agent/tests/local/agenton/compositor/__init__.pydeleted file mode 100644index 8b137891791..00000000000--- a/dify-agent/tests/local/agenton/compositor/__init__.py+++ /dev/null@@ -1 +0,0 @@-diff --git a/dify-agent/tests/local/agenton/compositor/test_builder_snapshot.py b/dify-agent/tests/local/agenton/compositor/test_builder_snapshot.pydeleted file mode 100644index b43b0d1e71f..00000000000--- a/dify-agent/tests/local/agenton/compositor/test_builder_snapshot.py+++ /dev/null@@ -1,337 +0,0 @@-import asyncio-from dataclasses import dataclass--import pytest-from pydantic import BaseModel, ConfigDict, ValidationError-from typing_extensions import override--import agenton.compositor as compositor_module-import agenton.layers as layers_module-from agenton.compositor import (- Compositor,- LayerConfigInput,- LayerNode,- LayerNodeConfig,- LayerProvider,- LayerProviderInput,-)-from agenton.layers import EmptyLayerConfig, Layer, LayerDeps, NoLayerDeps, PlainLayer-from agenton_collections.layers.plain import ObjectLayer, PromptLayer, PromptLayerConfig---EXPECTED_FACADE_EXPORTS = [- "Compositor",- "CompositorConfig",- "CompositorConfigValue",- "CompositorRun",- "CompositorSessionSnapshot",- "CompositorSessionSnapshotValue",- "CompositorTransformer",- "CompositorTransformerKwargs",- "LayerFactory",- "LayerNode",- "LayerNodeConfig",- "LayerProvider",- "LayerRunSlot",- "LayerSessionSnapshot",-]--EXPECTED_DIRECT_IMPORT_COMPAT_NAMES = ["LayerConfigInput", "LayerProviderInput"]---@dataclass(slots=True)-class InstanceOnlyLayer(PlainLayer[NoLayerDeps]):- pass---@dataclass(slots=True)-class RequiredConstructorLayer(PlainLayer[NoLayerDeps]):- value: str---def test_layer_provider_from_layer_type_uses_declared_schema_and_type_id() -> None:- provider = LayerProvider.from_layer_type(PromptLayer)-- assert provider.type_id == "plain.prompt"- assert provider.layer_type is PromptLayer-- layer = provider.create_layer(PromptLayerConfig(prefix="hello", user="ask politely"))-- assert isinstance(layer, PromptLayer)- assert layer.config == PromptLayerConfig(prefix="hello", user="ask politely")- assert layer.prefix_prompts == ["hello"]-- with pytest.raises(TypeError, match="cannot be created from empty config"):- LayerProvider.from_layer_type(RequiredConstructorLayer).create_layer()---def test_compositor_from_config_uses_providers_and_enter_configs_by_node_name() -> None:- compositor = Compositor.from_config(- {"layers": [{"name": "prompt", "type": "plain.prompt"}]},- providers=[PromptLayer],- )-- async def run() -> None:- async with compositor.enter(- configs={"prompt": {"prefix": "hello", "user": "ask politely", "suffix": ["bye"]}}- ) as active_run:- assert [prompt.value for prompt in active_run.prompts] == ["hello", "bye"]- assert [prompt.value for prompt in active_run.user_prompts] == ["ask politely"]-- asyncio.run(run())-- with pytest.raises(ValidationError):- asyncio.run(_enter_once(compositor, configs={"prompt": {"unknown": "field"}}))---def test_layer_node_config_has_no_runtime_state_or_layer_config() -> None:- node = LayerNodeConfig(- name="prompt",- type="plain.prompt",- deps={"source": "other"},- metadata={"label": "Prompt"},- )-- assert node.model_dump(mode="json") == {- "name": "prompt",- "type": "plain.prompt",- "deps": {"source": "other"},- "metadata": {"label": "Prompt"},- }- assert "runtime_state" not in LayerNodeConfig.model_fields- assert "config" not in LayerNodeConfig.model_fields---def test_node_providers_override_type_id_providers_for_serializable_graphs() -> None:- override_provider = LayerProvider.from_factory(- layer_type=PromptLayer,- create=lambda config: PromptLayer(prefix="override"),- )- compositor = Compositor.from_config(- {"layers": [{"name": "prompt", "type": "plain.prompt"}]},- providers=[PromptLayer],- node_providers={"prompt": override_provider},- )-- async def run() -> None:- async with compositor.enter(configs={"prompt": {"prefix": "ignored"}}) as active_run:- assert [prompt.value for prompt in active_run.prompts] == ["override"]-- asyncio.run(run())---def test_from_config_rejects_missing_duplicate_and_unknown_providers() -> None:- with pytest.raises(KeyError, match="Layer type id 'missing' is not registered"):- Compositor.from_config({"layers": [{"name": "node", "type": "missing"}]}, providers=[])-- with pytest.raises(ValueError, match="already registered"):- Compositor.from_config(- {"layers": [{"name": "prompt", "type": "plain.prompt"}]},- providers=[PromptLayer, PromptLayer],- )-- with pytest.raises(ValueError, match="must declare a type_id"):- Compositor.from_config(- {"layers": [{"name": "node", "type": "instance.only"}]},- providers=[InstanceOnlyLayer],- )-- with pytest.raises(ValueError, match="unknown layer node names: other"):- Compositor.from_config(- {"layers": [{"name": "prompt", "type": "plain.prompt"}]},- providers=[PromptLayer],- node_providers={"other": PromptLayer},- )---def test_compositor_run_get_layer_returns_named_layer_and_validates_type() -> None:- compositor = Compositor([LayerNode("obj", _object_provider("value"))])-- async def run() -> None:- async with compositor.enter() as active_run:- layer = active_run.get_layer("obj", ObjectLayer)- assert active_run.get_layer("obj") is layer- assert layer.value == "value"-- with pytest.raises(KeyError, match="Layer 'missing' is not defined"):- active_run.get_layer("missing")-- with pytest.raises(TypeError, match="Layer 'obj' must be PromptLayer, got ObjectLayer"):- active_run.get_layer("obj", PromptLayer)-- asyncio.run(run())---class ObjectConsumerDeps(LayerDeps):- obj: ObjectLayer[str] # pyright: ignore[reportUninitializedInstanceVariable]---@dataclass(slots=True)-class ObjectConsumerLayer(PlainLayer[ObjectConsumerDeps]):- @property- @override- def prefix_prompts(self) -> list[str]:- return [self.deps.obj.value]---def test_python_native_construction_mixes_layer_classes_and_providers() -> None:- compositor = Compositor(- [- LayerNode("prompt", PromptLayer),- LayerNode("obj", _object_provider("instance")),- LayerNode("consumer", ObjectConsumerLayer, deps={"obj": "obj"}),- ]- )-- async def run() -> None:- async with compositor.enter(configs={"prompt": {"prefix": "cfg"}}) as active_run:- assert [prompt.value for prompt in active_run.prompts] == ["cfg", "instance"]-- asyncio.run(run())---class SerializableState(BaseModel):- resource_id: str = ""- created: bool = False- resumed: bool = False-- model_config = ConfigDict(extra="forbid", validate_assignment=True)---@dataclass(slots=True)-class StateLayer(PlainLayer[NoLayerDeps, EmptyLayerConfig, SerializableState]):- created_hooks: int = 0- resumed_hooks: int = 0-- @override- async def on_context_create(self) -> None:- self.created_hooks += 1- self.runtime_state.created = True-- @override- async def on_context_resume(self) -> None:- self.resumed_hooks += 1- self.runtime_state.resumed = True---def test_snapshot_contains_runtime_state_only_not_config_deps_or_resources() -> None:- compositor = Compositor([LayerNode("state", StateLayer)])-- async def get_snapshot() -> dict[str, object]:- async with compositor.enter() as active_run:- state_layer = active_run.get_layer("state", StateLayer)- state_layer.runtime_state.resource_id = "abc"- assert active_run.session_snapshot is not None- return active_run.session_snapshot.model_dump(mode="json")-- dumped = asyncio.run(get_snapshot())- assert dumped == {- "schema_version": 1,- "layers": [- {- "name": "state",- "lifecycle_state": "closed",- "runtime_state": {"resource_id": "abc", "created": True, "resumed": False},- }- ],- }---def test_hydrate_validates_runtime_state_and_resume_mutates_layer_self() -> None:- compositor = Compositor([LayerNode("state", StateLayer)])-- bad_snapshot = {"layers": [{"name": "state", "lifecycle_state": "suspended", "runtime_state": {"wrong": "field"}}]}- with pytest.raises(ValidationError):- asyncio.run(_enter_once(compositor, session_snapshot=bad_snapshot))-- good_snapshot = {- "layers": [- {- "name": "state",- "lifecycle_state": "suspended",- "runtime_state": {"resource_id": "abc", "created": True, "resumed": False},- }- ]- }-- async def run() -> None:- async with compositor.enter(session_snapshot=good_snapshot) as active_run:- layer = active_run.get_layer("state", StateLayer)- assert layer.runtime_state.resource_id == "abc"- assert layer.runtime_state.resumed is True- assert layer.resumed_hooks == 1-- asyncio.run(run())---def test_hydrate_rejects_mismatched_snapshot_layer_names() -> None:- compositor = Compositor([LayerNode("state", StateLayer)])-- with pytest.raises(ValueError, match=r"Expected \[state\], got \[other\]"):- asyncio.run(- _enter_once(- compositor,- session_snapshot={"layers": [{"name": "other", "lifecycle_state": "new", "runtime_state": {}}]},- )- )---def test_removed_lifecycle_and_resource_apis_are_not_public_exports() -> None:- assert not hasattr(compositor_module, "CompositorBuilder")- assert not hasattr(compositor_module, "LayerRegistry")- assert not hasattr(compositor_module, "LayerDescriptor")- assert not hasattr(layers_module, "LayerControl")- assert not hasattr(layers_module, "EmptyRuntimeHandles")- assert not hasattr(Layer, "enter")- assert not hasattr(Layer, "hydrate_session_state")- assert not hasattr(Layer, "suspend_on_exit")- assert not hasattr(Layer, "delete_on_exit")- assert not hasattr(Layer, "runtime_handles")- assert not hasattr(Layer, "require_control")- assert not hasattr(Layer, "control_for")- assert not hasattr(Layer, "enter_async_resource")- assert not hasattr(Layer, "add_async_cleanup")---def test_facade_keeps_direct_import_type_aliases_without_expanding___all__() -> None:- assert compositor_module.LayerConfigInput is LayerConfigInput- assert compositor_module.LayerProviderInput is LayerProviderInput- assert LayerConfigInput.__module__ == "agenton.compositor"- assert LayerProviderInput.__module__ == "agenton.compositor"- assert LayerConfigInput.__name__ == "LayerConfigInput"- assert LayerProviderInput.__name__ == "LayerProviderInput"- assert "LayerConfigInput" not in compositor_module.__all__- assert "LayerProviderInput" not in compositor_module.__all__---def test_facade_export_surface_matches_split_contract() -> None:- compatibility_names = [*EXPECTED_FACADE_EXPORTS, *EXPECTED_DIRECT_IMPORT_COMPAT_NAMES]-- assert compositor_module.__all__ == EXPECTED_FACADE_EXPORTS-- namespace: dict[str, object] = {}- exec(- "from agenton.compositor import " + ", ".join(compatibility_names),- {},- namespace,- )-- for name in compatibility_names:- assert namespace[name] is getattr(compositor_module, name)---def _object_provider(value: str) -> LayerProvider[ObjectLayer[str]]:- return LayerProvider.from_factory(layer_type=ObjectLayer, create=lambda config: ObjectLayer(value))---async def _enter_once(- compositor: Compositor,- *,- configs: dict[str, object] | None = None,- session_snapshot: object | None = None,-) -> None:- async with compositor.enter(- configs=configs, # pyright: ignore[reportArgumentType]- session_snapshot=session_snapshot, # pyright: ignore[reportArgumentType]- ):- passdiff --git a/dify-agent/tests/local/agenton/compositor/test_direct_deps.py b/dify-agent/tests/local/agenton/compositor/test_direct_deps.pydeleted file mode 100644index b7ae26ec5cf..00000000000--- a/dify-agent/tests/local/agenton/compositor/test_direct_deps.py+++ /dev/null@@ -1,138 +0,0 @@-import asyncio-from dataclasses import dataclass--import pytest-from typing_extensions import override--from agenton.compositor import Compositor, LayerNode, LayerProvider-from agenton.layers import EmptyLayerConfig, LayerDeps, PlainLayer-from agenton_collections.layers.plain import ObjectLayer---class RenamedObjectDeps(LayerDeps):- renamed: ObjectLayer[str] # pyright: ignore[reportUninitializedInstanceVariable]---@dataclass(slots=True)-class RenamedConsumerLayer(PlainLayer[RenamedObjectDeps]):- @property- @override- def prefix_prompts(self) -> list[str]:- return [self.deps.renamed.value]---class SameNameObjectDeps(LayerDeps):- same: ObjectLayer[str] # pyright: ignore[reportUninitializedInstanceVariable]---@dataclass(slots=True)-class SameNameConsumerLayer(PlainLayer[SameNameObjectDeps]):- @property- @override- def prefix_prompts(self) -> list[str]:- return [self.deps.same.value]---class OptionalObjectDeps(LayerDeps):- maybe: ObjectLayer[str] | None # pyright: ignore[reportUninitializedInstanceVariable]---@dataclass(slots=True)-class OptionalConsumerLayer(PlainLayer[OptionalObjectDeps]):- pass---def _object_provider(value: str) -> LayerProvider[ObjectLayer[str]]:- return LayerProvider.from_factory(- layer_type=ObjectLayer,- create=lambda config: ObjectLayer(value),- )---def test_direct_deps_access_uses_explicit_dependency_rename() -> None:- compositor = Compositor(- [- LayerNode("actual", _object_provider("target")),- LayerNode("consumer", RenamedConsumerLayer, deps={"renamed": "actual"}),- ]- )-- async def run() -> None:- async with compositor.enter() as active_run:- target = active_run.get_layer("actual", ObjectLayer)- consumer = active_run.get_layer("consumer", RenamedConsumerLayer)- assert consumer.deps.renamed is target- assert [prompt.value for prompt in active_run.prompts] == ["target"]-- asyncio.run(run())---def test_direct_deps_access_uses_explicit_same_name_dependency() -> None:- compositor = Compositor(- [- LayerNode("same", _object_provider("target")),- LayerNode("consumer", SameNameConsumerLayer, deps={"same": "same"}),- ]- )-- async def run() -> None:- async with compositor.enter() as active_run:- target = active_run.get_layer("same", ObjectLayer)- consumer = active_run.get_layer("consumer", SameNameConsumerLayer)- assert consumer.deps.same is target- assert [prompt.value for prompt in active_run.prompts] == ["target"]-- asyncio.run(run())---def test_optional_missing_dependency_is_bound_to_none() -> None:- compositor = Compositor([LayerNode("consumer", OptionalConsumerLayer)])-- async def run() -> None:- async with compositor.enter() as active_run:- consumer = active_run.get_layer("consumer", OptionalConsumerLayer)- assert consumer.deps.maybe is None-- asyncio.run(run())---def test_missing_required_dependency_is_rejected_before_hooks() -> None:- compositor = Compositor([LayerNode("consumer", SameNameConsumerLayer)])-- with pytest.raises(ValueError, match="Dependency 'same' is required"):- asyncio.run(_enter_once(compositor))---def test_unknown_dependency_mapping_is_rejected_for_compositor_construction() -> None:- with pytest.raises(ValueError, match="unknown dependency keys: missing"):- Compositor([LayerNode("consumer", RenamedConsumerLayer, deps={"missing": "target"})])---def test_undefined_dependency_target_is_rejected_for_compositor_construction() -> None:- with pytest.raises(ValueError, match="depends on undefined layer names: missing_target"):- Compositor([LayerNode("consumer", RenamedConsumerLayer, deps={"renamed": "missing_target"})])---def test_dependency_target_must_precede_dependent_layer_in_graph_order() -> None:- with pytest.raises(ValueError, match="must target preceding layer nodes"):- Compositor(- [- LayerNode("consumer", RenamedConsumerLayer, deps={"renamed": "target"}),- LayerNode("target", _object_provider("value")),- ]- )---def test_duplicate_layer_node_name_is_rejected() -> None:- with pytest.raises(ValueError, match="Duplicate layer name 'same'"):- Compositor(- [- LayerNode("same", _object_provider("first")),- LayerNode("same", _object_provider("second")),- ]- )---async def _enter_once(compositor: Compositor) -> None:- async with compositor.enter(configs={"consumer": EmptyLayerConfig()}):- passdiff --git a/dify-agent/tests/local/agenton/compositor/test_enter.py b/dify-agent/tests/local/agenton/compositor/test_enter.pydeleted file mode 100644index d22b91a94a6..00000000000--- a/dify-agent/tests/local/agenton/compositor/test_enter.py+++ /dev/null@@ -1,982 +0,0 @@-import asyncio-from collections.abc import AsyncGenerator, Iterator-from contextlib import asynccontextmanager-from dataclasses import dataclass, field-from itertools import count--import pytest-from pydantic import BaseModel, ConfigDict, ValidationError-from typing_extensions import override--from agenton.compositor import Compositor, CompositorSessionSnapshot, LayerNode, LayerProvider-from agenton.layers import (- EmptyLayerConfig,- ExitIntent,- LayerConfig,- LifecycleState,- NoLayerDeps,- PlainLayer,-)---@dataclass(slots=True)-class TraceLayer(PlainLayer[NoLayerDeps]):- """Layer that records no-arg lifecycle events observable to tests."""-- events: list[str] = field(default_factory=list)-- @override- async def on_context_create(self) -> None:- self.events.append("create")-- @override- async def on_context_suspend(self) -> None:- self.events.append("suspend")-- @override- async def on_context_resume(self) -> None:- self.events.append("resume")-- @override- async def on_context_delete(self) -> None:- self.events.append("delete")---def _compositor(*layer_names: str) -> Compositor:- return Compositor([LayerNode(layer_name, TraceLayer) for layer_name in layer_names])---def test_same_compositor_enters_multiple_times_with_fresh_layers_and_snapshot_resume() -> None:- compositor = _compositor("first", "second")- runs = []-- async def run() -> None:- async with compositor.enter() as first_run:- assert [slot.lifecycle_state for slot in first_run.slots.values()] == [- LifecycleState.ACTIVE,- LifecycleState.ACTIVE,- ]- first_run.suspend_on_exit()- assert [slot.exit_intent for slot in first_run.slots.values()] == [- ExitIntent.SUSPEND,- ExitIntent.SUSPEND,- ]- runs.append(first_run)-- assert first_run.session_snapshot is not None- async with compositor.enter(session_snapshot=first_run.session_snapshot) as resumed_run:- assert resumed_run.get_layer("first", TraceLayer).events == ["resume"]- assert resumed_run.get_layer("second", TraceLayer).events == ["resume"]- runs.append(resumed_run)-- asyncio.run(run())-- first_layer = runs[0].get_layer("first", TraceLayer)- resumed_layer = runs[1].get_layer("first", TraceLayer)- assert first_layer is not resumed_layer- assert first_layer.events == ["create", "suspend"]- assert resumed_layer.events == ["resume", "delete"]- assert runs[1].session_snapshot is not None- assert [layer.lifecycle_state for layer in runs[1].session_snapshot.layers] == [- LifecycleState.CLOSED,- LifecycleState.CLOSED,- ]---def test_concurrent_enters_do_not_share_layer_instances() -> None:- compositor = _compositor("trace")-- async def enter_once() -> tuple[int, list[str]]:- async with compositor.enter() as run:- layer = run.get_layer("trace", TraceLayer)- await asyncio.sleep(0)- return id(layer), layer.events-- async def run_concurrently() -> list[tuple[int, list[str]]]:- return list(await asyncio.gather(enter_once(), enter_once()))-- results = asyncio.run(run_concurrently())-- assert results[0][0] != results[1][0]- assert results[0][1] == ["create", "delete"]- assert results[1][1] == ["create", "delete"]---class ConfiguredLayerConfig(LayerConfig):- value: str-- model_config = ConfigDict(extra="forbid")---@dataclass(slots=True)-class ConfiguredLayer(PlainLayer[NoLayerDeps, ConfiguredLayerConfig]):- type_id = "test.configured"-- value: str-- hooks: list[str] = field(default_factory=list)-- @classmethod- @override- def from_config(cls, config: ConfiguredLayerConfig) -> "ConfiguredLayer":- return cls(value=config.value)-- @override- async def on_context_create(self) -> None:- self.hooks.append(f"create:{self.config.value}")---def test_custom_factory_is_called_each_enter_with_typed_config() -> None:- calls: list[str] = []-- def create_layer(config: ConfiguredLayerConfig) -> ConfiguredLayer:- calls.append(config.value)- return ConfiguredLayer(value=f"factory:{config.value}")-- compositor = Compositor(- [LayerNode("configured", LayerProvider.from_factory(layer_type=ConfiguredLayer, create=create_layer))]- )-- async def run() -> None:- async with compositor.enter(configs={"configured": {"value": "one"}}) as first_run:- first_layer = first_run.get_layer("configured", ConfiguredLayer)- assert first_layer.value == "factory:one"- assert first_layer.config.value == "one"- async with compositor.enter(configs={"configured": ConfiguredLayerConfig(value="two")}) as second_run:- second_layer = second_run.get_layer("configured", ConfiguredLayer)- assert second_layer.value == "factory:two"- assert second_layer.config.value == "two"- assert second_layer is not first_layer-- asyncio.run(run())-- assert calls == ["one", "two"]---def test_provider_rejects_reused_layer_instance_before_hooks_run() -> None:- shared_layer = TraceLayer()- compositor = Compositor(- [- LayerNode(- "trace",- LayerProvider.from_factory(layer_type=TraceLayer, create=lambda config: shared_layer),- )- ]- )-- async def run() -> None:- async with compositor.enter():- pass-- with pytest.raises(ValueError, match="fresh layer instance"):- async with compositor.enter():- pass-- asyncio.run(run())-- assert shared_layer.events == ["create", "delete"]---def test_configs_are_validated_by_node_name_before_factory_call() -> None:- calls: list[str] = []-- def create_layer(config: ConfiguredLayerConfig) -> ConfiguredLayer:- calls.append(config.value)- return ConfiguredLayer(value=config.value)-- compositor = Compositor(- [LayerNode("configured", LayerProvider.from_factory(layer_type=ConfiguredLayer, create=create_layer))]- )-- with pytest.raises(ValueError, match="unknown layer node names: missing"):- asyncio.run(_enter_once(compositor, configs={"missing": {}}))-- with pytest.raises(ValidationError):- asyncio.run(_enter_once(compositor, configs={"configured": {"unknown": "field"}}))-- assert calls == []---def test_all_node_configs_are_validated_before_any_factory_runs() -> None:- calls: list[str] = []-- def create_layer(config: ConfiguredLayerConfig) -> ConfiguredLayer:- calls.append(config.value)- return ConfiguredLayer(value=config.value)-- provider = LayerProvider.from_factory(layer_type=ConfiguredLayer, create=create_layer)- compositor = Compositor([LayerNode("first", provider), LayerNode("second", provider)])-- with pytest.raises(ValidationError):- asyncio.run(- _enter_once(- compositor,- configs={"first": {"value": "valid"}, "second": {"unknown": "field"}},- )- )-- assert calls == []---def test_existing_config_model_instances_are_revalidated_before_factory_runs() -> None:- calls: list[str] = []-- def create_layer(config: ConfiguredLayerConfig) -> ConfiguredLayer:- calls.append(config.value)- return ConfiguredLayer(value=config.value)-- compositor = Compositor(- [LayerNode("configured", LayerProvider.from_factory(layer_type=ConfiguredLayer, create=create_layer))]- )- config = ConfiguredLayerConfig(value="valid")- config.value = 123 # pyright: ignore[reportAttributeAccessIssue]-- with pytest.raises(ValidationError):- asyncio.run(_enter_once(compositor, configs={"configured": config}))-- assert calls == []---def test_existing_snapshot_model_instances_are_revalidated_before_factory_runs() -> None:- calls = 0-- def create_layer(config: EmptyLayerConfig) -> TraceLayer:- nonlocal calls- calls += 1- return TraceLayer()-- compositor = Compositor(- [LayerNode("trace", LayerProvider.from_factory(layer_type=TraceLayer, create=create_layer))]- )- snapshot = CompositorSessionSnapshot.model_validate(- {"layers": [{"name": "trace", "lifecycle_state": "suspended", "runtime_state": {}}]}- )- snapshot.layers[0].lifecycle_state = LifecycleState.ACTIVE-- with pytest.raises(ValidationError, match="ACTIVE is internal-only"):- asyncio.run(_enter_once(compositor, session_snapshot=snapshot))-- assert calls == 0---class RuntimeState(BaseModel):- runtime_id: int | None = None- resumed_runtime_id: int | None = None- deleted_runtime_id: int | None = None- body_value: str | None = None-- model_config = ConfigDict(extra="forbid", validate_assignment=True)---@dataclass(slots=True)-class RuntimeStateLayer(PlainLayer[NoLayerDeps, EmptyLayerConfig, RuntimeState]):- next_id: Iterator[int] = field(default_factory=lambda: count(1))-- @override- async def on_context_create(self) -> None:- self.runtime_state.runtime_id = next(self.next_id)-- @override- async def on_context_resume(self) -> None:- self.runtime_state.resumed_runtime_id = self.runtime_state.runtime_id-- @override- async def on_context_delete(self) -> None:- self.runtime_state.deleted_runtime_id = self.runtime_state.runtime_id---def test_snapshot_hydrates_runtime_state_and_exit_snapshots_from_layer_self() -> None:- compositor = Compositor([LayerNode("state", RuntimeStateLayer)])-- async def create_suspend_resume_delete() -> tuple[CompositorSessionSnapshot, CompositorSessionSnapshot]:- async with compositor.enter() as first_run:- first_run.suspend_on_exit()- assert first_run.session_snapshot is not None-- async with compositor.enter(session_snapshot=first_run.session_snapshot) as resumed_run:- resumed_layer = resumed_run.get_layer("state", RuntimeStateLayer)- assert isinstance(resumed_layer.runtime_state, RuntimeState)- assert resumed_layer.runtime_state.runtime_id == 1- assert resumed_layer.runtime_state.resumed_runtime_id == 1- resumed_layer.runtime_state.body_value = "mutated on self"- assert resumed_run.session_snapshot is not None- return first_run.session_snapshot, resumed_run.session_snapshot-- suspended_snapshot, closed_snapshot = asyncio.run(create_suspend_resume_delete())-- assert suspended_snapshot.model_dump(mode="json") == {- "schema_version": 1,- "layers": [- {- "name": "state",- "lifecycle_state": "suspended",- "runtime_state": {- "runtime_id": 1,- "resumed_runtime_id": None,- "deleted_runtime_id": None,- "body_value": None,- },- }- ],- }- assert closed_snapshot.model_dump(mode="json") == {- "schema_version": 1,- "layers": [- {- "name": "state",- "lifecycle_state": "closed",- "runtime_state": {- "runtime_id": 1,- "resumed_runtime_id": 1,- "deleted_runtime_id": 1,- "body_value": "mutated on self",- },- }- ],- }---def test_run_snapshot_rejects_active_layers() -> None:- compositor = _compositor("trace")-- async def run() -> None:- async with compositor.enter() as active_run:- with pytest.raises(RuntimeError, match="Cannot snapshot active compositor run layers: trace"):- active_run.snapshot_session()-- asyncio.run(run())---def test_active_snapshot_input_is_rejected_before_factories_run() -> None:- calls = 0-- def create_layer(config: EmptyLayerConfig) -> TraceLayer:- nonlocal calls- calls += 1- return TraceLayer()-- compositor = Compositor(- [LayerNode("trace", LayerProvider.from_factory(layer_type=TraceLayer, create=create_layer))]- )- active_snapshot = {"layers": [{"name": "trace", "lifecycle_state": "active", "runtime_state": {}}]}-- with pytest.raises(ValidationError, match="ACTIVE is internal-only"):- CompositorSessionSnapshot.model_validate(active_snapshot)-- with pytest.raises(ValidationError, match="ACTIVE is internal-only"):- asyncio.run(_enter_once(compositor, session_snapshot=active_snapshot))-- assert calls == 0---def test_closed_snapshot_enter_is_rejected_before_hooks_run() -> None:- created_layers: list[TraceLayer] = []-- def create_layer(config: EmptyLayerConfig) -> TraceLayer:- layer = TraceLayer()- created_layers.append(layer)- return layer-- compositor = Compositor(- [LayerNode("trace", LayerProvider.from_factory(layer_type=TraceLayer, create=create_layer))]- )- closed_snapshot = {"layers": [{"name": "trace", "lifecycle_state": "closed", "runtime_state": {}}]}-- with pytest.raises(RuntimeError, match="CLOSED snapshots cannot be entered"):- asyncio.run(_enter_once(compositor, session_snapshot=closed_snapshot))-- assert len(created_layers) == 1- assert created_layers[0].events == []---class ResourceState(BaseModel):- created_with_resource: bool = False- deleted_with_resource: bool = False- saw_dependency_resource: bool = False-- model_config = ConfigDict(extra="forbid", validate_assignment=True)---@dataclass(slots=True)-class ParentResourceLayer(PlainLayer[NoLayerDeps, EmptyLayerConfig, ResourceState]):- events: list[str] = field(default_factory=list)- live_resource: object | None = None-- @override- @asynccontextmanager- async def resource_context(self) -> AsyncGenerator[None]:- self.events.append("parent.resource.enter")- self.live_resource = object()- try:- yield- finally:- self.events.append("parent.resource.exit")- self.live_resource = None-- @override- async def on_context_create(self) -> None:- assert self.live_resource is not None- self.events.append("parent.create")- self.runtime_state.created_with_resource = True-- @override- async def on_context_delete(self) -> None:- assert self.live_resource is not None- self.events.append("parent.delete")- self.runtime_state.deleted_with_resource = True-- @override- async def on_context_suspend(self) -> None:- assert self.live_resource is not None- self.events.append("parent.suspend")---class ChildResourceDeps(NoLayerDeps):- parent: ParentResourceLayer # pyright: ignore[reportUninitializedInstanceVariable]---@dataclass(slots=True)-class ChildResourceLayer(PlainLayer[ChildResourceDeps, EmptyLayerConfig, ResourceState]):- events: list[str] = field(default_factory=list)- live_resource: object | None = None-- @override- @asynccontextmanager- async def resource_context(self) -> AsyncGenerator[None]:- self.events.append("child.resource.enter")- self.live_resource = object()- try:- yield- finally:- self.events.append("child.resource.exit")- self.live_resource = None-- @override- async def on_context_create(self) -> None:- assert self.live_resource is not None- self.events.append("child.create")- self.runtime_state.created_with_resource = True- self.runtime_state.saw_dependency_resource = self.deps.parent.live_resource is not None-- @override- async def on_context_delete(self) -> None:- assert self.live_resource is not None- self.events.append("child.delete")- self.runtime_state.deleted_with_resource = True---@dataclass(slots=True)-class CreateFailureResourceLayer(PlainLayer[NoLayerDeps]):- events: list[str] = field(default_factory=list)- live_resource: bool = False-- @override- @asynccontextmanager- async def resource_context(self) -> AsyncGenerator[None]:- self.events.append("resource.enter")- self.live_resource = True- try:- yield- finally:- self.events.append("resource.exit")- self.live_resource = False-- @override- async def on_context_create(self) -> None:- assert self.live_resource is True- self.events.append("create")- raise RuntimeError("create failed")-- @override- async def on_context_delete(self) -> None:- self.events.append("delete")---@dataclass(slots=True)-class DeleteFailureResourceLayer(PlainLayer[NoLayerDeps]):- events: list[str] = field(default_factory=list)- live_resource: bool = False-- @override- @asynccontextmanager- async def resource_context(self) -> AsyncGenerator[None]:- self.events.append("resource.enter")- self.live_resource = True- try:- yield- finally:- self.events.append("resource.exit")- self.live_resource = False-- @override- async def on_context_create(self) -> None:- assert self.live_resource is True- self.events.append("create")-- @override- async def on_context_delete(self) -> None:- assert self.live_resource is True- self.events.append("delete")- raise RuntimeError("delete failed")---class ResumeResourceState(BaseModel):- created_with_resource: bool = False- resumed_with_resource: bool = False- suspended_with_resource: bool = False- deleted_with_resource: bool = False-- model_config = ConfigDict(extra="forbid", validate_assignment=True)---@dataclass(slots=True)-class SuspendResumeResourceLayer(PlainLayer[NoLayerDeps, EmptyLayerConfig, ResumeResourceState]):- events: list[str]- next_resource_id: Iterator[int]- live_resource: str | None = None-- @override- @asynccontextmanager- async def resource_context(self) -> AsyncGenerator[None]:- self.live_resource = f"resource-{next(self.next_resource_id)}"- self.events.append(f"resource.enter:{self.live_resource}")- try:- yield- finally:- assert self.live_resource is not None- self.events.append(f"resource.exit:{self.live_resource}")- self.live_resource = None-- @override- async def on_context_create(self) -> None:- assert self.live_resource is not None- self.events.append(f"create:{self.live_resource}")- self.runtime_state.created_with_resource = True-- @override- async def on_context_resume(self) -> None:- assert self.live_resource is not None- self.events.append(f"resume:{self.live_resource}")- self.runtime_state.resumed_with_resource = True-- @override- async def on_context_suspend(self) -> None:- assert self.live_resource is not None- self.events.append(f"suspend:{self.live_resource}")- self.runtime_state.suspended_with_resource = True-- @override- async def on_context_delete(self) -> None:- assert self.live_resource is not None- self.events.append(f"delete:{self.live_resource}")- self.runtime_state.deleted_with_resource = True---class CreateFailureChildResourceLayer(ChildResourceLayer):- @override- async def on_context_create(self) -> None:- assert self.live_resource is not None- self.events.append("child.create")- raise RuntimeError("child create failed")---class SuspendFailureChildResourceLayer(ChildResourceLayer):- @override- async def on_context_suspend(self) -> None:- assert self.live_resource is not None- self.events.append("child.suspend")- raise RuntimeError("child suspend failed")---def test_resource_context_wraps_hooks_and_body_in_dependency_order() -> None:- events: list[str] = []- compositor = Compositor(- [- LayerNode(- "parent",- LayerProvider.from_factory(- layer_type=ParentResourceLayer,- create=lambda config: ParentResourceLayer(events),- ),- ),- LayerNode(- "child",- LayerProvider.from_factory(- layer_type=ChildResourceLayer,- create=lambda config: ChildResourceLayer(events),- ),- deps={"parent": "parent"},- ),- ]- )-- async def run() -> CompositorSessionSnapshot:- async with compositor.enter() as active_run:- parent = active_run.get_layer("parent", ParentResourceLayer)- child = active_run.get_layer("child", ChildResourceLayer)- assert parent.live_resource is not None- assert child.live_resource is not None- assert child.deps.parent is parent- events.append("body")- assert active_run.session_snapshot is not None- assert parent.live_resource is None- assert child.live_resource is None- return active_run.session_snapshot-- snapshot = asyncio.run(run())-- assert events == [- "parent.resource.enter",- "parent.create",- "child.resource.enter",- "child.create",- "body",- "child.delete",- "child.resource.exit",- "parent.delete",- "parent.resource.exit",- ]- assert snapshot.model_dump(mode="json") == {- "schema_version": 1,- "layers": [- {- "name": "parent",- "lifecycle_state": "closed",- "runtime_state": {- "created_with_resource": True,- "deleted_with_resource": True,- "saw_dependency_resource": False,- },- },- {- "name": "child",- "lifecycle_state": "closed",- "runtime_state": {- "created_with_resource": True,- "deleted_with_resource": True,- "saw_dependency_resource": True,- },- },- ],- }---def test_resource_context_wraps_resume_and_suspend_with_fresh_resource_scope() -> None:- events: list[str] = []- resource_ids = count(1)- created_layers: list[SuspendResumeResourceLayer] = []-- def create_layer(config: EmptyLayerConfig) -> SuspendResumeResourceLayer:- layer = SuspendResumeResourceLayer(events=events, next_resource_id=resource_ids)- created_layers.append(layer)- return layer-- compositor = Compositor(- [LayerNode("trace", LayerProvider.from_factory(layer_type=SuspendResumeResourceLayer, create=create_layer))]- )-- async def run() -> tuple[CompositorSessionSnapshot, CompositorSessionSnapshot]:- async with compositor.enter() as first_run:- first_layer = first_run.get_layer("trace", SuspendResumeResourceLayer)- assert first_layer.live_resource == "resource-1"- first_run.suspend_on_exit()- assert first_run.session_snapshot is not None-- async with compositor.enter(session_snapshot=first_run.session_snapshot) as resumed_run:- resumed_layer = resumed_run.get_layer("trace", SuspendResumeResourceLayer)- assert resumed_layer.live_resource == "resource-2"- assert resumed_layer.live_resource != "resource-1"- assert resumed_run.session_snapshot is not None- return first_run.session_snapshot, resumed_run.session_snapshot-- suspended_snapshot, resumed_snapshot = asyncio.run(run())-- assert len(created_layers) == 2- assert all(layer.live_resource is None for layer in created_layers)- assert events == [- "resource.enter:resource-1",- "create:resource-1",- "suspend:resource-1",- "resource.exit:resource-1",- "resource.enter:resource-2",- "resume:resource-2",- "delete:resource-2",- "resource.exit:resource-2",- ]- assert suspended_snapshot.model_dump(mode="json") == {- "schema_version": 1,- "layers": [- {- "name": "trace",- "lifecycle_state": "suspended",- "runtime_state": {- "created_with_resource": True,- "resumed_with_resource": False,- "suspended_with_resource": True,- "deleted_with_resource": False,- },- }- ],- }- assert resumed_snapshot.model_dump(mode="json") == {- "schema_version": 1,- "layers": [- {- "name": "trace",- "lifecycle_state": "closed",- "runtime_state": {- "created_with_resource": True,- "resumed_with_resource": True,- "suspended_with_resource": True,- "deleted_with_resource": True,- },- }- ],- }---def test_resource_context_exits_when_run_body_raises() -> None:- events: list[str] = []- created_layers: list[ParentResourceLayer | ChildResourceLayer] = []-- def create_parent(config: EmptyLayerConfig) -> ParentResourceLayer:- layer = ParentResourceLayer(events)- created_layers.append(layer)- return layer-- def create_child(config: EmptyLayerConfig) -> ChildResourceLayer:- layer = ChildResourceLayer(events)- created_layers.append(layer)- return layer-- compositor = Compositor(- [- LayerNode("parent", LayerProvider.from_factory(layer_type=ParentResourceLayer, create=create_parent)),- LayerNode(- "child",- LayerProvider.from_factory(layer_type=ChildResourceLayer, create=create_child),- deps={"parent": "parent"},- ),- ]- )-- async def run() -> None:- async with compositor.enter():- events.append("body")- raise RuntimeError("body failed")-- with pytest.raises(RuntimeError, match="body failed"):- asyncio.run(run())-- assert [layer.live_resource for layer in created_layers] == [None, None]- assert events == [- "parent.resource.enter",- "parent.create",- "child.resource.enter",- "child.create",- "body",- "child.delete",- "child.resource.exit",- "parent.delete",- "parent.resource.exit",- ]---def test_resource_context_exits_when_run_body_is_cancelled() -> None:- events: list[str] = []- created_layers: list[ParentResourceLayer | ChildResourceLayer] = []-- def create_parent(config: EmptyLayerConfig) -> ParentResourceLayer:- layer = ParentResourceLayer(events)- created_layers.append(layer)- return layer-- def create_child(config: EmptyLayerConfig) -> ChildResourceLayer:- layer = ChildResourceLayer(events)- created_layers.append(layer)- return layer-- compositor = Compositor(- [- LayerNode("parent", LayerProvider.from_factory(layer_type=ParentResourceLayer, create=create_parent)),- LayerNode(- "child",- LayerProvider.from_factory(layer_type=ChildResourceLayer, create=create_child),- deps={"parent": "parent"},- ),- ]- )-- async def run() -> None:- async with compositor.enter():- events.append("body")- task = asyncio.current_task()- assert task is not None- task.cancel()- await asyncio.sleep(0)-- with pytest.raises(asyncio.CancelledError):- asyncio.run(run())-- assert [layer.live_resource for layer in created_layers] == [None, None]- assert events == [- "parent.resource.enter",- "parent.create",- "child.resource.enter",- "child.create",- "body",- "child.delete",- "child.resource.exit",- "parent.delete",- "parent.resource.exit",- ]---def test_dependency_resource_contexts_exit_when_child_create_fails() -> None:- events: list[str] = []- created_layers: list[ParentResourceLayer | CreateFailureChildResourceLayer] = []-- def create_parent(config: EmptyLayerConfig) -> ParentResourceLayer:- layer = ParentResourceLayer(events)- created_layers.append(layer)- return layer-- def create_child(config: EmptyLayerConfig) -> CreateFailureChildResourceLayer:- layer = CreateFailureChildResourceLayer(events)- created_layers.append(layer)- return layer-- compositor = Compositor(- [- LayerNode("parent", LayerProvider.from_factory(layer_type=ParentResourceLayer, create=create_parent)),- LayerNode(- "child",- LayerProvider.from_factory(layer_type=CreateFailureChildResourceLayer, create=create_child),- deps={"parent": "parent"},- ),- ]- )-- with pytest.raises(RuntimeError, match="child create failed"):- asyncio.run(_enter_once(compositor))-- assert [layer.live_resource for layer in created_layers] == [None, None]- assert events == [- "parent.resource.enter",- "parent.create",- "child.resource.enter",- "child.create",- "child.resource.exit",- "parent.delete",- "parent.resource.exit",- ]---def test_dependency_resource_contexts_exit_when_child_suspend_fails() -> None:- events: list[str] = []- created_layers: list[ParentResourceLayer | SuspendFailureChildResourceLayer] = []-- def create_parent(config: EmptyLayerConfig) -> ParentResourceLayer:- layer = ParentResourceLayer(events)- created_layers.append(layer)- return layer-- def create_child(config: EmptyLayerConfig) -> SuspendFailureChildResourceLayer:- layer = SuspendFailureChildResourceLayer(events)- created_layers.append(layer)- return layer-- compositor = Compositor(- [- LayerNode("parent", LayerProvider.from_factory(layer_type=ParentResourceLayer, create=create_parent)),- LayerNode(- "child",- LayerProvider.from_factory(layer_type=SuspendFailureChildResourceLayer, create=create_child),- deps={"parent": "parent"},- ),- ]- )-- async def run() -> None:- async with compositor.enter() as active_run:- events.append("body")- active_run.suspend_on_exit()-- with pytest.raises(RuntimeError, match="child suspend failed"):- asyncio.run(run())-- assert [layer.live_resource for layer in created_layers] == [None, None]- assert events == [- "parent.resource.enter",- "parent.create",- "child.resource.enter",- "child.create",- "body",- "child.suspend",- "child.resource.exit",- "parent.suspend",- "parent.resource.exit",- ]---def test_resource_context_exits_when_create_hook_raises() -> None:- created_layers: list[CreateFailureResourceLayer] = []-- def create_layer(config: EmptyLayerConfig) -> CreateFailureResourceLayer:- layer = CreateFailureResourceLayer()- created_layers.append(layer)- return layer-- compositor = Compositor(- [- LayerNode(- "trace",- LayerProvider.from_factory(layer_type=CreateFailureResourceLayer, create=create_layer),- )- ]- )-- with pytest.raises(RuntimeError, match="create failed"):- asyncio.run(_enter_once(compositor))-- assert len(created_layers) == 1- assert created_layers[0].events == ["resource.enter", "create", "resource.exit"]- assert created_layers[0].live_resource is False---def test_resource_context_exits_when_delete_hook_raises() -> None:- deleted_layers: list[DeleteFailureResourceLayer] = []-- def create_layer(config: EmptyLayerConfig) -> DeleteFailureResourceLayer:- layer = DeleteFailureResourceLayer()- deleted_layers.append(layer)- return layer-- compositor = Compositor(- [- LayerNode(- "trace",- LayerProvider.from_factory(layer_type=DeleteFailureResourceLayer, create=create_layer),- )- ]- )-- with pytest.raises(RuntimeError, match="delete failed"):- asyncio.run(_enter_once(compositor))-- assert len(deleted_layers) == 1- assert deleted_layers[0].events == ["resource.enter", "create", "delete", "resource.exit"]- assert deleted_layers[0].live_resource is False---async def _enter_once(- compositor: Compositor,- *,- configs: dict[str, object] | None = None,- session_snapshot: object | None = None,-) -> None:- async with compositor.enter(- configs=configs, # pyright: ignore[reportArgumentType]- session_snapshot=session_snapshot, # pyright: ignore[reportArgumentType]- ):- passdiff --git a/dify-agent/tests/local/agenton/compositor/test_transformers.py b/dify-agent/tests/local/agenton/compositor/test_transformers.pydeleted file mode 100644index 56a41d9fe09..00000000000--- a/dify-agent/tests/local/agenton/compositor/test_transformers.py+++ /dev/null@@ -1,156 +0,0 @@-import asyncio-from collections.abc import Callable, Sequence-from dataclasses import dataclass-from inspect import Parameter, signature--from typing_extensions import override--from agenton.compositor import Compositor, CompositorTransformerKwargs, LayerNode, LayerProvider-from agenton.layers import NoLayerDeps, PlainLayer, PlainPromptType, PlainToolType, PlainUserPromptType--type ToolCallable = Callable[..., object]-type WrappedPrompt = tuple[str, str]-type WrappedUserPrompt = tuple[str, str]---@dataclass(slots=True)-class PromptAndToolLayer(PlainLayer[NoLayerDeps]):- prefix: list[str]- user: list[str]- suffix: list[str]- tool_entries: list[ToolCallable]-- @property- @override- def prefix_prompts(self) -> list[str]:- return self.prefix-- @property- @override- def suffix_prompts(self) -> list[str]:- return self.suffix-- @property- @override- def user_prompts(self) -> list[str]:- return self.user-- @property- @override- def tools(self) -> list[ToolCallable]:- return self.tool_entries---def base_tool() -> str:- return "base"---def wrapped_tool() -> str:- return "wrapped"---def wrap_prompts(prompts: Sequence[PlainPromptType]) -> list[WrappedPrompt]:- return [("wrapped", prompt.value) for prompt in prompts]---def wrap_user_prompts(prompts: Sequence[PlainUserPromptType]) -> list[WrappedUserPrompt]:- return [("wrapped-user", prompt.value) for prompt in prompts]---def describe_tools(tools: Sequence[PlainToolType]) -> list[str]:- return [tool.value.__name__ for tool in tools]---def prompt_tool_provider(- *,- prefix: list[str] | None = None,- user: list[str] | None = None,- suffix: list[str] | None = None,- tool_entries: list[ToolCallable] | None = None,-) -> LayerProvider[PromptAndToolLayer]:- return LayerProvider.from_factory(- layer_type=PromptAndToolLayer,- create=lambda config: PromptAndToolLayer(- prefix=list(prefix or []),- user=list(user or []),- suffix=list(suffix or []),- tool_entries=list(tool_entries or []),- ),- )---def test_compositor_transformer_kwargs_keys_match_constructor_parameters() -> None:- transformer_kwargs = set(CompositorTransformerKwargs.__required_keys__)- parameters = signature(Compositor).parameters-- assert CompositorTransformerKwargs.__optional_keys__ == frozenset()- assert transformer_kwargs == {name for name in parameters if name.endswith("_transformer")}- assert all(parameters[name].kind is Parameter.KEYWORD_ONLY for name in transformer_kwargs)---def test_compositor_transformer_kwargs_keys_match_from_config_parameters() -> None:- transformer_kwargs = set(CompositorTransformerKwargs.__required_keys__)- parameters = signature(Compositor.from_config).parameters-- assert transformer_kwargs == {name for name in parameters if name.endswith("_transformer")}- assert all(parameters[name].kind is Parameter.KEYWORD_ONLY for name in transformer_kwargs)---def test_compositor_transforms_prompts_to_another_type_after_layer_ordering() -> None:- compositor: Compositor[WrappedPrompt, PlainToolType, PlainPromptType, PlainToolType] = Compositor(- [- LayerNode("first", prompt_tool_provider(prefix=["first-prefix"], suffix=["first-suffix"])),- LayerNode("second", prompt_tool_provider(prefix=["second-prefix"], suffix=["second-suffix"])),- ],- prompt_transformer=wrap_prompts,- )-- async def run() -> None:- async with compositor.enter() as active_run:- assert active_run.prompts == [- ("wrapped", "first-prefix"),- ("wrapped", "second-prefix"),- ("wrapped", "second-suffix"),- ("wrapped", "first-suffix"),- ]-- asyncio.run(run())---def test_compositor_transforms_tools_to_another_type_after_layer_aggregation() -> None:- compositor: Compositor[PlainPromptType, str, PlainPromptType, PlainToolType] = Compositor(- [LayerNode("tools", prompt_tool_provider(tool_entries=[base_tool, wrapped_tool]))],- tool_transformer=describe_tools,- )-- async def run() -> None:- async with compositor.enter() as active_run:- assert active_run.tools == ["base_tool", "wrapped_tool"]-- asyncio.run(run())---def test_compositor_transforms_user_prompts_after_layer_ordering() -> None:- compositor: Compositor[- PlainPromptType,- PlainToolType,- PlainPromptType,- PlainToolType,- WrappedUserPrompt,- PlainUserPromptType,- ] = Compositor(- [- LayerNode("first", prompt_tool_provider(user=["first-user"])),- LayerNode("second", prompt_tool_provider(user=["second-user"])),- ],- user_prompt_transformer=wrap_user_prompts,- )-- async def run() -> None:- async with compositor.enter() as active_run:- assert active_run.user_prompts == [- ("wrapped-user", "first-user"),- ("wrapped-user", "second-user"),- ]-- asyncio.run(run())diff --git a/dify-agent/tests/local/agenton/layers/__init__.py b/dify-agent/tests/local/agenton/layers/__init__.pydeleted file mode 100644index 8b137891791..00000000000--- a/dify-agent/tests/local/agenton/layers/__init__.py+++ /dev/null@@ -1 +0,0 @@-diff --git a/dify-agent/tests/local/agenton/layers/test_layer_deps.py b/dify-agent/tests/local/agenton/layers/test_layer_deps.pydeleted file mode 100644index 1ab0c543e20..00000000000--- a/dify-agent/tests/local/agenton/layers/test_layer_deps.py+++ /dev/null@@ -1,15 +0,0 @@-import pytest--from agenton.layers import LayerDeps-from agenton_collections.layers.plain import ObjectLayer, PromptLayer---class ObjectLayerDeps(LayerDeps):- """Deps container used to exercise runtime dependency validation."""-- object_layer: ObjectLayer[str] # pyright: ignore[reportUninitializedInstanceVariable]---def test_layer_deps_rejects_mismatched_runtime_layer_class() -> None:- with pytest.raises(TypeError, match="should be of type 'ObjectLayer'"):- ObjectLayerDeps(object_layer=PromptLayer())diff --git a/dify-agent/tests/local/agenton/layers/test_schema_inference.py b/dify-agent/tests/local/agenton/layers/test_schema_inference.pydeleted file mode 100644index 55af512e544..00000000000--- a/dify-agent/tests/local/agenton/layers/test_schema_inference.py+++ /dev/null@@ -1,92 +0,0 @@-from dataclasses import dataclass--from pydantic import BaseModel, ConfigDict--from agenton.compositor import LayerProvider-from agenton.layers import (- EmptyLayerConfig,- EmptyRuntimeState,- LayerConfig,- NoLayerDeps,- PlainLayer,-)---class InferredConfig(LayerConfig):- value: str = "configured"-- model_config = ConfigDict(extra="forbid")---class InferredState(BaseModel):- count: int = 0-- model_config = ConfigDict(extra="forbid", validate_assignment=True)---@dataclass(slots=True)-class GenericSchemaLayer(PlainLayer[NoLayerDeps, InferredConfig, InferredState]):- type_id = "test.generic-schema"-- @classmethod- def from_config(cls, config: InferredConfig) -> "GenericSchemaLayer":- return cls()-- async def on_context_create(self) -> None:- self.runtime_state.count += 1---@dataclass(slots=True)-class DefaultSchemaLayer(PlainLayer[NoLayerDeps]):- type_id = "test.default-schema"---def test_layer_infers_config_and_runtime_state_from_generics() -> None:- layer = GenericSchemaLayer()- layer.runtime_state = InferredState(count=3)-- assert GenericSchemaLayer.config_type is InferredConfig- assert GenericSchemaLayer.runtime_state_type is InferredState- assert isinstance(layer.runtime_state, InferredState)- assert layer.runtime_state.count == 3---def test_layer_uses_empty_schema_defaults_when_omitted() -> None:- layer = DefaultSchemaLayer()-- assert DefaultSchemaLayer.config_type is EmptyLayerConfig- assert DefaultSchemaLayer.runtime_state_type is EmptyRuntimeState- assert isinstance(layer.runtime_state, EmptyRuntimeState)---def test_invalid_declared_schema_type_is_rejected_clearly() -> None:- try:-- class InvalidSchemaLayer(PlainLayer[NoLayerDeps]):- config_type = dict # pyright: ignore[reportAssignmentType]-- except TypeError as e:- assert str(e) == "InvalidSchemaLayer.config_type must be a LayerConfig subclass."- else:- raise AssertionError("Expected TypeError.")-- try:-- class InvalidGenericSchemaLayer(PlainLayer[NoLayerDeps, dict[str, object]]): # pyright: ignore[reportInvalidTypeArguments]- pass-- except TypeError as e:- assert str(e) == "InvalidGenericSchemaLayer.config_type must be a LayerConfig subclass."- else:- raise AssertionError("Expected TypeError.")---def test_layer_provider_uses_inferred_schema_types() -> None:- provider = LayerProvider.from_layer_type(GenericSchemaLayer)-- layer = provider.create_layer({"value": "configured"})-- assert provider.type_id == "test.generic-schema"- assert provider.layer_type.config_type is InferredConfig- assert provider.layer_type.runtime_state_type is InferredState- assert isinstance(layer.config, InferredConfig)diff --git a/dify-agent/tests/local/agenton_collections/__init__.py b/dify-agent/tests/local/agenton_collections/__init__.pydeleted file mode 100644index 8b137891791..00000000000--- a/dify-agent/tests/local/agenton_collections/__init__.py+++ /dev/null@@ -1 +0,0 @@-diff --git a/dify-agent/tests/local/agenton_collections/layers/plain/__init__.py b/dify-agent/tests/local/agenton_collections/layers/plain/__init__.pydeleted file mode 100644index 8b137891791..00000000000--- a/dify-agent/tests/local/agenton_collections/layers/plain/__init__.py+++ /dev/null@@ -1 +0,0 @@-diff --git a/dify-agent/tests/local/agenton_collections/layers/plain/test_basic.py b/dify-agent/tests/local/agenton_collections/layers/plain/test_basic.pydeleted file mode 100644index 45928d079bd..00000000000--- a/dify-agent/tests/local/agenton_collections/layers/plain/test_basic.py+++ /dev/null@@ -1,6 +0,0 @@-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayer---def test_prompt_layer_type_id_constant_matches_implementation_class() -> None:- assert PLAIN_PROMPT_LAYER_TYPE_ID == "plain.prompt"- assert PromptLayer.type_id == PLAIN_PROMPT_LAYER_TYPE_IDdiff --git a/dify-agent/tests/local/agenton_collections/layers/plain/test_dynamic_tools.py b/dify-agent/tests/local/agenton_collections/layers/plain/test_dynamic_tools.pydeleted file mode 100644index 213d7ff992a..00000000000--- a/dify-agent/tests/local/agenton_collections/layers/plain/test_dynamic_tools.py+++ /dev/null@@ -1,75 +0,0 @@-import asyncio--import pytest-from pydantic_ai import Tool--from agenton_collections.layers.plain import DynamicToolsLayer, ObjectLayer, with_object---class Profile:- """Profile object used by object-bound tool tests."""-- name: str-- def __init__(self, name: str) -> None:- self.name = name---class OtherProfile:- """Different runtime object used to trigger object mismatch checks."""---@with_object(Profile)-def greet(profile: Profile, topic: str) -> str:- return f"{profile.name}: {topic}"---def test_with_object_rejects_tool_without_object_parameter() -> None:- def tool() -> str:- return "unused"-- with pytest.raises(ValueError, match="must accept the object dependency"):- with_object(Profile)(tool) # pyright: ignore[reportArgumentType]---def test_with_object_rejects_first_parameter_annotation_mismatch() -> None:- def tool(profile: OtherProfile) -> str:- return repr(profile)-- with pytest.raises(TypeError, match="first parameter should accept 'Profile'"):- with_object(Profile)(tool) # pyright: ignore[reportArgumentType]---def test_dynamic_tools_layer_rejects_mismatched_runtime_object_value() -> None:- layer = DynamicToolsLayer[Profile](tool_entries=(greet,))- layer.bind_deps({"object_layer": ObjectLayer[OtherProfile](OtherProfile())})-- with pytest.raises(TypeError, match="expected object dependency of type 'Profile'"):- layer.tools---def public_greet(topic: str) -> str:- return f"Ada: {topic}"---def test_dynamic_tools_layer_binds_object_as_pydantic_ai_equivalent_tool() -> None:- layer = DynamicToolsLayer[Profile](tool_entries=(greet,))- layer.bind_deps({"object_layer": ObjectLayer[Profile](Profile("Ada"))})-- expected_tool = Tool(public_greet, name="greet")- dynamic_tool = Tool(layer.tools[0], name="greet")- dynamic_result = asyncio.run(- dynamic_tool.function_schema.call(- {"topic": "layer composition"},- None, # pyright: ignore[reportArgumentType]- )- )- expected_result = asyncio.run(- expected_tool.function_schema.call(- {"topic": "layer composition"},- None, # pyright: ignore[reportArgumentType]- )- )-- assert dynamic_tool.tool_def == expected_tool.tool_def- assert dynamic_result == expected_resultdiff --git a/dify-agent/tests/local/agenton_collections/layers/pydantic_ai/test_bridge.py b/dify-agent/tests/local/agenton_collections/layers/pydantic_ai/test_bridge.pydeleted file mode 100644index 12a93959de3..00000000000--- a/dify-agent/tests/local/agenton_collections/layers/pydantic_ai/test_bridge.py+++ /dev/null@@ -1,56 +0,0 @@-from collections.abc import Callable-from dataclasses import dataclass-from typing import cast--from pydantic_ai import RunContext, Tool--from agenton_collections.layers.pydantic_ai import PydanticAIBridgeLayer---@dataclass(frozen=True, slots=True)-class Profile:- name: str---def profile_prompt(ctx: RunContext[Profile]) -> str:- return f"Profile: {ctx.deps.name}"---def existing_tool(ctx: RunContext[Profile]) -> str:- return ctx.deps.name---def raw_tool(ctx: RunContext[Profile], topic: str) -> str:- return f"{ctx.deps.name}: {topic}"---def test_pydantic_ai_bridge_layer_accepts_mixed_string_and_function_prompts() -> None:- layer = PydanticAIBridgeLayer[Profile](- prefix=("plain prefix", profile_prompt),- user=("first user", "second user"),- suffix="plain suffix",- )-- prefix_prompts = layer.prefix_prompts- user_prompts = layer.user_prompts- suffix_prompts = layer.suffix_prompts-- plain_prefix = cast(Callable[[], str], prefix_prompts[0])- plain_suffix = cast(Callable[[], str], suffix_prompts[0])- assert plain_prefix() == "plain prefix"- assert prefix_prompts[1] is profile_prompt- assert user_prompts == ["first user", "second user"]- assert plain_suffix() == "plain suffix"---def test_pydantic_ai_bridge_layer_accepts_mixed_tool_and_tool_function_entries() -> None:- pydantic_ai_tool = Tool(existing_tool)- layer = PydanticAIBridgeLayer[Profile](- tool_entries=(pydantic_ai_tool, raw_tool),- )-- tools = layer.tools-- assert tools[0] is pydantic_ai_tool- assert isinstance(tools[1], Tool)- assert tools[1].function is raw_tooldiff --git a/dify-agent/tests/local/agenton_collections/layers/pydantic_ai/test_history.py b/dify-agent/tests/local/agenton_collections/layers/pydantic_ai/test_history.pydeleted file mode 100644index fbe1405f534..00000000000--- a/dify-agent/tests/local/agenton_collections/layers/pydantic_ai/test_history.py+++ /dev/null@@ -1,96 +0,0 @@-import asyncio--from pydantic_ai.messages import ModelMessage, ModelRequest, ModelResponse, TextPart, UserPromptPart--from agenton.compositor import Compositor, LayerNode-from agenton.layers import LifecycleState-from agenton_collections.layers.pydantic_ai import PydanticAIHistoryLayer, PydanticAIHistoryRuntimeState---def test_pydantic_ai_history_layer_starts_empty_and_contributes_no_prompts_or_tools() -> None:- layer = PydanticAIHistoryLayer()-- assert layer.message_history == []- assert list(layer.prefix_prompts) == []- assert list(layer.suffix_prompts) == []- assert list(layer.user_prompts) == []- assert list(layer.tools) == []---def test_pydantic_ai_history_layer_replace_messages_saves_validated_copy() -> None:- layer = PydanticAIHistoryLayer()- messages = _sample_messages()-- layer.replace_messages(messages)- borrowed_messages = layer.message_history-- assert borrowed_messages == messages- assert borrowed_messages is not messages-- messages.append(ModelResponse(parts=[TextPart(content="later")]))- assert layer.message_history != messages---def test_pydantic_ai_history_layer_append_messages_preserves_order_and_internal_state() -> None:- layer = PydanticAIHistoryLayer()- request, response = _sample_messages()-- layer.replace_messages([request])- layer.append_messages((response,))-- borrowed_messages = layer.message_history- borrowed_messages.clear()-- assert layer.message_history == [request, response]---def test_pydantic_ai_history_layer_clear_removes_stored_messages() -> None:- layer = PydanticAIHistoryLayer()-- layer.replace_messages(_sample_messages())- layer.clear()-- assert layer.message_history == []- assert layer.runtime_state.messages == []---def test_pydantic_ai_history_runtime_state_round_trips_through_json_dump() -> None:- messages = _sample_messages()- runtime_state = PydanticAIHistoryRuntimeState(messages=messages)-- dumped_state = runtime_state.model_dump(mode="json")- restored_state = PydanticAIHistoryRuntimeState.model_validate(dumped_state)-- assert restored_state.messages == messages- assert isinstance(restored_state.messages[0], ModelRequest)- assert isinstance(restored_state.messages[1], ModelResponse)---def test_pydantic_ai_history_layer_messages_round_trip_through_session_snapshot() -> None:- compositor = Compositor([LayerNode("history", PydanticAIHistoryLayer)])- messages = _sample_messages()-- async def scenario() -> None:- async with compositor.enter() as first_run:- history_layer = first_run.get_layer("history", PydanticAIHistoryLayer)- history_layer.replace_messages(messages)- first_run.suspend_on_exit()-- assert first_run.session_snapshot is not None- assert first_run.session_snapshot.layers[0].lifecycle_state is LifecycleState.SUSPENDED-- async with compositor.enter(session_snapshot=first_run.session_snapshot) as resumed_run:- history_layer = resumed_run.get_layer("history", PydanticAIHistoryLayer)-- assert history_layer.message_history == messages- assert isinstance(history_layer.runtime_state.messages[0], ModelRequest)- assert isinstance(history_layer.runtime_state.messages[1], ModelResponse)-- asyncio.run(scenario())---def _sample_messages() -> list[ModelMessage]:- return [- ModelRequest(parts=[UserPromptPart(content="Hello")]),- ModelResponse(parts=[TextPart(content="Hi there")]),- ]diff --git a/dify-agent/tests/local/agenton_collections/transformers/test_pydantic_ai.py b/dify-agent/tests/local/agenton_collections/transformers/test_pydantic_ai.pydeleted file mode 100644index 4ff49b1e1a3..00000000000--- a/dify-agent/tests/local/agenton_collections/transformers/test_pydantic_ai.py+++ /dev/null@@ -1,85 +0,0 @@-from collections.abc import Callable-from typing import cast--from pydantic_ai import Tool--from agenton.layers.types import (- PlainPromptType,- PlainToolType,- PlainUserPromptType,- PydanticAIPromptType,- PydanticAIToolType,- PydanticAIUserPromptType,-)-from agenton_collections.transformers.pydantic_ai import PYDANTIC_AI_TRANSFORMERS---def plain_tool(name: str) -> str:- return f"hello {name}"---def dynamic_prompt() -> str:- return "dynamic prompt"---def test_pydantic_ai_transformers_wrap_tagged_plain_prompts() -> None:- prompts = [PlainPromptType("plain prompt")]-- result = PYDANTIC_AI_TRANSFORMERS["prompt_transformer"](prompts)-- assert len(result) == 1- prompt_func = cast(Callable[[], str], result[0])- assert prompt_func() == "plain prompt"---def test_pydantic_ai_transformers_preserve_tagged_existing_prompt_functions() -> None:- result = PYDANTIC_AI_TRANSFORMERS["prompt_transformer"]([PydanticAIPromptType(dynamic_prompt)])-- assert result == [dynamic_prompt]---def test_pydantic_ai_transformers_accept_mixed_tagged_prompt_types() -> None:- result = PYDANTIC_AI_TRANSFORMERS["prompt_transformer"](- [PlainPromptType("plain prompt"), PydanticAIPromptType(dynamic_prompt)]- )-- plain_prompt = cast(Callable[[], str], result[0])- assert plain_prompt() == "plain prompt"- assert result[1] is dynamic_prompt---def test_pydantic_ai_transformers_accept_tagged_user_prompt_types() -> None:- result = PYDANTIC_AI_TRANSFORMERS["user_prompt_transformer"](- [PlainUserPromptType("plain user"), PydanticAIUserPromptType("pydantic user")]- )-- assert result == ["plain user", "pydantic user"]---def test_pydantic_ai_transformers_wrap_tagged_plain_tools() -> None:- result = PYDANTIC_AI_TRANSFORMERS["tool_transformer"]([PlainToolType(plain_tool)])-- assert len(result) == 1- tool = result[0]- assert isinstance(tool, Tool)- assert tool.function is plain_tool---def test_pydantic_ai_transformers_preserve_tagged_existing_tools() -> None:- pydantic_ai_tool = Tool(plain_tool)-- result = PYDANTIC_AI_TRANSFORMERS["tool_transformer"]([PydanticAIToolType(pydantic_ai_tool)])-- assert result == [pydantic_ai_tool]---def test_pydantic_ai_transformers_accept_tagged_tool_types() -> None:- pydantic_ai_tool = Tool(plain_tool)-- result = PYDANTIC_AI_TRANSFORMERS["tool_transformer"](- [PlainToolType(plain_tool), PydanticAIToolType(pydantic_ai_tool)]- )-- assert isinstance(result[0], Tool)- assert result[0].function is plain_tool- assert result[1] is pydantic_ai_tooldiff --git a/dify-agent/tests/local/dify_agent/client/test_client.py b/dify-agent/tests/local/dify_agent/client/test_client.pyindex 3f2a4001786..c1bddce04e3 100644--- a/dify-agent/tests/local/dify_agent/client/test_client.py+++ b/dify-agent/tests/local/dify_agent/client/test_client.py@@ -9,8 +9,7 @@ from typing import cast, overrideimport httpximport pytest-from agenton.compositor import CompositorSessionSnapshot-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID+from dify_agent.protocol.snapshot import SessionSnapshotfrom dify_agent.layers.execution_context import DifyExecutionContextLayerConfigfrom dify_agent.client import _client as client_modulefrom dify_agent.client import (@@ -48,8 +47,8 @@ from dify_agent.protocol import (def _create_run_payload() -> dict[str, object]:return {"composition": {- "schema_version": 1,- "layers": [{"name": "prompt", "type": PLAIN_PROMPT_LAYER_TYPE_ID, "config": {"user": "hello"}}],+ "schema_version": 2,+ "layers": [{"name": "prompt", "config": {"user": "hello"}}],}}@@ -67,7 +66,7 @@ def _run_succeeded_event(*, event_id: str = "2-0", run_id: str = "run-1") -> Runreturn RunSucceededEvent(id=event_id,run_id=run_id,- data=RunSucceededEventData(output="done", session_snapshot=CompositorSessionSnapshot(layers=[])),+ data=RunSucceededEventData(output="done", session_snapshot=SessionSnapshot(layers={})),)@@ -247,7 +246,7 @@ def test_async_methods_and_wait_run_parse_protocol_dtos() -> None:def test_cancel_run_and_wait_sync_resumes_after_cursor_and_returns_cancelled_snapshot() -> None:- snapshot = CompositorSessionSnapshot(layers=[])+ snapshot = SessionSnapshot(layers={})def handler(request: httpx.Request) -> httpx.Response:if request.method == "POST":diff --git a/dify-agent/tests/local/dify_agent/layers/ask_human/test_configs.py b/dify-agent/tests/local/dify_agent/layers/ask_human/test_configs.pydeleted file mode 100644index f9b42220e03..00000000000--- a/dify-agent/tests/local/dify_agent/layers/ask_human/test_configs.py+++ /dev/null@@ -1,73 +0,0 @@-import pytest-from pydantic import ValidationError--import dify_agent.layers.ask_human as ask_human_exports-from dify_agent.layers.ask_human import DIFY_ASK_HUMAN_LAYER_TYPE_ID, DifyAskHumanLayerConfig-from dify_agent.layers.ask_human.schema import AskHumanToolArgs---def test_ask_human_package_exports_client_safe_symbols_only() -> None:- assert ask_human_exports.DIFY_ASK_HUMAN_LAYER_TYPE_ID == "dify.ask_human"- assert ask_human_exports.__all__ == [- "AskHumanAction",- "AskHumanActionStyle",- "AskHumanField",- "AskHumanFieldType",- "AskHumanFileField",- "AskHumanFileListField",- "AskHumanParagraphField",- "AskHumanResultStatus",- "AskHumanSelectField",- "AskHumanSelectOption",- "AskHumanSelectedAction",- "AskHumanToolArgs",- "AskHumanToolResult",- "AskHumanUrgency",- "DEFAULT_ASK_HUMAN_TOOL_DESCRIPTION",- "DIFY_ASK_HUMAN_LAYER_TYPE_ID",- "DifyAskHumanLayerConfig",- ]- assert not hasattr(ask_human_exports, "DifyAskHumanLayer")---def test_ask_human_layer_config_defaults_and_effective_description() -> None:- config = DifyAskHumanLayerConfig()-- assert DIFY_ASK_HUMAN_LAYER_TYPE_ID == "dify.ask_human"- assert config.model_dump(mode="json") == {- "enabled": True,- "tool_name": "ask_human",- "tool_description": None,- "max_fields": 8,- "max_actions": 4,- "allowed_field_types": ["paragraph", "select"],- "allow_file_fields": False,- "max_markdown_chars": 8000,- "max_question_chars": 1000,- "max_field_label_chars": 120,- "max_action_label_chars": 80,- }- assert "Ask a human for missing information" in config.effective_tool_description---def test_ask_human_layer_config_rejects_invalid_tool_name() -> None:- with pytest.raises(ValidationError, match="tool_name must be a valid tool identifier"):- _ = DifyAskHumanLayerConfig(tool_name="ask-human")---def test_ask_human_layer_config_rejects_file_field_types_when_disabled() -> None:- with pytest.raises(ValidationError, match="cannot include file field types"):- _ = DifyAskHumanLayerConfig(allowed_field_types=["paragraph", "file"])---def test_ask_human_tool_args_reject_duplicate_field_names() -> None:- with pytest.raises(ValidationError, match="field name 'comment' must be unique"):- _ = AskHumanToolArgs.model_validate(- {- "question": "Need a reply",- "fields": [- {"type": "paragraph", "name": "comment", "label": "Comment"},- {"type": "paragraph", "name": "comment", "label": "Another comment"},- ],- }- )diff --git a/dify-agent/tests/local/dify_agent/layers/ask_human/test_layer.py b/dify-agent/tests/local/dify_agent/layers/ask_human/test_layer.pydeleted file mode 100644index 903a3164a01..00000000000--- a/dify-agent/tests/local/dify_agent/layers/ask_human/test_layer.py+++ /dev/null@@ -1,152 +0,0 @@-import asyncio-import inspect-from collections.abc import Awaitable-from typing import Any, cast--import pytest-from pydantic_ai.messages import ToolCallPart-from pydantic_ai.tools import DeferredToolRequests, ToolDefinition--from dify_agent.layers.ask_human import DifyAskHumanLayerConfig-from dify_agent.layers.ask_human.schema import AskHumanToolArgs-from dify_agent.layers.ask_human.layer import DifyAskHumanLayer---async def _await_tool_definition(value: Awaitable[ToolDefinition | None]) -> ToolDefinition | None:- return await value---def test_ask_human_layer_exposes_one_external_tool_and_prompt_hint() -> None:- config = DifyAskHumanLayerConfig(- tool_name="human_gate",- tool_description="Collect a human decision.",- max_fields=2,- max_actions=3,- allowed_field_types=["paragraph"],- allow_file_fields=False,- max_question_chars=240,- max_markdown_chars=512,- max_field_label_chars=32,- max_action_label_chars=16,- )- layer = DifyAskHumanLayer.from_config(config)-- prompt_hint = layer.build_prompt_hint()- tool = layer.tools[0]- prepare = tool.prepare- assert prepare is not None- prepared_or_awaitable = prepare(- cast(Any, None),- ToolDefinition(- name=tool.name, description=tool.description, parameters_json_schema=tool.function_schema.json_schema- ),- )- prepared = (- asyncio.run(_await_tool_definition(cast(Awaitable[ToolDefinition | None], prepared_or_awaitable)))- if inspect.isawaitable(prepared_or_awaitable)- else prepared_or_awaitable- )-- assert len(layer.prefix_prompts) == 1- assert len(layer.tools) == 1- assert "Allowed field types: paragraph." in prompt_hint- assert "File upload fields are disabled." in prompt_hint- assert "Use at most 2 field(s)." in prompt_hint- assert "Use at most 3 action(s)." in prompt_hint- assert "Keep 'question' under 240 characters." in prompt_hint- assert "Keep 'markdown' under 512 characters." in prompt_hint- assert "Keep each field label under 32 characters." in prompt_hint- assert "Keep each action label under 16 characters." in prompt_hint- assert prepared is not None- assert prepared.name == "human_gate"- assert prepared.description == "Collect a human decision."- assert prepared.kind == "external"- assert prepared.parameters_json_schema == AskHumanToolArgs.model_json_schema()---def test_ask_human_layer_normalizes_default_action_in_deferred_payload() -> None:- layer = DifyAskHumanLayer.from_config(DifyAskHumanLayerConfig())-- payload = layer.build_deferred_tool_call_payload(- DeferredToolRequests(- calls=[- ToolCallPart(- tool_name="ask_human",- args={- "question": "Need a human answer",- "fields": [{"type": "paragraph", "name": "comment", "label": "Comment"}],- },- tool_call_id="call-1",- )- ]- )- )-- assert payload.tool_call_id == "call-1"- assert payload.tool_name == "ask_human"- assert payload.args == {- "title": None,- "question": "Need a human answer",- "markdown": None,- "fields": [- {- "type": "paragraph",- "name": "comment",- "label": "Comment",- "required": False,- "placeholder": None,- "default": None,- }- ],- "actions": [{"id": "submit", "label": "Submit", "style": "primary"}],- "urgency": "normal",- }- assert payload.metadata == {- "layer_type": "dify.ask_human",- "tool_name": "ask_human",- "schema_version": 1,- }---def test_ask_human_layer_rejects_disallowed_field_types_in_deferred_payload() -> None:- layer = DifyAskHumanLayer.from_config(DifyAskHumanLayerConfig(allowed_field_types=["paragraph"]))-- with pytest.raises(ValueError, match="field type 'select' is not allowed"):- _ = layer.build_deferred_tool_call_payload(- DeferredToolRequests(- calls=[- ToolCallPart(- tool_name="ask_human",- args={- "question": "Need a choice",- "fields": [- {- "type": "select",- "name": "decision",- "label": "Decision",- "options": [{"value": "yes", "label": "Yes"}],- }- ],- },- tool_call_id="call-2",- )- ]- )- )---def test_ask_human_layer_rejects_tool_name_mismatch_in_deferred_payload() -> None:- layer = DifyAskHumanLayer.from_config(DifyAskHumanLayerConfig(tool_name="human_gate"))-- with pytest.raises(ValueError, match="deferred tool name must be 'human_gate', got 'ask_human'"):- _ = layer.build_deferred_tool_call_payload(- DeferredToolRequests(- calls=[- ToolCallPart(- tool_name="ask_human",- args={"question": "Need a human answer"},- tool_call_id="call-3",- )- ]- )- )diff --git a/dify-agent/tests/local/dify_agent/layers/config/test_layer.py b/dify-agent/tests/local/dify_agent/layers/config/test_layer.pyindex c66f0c88a47..1190b861df6 100644--- a/dify-agent/tests/local/dify_agent/layers/config/test_layer.py+++ b/dify-agent/tests/local/dify_agent/layers/config/test_layer.py@@ -1,257 +1,88 @@-"""Behavior tests for the runtime Dify config layer."""--from __future__ import annotations+"""Config pre-pulls run inside Shell and persist only completed initialization."""import json-from typing import Literal+import httpximport pytest-from dify_agent.layers.config import DifyConfigLayerConfig-from dify_agent.layers.config.layer import (- DifyConfigLayer,- DifyConfigLayerError,- _AGENT_FILE_UPLOAD_REPLY_HINT,-)-from dify_agent.layers.shell import DifyShellLayerConfig-from dify_agent.layers.shell.layer import CompleteRemoteCommandResult, DifyShellLayer---def _shell_layer() -> DifyShellLayer:- return DifyShellLayer.from_config_with_settings(- DifyShellLayerConfig(),- )---def _build_layer(*, writable: bool = True) -> DifyConfigLayer:- layer = DifyConfigLayer.from_config(- DifyConfigLayerConfig.model_validate(- {- "agent_id": "agent-1",- "config_version": {"id": "cfg-1", "kind": "build_draft", "writable": writable},- "skills": [{"name": "runtime-skill", "description": "Runtime skill."}],- "files": [{"name": "runtime-file.txt"}],- "env_keys": ["RUNTIME_KEY"],- "note": "Runtime note.",- "mentioned_skill_names": ["alpha"],- "mentioned_file_names": ["guide.txt"],- }- )- )- layer.bind_deps({"shell": _shell_layer()})- return layer---def _remote_result(- output: str,- *,- exit_code: int | None = 0,- output_complete: bool = True,- incomplete_reason: Literal["output_limit", "timeout"] | None = None,-) -> CompleteRemoteCommandResult:- return CompleteRemoteCommandResult(- job_id="remote-config-pull",- status="exited",- done=True,- exit_code=exit_code,- output=output,- output_complete=output_complete,- incomplete_reason=incomplete_reason,- offset=len(output),- output_path="/tmp/config-pull-output.log",- )---def _skill_pull_output(*names: str, include_skill: bool = True) -> str:- items = []- if include_skill:- items = [- {- "name": name,- "archive_path": f"/workspace/.dify_conf/skills/{name}.zip",- "directory_path": f"/workspace/.dify_conf/skills/{name}",- "skill_md": "# Alpha\nUse it.\n",- }- for name in names or ("alpha",)- ]- return json.dumps({"items": items})---def _file_pull_output(*names: str, include_file: bool = True) -> str:- items = []- if include_file:- items = [{"name": name, "path": f"/workspace/.dify_conf/files/{name}"} for name in names or ("guide.txt",)]- return json.dumps({"items": items})---def test_build_shell_pull_scripts_include_targets() -> None:- layer = _build_layer()-- skill_script = layer._build_shell_skill_pull_script(["alpha", "skill with space"])- file_script = layer._build_shell_file_pull_script(["guide.txt", "file with space.txt"])-- assert skill_script == "set -eu\ndify-agent config skills pull --json alpha 'skill with space'"- assert file_script == "set -eu\ndify-agent config files pull --json guide.txt 'file with space.txt'"---async def test_on_context_create_computes_runtime_fields_and_pulls_mentioned_assets_in_batches(- monkeypatch: pytest.MonkeyPatch,-) -> None:- layer = _build_layer()- captured_scripts: list[str] = []- active_commands = 0- max_active_commands = 0-- async def fake_run_remote_script(self, script: str, *, inject_agent_stub_env: bool = False, timeout: float = 10.0):- nonlocal active_commands, max_active_commands- del self, timeout- assert inject_agent_stub_env is True- assert "--help" not in script- assert "dify-agent config manifest" not in script- captured_scripts.append(script)- active_commands += 1- max_active_commands = max(max_active_commands, active_commands)- active_commands -= 1- if "skills pull" in script:- return _remote_result(_skill_pull_output())- if "files pull" in script:- return _remote_result(_file_pull_output())- raise AssertionError(f"unexpected script: {script}")-- monkeypatch.setattr(DifyShellLayer, "run_remote_script", fake_run_remote_script)-- await layer.on_context_create()-- assert max_active_commands == 1- assert len(captured_scripts) == 2- assert captured_scripts == [- "set -eu\ndify-agent config skills pull --json alpha",- "set -eu\ndify-agent config files pull --json guide.txt",- ]- assert layer.runtime_state.pulled_skill_outputs == {"alpha": "/workspace/.dify_conf/skills/alpha\n# Alpha\nUse it."}- assert layer.runtime_state.pulled_file_outputs == {"guide.txt": "/workspace/.dify_conf/files/guide.txt"}- assert "dify-agent config note push --help" in layer.runtime_state.config_cli_help- assert "dify-agent file upload --help" in layer.runtime_state.config_cli_help- assert "dify-agent file public-url --help" in layer.runtime_state.config_cli_help- assert "dify-agent file download --help" in layer.runtime_state.config_cli_help- assert layer.runtime_state.push_spec_json_schema == ""- suffix_prompt = layer.build_suffix_prompt()- assert suffix_prompt.index("Agent config CLI reference for installed `dify-agent`:") < suffix_prompt.index(- "Agent file CLI reference for installed `dify-agent`:"- )- assert "$ dify-agent file upload --help" in suffix_prompt- assert "$ dify-agent file public-url --help" in suffix_prompt- assert "$ dify-agent file download --help" in suffix_prompt- assert suffix_prompt.index("$ dify-agent file upload --help") < suffix_prompt.index(- "$ dify-agent file public-url --help"- )- assert suffix_prompt.index("$ dify-agent file public-url --help") < suffix_prompt.index(- "$ dify-agent file download --help"- )- assert _AGENT_FILE_UPLOAD_REPLY_HINT in suffix_prompt+from dify_agent.adapters.shell.protocols import CompleteShellCommandResult+from dify_agent.layers.config import layer as config_module+from dify_agent.layers.shell.layer import ShellSession+from dify_agent.protocol.schemas import RunLayerSpec+from dify_agent.runtime.context import Services+from dify_agent.runtime_backend import RuntimeBackendProfile+from tests.local.dify_agent.runtime.test_runner import Backend, Commands, request, run_runner, runtime_specs@pytest.mark.anyio-async def test_on_context_create_batches_all_mentioned_assets_into_two_serial_jobs(- monkeypatch: pytest.MonkeyPatch,-) -> None:- layer = _build_layer()- layer.config = layer.config.model_copy(- update={- "mentioned_skill_names": [f"skill-{index}" for index in range(4)],- "mentioned_file_names": [f"file-{index}.txt" for index in range(4)],- }- )- captured_scripts: list[str] = []-- async def fake_run_remote_script(self, script: str, *, inject_agent_stub_env: bool = False, timeout: float = 10.0):- del self, timeout- assert inject_agent_stub_env is True- captured_scripts.append(script)- if "skills pull" in script:- return _remote_result(_skill_pull_output(*(f"skill-{index}" for index in range(4))))- return _remote_result(_file_pull_output(*(f"file-{index}.txt" for index in range(4))))-- monkeypatch.setattr(DifyShellLayer, "run_remote_script", fake_run_remote_script)-- await layer.on_context_create()-- assert captured_scripts == [- "set -eu\ndify-agent config skills pull --json skill-0 skill-1 skill-2 skill-3",- "set -eu\ndify-agent config files pull --json file-0.txt file-1.txt file-2.txt file-3.txt",- ]- assert set(layer.runtime_state.pulled_skill_outputs) == {f"skill-{index}" for index in range(4)}- assert set(layer.runtime_state.pulled_file_outputs) == {f"file-{index}.txt" for index in range(4)}---async def test_on_context_resume_does_not_recompute_or_pull(monkeypatch: pytest.MonkeyPatch) -> None:- layer = _build_layer()- layer.runtime_state.config_context_json = "cached"- layer.runtime_state.config_cli_help = {"cached": "help"}-- async def fail_run_remote_script(self, script: str, *, inject_agent_stub_env: bool = False, timeout: float = 10.0):- del self, script, inject_agent_stub_env, timeout- raise AssertionError("resume must not run config shell commands")-- monkeypatch.setattr(DifyShellLayer, "run_remote_script", fail_run_remote_script)-- await layer.on_context_resume()-- assert layer.runtime_state.config_context_json == "cached"- assert layer.runtime_state.config_cli_help == {"cached": "help"}---async def test_on_context_create_raises_when_shell_output_is_truncated(- monkeypatch: pytest.MonkeyPatch,-) -> None:- layer = _build_layer()-- async def fake_run_remote_script(self, script: str, *, inject_agent_stub_env: bool = False, timeout: float = 10.0):- del self, inject_agent_stub_env, timeout- if "skills pull" in script:- return _remote_result(_skill_pull_output(), output_complete=False, incomplete_reason="output_limit")- return _remote_result(_file_pull_output())-- monkeypatch.setattr(DifyShellLayer, "run_remote_script", fake_run_remote_script)-- with pytest.raises(DifyConfigLayerError, match="output was incomplete"):- await layer.on_context_create()---async def test_on_context_create_raises_when_mentioned_skill_is_missing(- monkeypatch: pytest.MonkeyPatch,-) -> None:- layer = _build_layer()-- async def fake_run_remote_script(self, script: str, *, inject_agent_stub_env: bool = False, timeout: float = 10.0):- del self, inject_agent_stub_env, timeout- if "skills pull" in script:- return _remote_result(_skill_pull_output(include_skill=False))- return _remote_result(_file_pull_output())-- monkeypatch.setattr(DifyShellLayer, "run_remote_script", fake_run_remote_script)-- with pytest.raises(DifyConfigLayerError, match="missing pull output"):- await layer.on_context_create()---async def test_on_context_create_raises_when_mentioned_file_is_missing(- monkeypatch: pytest.MonkeyPatch,-) -> None:- layer = _build_layer()-- async def fake_run_remote_script(self, script: str, *, inject_agent_stub_env: bool = False, timeout: float = 10.0):- del self, inject_agent_stub_env, timeout- if "skills pull" in script:- return _remote_result(_skill_pull_output())- return _remote_result(_file_pull_output(include_file=False))-- monkeypatch.setattr(DifyShellLayer, "run_remote_script", fake_run_remote_script)+async def test_first_pull_failure_retries_then_current_config_refreshes_without_repull(monkeypatch):+ commands = Commands()+ backend = Backend(commands)+ pulls = []+ fail = True++ async def pull(session, script, **kwargs):+ assert backend.active+ assert kwargs["inject_agent_stub_env"] is True+ pulls.append(script)+ output = (+ ""+ if fail+ else json.dumps(+ {"items": [{"name": "skill", "directory_path": "/skills/skill", "skill_md": "Instructions from skill"}]}+ )+ )+ return CompleteShellCommandResult("pull", "exited", True, 1 if fail else 0, output, True, None, len(output))++ monkeypatch.setattr(ShellSession, "run_remote_script", pull)+ seen_instructions = []++ async def stream(messages, info):+ assert "Instructions from skill" in info.instructions+ seen_instructions.append(info.instructions)+ yield "done"++ def spec(note, *, writable=False):+ return RunLayerSpec(+ name="config",+ config={+ "mentioned_skill_names": ["skill"],+ "note": note,+ "config_version": {"kind": "build_draft" if writable else "snapshot", "writable": writable},+ },+ )- with pytest.raises(DifyConfigLayerError, match="missing pull output"):- await layer.on_context_create()+ async with httpx.AsyncClient() as client:+ services = Services(client, client, runtime_backend_profile=RuntimeBackendProfile(None, backend))+ # Config precedes both resources in the submitted list; native ordering owns entry.+ first, _ = run_runner(request(spec("original"), *runtime_specs()), services, monkeypatch, stream)+ with pytest.raises(config_module.DifyConfigLayerError):+ await first.run()+ assert first.terminal_session_snapshot.layers["config"]["initialized"] is False+ assert backend.released == 1+ fail = False+ second, _ = run_runner(+ request(spec("original"), *runtime_specs(), snapshot=first.terminal_session_snapshot),+ services,+ monkeypatch,+ stream,+ run_id="second",+ )+ await second.run()+ assert second.terminal_session_snapshot.layers["config"]["initialized"] is True+ third, _ = run_runner(+ request(spec("revised", writable=True), *runtime_specs(), snapshot=second.terminal_session_snapshot),+ services,+ monkeypatch,+ stream,+ run_id="third",+ )+ await third.run()+ assert len(pulls) == 2+ assert backend.acquired == backend.released == 3+ state = third.terminal_session_snapshot.layers["config"]+ assert "original" in seen_instructions[0] and "revised" in seen_instructions[1]+ assert "dify-agent config env push --help" not in seen_instructions[0]+ assert "dify-agent config env push --help" in seen_instructions[1]+ assert set(state) == {"initialized", "pulled_skill_outputs", "pulled_file_outputs"}+ assert "Instructions from skill" in state["pulled_skill_outputs"]["skill"]diff --git a/dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_configs.py b/dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_configs.pyindex 8e795112853..42451428021 100644--- a/dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_configs.py+++ b/dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_configs.py@@ -1,62 +1,32 @@import pytestfrom pydantic import ValidationError-import dify_agent.layers.dify_core_tools as dify_core_tools_exportsfrom dify_agent.layers.dify_core_tools import DifyCoreToolConfig, DifyCoreToolsLayerConfigdef test_dify_core_tools_package_exports_client_safe_config_symbols_only() -> None:assert dify_core_tools_exports.__all__ == [- "DIFY_CORE_TOOLS_LAYER_TYPE_ID","DifyCoreToolConfig","DifyCoreToolProviderType","DifyCoreToolsLayerConfig",]- assert dify_core_tools_exports.DIFY_CORE_TOOLS_LAYER_TYPE_ID == "dify.core.tools"def test_dify_core_tools_layer_config_accepts_supported_provider_types() -> None:config = DifyCoreToolsLayerConfig.model_validate({"tools": [- {- "provider_type": "plugin",- "provider_id": "langgenius/search/search",- "tool_name": "search",- },- {- "provider_type": "builtin",- "provider_id": "audio",- "tool_name": "transcribe",- },- {- "provider_type": "api",- "provider_id": "weather",- "tool_name": "forecast",- },- {- "provider_type": "workflow",- "provider_id": "workflow-tool",- "tool_name": "run_workflow",- },- {- "provider_type": "mcp",- "provider_id": "server-1",- "tool_name": "search_docs",- },+ {"provider_type": "plugin", "provider_id": "langgenius/search/search", "tool_name": "search"},+ {"provider_type": "builtin", "provider_id": "audio", "tool_name": "transcribe"},+ {"provider_type": "api", "provider_id": "weather", "tool_name": "forecast"},+ {"provider_type": "workflow", "provider_id": "workflow-tool", "tool_name": "run_workflow"},+ {"provider_type": "mcp", "provider_id": "server-1", "tool_name": "search_docs"},]})-assert [tool.provider_type for tool in config.tools] == ["plugin", "builtin", "api", "workflow", "mcp"]def test_dify_core_tool_config_rejects_unsupported_provider_types() -> None:with pytest.raises(ValidationError, match="provider_type"):- _ = DifyCoreToolConfig.model_validate(- {- "provider_type": "app",- "provider_id": "app-tool",- "tool_name": "run",- }- )+ _ = DifyCoreToolConfig.model_validate({"provider_type": "app", "provider_id": "app-tool", "tool_name": "run"})diff --git a/dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_layer.py b/dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_layer.pyindex f5813c0f7f8..2fe15eb5f03 100644--- a/dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_layer.py+++ b/dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_layer.py@@ -1,290 +1,88 @@-import asyncio-import sys-import types+"""Core tools retain their prepared schemas and API-owned credentials."""++import jsonimport httpximport pytest-from agenton.compositor import Compositor, LayerNode, LayerProvider---def _install_graphon_stubs() -> None:- if "graphon.model_runtime.entities.llm_entities" in sys.modules:- return-- graphon_module = types.ModuleType("graphon")- model_runtime_module = types.ModuleType("graphon.model_runtime")- entities_module = types.ModuleType("graphon.model_runtime.entities")- llm_entities_module = types.ModuleType("graphon.model_runtime.entities.llm_entities")- message_entities_module = types.ModuleType("graphon.model_runtime.entities.message_entities")-- setattr(llm_entities_module, "LLMResultChunk", type("LLMResultChunk", (), {}))- setattr(llm_entities_module, "LLMUsage", type("LLMUsage", (), {}))-- for name in (- "AssistantPromptMessage",- "AudioPromptMessageContent",- "DocumentPromptMessageContent",- "ImagePromptMessageContent",- "PromptMessage",- "PromptMessageContentUnionTypes",- "PromptMessageTool",- "SystemPromptMessage",- "TextPromptMessageContent",- "ToolPromptMessage",- "UserPromptMessage",- "VideoPromptMessageContent",- ):- setattr(message_entities_module, name, type(name, (), {}))-- sys.modules["graphon"] = graphon_module- sys.modules["graphon.model_runtime"] = model_runtime_module- sys.modules["graphon.model_runtime.entities"] = entities_module- sys.modules["graphon.model_runtime.entities.llm_entities"] = llm_entities_module- sys.modules["graphon.model_runtime.entities.message_entities"] = message_entities_module-- setattr(graphon_module, "model_runtime", model_runtime_module)- setattr(model_runtime_module, "entities", entities_module)- setattr(entities_module, "llm_entities", llm_entities_module)- setattr(entities_module, "message_entities", message_entities_module)---_install_graphon_stubs()--from dify_agent.layers.dify_core_tools.configs import DifyCoreToolConfig, DifyCoreToolsLayerConfig # noqa: E402-from dify_agent.layers.dify_core_tools.layer import DifyCoreToolsLayer # noqa: E402-from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig # noqa: E402-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer # noqa: E402---def _execution_context_provider() -> LayerProvider[DifyExecutionContextLayer]:- return LayerProvider.from_factory(- layer_type=DifyExecutionContextLayer,- create=lambda config: DifyExecutionContextLayer.from_config_with_settings(- DifyExecutionContextLayerConfig.model_validate(config),- daemon_url="http://plugin-daemon",- daemon_api_key="daemon-secret",- ),- )---def _core_tools_provider() -> LayerProvider[DifyCoreToolsLayer]:- return LayerProvider.from_factory(- layer_type=DifyCoreToolsLayer,- create=lambda config: DifyCoreToolsLayer.from_config_with_settings(- DifyCoreToolsLayerConfig.model_validate(config),- inner_api_url="http://dify-api",- inner_api_key="inner-secret",- ),- )---def _execution_context_config() -> DifyExecutionContextLayerConfig:- return DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_id="user-1",- user_from="account",- app_id="app-1",- workflow_id="workflow-1",- workflow_run_id="workflow-run-1",- node_id="node-1",- node_execution_id="node-exec-1",- conversation_id="conversation-1",- agent_id="agent-1",- agent_config_version_id="snapshot-1",- agent_mode="workflow_run",- invoke_from="service-api",- )---def test_core_tools_layer_exposes_pydantic_ai_tool_and_returns_inner_api_observation() -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("core_tools", _core_tools_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient(- transport=httpx.MockTransport(- lambda _request: httpx.Response(- 200,- json={- "messages": [{"type": "text", "message": {"text": "done"}}],- "observation": "done",- "metadata": {"provider_type": "builtin"},- },- )- )- ) as http_client:- async with compositor.enter(- configs={- "execution_context": _execution_context_config(),- "core_tools": DifyCoreToolsLayerConfig(- tools=[- DifyCoreToolConfig(- provider_type="builtin",- provider_id="audio",- tool_name="transcribe",- name="transcribe",- description="Transcribe audio.",- parameters=[],- parameters_json_schema={"type": "object", "properties": {}, "required": []},- )- ]- ),- }- ) as run:- layer = run.get_layer("core_tools", DifyCoreToolsLayer)- tool = (await layer.get_tools(http_client=http_client))[0]- result = await tool.function_schema.call({}, None) # pyright: ignore[reportArgumentType]- assert result == "done"-- asyncio.run(scenario())+from dify_agent.layers.dify_core_tools.layer import Config, Toolset+from dify_agent.layers.execution_context.configs import DifyExecutionContextLayerConfig+from dify_agent.runtime.context import Deps, Services+from tests.local.dify_agent.module_support import invoke_native_tool@pytest.mark.parametrize(- ("response", "expected"),+ "status,body,expected",[+ (200, {"observation": "completed", "messages": [], "metadata": {}}, "completed"),+ (429, {"code": "rate_limit", "message": "busy"}, "temporarily unavailable"),+ (404, {"code": "app_not_found", "message": "missing"}, "app context no longer exists"),+ (403, {"code": "app_tenant_mismatch", "message": "invalid"}, "app context is invalid"),+ (422, {"code": "agent_tool_credential_invalid", "message": "invalid"}, "check your tool provider credentials"),(- httpx.Response(404, json={"code": "app_not_found", "message": "App not found."}),- "Tool is unavailable because its app context no longer exists.",- ),- (- httpx.Response(403, json={"code": "app_tenant_mismatch", "message": "App does not belong to tenant."}),- "Tool is unavailable because its app context is invalid.",- ),- (- httpx.Response(404, json={"code": "agent_tool_declaration_not_found", "message": "tool missing"}),+ 404,+ {"code": "agent_tool_declaration_not_found", "message": "missing"},"there is not a tool named transcribe",),(- httpx.Response(- 422,- json={"code": "agent_tool_credential_invalid", "message": "credential region is required"},- ),- "Please check your tool provider credentials",- ),- (- httpx.Response(422, json={"code": "tool_parameters_invalid", "message": "query is required"}),- "tool parameters validation error: query is required, please check your tool parameters",- ),- (- httpx.Response(422, json={"code": "agent_tool_invoke_failed", "message": "workflow crashed"}),- "tool invoke error: workflow crashed",+ 422,+ {"code": "tool_parameters_invalid", "message": "query required"},+ "tool parameters validation error: query required",),],)-def test_core_tools_layer_maps_specific_inner_api_error_codes_to_observations(- response: httpx.Response,- expected: str,-) -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("core_tools", _core_tools_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient(transport=httpx.MockTransport(lambda _request: response)) as http_client:- async with compositor.enter(- configs={- "execution_context": _execution_context_config(),- "core_tools": DifyCoreToolsLayerConfig(- tools=[- DifyCoreToolConfig(- provider_type="builtin",- provider_id="audio",- tool_name="transcribe",- name="transcribe",- description="Transcribe audio.",- parameters=[],- parameters_json_schema={"type": "object", "properties": {}, "required": []},- )- ]- ),- }- ) as run:- layer = run.get_layer("core_tools", DifyCoreToolsLayer)- tool = (await layer.get_tools(http_client=http_client))[0]- result = await tool.function_schema.call({}, None) # pyright: ignore[reportArgumentType]- assert result == expected-- asyncio.run(scenario())---def test_core_tools_layer_reports_missing_execution_context_without_parameter_validation_text() -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("core_tools", _core_tools_provider(), deps={"execution_context": "execution_context"}),- ]+async def test_native_tool_preserves_schema_invocation_and_observations(status, body, expected):+ schema = {"type": "object", "properties": {"source": {"type": "string"}}, "required": ["source"]}+ config = Config(+ tools=[+ {+ "provider_type": "builtin",+ "provider_id": "audio",+ "tool_name": "transcribe",+ "credential_id": "credential",+ "runtime_parameters": {"region": "hidden"},+ "parameters_json_schema": schema,+ }+ ]+ )+ identity = DifyExecutionContextLayerConfig(+ tenant_id="tenant",+ user_id="user",+ user_from="account",+ app_id="app",+ agent_mode="agent_app",+ invoke_from="web-app",+ )+ sent = []++ def handler(request):+ assert request.url.path == "/inner/api/agent/tools/invoke"+ assert request.headers["X-Inner-Api-Key"] == "secret"+ sent.append(json.loads(request.content))+ return httpx.Response(status, json=body)++ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:+ deps = Deps(+ layers={+ "core_tools": {"config": config.model_dump(mode="json"), "state": {}},+ "execution_context": {"config": identity.model_dump(mode="json"), "state": {}},+ },+ services=Services(client, client, inner_api_key="secret"),+ run_id="test",)- async with httpx.AsyncClient(- transport=httpx.MockTransport(lambda _request: httpx.Response(200, json={"observation": "unused"}))- ) as http_client:- async with compositor.enter(- configs={- "execution_context": _execution_context_config().model_copy(update={"app_id": None}),- "core_tools": DifyCoreToolsLayerConfig(- tools=[- DifyCoreToolConfig(- provider_type="builtin",- provider_id="audio",- tool_name="transcribe",- name="transcribe",- description="Transcribe audio.",- parameters=[],- parameters_json_schema={"type": "object", "properties": {}, "required": []},- )- ]- ),- }- ) as run:- layer = run.get_layer("core_tools", DifyCoreToolsLayer)- tool = (await layer.get_tools(http_client=http_client))[0]- result = await tool.function_schema.call({}, None) # pyright: ignore[reportArgumentType]- assert result == "Tool is unavailable because required execution context is missing."-- asyncio.run(scenario())+ def inspect(info):+ tool = info.function_tools[0]+ assert tool.name == "transcribe"+ assert tool.parameters_json_schema == schema+ assert tool.strict is False- "response", [httpx.Response(429, json={"code": "knowledge_rate_limited"}), httpx.Response(502)]-)-def test_core_tools_layer_converts_retryable_failures_to_temporary_unavailable_observation(- response: httpx.Response,-) -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("core_tools", _core_tools_provider(), deps={"execution_context": "execution_context"}),- ]+ result = await invoke_native_tool(+ deps, Toolset("core_tools"), "transcribe", {"source": "audio.mp3"}, inspect=inspect)- async with httpx.AsyncClient(transport=httpx.MockTransport(lambda _request: response)) as http_client:- async with compositor.enter(- configs={- "execution_context": _execution_context_config(),- "core_tools": DifyCoreToolsLayerConfig(- tools=[- DifyCoreToolConfig(- provider_type="builtin",- provider_id="audio",- tool_name="transcribe",- name="transcribe",- description="Transcribe audio.",- parameters=[],- parameters_json_schema={"type": "object", "properties": {}, "required": []},- )- ]- ),- }- ) as run:- layer = run.get_layer("core_tools", DifyCoreToolsLayer)- tool = (await layer.get_tools(http_client=http_client))[0]- result = await tool.function_schema.call({}, None) # pyright: ignore[reportArgumentType]- assert result == "Tool is temporarily unavailable. Please continue without it if possible."-- asyncio.run(scenario())+ assert expected in result.output+ assert sent[0]["caller"]["tenant_id"] == "tenant"+ assert sent[0]["tool"]["runtime_parameters"] == {"region": "hidden"}+ assert sent[0]["tool"]["tool_parameters"] == {"source": "audio.mp3"}+ assert not client.is_closeddiff --git a/dify-agent/tests/local/dify_agent/layers/dify_plugin/test_configs.py b/dify-agent/tests/local/dify_agent/layers/dify_plugin/test_configs.pyindex 2f9f6880564..d10001c02b4 100644--- a/dify-agent/tests/local/dify_agent/layers/dify_plugin/test_configs.py+++ b/dify-agent/tests/local/dify_agent/layers/dify_plugin/test_configs.py@@ -1,8 +1,6 @@from types import SimpleNamespace-import pytestfrom pydantic import ValidationError-import dify_agent.layers.dify_plugin as dify_plugin_exportsfrom dify_agent.layers.dify_plugin import (DifyPluginLLMLayerConfig,@@ -18,8 +16,6 @@ from dify_agent.layers.dify_plugin import (def test_dify_plugin_package_exports_client_safe_config_symbols_only() -> None:assert dify_plugin_exports.__all__ == [- "DIFY_PLUGIN_LLM_LAYER_TYPE_ID",- "DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID","DifyPluginCredentialValue","DifyPluginLLMLayerConfig","DifyPluginToolCredentialType",@@ -31,8 +27,6 @@ def test_dify_plugin_package_exports_client_safe_config_symbols_only() -> None:"DifyPluginToolsLayerConfig","DifyPluginToolValue",]- assert dify_plugin_exports.DIFY_PLUGIN_LLM_LAYER_TYPE_ID == "dify.plugin.llm"- assert dify_plugin_exports.DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID == "dify.plugin.tools"assert not hasattr(dify_plugin_exports, "DifyPluginLLMLayer")@@ -44,36 +38,28 @@ def test_dify_plugin_llm_config_discards_legacy_credentials() -> None:"model": "gpt-4o-mini","credentials": {"api_key": "secret", "nested": {"legacy": True}},"model_settings": {"temperature": 0.2, "max_tokens": 64},- "context_window_tokens": 128_000,+ "context_window_tokens": 128000,})-assert config.plugin_id == "langgenius/openai"assert config.model_provider == "openai"assert not hasattr(config, "credentials")assert "credentials" not in config.model_dump(mode="json")assert config.model_settings == {"temperature": 0.2, "max_tokens": 64}- assert config.context_window_tokens == 128_000+ assert config.context_window_tokens == 128000def test_dify_plugin_llm_config_rejects_old_provider_field() -> None:with pytest.raises(ValidationError):_ = DifyPluginLLMLayerConfig.model_validate(- {- "provider": "openai",- "plugin_id": "langgenius/openai",- "model": "gpt-4o-mini",- }+ {"provider": "openai", "plugin_id": "langgenius/openai", "model": "gpt-4o-mini"})def test_dify_plugin_llm_config_rejects_non_positive_context_window() -> None:with pytest.raises(ValidationError):_ = DifyPluginLLMLayerConfig(- plugin_id="langgenius/openai",- model_provider="openai",- model="gpt-4o-mini",- context_window_tokens=0,+ plugin_id="langgenius/openai", model_provider="openai", model="gpt-4o-mini", context_window_tokens=0)@@ -102,15 +88,12 @@ def test_dify_plugin_tools_layer_config_accepts_prepared_parameters_and_schema()],parameters_json_schema={"type": "object",- "properties": {- "query": {"type": "string", "description": "Search query"},- },+ "properties": {"query": {"type": "string", "description": "Search query"}},"required": ["query"],},)])-assert config.tools[0].plugin_id == "langgenius/tools"assert config.tools[0].provider == "search"assert config.tools[0].tool_name == "web_search"@@ -134,15 +117,9 @@ def test_dify_plugin_tool_parameter_accepts_api_tool_parameter_dump_shape() -> N"default": "dify","llm_description": "Search query","input_schema": {"type": "string"},- "options": [- {- "value": "dify",- "label": {"en_US": "Dify"},- }- ],+ "options": [{"value": "dify", "label": {"en_US": "Dify"}}],})-assert parameter.name == "query"assert parameter.type is DifyPluginToolParameterType.SELECTassert parameter.form is DifyPluginToolParameterForm.LLM@@ -166,7 +143,6 @@ def test_dify_plugin_tool_parameter_accepts_api_tool_parameter_attributes() -> Noptions=[SimpleNamespace(value="en", label=SimpleNamespace(en_US="English"))],))-assert parameter.name == "language"assert parameter.type is DifyPluginToolParameterType.STRINGassert parameter.form is DifyPluginToolParameterForm.FORM@@ -216,9 +192,5 @@ def test_dify_plugin_tool_config_rejects_strict_flag() -> None:def test_dify_plugin_tool_config_requires_explicit_credential_type() -> None:with pytest.raises(ValidationError):_ = DifyPluginToolConfig.model_validate(- {- "plugin_id": "langgenius/tools",- "provider": "search",- "tool_name": "web_search",- }+ {"plugin_id": "langgenius/tools", "provider": "search", "tool_name": "web_search"})diff --git a/dify-agent/tests/local/dify_agent/layers/dify_plugin/test_layers.py b/dify-agent/tests/local/dify_agent/layers/dify_plugin/test_layers.pyindex a47efd75437..4d089ed7a07 100644--- a/dify-agent/tests/local/dify_agent/layers/dify_plugin/test_layers.py+++ b/dify-agent/tests/local/dify_agent/layers/dify_plugin/test_layers.py@@ -1,1047 +1,160 @@-import asyncio+"""Plugin tools use JSON identity, prepared schemas and native dispatch."""+import json-from types import SimpleNamespaceimport httpximport pytest-from pydantic import JsonValue-from agenton.compositor import Compositor, LayerNode, LayerProvider-from dify_agent.adapters.llm import DifyLLMAdapterModel-from dify_agent.layers.dify_plugin.configs import (- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,- DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,- DifyPluginLLMLayerConfig,- DifyPluginToolConfig,- DifyPluginToolOption,- DifyPluginToolParameter,- DifyPluginToolParameterForm,- DifyPluginToolParameterType,- DifyPluginToolsLayerConfig,-)-from dify_agent.layers.dify_plugin.llm_layer import DifyPluginLLMLayer-from dify_agent.layers.dify_plugin.tools_layer import DifyPluginToolsLayer, _PluginToolFileContext-from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer+from dify_agent.layers.dify_plugin import tools_layer+from dify_agent.layers.dify_plugin.llm_layer import Capability as ModelCapability, Config as ModelConfig+from dify_agent.layers.execution_context.configs import DifyExecutionContextLayerConfig+from dify_agent.runtime.context import Deps, Services+from tests.local.dify_agent.module_support import invoke_native_tool-def _execution_context_config() -> DifyExecutionContextLayerConfig:+def identity():return DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_id="user-1",+ tenant_id="tenant",+ user_id="user",user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- )---def _llm_config() -> DifyPluginLLMLayerConfig:- return DifyPluginLLMLayerConfig(- plugin_id="langgenius/openai",- model_provider="openai",- model="demo-model",- model_settings={"temperature": 0.2},- )---def _tools_config() -> DifyPluginToolsLayerConfig:- return DifyPluginToolsLayerConfig(- tools=[- DifyPluginToolConfig(- plugin_id="langgenius/tools",- provider="search",- tool_name="web_search",- credential_type="api-key",- description="Search the web.",- runtime_parameters={"api_version": "2026-01", "auth_scope": "workspace"},- parameters=_prepared_tool_parameters(),- parameters_json_schema=_prepared_tool_schema(),- )- ]+ app_id="app",+ agent_mode="agent_app",+ invoke_from="web-app",)-def _missing_hidden_parameter_tools_config() -> DifyPluginToolsLayerConfig:- return DifyPluginToolsLayerConfig(+async def test_native_plugin_tool_prepares_schema_merges_hidden_parameters_and_decodes_stream():+ schema = {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}+ config = tools_layer.Config(tools=[- DifyPluginToolConfig(- plugin_id="langgenius/tools",- provider="search",- tool_name="web_search",- credential_type="api-key",- description="Search the web.",- runtime_parameters={"api_version": "2026-01"},- parameters=_prepared_tool_parameters(),- parameters_json_schema=_prepared_tool_schema(),- )+ {+ "plugin_id": "langgenius/search",+ "provider": "search",+ "tool_name": "web_search",+ "name": "search",+ "credential_type": "api-key",+ "credentials": {"api_key": "tool-secret"},+ "runtime_parameters": {"scope": "workspace"},+ "parameters_json_schema": schema,+ "parameters": [+ {"name": "query", "type": "string", "form": "llm", "required": True},+ {"name": "scope", "type": "string", "form": "form", "required": True},+ {"name": "region", "type": "string", "form": "form", "default": "global"},+ ],+ }])---def _execution_context_provider() -> LayerProvider[DifyExecutionContextLayer]:- return LayerProvider.from_factory(- layer_type=DifyExecutionContextLayer,- create=lambda config: DifyExecutionContextLayer.from_config_with_settings(- DifyExecutionContextLayerConfig.model_validate(config),- daemon_url="http://plugin-daemon",- daemon_api_key="daemon-secret",- ),- )---def _tools_provider() -> LayerProvider[DifyPluginToolsLayer]:- return LayerProvider.from_factory(- layer_type=DifyPluginToolsLayer,- create=lambda config: DifyPluginToolsLayer.from_config_with_settings(- DifyPluginToolsLayerConfig.model_validate(config),- inner_api_url="http://dify-api",- inner_api_key="inner-secret",- ),- )---def _prepared_tool_parameters() -> list[DifyPluginToolParameter]:- return [- DifyPluginToolParameter(- name="query",- type=DifyPluginToolParameterType.STRING,- form=DifyPluginToolParameterForm.LLM,- required=True,- llm_description="Search query",- ),- DifyPluginToolParameter(- name="region",- type=DifyPluginToolParameterType.SELECT,- form=DifyPluginToolParameterForm.LLM,- required=False,- llm_description="Search region",- options=[DifyPluginToolOption(value="global"), DifyPluginToolOption(value="cn")],- ),- DifyPluginToolParameter(- name="api_version",- type=DifyPluginToolParameterType.STRING,- form=DifyPluginToolParameterForm.FORM,- required=True,- llm_description="Hidden API version",- ),- DifyPluginToolParameter(- name="auth_scope",- type=DifyPluginToolParameterType.STRING,- form=DifyPluginToolParameterForm.FORM,- required=True,- llm_description="Hidden auth scope",- ),- ]---def _prepared_tool_schema() -> dict[str, JsonValue]:- return {- "type": "object",- "properties": {- "query": {"type": "string", "description": "Search query"},- "region": {- "type": "string",- "description": "Search region",- "enum": ["global", "cn"],+ seen = []++ def handler(request):+ assert request.url.path == "/plugin/tenant/dispatch/tool/invoke"+ assert request.headers["X-Plugin-ID"] == "langgenius/search"+ assert request.headers["X-Api-Key"] == "daemon-secret"+ seen.append(json.loads(request.content))+ return httpx.Response(+ 200,+ text="data: "+ + json.dumps({"code": 0, "message": "ok", "data": {"type": "text", "message": {"text": "found"}}})+ + "\n",+ )++ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:+ deps = Deps(+ layers={+ "tools": {"config": config.model_dump(mode="json"), "state": {}},+ "execution_context": {"config": identity().model_dump(mode="json"), "state": {}},},- },- "required": ["query"],- }---def _llm_only_parameter(*, name: str, description: str, default: JsonValue = None) -> DifyPluginToolParameter:- return DifyPluginToolParameter(- name=name,- type=DifyPluginToolParameterType.STRING,- form=DifyPluginToolParameterForm.LLM,- required=default is None,- default=default,- llm_description=description,- )+ services=Services(client, client, plugin_daemon_api_key="daemon-secret"),+ run_id="test",+ )+ def inspect(info):+ assert info.function_tools[0].name == "search"+ assert info.function_tools[0].parameters_json_schema == schema-def _file_parameter(- *,- name: str = "source",- parameter_type: DifyPluginToolParameterType = DifyPluginToolParameterType.FILE,-) -> DifyPluginToolParameter:- return DifyPluginToolParameter(- name=name,- type=parameter_type,- form=DifyPluginToolParameterForm.LLM,- required=True,- llm_description="Source file",- )+ result = await invoke_native_tool(+ deps, tools_layer.Toolset("tools"), "search", {"query": "dify"}, inspect=inspect+ )+ assert result.output == "found"+ assert seen[0]["user_id"] == "user"+ assert seen[0]["data"]["tool_parameters"] == {"query": "dify", "scope": "workspace", "region": "global"}+ assert not client.is_closed-def _file_tools_config(- *,- parameter_type: DifyPluginToolParameterType = DifyPluginToolParameterType.FILE,-) -> DifyPluginToolsLayerConfig:- return DifyPluginToolsLayerConfig(+ "value,download",+ [+ ({"transfer_method": "tool_file", "reference": "dify-file-ref:file-1"}, True),+ ("https://example.com/file.pdf", False),+ ],+)+async def test_native_plugin_tool_converts_file_inputs(value, download):+ config = tools_layer.Config(tools=[- DifyPluginToolConfig(- plugin_id="langgenius/tools",- provider="search",- tool_name="read_file",- credential_type="api-key",- parameters=[_file_parameter(parameter_type=parameter_type)],- parameters_json_schema={- "type": "object",- "properties": {"source": {"type": "string"}},- "required": ["source"],- },- )- ]- )---def _invoke_stream_response(- *,- error_payload: dict[str, object] | None = None,- chunked_blob: bool = False,-) -> httpx.Response:- if error_payload is not None:- return httpx.Response(400, json=error_payload)-- if chunked_blob:- stream_payload = "\n".join(- [- f"data: {json.dumps({'code': 0, 'message': 'ok', 'data': {'type': 'blob_chunk', 'message': {'id': 'blob-1', 'sequence': 0, 'total_length': 11, 'blob': 'aGVsbG8g', 'end': False}}})}",- f"data: {json.dumps({'code': 0, 'message': 'ok', 'data': {'type': 'blob_chunk', 'message': {'id': 'blob-1', 'sequence': 1, 'total_length': 11, 'blob': 'd29ybGQ=', 'end': True}}})}",- "",- ]- )- return httpx.Response(200, text=stream_payload)-- stream_payload = "\n".join(- [- f"data: {json.dumps({'code': 0, 'message': 'ok', 'data': {'type': 'text', 'message': {'text': 'found '}}})}",- f"data: {json.dumps({'code': 0, 'message': 'ok', 'data': {'type': 'json', 'message': {'json_object': {'count': 1}}}})}",- "",+ {+ "plugin_id": "files",+ "provider": "file",+ "tool_name": "read",+ "credential_type": "unauthorized",+ "parameters": [{"name": "source", "type": "file", "form": "llm", "required": True}],+ "parameters_json_schema": {"type": "object", "properties": {"source": {}}, "required": ["source"]},+ }])- return httpx.Response(200, text=stream_payload)+ sent = []--def _tool_transport(- *,- invoke_error_payload: dict[str, object] | None = None,- chunked_blob: bool = False,-) -> httpx.MockTransport:- def handler(request: httpx.Request) -> httpx.Response:- if request.url.path.endswith("/dispatch/tool/invoke"):- payload = json.loads(request.content.decode("utf-8"))- assert payload["user_id"] == "user-1"- assert payload["data"]["provider"] == "search"- assert payload["data"]["tool"] == "web_search"- assert payload["data"]["credential_type"] == "api-key"- assert payload["data"]["tool_parameters"] == {- "query": "dify",- "region": "global",- "api_version": "2026-01",- "auth_scope": "workspace",- }- return _invoke_stream_response(error_payload=invoke_error_payload, chunked_blob=chunked_blob)-- raise AssertionError(f"Unexpected request path: {request.url.path}")-- return httpx.MockTransport(handler)---def _file_tool_transport(- *,- expected_source: object,- download_response: dict[str, object] | None = None,-) -> httpx.MockTransport:- def handler(request: httpx.Request) -> httpx.Response:- if request.url.path.endswith("/inner/api/download/file/request"):- assert download_response is not None- payload = json.loads(request.content.decode("utf-8"))+ def handler(request):+ payload = json.loads(request.content)+ if request.url.path.endswith("/download/file/request"):+ assert downloadassert payload["file"] == {"transfer_method": "tool_file", "reference": "dify-file-ref:file-1"}- return httpx.Response(200, json={"data": download_response})-- if request.url.path.endswith("/dispatch/tool/invoke"):- payload = json.loads(request.content.decode("utf-8"))- assert payload["data"]["tool_parameters"]["source"] == expected_source- return _invoke_stream_response()-- raise AssertionError(f"Unexpected request path: {request.url.path}")-- return httpx.MockTransport(handler)---def test_dify_plugin_type_id_constants_match_implementation_classes() -> None:- assert DIFY_PLUGIN_LLM_LAYER_TYPE_ID == DifyPluginLLMLayer.type_id- assert DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID == DifyPluginToolsLayer.type_id---def test_dify_plugin_llm_layer_builds_adapter_model_from_direct_dependency() -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("renamed-execution-context", _execution_context_provider()),- LayerNode("llm", DifyPluginLLMLayer, deps={"execution_context": "renamed-execution-context"}),- ]- )- async with httpx.AsyncClient(transport=httpx.MockTransport(lambda _request: httpx.Response(200))) as client:- async with compositor.enter(- configs={- "renamed-execution-context": _execution_context_config(),- "llm": _llm_config(),- }- ) as run:- execution_context = run.get_layer("renamed-execution-context", DifyExecutionContextLayer)- llm = run.get_layer("llm", DifyPluginLLMLayer)-- model = llm.get_model(http_client=client, agent_run_id="00000000-0000-0000-0000-000000000001")-- assert llm.deps.execution_context is execution_context- assert isinstance(model, DifyLLMAdapterModel)- assert model.model_name == "demo-model"- assert model.model_provider == "openai"- assert not hasattr(model, "credentials")- assert model.provider.name == "DifyAPI/langgenius/openai"- assert model.provider.client.http_client is client-- asyncio.run(scenario())---def test_dify_plugin_tools_layer_uses_prepared_tool_definition_and_invokes_daemon() -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient(transport=_tool_transport()) as client:- async with compositor.enter(- configs={"execution_context": _execution_context_config(), "tools": _tools_config()}- ) as run:- tools_layer = run.get_layer("tools", DifyPluginToolsLayer)- tool = (await tools_layer.get_tools(http_client=client, dify_api_http_client=client))[0]-- tool_def = await tool.prepare_tool_def(None) # pyright: ignore[reportArgumentType]- result = await tool.function_schema.call(- {"query": "dify", "region": "global"},- None, # pyright: ignore[reportArgumentType]- )-- assert tool.name == "web_search"- assert tool.description == "Search the web."- assert tool_def is not None- assert tool_def.parameters_json_schema == _prepared_tool_schema()- assert tool_def.strict is False- assert result == 'found {"count": 1}'-- asyncio.run(scenario())---def test_dify_plugin_tools_layer_uses_each_tool_plugin_id_for_transport() -> None:- async def scenario() -> None:- seen_requests: list[tuple[str, str, str, str]] = []-- def handler(request: httpx.Request) -> httpx.Response:- if request.url.path.endswith("/dispatch/tool/invoke"):- payload = json.loads(request.content.decode("utf-8"))- seen_requests.append(- (- request.headers["X-Plugin-ID"],- payload["user_id"],- payload["data"]["provider"],- payload["data"]["tool"],- )- )- return _invoke_stream_response()-- raise AssertionError(f"Unexpected request path: {request.url.path}")-- tools_config = DifyPluginToolsLayerConfig(- tools=[- DifyPluginToolConfig(- plugin_id="langgenius/tools-a",- provider="search-a",- tool_name="web_search_a",- credential_type="api-key",- parameters=[_llm_only_parameter(name="query", description="Search query A")],- parameters_json_schema={- "type": "object",- "properties": {"query": {"type": "string", "description": "Search query A"}},- "required": ["query"],- },- ),- DifyPluginToolConfig(- plugin_id="langgenius/tools-b",- provider="search-b",- tool_name="web_search_b",- credential_type="api-key",- parameters=[_llm_only_parameter(name="query", description="Search query B")],- parameters_json_schema={- "type": "object",- "properties": {"query": {"type": "string", "description": "Search query B"}},- "required": ["query"],- },- ),- ]- )-- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:- async with compositor.enter(- configs={"execution_context": _execution_context_config(), "tools": tools_config}- ) as run:- tools = await run.get_layer("tools", DifyPluginToolsLayer).get_tools(- http_client=client, dify_api_http_client=client- )-- await tools[0].function_schema.call({"query": "first"}, None) # pyright: ignore[reportArgumentType]- await tools[1].function_schema.call({"query": "second"}, None) # pyright: ignore[reportArgumentType]-- assert seen_requests == [- ("langgenius/tools-a", "user-1", "search-a", "web_search_a"),- ("langgenius/tools-b", "user-1", "search-b", "web_search_b"),- ]-- asyncio.run(scenario())---def test_dify_plugin_tools_layer_casts_prepared_parameter_values_before_invocation() -> None:- async def scenario() -> None:- def handler(request: httpx.Request) -> httpx.Response:- if request.url.path.endswith("/dispatch/tool/invoke"):- payload = json.loads(request.content.decode("utf-8"))- assert payload["user_id"] == "user-1"- assert payload["data"]["tool_parameters"] == {- "enabled": True,- "count": 7,- "tags": ["a", "b"],- "metadata": {"source": "docs"},- "model": {"provider": "openai", "model": "gpt-4o-mini"},- }- return _invoke_stream_response()-- raise AssertionError(f"Unexpected request path: {request.url.path}")-- tools_config = DifyPluginToolsLayerConfig(- tools=[- DifyPluginToolConfig(- plugin_id="langgenius/tools",- provider="search",- tool_name="web_search",- credential_type="api-key",- parameters=[- DifyPluginToolParameter(- name="enabled",- type=DifyPluginToolParameterType.BOOLEAN,- form=DifyPluginToolParameterForm.LLM,- required=True,- llm_description="Enable search",- ),- DifyPluginToolParameter(- name="count",- type=DifyPluginToolParameterType.NUMBER,- form=DifyPluginToolParameterForm.LLM,- required=True,- llm_description="Result count",- ),- DifyPluginToolParameter(- name="tags",- type=DifyPluginToolParameterType.ARRAY,- form=DifyPluginToolParameterForm.LLM,- required=True,- llm_description="Tags",- input_schema={"type": "array", "items": {"type": "string"}},- ),- DifyPluginToolParameter(- name="metadata",- type=DifyPluginToolParameterType.OBJECT,- form=DifyPluginToolParameterForm.LLM,- required=True,- llm_description="Metadata",- input_schema={"type": "object", "additionalProperties": True},- ),- DifyPluginToolParameter(- name="model",- type=DifyPluginToolParameterType.MODEL_SELECTOR,- form=DifyPluginToolParameterForm.LLM,- required=True,- llm_description="Model selector",- input_schema={"type": "object", "additionalProperties": True},- ),- ],- parameters_json_schema={- "type": "object",- "properties": {- "enabled": {"type": "boolean", "description": "Enable search"},- "count": {"type": "number", "description": "Result count"},- "tags": {"type": "array", "items": {"type": "string"}, "description": "Tags"},- "metadata": {- "type": "object",- "additionalProperties": True,- "description": "Metadata",- },- "model": {- "type": "object",- "additionalProperties": True,- "description": "Model selector",- },- },- "required": ["enabled", "count", "tags", "metadata", "model"],- },- )- ]- )-- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:- async with compositor.enter(- configs={"execution_context": _execution_context_config(), "tools": tools_config}- ) as run:- tool = (- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(- http_client=client, dify_api_http_client=client- )- )[0]-- result = await tool.function_schema.call(- {- "enabled": "yes",- "count": "7",- "tags": '["a", "b"]',- "metadata": '{"source": "docs"}',- "model": {"provider": "openai", "model": "gpt-4o-mini"},- },- None, # pyright: ignore[reportArgumentType]- )-- assert result == 'found {"count": 1}'-- asyncio.run(scenario())---def test_dify_plugin_tools_layer_sends_prepared_parameter_defaults_to_daemon() -> None:- async def scenario() -> None:- def handler(request: httpx.Request) -> httpx.Response:- if request.url.path.endswith("/dispatch/tool/invoke"):- payload = json.loads(request.content.decode("utf-8"))- assert payload["data"]["tool_parameters"] == {- "query": "dify",- "region": "global",- }- return _invoke_stream_response()-- raise AssertionError(f"Unexpected request path: {request.url.path}")-- tools_config = DifyPluginToolsLayerConfig(- tools=[- DifyPluginToolConfig(- plugin_id="langgenius/tools",- provider="search",- tool_name="web_search",- credential_type="api-key",- parameters=[- _llm_only_parameter(name="query", description="Search query"),- _llm_only_parameter(name="region", description="Search region", default="global"),- ],- parameters_json_schema={- "type": "object",- "properties": {- "query": {"type": "string", "description": "Search query"},- "region": {"type": "string", "description": "Search region"},- },- "required": ["query"],- },- )- ]- )-- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:- async with compositor.enter(- configs={"execution_context": _execution_context_config(), "tools": tools_config}- ) as run:- tool = (- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(- http_client=client, dify_api_http_client=client- )- )[0]-- result = await tool.function_schema.call(- {"query": "dify"},- None, # pyright: ignore[reportArgumentType]- )-- assert result == 'found {"count": 1}'-- asyncio.run(scenario())---def test_dify_plugin_tools_layer_converts_remote_url_file_string() -> None:- async def scenario() -> None:- expected_source = {- "dify_model_identity": "__dify__file__",- "type": "custom",- "url": "https://example.com/report.pdf",- "filename": "report.pdf",- "mime_type": "application/pdf",- "extension": ".pdf",- "size": -1,- }- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient(transport=_file_tool_transport(expected_source=expected_source)) as client:- async with compositor.enter(- configs={"execution_context": _execution_context_config(), "tools": _file_tools_config()}- ) as run:- tool = (- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(- http_client=client,- dify_api_http_client=client,- )- )[0]- result = await tool.function_schema.call(- {"source": "https://example.com/report.pdf"},- None, # pyright: ignore[reportArgumentType]- )-- assert result == 'found {"count": 1}'-- asyncio.run(scenario())---def test_dify_plugin_tools_layer_converts_remote_url_file_mapping() -> None:- async def scenario() -> None:- expected_source = {- "dify_model_identity": "__dify__file__",- "type": "custom",- "url": "https://example.com/report.pdf",- "filename": "report.pdf",- "mime_type": "application/pdf",- "extension": ".pdf",- "size": -1,- }- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient(transport=_file_tool_transport(expected_source=expected_source)) as client:- async with compositor.enter(- configs={"execution_context": _execution_context_config(), "tools": _file_tools_config()}- ) as run:- tool = (- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(- http_client=client,- dify_api_http_client=client,- )- )[0]- result = await tool.function_schema.call(- {"source": {"transfer_method": "remote_url", "url": "https://example.com/report.pdf"}},- None, # pyright: ignore[reportArgumentType]- )-- assert result == 'found {"count": 1}'-- asyncio.run(scenario())---def test_dify_plugin_tools_layer_resolves_tool_file_mapping_before_invocation() -> None:- async def scenario() -> None:- expected_source = {- "dify_model_identity": "__dify__file__",- "type": "custom",- "url": "https://signed.example/report.pdf",- "filename": "report.pdf",- "mime_type": "application/pdf",- "extension": ".pdf",- "size": 42,- }- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient(- transport=_file_tool_transport(- expected_source=expected_source,- download_response={- "filename": "report.pdf",- "mime_type": "application/pdf",- "size": 42,- "download_url": "https://signed.example/report.pdf",+ return httpx.Response(+ 200,+ json={+ "data": {+ "download_url": "https://example.com/file.pdf",+ "filename": "file.pdf",+ "mime_type": "application/pdf",+ "size": 10,+ }},)- ) as client:- async with compositor.enter(- configs={"execution_context": _execution_context_config(), "tools": _file_tools_config()}- ) as run:- tool = (- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(- http_client=client,- dify_api_http_client=client,- )- )[0]- result = await tool.function_schema.call(- {"source": {"transfer_method": "tool_file", "reference": "dify-file-ref:file-1"}},- None, # pyright: ignore[reportArgumentType]- )-- assert result == 'found {"count": 1}'-- asyncio.run(scenario())---def test_dify_plugin_tools_layer_converts_files_parameter_values() -> None:- async def scenario() -> None:- expected_source = [- {- "dify_model_identity": "__dify__file__",- "type": "custom",- "url": "https://example.com/a.txt",- "filename": "a.txt",- "mime_type": "text/plain",- "extension": ".txt",- "size": -1,- },- {- "dify_model_identity": "__dify__file__",- "type": "custom",- "url": "https://example.com/b.txt",- "filename": "b.txt",- "mime_type": "text/plain",- "extension": ".txt",- "size": -1,- },- ]- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient(transport=_file_tool_transport(expected_source=expected_source)) as client:- async with compositor.enter(- configs={- "execution_context": _execution_context_config(),- "tools": _file_tools_config(parameter_type=DifyPluginToolParameterType.FILES),- }- ) as run:- tool = (- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(- http_client=client,- dify_api_http_client=client,- )- )[0]- result = await tool.function_schema.call(- {"source": ["https://example.com/a.txt", "https://example.com/b.txt"]},- None, # pyright: ignore[reportArgumentType]- )-- assert result == 'found {"count": 1}'-- asyncio.run(scenario())---def test_dify_plugin_tools_layer_rejects_multiple_values_for_single_file() -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient(transport=httpx.MockTransport(lambda _request: httpx.Response(500))) as client:- async with compositor.enter(- configs={"execution_context": _execution_context_config(), "tools": _file_tools_config()}- ) as run:- tool = (- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(- http_client=client,- dify_api_http_client=client,- )- )[0]- result = await tool.function_schema.call(- {"source": ["https://example.com/a.txt", "https://example.com/b.txt"]},- None, # pyright: ignore[reportArgumentType]- )- assert "only accepts one file" in result-- asyncio.run(scenario())---def test_dify_plugin_tools_layer_rejects_path_without_shell() -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient(transport=httpx.MockTransport(lambda _request: httpx.Response(500))) as client:- async with compositor.enter(- configs={"execution_context": _execution_context_config(), "tools": _file_tools_config()}- ) as run:- tool = (- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(- http_client=client,- dify_api_http_client=client,- )- )[0]- result = await tool.function_schema.call(- {"source": "outputs/report.pdf"},- None, # pyright: ignore[reportArgumentType]- )- assert "require an active shell layer" in result-- asyncio.run(scenario())---def test_plugin_tool_file_context_uploads_sandbox_path_and_resolves_signed_url() -> None:- class FakeShell:- script: str | None = None-- async def run_remote_script_complete(self, script: str, **_kwargs: object) -> object:- self.script = script- return SimpleNamespace(- exit_code=0,- status="done",- output_complete=True,- output=(- "noise\n"- "<<<DIFY_PLUGIN_TOOL_FILE_UPLOAD_BEGIN>>>"- '{"transfer_method":"tool_file","reference":"dify-file-ref:file-1"}'- "<<<DIFY_PLUGIN_TOOL_FILE_UPLOAD_END>>>\n"- ),- )-- class FakeFileClient:- async def request_download(self, **_kwargs: object) -> object:- return SimpleNamespace(- filename="report.pdf",- mime_type="application/pdf",- size=42,- download_url="https://signed.example/report.pdf",- )-- async def scenario() -> None:- shell = FakeShell()- context = _PluginToolFileContext(- file_client=FakeFileClient(), # pyright: ignore[reportArgumentType]- execution_context=_execution_context_config(),- shell=shell, # pyright: ignore[reportArgumentType]- )- result = await context.to_plugin_file_parameter("outputs/report.pdf")-- assert result == {- "dify_model_identity": "__dify__file__",- "type": "custom",- "url": "https://signed.example/report.pdf",- "filename": "report.pdf",- "mime_type": "application/pdf",- "extension": ".pdf",- "size": 42,- }- assert shell.script is not None- assert "outputs/report.pdf" in shell.script-- asyncio.run(scenario())---def test_dify_plugin_tools_layer_requires_hidden_runtime_parameters_in_prepared_config() -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient(transport=_tool_transport()) as client:- async with compositor.enter(- configs={- "execution_context": _execution_context_config(),- "tools": _missing_hidden_parameter_tools_config(),- }- ) as run:- with pytest.raises(ValueError, match="requires non-LLM runtime_parameters for: auth_scope"):- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(- http_client=client, dify_api_http_client=client- )-- asyncio.run(scenario())---def test_dify_plugin_tools_layer_returns_agent_friendly_error_text() -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient(- transport=_tool_transport(- invoke_error_payload={- "error_type": "PluginDaemonBadRequestError",- "message": "missing query",- }- )- ) as client:- async with compositor.enter(- configs={"execution_context": _execution_context_config(), "tools": _tools_config()}- ) as run:- tool = (- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(- http_client=client, dify_api_http_client=client- )- )[0]- result = await tool.function_schema.call(- {"query": "dify", "region": "global"},- None, # pyright: ignore[reportArgumentType]- )-- assert result == "tool parameters validation error: missing query, please check your tool parameters"-- asyncio.run(scenario())---def test_dify_plugin_tools_layer_propagates_unexpected_transport_errors() -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),- ]+ sent.append(payload["data"]["tool_parameters"]["source"])+ return httpx.Response(+ 200, text='data: {"code":0,"message":"ok","data":{"type":"text","message":{"text":"read"}}}\n')- def handler(request: httpx.Request) -> httpx.Response:- if request.url.path.endswith("/dispatch/tool/invoke"):- raise RuntimeError("unexpected transport failure")-- raise AssertionError(f"Unexpected request path: {request.url.path}")-- async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:- async with compositor.enter(- configs={"execution_context": _execution_context_config(), "tools": _tools_config()}- ) as run:- tool = (- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(- http_client=client, dify_api_http_client=client- )- )[0]-- with pytest.raises(RuntimeError, match="unexpected transport failure"):- await tool.function_schema.call(- {"query": "dify", "region": "global"},- None, # pyright: ignore[reportArgumentType]- )-- asyncio.run(scenario())--- ("invoke_error_payload", "expected_text"),- [- (- {- "error_type": "PluginInvokeError",- "message": json.dumps(- {- "error_type": "PluginDaemonUnauthorizedError",- "message": "invalid api key",- }- ),+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:+ deps = Deps(+ layers={+ "tools": {"config": config.model_dump(mode="json"), "state": {}},+ "execution_context": {"config": identity().model_dump(mode="json"), "state": {}},},- "Please check your tool provider credentials",- ),- (- {- "error_type": "PluginInvokeError",- "message": json.dumps(- {- "error_type": "ToolNotFoundError",- "message": "missing plugin tool",- }- ),- },- "there is not a tool named web_search",- ),- ],-)-def test_dify_plugin_tools_layer_maps_nested_plugin_invoke_errors_to_agent_text(- invoke_error_payload: dict[str, object],- expected_text: str,-) -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),- ]+ services=Services(client, client),+ run_id="test",)- async with httpx.AsyncClient(transport=_tool_transport(invoke_error_payload=invoke_error_payload)) as client:- async with compositor.enter(- configs={"execution_context": _execution_context_config(), "tools": _tools_config()}- ) as run:- tool = (- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(- http_client=client, dify_api_http_client=client- )- )[0]- result = await tool.function_schema.call(- {"query": "dify", "region": "global"},- None, # pyright: ignore[reportArgumentType]- )-- assert result == expected_text+ result = await invoke_native_tool(deps, tools_layer.Toolset("tools"), "read", {"source": value})+ assert result.output == "read"+ assert sent[0]["url"] == "https://example.com/file.pdf"- asyncio.run(scenario())--def test_dify_plugin_tools_layer_merges_blob_chunks_before_observation_conversion() -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),- ]+async def test_model_assembly_reads_config_reference_and_borrows_shared_client():+ config = ModelConfig(+ plugin_id="langgenius/openai", model_provider="openai", model="demo", execution_context="renamed"+ )+ async with httpx.AsyncClient() as client:+ deps = Deps(+ layers={+ "llm": {"config": config.model_dump(mode="json"), "state": {}},+ "renamed": {"config": identity().model_dump(mode="json"), "state": {}},+ },+ services=Services(client, client),+ run_id="test",)- async with httpx.AsyncClient(transport=_tool_transport(chunked_blob=True)) as client:- async with compositor.enter(- configs={"execution_context": _execution_context_config(), "tools": _tools_config()}- ) as run:- tool = (- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(- http_client=client, dify_api_http_client=client- )- )[0]- result = await tool.function_schema.call(- {"query": "dify", "region": "global"},- None, # pyright: ignore[reportArgumentType]- )-- assert "hello world" in result- assert "sequence=0" not in result-- asyncio.run(scenario())+ model = ModelCapability("llm").build_model(deps)+ assert model.model_name == "demo"+ assert model.provider.client.http_client is client+ assert model.provider.name == "DifyAPI/langgenius/openai"diff --git a/dify-agent/tests/local/dify_agent/layers/execution_context/test_configs.py b/dify-agent/tests/local/dify_agent/layers/execution_context/test_configs.pyindex 2c26f0dfb14..34aa332c5d8 100644--- a/dify-agent/tests/local/dify_agent/layers/execution_context/test_configs.py+++ b/dify-agent/tests/local/dify_agent/layers/execution_context/test_configs.py@@ -1,32 +1,24 @@import pytestfrom pydantic import ValidationError-import dify_agent.layers.execution_context as execution_context_exportsfrom dify_agent.layers.execution_context import DifyExecutionContextLayerConfigdef test_execution_context_package_exports_client_safe_config_symbols_only() -> None:assert execution_context_exports.__all__ == [- "DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID","DifyExecutionContextAgentConfigVersionKind","DifyExecutionContextAgentMode","DifyExecutionContextInvokeFrom","DifyExecutionContextLayerConfig","DifyExecutionContextUserFrom",]- assert execution_context_exports.DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID == "dify.execution_context"assert not hasattr(execution_context_exports, "DifyExecutionContextLayer")def test_execution_context_accepts_real_invoke_from_user_from_and_agent_mode() -> None:config = DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_id="user-1",- user_from="end-user",- invoke_from="web-app",- agent_mode="agent_app",+ tenant_id="tenant-1", user_id="user-1", user_from="end-user", invoke_from="web-app", agent_mode="agent_app")-assert config.user_from == "end-user"assert config.invoke_from == "web-app"assert config.agent_mode == "agent_app"@@ -53,14 +45,12 @@ def test_execution_context_layer_config_forbids_runtime_settings_and_unknown_fieagent_mode="workflow_run",invoke_from="service-api",)-assert config.tenant_id == "tenant-1"assert config.user_id == "user-1"assert config.user_from == "account"assert config.workflow_id == "workflow-1"assert config.agent_mode == "workflow_run"assert config.invoke_from == "service-api"-with pytest.raises(ValidationError):_ = DifyExecutionContextLayerConfig.model_validate({@@ -71,7 +61,6 @@ def test_execution_context_layer_config_forbids_runtime_settings_and_unknown_fie"daemon_url": "http://daemon",})-with pytest.raises(ValidationError):_ = DifyExecutionContextLayerConfig.model_validate({diff --git a/dify-agent/tests/local/dify_agent/layers/execution_context/test_layer.py b/dify-agent/tests/local/dify_agent/layers/execution_context/test_layer.pydeleted file mode 100644index cc8ccb29c78..00000000000--- a/dify-agent/tests/local/dify_agent/layers/execution_context/test_layer.py+++ /dev/null@@ -1,94 +0,0 @@-import asyncio--import httpx-import pytest--from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer---def _execution_context_layer() -> DifyExecutionContextLayer:- return DifyExecutionContextLayer.from_config_with_settings(- DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_id="user-1",- user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- ),- daemon_url="http://plugin-daemon",- daemon_api_key="daemon-secret",- )---def test_execution_context_type_id_constant_matches_implementation_class() -> None:- assert DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID == DifyExecutionContextLayer.type_id---def test_execution_context_layer_creates_tool_client_from_shared_http_client() -> None:- async def scenario() -> None:- execution_context = _execution_context_layer()- async with httpx.AsyncClient(transport=httpx.MockTransport(lambda _request: httpx.Response(200))) as client:- tool_client = execution_context.create_tool_client(plugin_id="langgenius/tools", http_client=client)-- assert tool_client.http_client is client- assert tool_client.tenant_id == "tenant-1"- assert tool_client.user_id == "user-1"- assert tool_client.plugin_id == "langgenius/tools"- assert tool_client.plugin_daemon_url == "http://plugin-daemon"- assert tool_client.plugin_daemon_api_key == "daemon-secret"- assert client.is_closed is False-- asyncio.run(scenario())---def test_execution_context_layer_rejects_closed_shared_http_client() -> None:- async def scenario() -> None:- execution_context = _execution_context_layer()- client = httpx.AsyncClient(trust_env=False)- await client.aclose()-- with pytest.raises(RuntimeError, match="open shared HTTP client"):- _ = execution_context.create_tool_client(plugin_id="langgenius/tools", http_client=client)-- asyncio.run(scenario())---def test_execution_context_layer_lifecycle_does_not_manage_http_client() -> None:- from agenton.compositor import Compositor, LayerNode, LayerProvider-- provider = LayerProvider.from_factory(- layer_type=DifyExecutionContextLayer,- create=lambda config: DifyExecutionContextLayer.from_config_with_settings(- DifyExecutionContextLayerConfig.model_validate(config),- daemon_url="http://plugin-daemon",- daemon_api_key="daemon-secret",- ),- )-- async def scenario() -> None:- compositor = Compositor([LayerNode("execution_context", provider)])- async with httpx.AsyncClient(transport=httpx.MockTransport(lambda _request: httpx.Response(200))) as client:- async with compositor.enter(- configs={- "execution_context": DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_id="user-1",- user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- )- }- ) as run:- execution_context = run.get_layer("execution_context", DifyExecutionContextLayer)- tool_client = execution_context.create_tool_client(- plugin_id="langgenius/tools",- http_client=client,- )- run.suspend_layer_on_exit("execution_context")-- assert run.session_snapshot is not None- assert tool_client.http_client is client- assert client.is_closed is False-- asyncio.run(scenario())diff --git a/dify-agent/tests/local/dify_agent/layers/knowledge/test_layer.py b/dify-agent/tests/local/dify_agent/layers/knowledge/test_layer.pyindex 17134bf3844..17eb267378f 100644--- a/dify-agent/tests/local/dify_agent/layers/knowledge/test_layer.py+++ b/dify-agent/tests/local/dify_agent/layers/knowledge/test_layer.py@@ -1,554 +1,185 @@-import asyncio+"""Knowledge module behavior using actual native Agent hooks and tool dispatch."""+import jsonimport httpximport pytest-from pydantic_ai import Tool--from agenton.compositor import Compositor, LayerNode, LayerProvider-from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer-from dify_agent.layers.knowledge.client import (- DifyKnowledgeBaseClient,- DifyKnowledgeBaseClientError,- DifyKnowledgeRetrieveResponse,-)-from dify_agent.layers.knowledge.configs import DifyKnowledgeBaseLayerConfig-from dify_agent.layers.knowledge.layer import (- BLANK_QUERY_OBSERVATION,- DifyKnowledgeBaseLayer,- NO_RESULTS_OBSERVATION,- TEMPORARY_UNAVAILABLE_OBSERVATION,-)---def _execution_context_config(**overrides: object) -> DifyExecutionContextLayerConfig:- payload: dict[str, object] = {- "tenant_id": "tenant-1",- "user_id": "user-1",- "user_from": "account",- "app_id": "app-1",- "agent_mode": "agent_app",- "invoke_from": "web-app",- }- payload.update(overrides)- return DifyExecutionContextLayerConfig.model_validate(payload)---def _knowledge_config(**overrides: object) -> DifyKnowledgeBaseLayerConfig:- set_payload: dict[str, object] = {- "id": "support",- "name": "Support KB",- "datasets": [{"id": "dataset-1"}],- "query": {"mode": "generated_query"},- "retrieval": {"mode": "multiple", "top_k": 4},- }- for key in ("id", "name", "description", "datasets", "query", "retrieval", "metadata_filtering"):- if key in overrides:- set_payload[key] = overrides.pop(key)- if "dataset_ids" in overrides:- dataset_ids = overrides.pop("dataset_ids")- assert isinstance(dataset_ids, list)- set_payload["datasets"] = [{"id": dataset_id} for dataset_id in dataset_ids]- payload: dict[str, object] = {- "sets": [set_payload],- }- payload.update(overrides)- return DifyKnowledgeBaseLayerConfig.model_validate(payload)---def _execution_context_provider() -> LayerProvider[DifyExecutionContextLayer]:- return LayerProvider.from_factory(- layer_type=DifyExecutionContextLayer,- create=lambda config: DifyExecutionContextLayer.from_config_with_settings(- DifyExecutionContextLayerConfig.model_validate(config),- daemon_url="http://plugin-daemon",- daemon_api_key="daemon-secret",- ),- )---def _knowledge_provider() -> LayerProvider[DifyKnowledgeBaseLayer]:- return LayerProvider.from_factory(- layer_type=DifyKnowledgeBaseLayer,- create=lambda config: DifyKnowledgeBaseLayer.from_config_with_settings(- DifyKnowledgeBaseLayerConfig.model_validate(config),- inner_api_url="http://dify-api",- inner_api_key="inner-secret",- ),- )---def test_knowledge_layer_exposes_one_set_scoped_tool_definition() -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient() as http_client:- async with compositor.enter(- configs={- "execution_context": _execution_context_config(),- "knowledge": _knowledge_config(),- }- ) as run:- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]- tool_def = await tool.prepare_tool_def(None) # pyright: ignore[reportArgumentType]- assert isinstance(tool, Tool)- assert tool.name == "knowledge_base_search"- assert tool.description is not None- assert "Pick one configured set_name" in tool.description- assert tool_def is not None- assert tool_def.description is not None- assert "Pick one configured set_name" in tool_def.description- assert tool_def.parameters_json_schema == {- "type": "object",- "properties": {- "set_name": {- "type": "string",- "enum": ["Support KB"],- "description": "Knowledge set to search.",- },- "query": {- "type": "string",- "description": "Search query for the selected knowledge set.",- },- },- "required": ["set_name", "query"],- "additionalProperties": False,- }-- asyncio.run(scenario())+from pydantic_ai import Agent+from pydantic_ai.messages import ModelRequest, ModelResponse, TextPart, UserPromptPart+from pydantic_ai.models.function import FunctionModel--def test_knowledge_layer_rejects_blank_query_locally() -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient() as http_client:- async with compositor.enter(- configs={- "execution_context": _execution_context_config(),- "knowledge": _knowledge_config(),- }- ) as run:- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]- result = await tool.function_schema.call( # pyright: ignore[reportArgumentType]- {"set_name": "Support KB", "query": " "},- None, # pyright: ignore[reportArgumentType]- )- assert result == BLANK_QUERY_OBSERVATION-- asyncio.run(scenario())---def test_knowledge_layer_exposes_no_tool_when_all_sets_are_user_query(monkeypatch: pytest.MonkeyPatch) -> None:- async def fake_retrieve(self: DifyKnowledgeBaseClient, **_kwargs: object) -> DifyKnowledgeRetrieveResponse:- del self- return DifyKnowledgeRetrieveResponse.model_validate({"results": [], "usage": {}})-- monkeypatch.setattr(DifyKnowledgeBaseClient, "retrieve", fake_retrieve)-- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient() as http_client:- async with compositor.enter(- configs={- "execution_context": _execution_context_config(),- "knowledge": _knowledge_config(query={"mode": "user_query", "value": "release notes"}),- }- ) as run:- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)- assert await knowledge_layer.get_tools(http_client=http_client) == []-- asyncio.run(scenario())+from dify_agent.layers.knowledge.layer import Capability, Config, State, TEMPORARY_UNAVAILABLE_OBSERVATION+from dify_agent.layers.knowledge.client import DifyKnowledgeBaseClientError+from dify_agent.layers.execution_context.configs import DifyExecutionContextLayerConfig+from dify_agent.runtime.context import Deps, Services+from tests.local.dify_agent.module_support import invoke_native_tool-def test_knowledge_layer_fetches_user_query_sets_on_context_entry(monkeypatch: pytest.MonkeyPatch) -> None:- seen_requests: list[dict[str, object]] = []-- async def fake_retrieve(self: DifyKnowledgeBaseClient, **kwargs: object) -> DifyKnowledgeRetrieveResponse:- del self- seen_requests.append(kwargs)- return DifyKnowledgeRetrieveResponse.model_validate(+def config(*, eager=False, query="release", dataset="dataset"):+ return Config(+ sets=[{- "results": [- {- "metadata": {- "_source": "knowledge",- "dataset_name": "Docs",- "document_name": "Release.md",- "score": 0.8,- },- "title": "Release",- "files": [],- "content": "Version notes",- "summary": None,- }- ],- "usage": {},+ "id": "support",+ "name": "Support",+ "datasets": [{"id": dataset}],+ "query": {"mode": "user_query", "value": query} if eager else {"mode": "generated_query"},+ "retrieval": {"mode": "multiple", "top_k": 4},}- )-- monkeypatch.setattr(DifyKnowledgeBaseClient, "retrieve", fake_retrieve)-- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with compositor.enter(- configs={- "execution_context": _execution_context_config(),- "knowledge": _knowledge_config(query={"mode": "user_query", "value": "release notes"}),- }- ) as run:- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)- assert len(seen_requests) == 1- assert seen_requests[0]["query"] == "release notes"- assert seen_requests[0]["dataset_ids"] == ["dataset-1"]- assert knowledge_layer.runtime_state.eager_config_fingerprint- assert knowledge_layer.runtime_state.eager_results[0].status == "success"- assert knowledge_layer.user_prompts == [- "Knowledge retrieval results:\n\n"- "Set: Support KB\n"- "Query: release notes\n"- "Results:\n"- "1. Title: Release\n"- " Dataset: Docs\n"- " Document: Release.md\n"- " Score: 0.8\n"- " Content: Version notes"- ]- await knowledge_layer.on_context_resume()- assert len(seen_requests) == 1-- asyncio.run(scenario())+ ]+ )- ("field_name", "field_value"),- [- ("user_id", None),- ("user_from", None),- ("app_id", None),- ],-)-def test_knowledge_layer_fails_fast_when_execution_context_is_missing_required_fields(- field_name: str,- field_value: object,-) -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient() as http_client:- async with compositor.enter(- configs={- "execution_context": _execution_context_config(),- "knowledge": _knowledge_config(),- }- ) as run:- execution_context_layer = run.get_layer("execution_context", DifyExecutionContextLayer)- setattr(execution_context_layer.config, field_name, field_value)- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)- with pytest.raises(ValueError, match=field_name):- _ = await knowledge_layer.get_tools(http_client=http_client)+def deps_for(client, config, state=None):+ identity = DifyExecutionContextLayerConfig(+ tenant_id="tenant",+ user_id="user",+ user_from="account",+ app_id="app",+ agent_mode="agent_app",+ invoke_from="web-app",+ )+ return Deps(+ layers={+ "knowledge": {"config": config.model_dump(mode="json"), "state": state or State().model_dump(mode="json")},+ "execution_context": {"config": identity.model_dump(mode="json"), "state": {}},+ },+ services=Services(client, client),+ run_id="test",+ )- asyncio.run(scenario())+async def test_eager_results_are_in_user_role_and_cache_uses_current_config():+ requests = []-def test_knowledge_layer_formats_results_and_truncates_observation() -> None:- def handler(_request: httpx.Request) -> httpx.Response:+ def handler(request):+ assert request.url.path == "/inner/api/knowledge/retrieve"+ requests.append(json.loads(request.content))return httpx.Response(200,json={"results": [{- "metadata": {- "_source": "knowledge",- "dataset_name": "Docs",- "document_name": "Guide.md",- "score": 0.9,- },- "title": "Guide",+ "metadata": {"dataset_name": "Docs", "document_name": "Release", "score": 0.8},+ "title": "Release","files": [],- "content": "ABCDEFGHIJKL",- "summary": None,+ "content": "Version notes",}],"usage": {},},)- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http_client:- async with compositor.enter(- configs={- "execution_context": _execution_context_config(),- "knowledge": _knowledge_config(max_result_content_chars=8, max_observation_chars=160),- }- ) as run:- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]- result = await tool.function_schema.call( # pyright: ignore[reportArgumentType]- {"set_name": "Support KB", "query": "reset"},- None, # pyright: ignore[reportArgumentType]- )- assert result.startswith("Knowledge base search results:\n1. Title: Guide")- assert "Dataset: Docs" in result- assert "Document: Guide.md" in result- assert "Score: 0.9" in result- assert "Content: ABCDE..." in result- assert len(result) <= 160-- asyncio.run(scenario())+ seen = []+ async def model(messages, info):+ assert info.function_tools == []+ seen.append(list(messages))+ return ModelResponse(parts=[TextPart("done")])-def test_knowledge_layer_returns_no_results_observation() -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient(- transport=httpx.MockTransport(lambda _request: httpx.Response(200, json={"results": [], "usage": {}}))- ) as http_client:- async with compositor.enter(- configs={- "execution_context": _execution_context_config(),- "knowledge": _knowledge_config(),- }- ) as run:- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]- result = await tool.function_schema.call( # pyright: ignore[reportArgumentType]- {"set_name": "Support KB", "query": "reset"},- None, # pyright: ignore[reportArgumentType]- )- assert result == NO_RESULTS_OBSERVATION-- asyncio.run(scenario())---def test_knowledge_layer_converts_retryable_failures_into_observation() -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),- ]- )- async with httpx.AsyncClient(- transport=httpx.MockTransport(- lambda _request: httpx.Response(429, json={"code": "knowledge_rate_limited", "message": "slow down"})+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:+ deps = deps_for(client, config(eager=True))+ for _ in range(2):+ await Agent(FunctionModel(model), deps_type=Deps, capabilities=[Capability("knowledge")]).run(+ "question", deps=deps)- ) as http_client:- async with compositor.enter(- configs={- "execution_context": _execution_context_config(),- "knowledge": _knowledge_config(),- }- ) as run:- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]- result = await tool.function_schema.call( # pyright: ignore[reportArgumentType]- {"set_name": "Support KB", "query": "reset"},- None, # pyright: ignore[reportArgumentType]- )- assert result == TEMPORARY_UNAVAILABLE_OBSERVATION-- asyncio.run(scenario())+ assert len(requests) == 1+ assert requests[0]["caller"]["tenant_id"] == "tenant"+ assert requests[0]["dataset_ids"] == ["dataset"]+ prompts = [+ p.content for m in seen[0] if isinstance(m, ModelRequest) for p in m.parts if isinstance(p, UserPromptPart)+ ]+ assert prompts[0] == "question"+ assert "Knowledge retrieval results" in prompts[1]+ assert "Version notes" in prompts[1]+ assert deps.layers["knowledge"]["state"]["eager_results"][0]["status"] == "success"+ old_fingerprint = deps.layers["knowledge"]["state"]["eager_config_fingerprint"]+ deps.layers["knowledge"]["config"] = config(eager=True, query="changed", dataset="new").model_dump(mode="json")+ await Agent(FunctionModel(model), deps_type=Deps, capabilities=[Capability("knowledge")]).run(+ "question", deps=deps+ )+ assert len(requests) == 2+ assert requests[1]["query"] == "changed" and requests[1]["dataset_ids"] == ["new"]+ assert deps.layers["knowledge"]["state"]["eager_config_fingerprint"] != old_fingerprint+ assert not client.is_closed@pytest.mark.parametrize(- "transport_error",+ "query,status,expected",[- lambda request: httpx.ReadTimeout("timed out", request=request),- lambda request: httpx.ConnectError("connection failed", request=request),+ ("release", 200, "No relevant knowledge base results"),+ (" ", 200, "requires a non-empty query"),+ ("release", 429, "temporarily unavailable"),],)-def test_knowledge_layer_converts_retryable_transport_failures_into_observation(transport_error) -> None:- def handler(request: httpx.Request) -> httpx.Response:- raise transport_error(request)+async def test_generated_query_native_tool_preserves_local_validation_and_retry_policy(query, status, expected):+ requests = []- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),- ]+ def handler(request):+ requests.append(json.loads(request.content))+ return httpx.Response(+ status, json={"results": [], "usage": {}} if status == 200 else {"code": "busy", "message": "busy"})- async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http_client:- async with compositor.enter(- configs={- "execution_context": _execution_context_config(),- "knowledge": _knowledge_config(),- }- ) as run:- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]- result = await tool.function_schema.call( # pyright: ignore[reportArgumentType]- {"set_name": "Support KB", "query": "reset"},- None, # pyright: ignore[reportArgumentType]- )- assert result == TEMPORARY_UNAVAILABLE_OBSERVATION- asyncio.run(scenario())+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:+ deps = deps_for(client, config())+ def inspect(info):+ schema = info.function_tools[0].parameters_json_schema+ assert schema["properties"]["set_name"]["enum"] == ["Support"]+ assert set(schema["properties"]) == {"set_name", "query"}-def test_knowledge_layer_raises_non_retryable_client_errors() -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),- ]+ result = await invoke_native_tool(+ deps,+ Capability("knowledge").get_toolset(),+ "knowledge_base_search",+ {"set_name": "Support", "query": query},+ inspect=inspect,)- async with httpx.AsyncClient(- transport=httpx.MockTransport(- lambda _request: httpx.Response(403, json={"code": "dataset_tenant_mismatch", "message": "forbidden"})- )- ) as http_client:- async with compositor.enter(- configs={- "execution_context": _execution_context_config(),- "knowledge": _knowledge_config(),- }- ) as run:- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]- with pytest.raises(DifyKnowledgeBaseClientError) as exc_info:- await tool.function_schema.call( # pyright: ignore[reportArgumentType]- {"set_name": "Support KB", "query": "reset"},- None, # pyright: ignore[reportArgumentType]- )- assert exc_info.value.status_code == 403+ assert expected in result.output+ assert len(requests) == (0 if not query.strip() else 1)- asyncio.run(scenario())--def test_knowledge_layer_raises_for_malformed_success_responses() -> None:- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),- ]+async def test_nonretryable_eager_failure_leaves_previous_cache_for_retry():+ async with httpx.AsyncClient(+ transport=httpx.MockTransport(+ lambda request: httpx.Response(404, json={"code": "dataset_not_found", "message": "missing"}))- async with httpx.AsyncClient(- transport=httpx.MockTransport(lambda _request: httpx.Response(200, json={"bad": []}))- ) as http_client:- async with compositor.enter(- configs={- "execution_context": _execution_context_config(),- "knowledge": _knowledge_config(),- }- ) as run:- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]- with pytest.raises(DifyKnowledgeBaseClientError) as exc_info:- await tool.function_schema.call( # pyright: ignore[reportArgumentType]- {"set_name": "Support KB", "query": "reset"},- None, # pyright: ignore[reportArgumentType]- )- assert exc_info.value.error_code == "invalid_response"- assert exc_info.value.retryable is False-- asyncio.run(scenario())+ ) as client:+ deps = deps_for(client, config(eager=True), {"eager_config_fingerprint": "previous", "eager_results": []})+ async def model(messages, info):+ raise AssertionError("model must not execute after eager failure")-def test_knowledge_layer_sends_execution_context_and_static_config_to_inner_api() -> None:- def handler(request: httpx.Request) -> httpx.Response:- payload = json.loads(request.content.decode("utf-8"))- assert request.headers["X-Inner-Api-Key"] == "inner-secret"- assert payload["caller"] == {- "tenant_id": "tenant-1",- "user_id": "user-1",- "app_id": "app-1",- "user_from": "account",- "invoke_from": "web-app",- }- assert payload["dataset_ids"] == ["dataset-1", "dataset-2"]- assert payload["query"] == "reset"- assert payload["retrieval"]["top_k"] == 2- assert payload["metadata_filtering"] == {- "mode": "manual",- "conditions": {- "logical_operator": "and",- "conditions": [- {- "name": "category",- "comparison_operator": "contains",- "value": "auth",- }- ],- },- }- return httpx.Response(200, json={"results": [], "usage": {}})+ with pytest.raises(DifyKnowledgeBaseClientError):+ await Agent(FunctionModel(model), deps_type=Deps, capabilities=[Capability("knowledge")]).run(+ "question", deps=deps+ )+ assert deps.layers["knowledge"]["state"]["eager_config_fingerprint"] == "previous"+++async def test_retryable_eager_failure_is_saved_as_user_observation():+ async with httpx.AsyncClient(+ transport=httpx.MockTransport(lambda request: httpx.Response(429, json={"code": "busy", "message": "busy"}))+ ) as client:+ deps = deps_for(client, config(eager=True))++ async def model(messages, info):+ assert any(+ TEMPORARY_UNAVAILABLE_OBSERVATION in str(p.content)+ for m in messages+ if isinstance(m, ModelRequest)+ for p in m.parts+ if isinstance(p, UserPromptPart)+ )+ return ModelResponse(parts=[TextPart("done")])- async def scenario() -> None:- compositor = Compositor(- [- LayerNode("execution_context", _execution_context_provider()),- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),- ]+ await Agent(FunctionModel(model), deps_type=Deps, capabilities=[Capability("knowledge")]).run(+ "question", deps=deps)- async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http_client:- async with compositor.enter(- configs={- "execution_context": _execution_context_config(),- "knowledge": _knowledge_config(- dataset_ids=["dataset-1", "dataset-2"],- retrieval={"mode": "multiple", "top_k": 2},- metadata_filtering={- "mode": "manual",- "conditions": {- "logical_operator": "and",- "conditions": [- {- "name": "category",- "comparison_operator": "contains",- "value": "auth",- }- ],- },- },- ),- }- ) as run:- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]- result = await tool.function_schema.call( # pyright: ignore[reportArgumentType]- {"set_name": "Support KB", "query": "reset"},- None, # pyright: ignore[reportArgumentType]- )- assert result == NO_RESULTS_OBSERVATION-- asyncio.run(scenario())+ state = State.model_validate(deps.layers["knowledge"]["state"])+ assert state.eager_results[0].status == "temporarily_unavailable"+ assert state.eager_config_fingerprint is not Nonediff --git a/dify-agent/tests/local/dify_agent/layers/output/test_configs.py b/dify-agent/tests/local/dify_agent/layers/output/test_configs.pyindex ad7cca5ab22..bcd44ad556f 100644--- a/dify-agent/tests/local/dify_agent/layers/output/test_configs.py+++ b/dify-agent/tests/local/dify_agent/layers/output/test_configs.py@@ -1,10 +1,10 @@import pytestfrom pydantic import JsonValue, TypeAdapter, ValidationErrorfrom pydantic_ai.output import ToolOutput-import dify_agent.layers.output as output_exports-from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig-from dify_agent.layers.output.output_layer import DifyOutputLayer+from dify_agent.layers.output import DifyOutputLayerConfig+from dify_agent.layers.output.output_layer import Capability+from tests.local.dify_agent.module_support import deps_fordef _json_schema() -> dict[str, JsonValue]:@@ -25,43 +25,24 @@ def _recursive_json_schema() -> dict[str, JsonValue]:"type": "object","properties": {"node": {"$ref": "#/$defs/node"}},"$defs": {- "node": {- "type": "object",- "properties": {"child": {"$ref": "#/$defs/node"}},- "additionalProperties": False,- }+ "node": {"type": "object", "properties": {"child": {"$ref": "#/$defs/node"}}, "additionalProperties": False}},"additionalProperties": False,}def _remote_ref_schema() -> dict[str, JsonValue]:- return {- "type": "object",- "properties": {- "title": {"$ref": "https://example.com/schema.json"},- },- }+ return {"type": "object", "properties": {"title": {"$ref": "https://example.com/schema.json"}}}def _literal_dollar_ref_value_schema() -> dict[str, JsonValue]:return {"type": "object","properties": {- "payload": {- "const": {- "$ref": "https://example.com/literal",- "kind": "literal",- },- },+ "payload": {"const": {"$ref": "https://example.com/literal", "kind": "literal"}},"metadata": {"type": "object",- "examples": [- {- "$ref": "https://example.com/example",- "note": "example value",- }- ],+ "examples": [{"$ref": "https://example.com/example", "note": "example value"}],},},"required": ["payload", "metadata"],@@ -72,42 +53,23 @@ def _literal_dollar_ref_value_schema() -> dict[str, JsonValue]:def _object_local_definitions_ref_schema() -> dict[str, JsonValue]:return {"type": "object",- "properties": {- "items": {"$ref": "#/definitions/itemArray"},- },+ "properties": {"items": {"$ref": "#/definitions/itemArray"}},"required": ["items"],- "definitions": {- "itemArray": {- "type": "array",- "items": {"type": "string"},- },- },+ "definitions": {"itemArray": {"type": "array", "items": {"type": "string"}}},}def _object_local_defs_ref_schema() -> dict[str, JsonValue]:return {"type": "object",- "properties": {- "items": {"$ref": "#/$defs/itemArray"},- },+ "properties": {"items": {"$ref": "#/$defs/itemArray"}},"required": ["items"],- "$defs": {- "itemArray": {- "type": "array",- "items": {"type": "string"},- },- },+ "$defs": {"itemArray": {"type": "array", "items": {"type": "string"}}},}def _invalid_json_schema() -> dict[str, JsonValue]:- return {- "type": "object",- "properties": {- "title": {"type": "wat"},- },- }+ return {"type": "object", "properties": {"title": {"type": "wat"}}}def _validated_output_type(output_spec: object) -> object:@@ -116,23 +78,14 @@ def _validated_output_type(output_spec: object) -> object:def test_output_package_exports_client_safe_config_symbols_only() -> None:- assert output_exports.__all__ == ["DIFY_OUTPUT_LAYER_TYPE_ID", "DifyOutputLayerConfig"]- assert output_exports.DIFY_OUTPUT_LAYER_TYPE_ID == "dify.output"+ assert output_exports.__all__ == ["DifyOutputLayerConfig"]assert not hasattr(output_exports, "DifyOutputLayer")def test_output_layer_config_accepts_valid_object_schema_without_public_tool_name() -> None:config = DifyOutputLayerConfig(json_schema=_json_schema())-- assert DIFY_OUTPUT_LAYER_TYPE_ID == "dify.output"assert hasattr(config, "name") is False- assert config.model_dump(mode="json") == {- "json_schema": _json_schema(),- "description": None,- "strict": None,- }- assert config.description is None- assert config.strict is None+ assert config.model_dump(mode="json") == {"json_schema": _json_schema(), "description": None, "strict": None}def test_output_layer_config_rejects_non_object_top_level_json_schema() -> None:@@ -153,19 +106,13 @@ def test_output_layer_config_rejects_invalid_input(payload: dict[str, object], mdef test_output_layer_builds_validated_output_contract_for_object_schema() -> None:- config = DifyOutputLayerConfig(- json_schema=_json_schema(),- description="Structured incident summary.",- strict=True,- )-- layer = DifyOutputLayer.from_config(config)- output_contract = layer.build_output_contract()+ config = DifyOutputLayerConfig(json_schema=_json_schema(), description="Structured incident summary.", strict=True)+ layer = _output(config)+ output_contract = layeroutput_type = output_contract.output_typeoutput_schema = TypeAdapter(output_type.output).json_schema() if isinstance(output_type, ToolOutput) else {}valid_output = {"title": "Database outage", "severity": "high", "actions": ["page on-call"]}output_adapter = TypeAdapter(_validated_output_type(output_contract.output_type))-assert isinstance(output_type, ToolOutput)assert output_type.name == "final_output"assert output_type.description is None@@ -191,39 +138,27 @@ def test_output_layer_builds_validated_output_contract_for_object_schema() -> No),],)-def test_output_layer_object_contract_retries_invalid_model_output(invalid_output: JsonValue, message: str) -> None:- output_contract = DifyOutputLayer.from_config(- DifyOutputLayerConfig(json_schema=_json_schema())- ).build_output_contract()+def test_output_layer_object_contract_rejects_invalid_output(invalid_output: JsonValue, message: str) -> None:+ output_contract = _output(DifyOutputLayerConfig(json_schema=_json_schema()))output_adapter = TypeAdapter(_validated_output_type(output_contract.output_type))-with pytest.raises(ValidationError, match=message):_ = output_adapter.validate_python(invalid_output)def test_output_layer_rejects_non_defs_local_ref_in_direct_object_schema() -> None:- layer = DifyOutputLayer.from_config(DifyOutputLayerConfig(json_schema=_object_local_definitions_ref_schema()))-- with pytest.raises(ValueError, match=r"Only local refs under '#/\$defs/' are supported"):- _ = layer.build_output_contract()+ config = DifyOutputLayerConfig(json_schema=_object_local_definitions_ref_schema())+ with pytest.raises(ValueError, match="Only local refs under '#/\\$defs/' are supported"):+ _ = _output(config)def test_output_layer_keeps_local_defs_ref_working_in_direct_object_schema() -> None:- output_contract = DifyOutputLayer.from_config(- DifyOutputLayerConfig(json_schema=_object_local_defs_ref_schema())- ).build_output_contract()+ output_contract = _output(DifyOutputLayerConfig(json_schema=_object_local_defs_ref_schema()))output_adapter = TypeAdapter(_validated_output_type(output_contract.output_type))output_schema = output_adapter.json_schema()-assert isinstance(output_contract.output_type, ToolOutput)assert output_schema == {"type": "object",- "properties": {- "items": {- "type": "array",- "items": {"type": "string"},- },- },+ "properties": {"items": {"type": "array", "items": {"type": "string"}}},"required": ["items"],"title": "final_output",}@@ -231,44 +166,31 @@ def test_output_layer_keeps_local_defs_ref_working_in_direct_object_schema() ->def test_output_layer_rejects_recursive_json_schema_during_contract_build() -> None:- layer = DifyOutputLayer.from_config(DifyOutputLayerConfig(json_schema=_recursive_json_schema()))-+ config = DifyOutputLayerConfig(json_schema=_recursive_json_schema())with pytest.raises(ValueError):- _ = layer.build_output_contract()+ _ = _output(config)def test_output_layer_rejects_invalid_json_schema_during_contract_build() -> None:- layer = DifyOutputLayer.from_config(DifyOutputLayerConfig(json_schema=_invalid_json_schema()))-+ config = DifyOutputLayerConfig(json_schema=_invalid_json_schema())with pytest.raises(ValueError):- _ = layer.build_output_contract()+ _ = _output(config)def test_output_layer_rejects_remote_ref_during_contract_build() -> None:- layer = DifyOutputLayer.from_config(DifyOutputLayerConfig(json_schema=_remote_ref_schema()))-- with pytest.raises(ValueError, match=r"Remote \$ref values are not supported"):- _ = layer.build_output_contract()+ config = DifyOutputLayerConfig(json_schema=_remote_ref_schema())+ with pytest.raises(ValueError, match="Remote \\$ref values are not supported"):+ _ = _output(config)def test_output_layer_allows_literal_dollar_ref_values_under_const_and_examples() -> None:- layer = DifyOutputLayer.from_config(DifyOutputLayerConfig(json_schema=_literal_dollar_ref_value_schema()))-- output_contract = layer.build_output_contract()+ layer = _output(DifyOutputLayerConfig(json_schema=_literal_dollar_ref_value_schema()))+ output_contract = layeroutput_adapter = TypeAdapter(_validated_output_type(output_contract.output_type))-assert output_adapter.validate_python(- {- "payload": {- "$ref": "https://example.com/literal",- "kind": "literal",- },- "metadata": {"note": "runtime value"},- }- ) == {- "payload": {- "$ref": "https://example.com/literal",- "kind": "literal",- },- "metadata": {"note": "runtime value"},- }+ {"payload": {"$ref": "https://example.com/literal", "kind": "literal"}, "metadata": {"note": "runtime value"}}+ ) == {"payload": {"$ref": "https://example.com/literal", "kind": "literal"}, "metadata": {"note": "runtime value"}}+++def _output(config):+ return Capability("output").build_output_contract(deps_for("output", config))diff --git a/dify-agent/tests/local/dify_agent/layers/shell/test_configs.py b/dify-agent/tests/local/dify_agent/layers/shell/test_configs.pyindex a4dbdb1641b..fe953503e25 100644--- a/dify-agent/tests/local/dify_agent/layers/shell/test_configs.py+++ b/dify-agent/tests/local/dify_agent/layers/shell/test_configs.py@@ -1,9 +1,7 @@import pytestfrom pydantic import ValidationError-import dify_agent.layers.shell as shell_exportsfrom dify_agent.layers.shell import (- DIFY_SHELL_LAYER_TYPE_ID,DifyShellCliToolConfig,DifyShellEnvVarConfig,DifyShellLayerConfig,@@ -13,26 +11,24 @@ from dify_agent.layers.shell import (def test_shell_package_exports_client_safe_config_symbols_only() -> None:assert shell_exports.__all__ == [- "DIFY_SHELL_LAYER_TYPE_ID","DifyShellCliToolConfig","DifyShellEnvVarConfig","DifyShellLayerConfig","DifyShellSecretRefConfig",]- assert DIFY_SHELL_LAYER_TYPE_ID == "dify.shell"assert not hasattr(shell_exports, "DifyShellLayer")def test_shell_layer_config_defaults_and_forbids_unknown_fields() -> None:config = DifyShellLayerConfig()-assert config.model_dump() == {+ "runtime": "runtime",+ "execution_context": "execution_context","cli_tools": [],"env": [],"secret_refs": [],"redact_patterns": [],}-with pytest.raises(ValidationError):_ = DifyShellLayerConfig.model_validate({"entrypoint": "http://shellctl"})@@ -50,7 +46,6 @@ def test_shell_layer_config_accepts_agent_soul_shell_settings() -> None:env=[DifyShellEnvVarConfig(name="PROJECT_NAME", value="demo")],secret_refs=[DifyShellSecretRefConfig(name="OPENAI_API_KEY", ref="credential-1")],)-assert config.cli_tools[0].install_commands == ["apt-get update", "apt-get install -y ripgrep"]assert config.cli_tools[0].env[0].name == "RG_CONFIG_PATH"assert config.cli_tools[0].secret_refs[0].ref == "credential-2"@@ -61,6 +56,5 @@ def test_shell_layer_config_accepts_agent_soul_shell_settings() -> None:def test_shell_layer_config_rejects_invalid_env_names() -> None:with pytest.raises(ValidationError):_ = DifyShellEnvVarConfig(name="1_BAD", value="x")-with pytest.raises(ValidationError):_ = DifyShellSecretRefConfig(name="BAD-NAME", ref="secret")diff --git a/dify-agent/tests/local/dify_agent/layers/shell/test_layer.py b/dify-agent/tests/local/dify_agent/layers/shell/test_layer.pyindex ae75ff1aea0..081da9d147a 100644--- a/dify-agent/tests/local/dify_agent/layers/shell/test_layer.py+++ b/dify-agent/tests/local/dify_agent/layers/shell/test_layer.py@@ -11,17 +11,14 @@ import pytestimport dify_agent.layers.shell.layer as shell_layer_moduleimport dify_agent.runtime.command_runner as command_runner_modulefrom dify_agent.layers.shell import (- DIFY_SHELL_LAYER_TYPE_ID,- DifyShellCliToolConfig,DifyShellEnvVarConfig,DifyShellLayerConfig,)from dify_agent.layers.shell.layer import (CompleteRemoteCommandResult,DEFAULT_TERMINATE_GRACE_SECONDS,- DifyShellLayer,- DifyShellLayerDeps,- DifyShellRuntimeState,+ ShellSession,+ State,)from dify_agent.adapters.shell.protocols import (ShellCommandResult,@@ -30,11 +27,7 @@ from dify_agent.adapters.shell.protocols import (ShellProviderError,)from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer-from dify_agent.layers.runtime import DifyRuntimeLayerConfig-from dify_agent.layers.runtime.layer import DifyRuntimeLayerfrom dify_agent.runtime_backend import (- ExecutionBindingBackend,RuntimeLayout,RuntimeLease,)@@ -232,8 +225,8 @@ class FakeResource:@dataclass(slots=True)-class FakeProvider:- """Test fixture retaining the old name while representing an active lease."""+class FakeLeaseFixture:+ """Command fixture for an acquired runtime lease."""resource: FakeResource@@ -243,34 +236,29 @@ def _layer(commands: FakeCommands,config: DifyShellLayerConfig | None = None,shell_home_root: str = "/home",-) -> tuple[DifyShellLayer, FakeProvider]:- provider = FakeProvider(resource=FakeResource(commands=commands))+) -> tuple[ShellSession, FakeLeaseFixture]:+ provider = FakeLeaseFixture(resource=FakeResource(commands=commands))root = shell_home_root.rstrip("/")provider.resource.layout = RuntimeLayout(home_dir=f"{root}/agent-1",workspace_dir=f"{root}/agent-1/workspace/abc12ff",)- layer = DifyShellLayer.from_config_with_settings(- config or DifyShellLayerConfig(),- )- runtime = DifyRuntimeLayer.from_config_with_backend(- DifyRuntimeLayerConfig(backend_binding_ref="binding-1"),- backend=cast(ExecutionBindingBackend, object()),- )- runtime._lease = cast(RuntimeLease, cast(object, provider.resource))- layer.deps = DifyShellLayerDeps(- runtime=runtime,- execution_context=None,- )+ from tests.local.dify_agent.module_support import deps_for++ cfg = config or DifyShellLayerConfig()+ cfg = cfg.model_copy(update={"execution_context": None})+ deps = deps_for("shell", cfg, State().model_dump(mode="json"))+ deps.resources.leases["runtime"] = cast(RuntimeLease, provider.resource)+ layer = ShellSession("shell", deps)return layer, provider-def _bind_execution_context(layer: DifyShellLayer, *, agent_id: str | None = "agent-1") -> None:- layer.deps.execution_context = DifyExecutionContextLayer.from_config_with_settings(- _execution_context_config(agent_id=agent_id),- daemon_url="http://plugin-daemon",- daemon_api_key="",- )+def _bind_execution_context(layer: ShellSession, *, agent_id: str | None = "agent-1") -> None:+ layer.deps.layers["execution_context"] = {+ "config": _execution_context_config(agent_id=agent_id).model_dump(mode="json"),+ "state": {},+ }+ layer.deps.layers["shell"]["config"]["execution_context"] = "execution_context"def _execution_context_config(*, agent_id: str | None = None) -> DifyExecutionContextLayerConfig:@@ -291,27 +279,14 @@ def _runtime_state(sandbox_id: str | None = None,job_ids: list[str] | None = None,job_offsets: dict[str, int] | None = None,-) -> DifyShellRuntimeState:+) -> State:del session_id, workspace_cwd, sandbox_id- return DifyShellRuntimeState(+ return State(job_ids=[] if job_ids is None else job_ids,job_offsets={} if job_offsets is None else job_offsets,)-def test_shell_type_id_constant_matches_implementation_class() -> None:- assert DIFY_SHELL_LAYER_TYPE_ID == DifyShellLayer.type_id---def test_shell_layer_tools_have_non_empty_descriptions() -> None:- layer = DifyShellLayer.from_config_with_settings(DifyShellLayerConfig())-- descriptions = {tool.name: tool.description for tool in layer.tools}-- assert set(descriptions) == {"shell_run", "shell_wait", "shell_input", "shell_interrupt"}- assert all(description and description.strip() for description in descriptions.values())--def test_shell_prefix_prompt_describes_workspace_as_temp_space() -> None:prompt = shell_layer_module._SHELL_LAYER_PREFIX_PROMPT@@ -321,33 +296,6 @@ def test_shell_prefix_prompt_describes_workspace_as_temp_space() -> None:assert "<cwd>/.tmp" not in prompt-def test_shell_layer_create_bootstraps_inside_sandbox_workspace() -> None:- expected_home = "/home/agent-1"- expected_workspace_cwd = "/home/agent-1/workspace/abc12ff"-- def run_handler(script: str, cwd: str | None, env: Mapping[str, str] | None, timeout: float) -> ShellCommandResult:- assert env == {"HOME": expected_home}- assert cwd == expected_workspace_cwd- assert "apt-get install -y ripgrep" in script- return _command_result("bootstrap-job", status="exited", done=True, exit_code=0)-- layer, provider = _layer(- commands=FakeCommands(run_handler=run_handler),- config=DifyShellLayerConfig(- cli_tools=[DifyShellCliToolConfig(name="ripgrep", install_commands=["apt-get install -y ripgrep"])],- ),- )- _bind_execution_context(layer)-- async def scenario() -> None:- async with layer.resource_context():- await layer.on_context_create()-- asyncio.run(scenario())-- assert [call.job_id for call in provider.resource.commands.delete_calls] == ["bootstrap-job"]--def test_shell_layer_uses_sandbox_layout_for_home_and_workspace_cwd() -> None:expected_home = "/home/agent-1"expected_workspace_cwd = "/home/agent-1/workspace/abc12ff"@@ -363,14 +311,12 @@ def test_shell_layer_uses_sandbox_layout_for_home_and_workspace_cwd() -> None:commands = FakeCommands(run_handler=run_handler)layer, _provider = _layer(commands=commands)_bind_execution_context(layer)- tools = {tool.name: tool for tool in layer.tools}async def scenario() -> None:- async with layer.resource_context():- run_result = await tools["shell_run"].function_schema.call({"script": "pwd"}, None) # pyright: ignore[reportArgumentType]- metadata, output = _parse_tagged_observation(run_result)- assert metadata["job_id"] == "user-job"- assert output == expected_home+ run_result = await layer._tool_run(**{"script": "pwd"}) # pyright: ignore[reportArgumentType]+ metadata, output = _parse_tagged_observation(run_result)+ assert metadata["job_id"] == "user-job"+ assert output == expected_homeasyncio.run(scenario())@@ -378,55 +324,6 @@ def test_shell_layer_uses_sandbox_layout_for_home_and_workspace_cwd() -> None:assert commands.delete_calls == []-def test_shell_layer_suspend_cleans_tracked_jobs_without_owning_sandbox() -> None:- commands = FakeCommands()- layer, _provider = _layer(commands=commands)- layer.runtime_state = _runtime_state()- layer._job_agent_stub_tokens.update({"job-1": "token-1", "job-2": "token-2"})-- async def scenario() -> None:- async with layer.resource_context():- await layer.on_context_suspend()-- asyncio.run(scenario())- assert commands.delete_calls == []- assert layer._job_agent_stub_tokens == {}---def test_shell_layer_resume_requires_active_sandbox_lease_only() -> None:- commands = FakeCommands()- layer, _provider = _layer(commands=commands)- _bind_execution_context(layer)- layer.runtime_state = _runtime_state()-- async def scenario() -> None:- async with layer.resource_context():- await layer.on_context_resume()-- asyncio.run(scenario())-- assert commands.run_calls == []---def test_shell_layer_delete_cleans_tracked_jobs_without_deleting_workspace() -> None:- commands = FakeCommands()- layer, _provider = _layer(commands=commands)- _bind_execution_context(layer)- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 9})- layer._job_agent_stub_tokens["user-job"] = "long-lived-test-token"-- async def scenario() -> None:- async with layer.resource_context():- await layer.on_context_delete()-- asyncio.run(scenario())-- assert [call.job_id for call in commands.delete_calls] == ["user-job"]- assert layer.runtime_state.job_ids == []- assert layer.runtime_state.job_offsets == {}- assert layer._job_agent_stub_tokens == {}--def test_shell_layer_tools_map_inputs_and_maintain_offsets_with_tail_end() -> None:def run_handler(script: str, cwd: str | None, env: Mapping[str, str] | None, timeout: float) -> ShellCommandResult:assert script == "pwd"@@ -478,51 +375,40 @@ def test_shell_layer_tools_map_inputs_and_maintain_offsets_with_tail_end() -> No)layer, _provider = _layer(commands=commands)_bind_execution_context(layer)- tools = {tool.name: tool for tool in layer.tools}- layer.runtime_state = _runtime_state()+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- run_result = await tools["shell_run"].function_schema.call({"script": "pwd"}, None) # pyright: ignore[reportArgumentType]- wait_result = await tools["shell_wait"].function_schema.call(- {"job_id": "user-job", "timeout": 4.0},- None, # pyright: ignore[reportArgumentType]- )- input_result = await tools["shell_input"].function_schema.call(- {"job_id": "user-job", "text": "ls\n", "timeout": 5.0},- None, # pyright: ignore[reportArgumentType]- )- interrupt_result = await tools["shell_interrupt"].function_schema.call(- {"job_id": "user-job", "grace_seconds": 1.5},- None, # pyright: ignore[reportArgumentType]- )-- run_metadata, run_output = _parse_tagged_observation(run_result)- wait_metadata, wait_output = _parse_tagged_observation(wait_result)- input_metadata, input_output = _parse_tagged_observation(input_result)- interrupt_metadata, interrupt_output = _parse_tagged_observation(interrupt_result)-- assert run_metadata == {- "job_id": "user-job",- "status": "running",- "done": False,- "exit_code": None,- "output_path": "/tmp/resolved.log",- }- assert "head-output" in run_output- assert "tail-output" in run_output- assert wait_metadata["job_id"] == "user-job"- assert wait_output == "more\n"- assert input_metadata["exit_code"] == 0- assert input_output == "file.txt\n"- assert interrupt_metadata == {- "job_id": "user-job",- "status": "terminated",- "done": True,- "exit_code": 130,- "output_path": "/tmp/resolved.log",- }- assert interrupt_output == "Job was interrupted."+ run_result = await layer._tool_run(**{"script": "pwd"}) # pyright: ignore[reportArgumentType]+ wait_result = await layer._tool_wait(**{"job_id": "user-job", "timeout": 4.0})+ input_result = await layer._tool_input(**{"job_id": "user-job", "text": "ls\n", "timeout": 5.0})+ interrupt_result = await layer._tool_interrupt(**{"job_id": "user-job", "grace_seconds": 1.5})++ run_metadata, run_output = _parse_tagged_observation(run_result)+ wait_metadata, wait_output = _parse_tagged_observation(wait_result)+ input_metadata, input_output = _parse_tagged_observation(input_result)+ interrupt_metadata, interrupt_output = _parse_tagged_observation(interrupt_result)++ assert run_metadata == {+ "job_id": "user-job",+ "status": "running",+ "done": False,+ "exit_code": None,+ "output_path": "/tmp/resolved.log",+ }+ assert "head-output" in run_output+ assert "tail-output" in run_output+ assert wait_metadata["job_id"] == "user-job"+ assert wait_output == "more\n"+ assert input_metadata["exit_code"] == 0+ assert input_output == "file.txt\n"+ assert interrupt_metadata == {+ "job_id": "user-job",+ "status": "terminated",+ "done": True,+ "exit_code": 130,+ "output_path": "/tmp/resolved.log",+ }+ assert interrupt_output == "Job was interrupted."asyncio.run(scenario())@@ -552,22 +438,19 @@ def test_shell_run_keeps_original_offset_when_tail_lookup_fails_for_truncated_oucommands = FakeCommands(run_handler=run_handler, tail_handler=tail_handler)layer, _provider = _layer(commands=commands)_bind_execution_context(layer)- tools = {tool.name: tool for tool in layer.tools}- layer.runtime_state = _runtime_state()+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- run_result = await tools["shell_run"].function_schema.call({"script": "pwd"}, None) # pyright: ignore[reportArgumentType]- metadata, output = _parse_tagged_observation(run_result)- assert metadata == {- "job_id": "user-job",- "status": "running",- "done": False,- "exit_code": None,- "output_path": "/tmp/current.log",- }- assert "head-output" in output- assert set(metadata) == {"job_id", "status", "done", "exit_code", "output_path"}+ run_result = await layer._tool_run(**{"script": "pwd"}) # pyright: ignore[reportArgumentType]+ metadata, output = _parse_tagged_observation(run_result)+ assert metadata == {+ "job_id": "user-job",+ "status": "running",+ "done": False,+ "exit_code": None,+ "output_path": "/tmp/current.log",+ }+ assert "head-output" in outputasyncio.run(scenario())@@ -590,18 +473,16 @@ def test_shell_run_formats_large_non_truncated_output_without_tail_lookup() -> N)layer, _provider = _layer(commands=commands)_bind_execution_context(layer)- tools = {tool.name: tool for tool in layer.tools}- layer.runtime_state = _runtime_state()+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- result = await tools["shell_run"].function_schema.call({"script": "cat large.log"}, None) # pyright: ignore[reportArgumentType]- metadata, output = _parse_tagged_observation(result)- assert metadata["output_path"] == "/tmp/large.log"- assert output.startswith("head-y")- assert "max output size is limited to 8192 bytes" in output- assert output.endswith("(check the /tmp/large.log for full output)")- assert "-tail" in output+ result = await layer._tool_run(**{"script": "cat large.log"}) # pyright: ignore[reportArgumentType]+ metadata, output = _parse_tagged_observation(result)+ assert metadata["output_path"] == "/tmp/large.log"+ assert output.startswith("head-y")+ assert "max output size is limited to 8192 bytes" in output+ assert output.endswith("(check the /tmp/large.log for full output)")+ assert "-tail" in outputasyncio.run(scenario())assert commands.tail_calls == []@@ -613,21 +494,19 @@ def test_shell_interrupt_succeeds_when_tail_lookup_fails() -> None:tail_handler=lambda job_id: (_ for _ in ()).throw(RuntimeError("tail unavailable")),)layer, _provider = _layer(commands=commands)- tools = {tool.name: tool for tool in layer.tools}- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 22})+ layer.save_state(_runtime_state(job_ids=["user-job"], job_offsets={"user-job": 22}))layer._job_agent_stub_tokens["user-job"] = "actual-long-jwe-token"async def scenario() -> None:- async with layer.resource_context():- result = await tools["shell_interrupt"].function_schema.call({"job_id": "user-job"}, None) # pyright: ignore[reportArgumentType]- metadata, output = _parse_tagged_observation(result)- assert metadata == {- "job_id": "user-job",- "status": "terminated",- "done": True,- "exit_code": 130,- }- assert output == "Job was interrupted."+ result = await layer._tool_interrupt(**{"job_id": "user-job"}) # pyright: ignore[reportArgumentType]+ metadata, output = _parse_tagged_observation(result)+ assert metadata == {+ "job_id": "user-job",+ "status": "terminated",+ "done": True,+ "exit_code": 130,+ }+ assert output == "Job was interrupted."asyncio.run(scenario())assert layer._job_agent_stub_tokens == {}@@ -644,13 +523,11 @@ def test_shell_run_returns_provider_timeout_error_observation_without_unexpected)layer, _provider = _layer(commands=commands)_bind_execution_context(layer)- tools = {tool.name: tool for tool in layer.tools}- layer.runtime_state = _runtime_state()+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- result = await tools["shell_run"].function_schema.call({"script": "pwd"}, None) # pyright: ignore[reportArgumentType]- _assert_error_observation(result, includes="timeout")+ result = await layer._tool_run(**{"script": "pwd"}) # pyright: ignore[reportArgumentType]+ _assert_error_observation(result, includes="timeout")asyncio.run(scenario())assert logged == []@@ -666,16 +543,11 @@ def test_shell_wait_returns_provider_request_error_observation_with_job_id_and_n))layer, _provider = _layer(commands=commands)- tools = {tool.name: tool for tool in layer.tools}- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 3})+ layer.save_state(_runtime_state(job_ids=["user-job"], job_offsets={"user-job": 3}))async def scenario() -> None:- async with layer.resource_context():- result = await tools["shell_wait"].function_schema.call(- {"job_id": "user-job", "timeout": 4.0},- None, # pyright: ignore[reportArgumentType]- )- _assert_error_observation(result, job_id="user-job", includes="request_error")+ result = await layer._tool_wait(**{"job_id": "user-job", "timeout": 4.0})+ _assert_error_observation(result, job_id="user-job", includes="request_error")asyncio.run(scenario())assert logged == []@@ -691,16 +563,11 @@ def test_shell_input_returns_provider_timeout_error_observation_with_job_id_and_))layer, _provider = _layer(commands=commands)- tools = {tool.name: tool for tool in layer.tools}- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 6})+ layer.save_state(_runtime_state(job_ids=["user-job"], job_offsets={"user-job": 6}))async def scenario() -> None:- async with layer.resource_context():- result = await tools["shell_input"].function_schema.call(- {"job_id": "user-job", "text": "ls\n", "timeout": 5.0},- None, # pyright: ignore[reportArgumentType]- )- _assert_error_observation(result, job_id="user-job", includes="timeout")+ result = await layer._tool_input(**{"job_id": "user-job", "text": "ls\n", "timeout": 5.0})+ _assert_error_observation(result, job_id="user-job", includes="timeout")asyncio.run(scenario())assert logged == []@@ -716,16 +583,11 @@ def test_shell_interrupt_returns_provider_request_error_observation_with_job_id_))layer, _provider = _layer(commands=commands)- tools = {tool.name: tool for tool in layer.tools}- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 22})+ layer.save_state(_runtime_state(job_ids=["user-job"], job_offsets={"user-job": 22}))async def scenario() -> None:- async with layer.resource_context():- result = await tools["shell_interrupt"].function_schema.call(- {"job_id": "user-job", "grace_seconds": 1.5},- None, # pyright: ignore[reportArgumentType]- )- _assert_error_observation(result, job_id="user-job", includes="request_error")+ result = await layer._tool_interrupt(**{"job_id": "user-job", "grace_seconds": 1.5})+ _assert_error_observation(result, job_id="user-job", includes="request_error")asyncio.run(scenario())assert logged == []@@ -740,13 +602,11 @@ def test_shell_run_returns_error_observation_and_logs_unexpected_exception()layer, _provider = _layer(commands=commands)_bind_execution_context(layer)- tools = {tool.name: tool for tool in layer.tools}- layer.runtime_state = _runtime_state()+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- result = await tools["shell_run"].function_schema.call({"script": "pwd"}, None) # pyright: ignore[reportArgumentType]- _assert_error_observation(result, includes="boom")+ result = await layer._tool_run(**{"script": "pwd"}) # pyright: ignore[reportArgumentType]+ _assert_error_observation(result, includes="boom")asyncio.run(scenario())assert logged == [@@ -765,16 +625,11 @@ def test_shell_wait_returns_error_observation_and_logs_unexpected_exception(wait_handler=lambda job_id, offset, timeout: (_ for _ in ()).throw(_UnexpectedToolError("wait exploded")))layer, _provider = _layer(commands=commands)- tools = {tool.name: tool for tool in layer.tools}- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 3})+ layer.save_state(_runtime_state(job_ids=["user-job"], job_offsets={"user-job": 3}))async def scenario() -> None:- async with layer.resource_context():- result = await tools["shell_wait"].function_schema.call(- {"job_id": "user-job", "timeout": 4.0},- None, # pyright: ignore[reportArgumentType]- )- _assert_error_observation(result, job_id="user-job", includes="wait exploded")+ result = await layer._tool_wait(**{"job_id": "user-job", "timeout": 4.0})+ _assert_error_observation(result, job_id="user-job", includes="wait exploded")asyncio.run(scenario())assert logged == [@@ -795,16 +650,11 @@ def test_shell_input_returns_error_observation_and_logs_unexpected_exception())layer, _provider = _layer(commands=commands)- tools = {tool.name: tool for tool in layer.tools}- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 6})+ layer.save_state(_runtime_state(job_ids=["user-job"], job_offsets={"user-job": 6}))async def scenario() -> None:- async with layer.resource_context():- result = await tools["shell_input"].function_schema.call(- {"job_id": "user-job", "text": "ls\n", "timeout": 5.0},- None, # pyright: ignore[reportArgumentType]- )- _assert_error_observation(result, job_id="user-job", includes="stdin exploded")+ result = await layer._tool_input(**{"job_id": "user-job", "text": "ls\n", "timeout": 5.0})+ _assert_error_observation(result, job_id="user-job", includes="stdin exploded")asyncio.run(scenario())assert logged == [@@ -825,16 +675,11 @@ def test_shell_interrupt_returns_error_observation_and_logs_unexpected_exception))layer, _provider = _layer(commands=commands)- tools = {tool.name: tool for tool in layer.tools}- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 22})+ layer.save_state(_runtime_state(job_ids=["user-job"], job_offsets={"user-job": 22}))async def scenario() -> None:- async with layer.resource_context():- result = await tools["shell_interrupt"].function_schema.call(- {"job_id": "user-job", "grace_seconds": 1.5},- None, # pyright: ignore[reportArgumentType]- )- _assert_error_observation(result, job_id="user-job", includes="interrupt exploded")+ result = await layer._tool_interrupt(**{"job_id": "user-job", "grace_seconds": 1.5})+ _assert_error_observation(result, job_id="user-job", includes="interrupt exploded")asyncio.run(scenario())assert logged == [@@ -854,20 +699,18 @@ def test_shell_interrupt_logs_unexpected_tail_failure_but_still_succeeds(tail_handler=lambda job_id: (_ for _ in ()).throw(_UnexpectedToolError("tail exploded")),)layer, _provider = _layer(commands=commands)- tools = {tool.name: tool for tool in layer.tools}- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 22})+ layer.save_state(_runtime_state(job_ids=["user-job"], job_offsets={"user-job": 22}))async def scenario() -> None:- async with layer.resource_context():- result = await tools["shell_interrupt"].function_schema.call({"job_id": "user-job"}, None) # pyright: ignore[reportArgumentType]- metadata, output = _parse_tagged_observation(result)- assert metadata == {- "job_id": "user-job",- "status": "terminated",- "done": True,- "exit_code": 130,- }- assert output == "Job was interrupted."+ result = await layer._tool_interrupt(**{"job_id": "user-job"}) # pyright: ignore[reportArgumentType]+ metadata, output = _parse_tagged_observation(result)+ assert metadata == {+ "job_id": "user-job",+ "status": "terminated",+ "done": True,+ "exit_code": 130,+ }+ assert output == "Job was interrupted."asyncio.run(scenario())assert logged == [@@ -902,12 +745,11 @@ def test_agent_stub_token_omits_workspace_session_identity() -> None:layer, _provider = _layer(commands=FakeCommands(run_handler=run_handler))_bind_execution_context(layer)- layer.agent_stub_api_base_url = "http://localhost:5050/agent-stub"- layer.agent_stub_token_factory = token_factory+ layer.deps.services.agent_stub_api_base_url = "http://localhost:5050/agent-stub"+ layer.deps.services.agent_stub_token_factory = token_factoryasync def scenario() -> None:- async with layer.resource_context():- _ = await layer.run_remote_script_complete("true", inject_agent_stub_env=True)+ _ = await layer.run_remote_script_complete("true", inject_agent_stub_env=True)asyncio.run(scenario())@@ -920,13 +762,11 @@ def test_shell_run_propagates_cancelled_error() -> None:)layer, _provider = _layer(commands=commands)_bind_execution_context(layer)- tools = {tool.name: tool for tool in layer.tools}- layer.runtime_state = _runtime_state()+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- with pytest.raises(asyncio.CancelledError):- await tools["shell_run"].function_schema.call({"script": "pwd"}, None) # pyright: ignore[reportArgumentType]+ with pytest.raises(asyncio.CancelledError):+ await layer._tool_run(**{"script": "pwd"}) # pyright: ignore[reportArgumentType]asyncio.run(scenario())@@ -953,15 +793,14 @@ def test_run_remote_script_complete_uses_read_output_before_wait_and_deletes_jobcommands = FakeCommands(run_handler=run_handler, wait_handler=wait_handler)layer, _provider = _layer(commands=commands)_bind_execution_context(layer)- layer.runtime_state = _runtime_state()+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- result = await layer.run_remote_script_complete("printf 'abcdefghi'")- assert isinstance(result, CompleteRemoteCommandResult)- assert result.output == "abcdefghi"- assert result.output_complete is True- assert result.incomplete_reason is None+ result = await layer.run_remote_script_complete("printf 'abcdefghi'")+ assert isinstance(result, CompleteRemoteCommandResult)+ assert result.output == "abcdefghi"+ assert result.output_complete is True+ assert result.incomplete_reason is Noneasyncio.run(scenario())assert events == ["run", "read_output", "wait"]@@ -990,13 +829,12 @@ def test_run_remote_script_complete_uses_agent_specific_home_and_workspace_cwd()commands = FakeCommands(run_handler=run_handler)layer, _provider = _layer(commands=commands)_bind_execution_context(layer)- layer.runtime_state = _runtime_state()+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- result = await layer.run_remote_script_complete("pwd")- assert isinstance(result, CompleteRemoteCommandResult)- assert result.output == expected_home+ result = await layer.run_remote_script_complete("pwd")+ assert isinstance(result, CompleteRemoteCommandResult)+ assert result.output == expected_homeasyncio.run(scenario())assert [call.job_id for call in commands.delete_calls] == ["remote-job"]@@ -1023,13 +861,12 @@ def test_run_remote_script_complete_passes_config_env_values_to_shellctl_env() -config=DifyShellLayerConfig(env=[DifyShellEnvVarConfig(name="API_TOKEN", value="inline-secret-value")]),)_bind_execution_context(layer)- layer.runtime_state = _runtime_state()+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- result = await layer.run_remote_script_complete("printenv API_TOKEN")- assert isinstance(result, CompleteRemoteCommandResult)- assert result.output == "inline-secret-value\n"+ result = await layer.run_remote_script_complete("printenv API_TOKEN")+ assert isinstance(result, CompleteRemoteCommandResult)+ assert result.output == "inline-secret-value\n"asyncio.run(scenario())assert [call.job_id for call in commands.delete_calls] == ["remote-job"]@@ -1056,13 +893,12 @@ def test_run_remote_script_uses_agent_specific_home_and_workspace_cwd() -> None:commands = FakeCommands(run_handler=run_handler)layer, _provider = _layer(commands=commands)_bind_execution_context(layer)- layer.runtime_state = _runtime_state()+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- result = await layer.run_remote_script("pwd")- assert isinstance(result, CompleteRemoteCommandResult)- assert result.output == expected_home+ result = await layer.run_remote_script("pwd")+ assert isinstance(result, CompleteRemoteCommandResult)+ assert result.output == expected_homeasyncio.run(scenario())assert [call.job_id for call in commands.delete_calls] == ["remote-job"]@@ -1088,15 +924,14 @@ def test_run_remote_script_complete_returns_incomplete_reason_for_output_limit())layer, _provider = _layer(commands=commands)_bind_execution_context(layer)- layer.runtime_state = _runtime_state()+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- result = await layer.run_remote_script_complete("printf 'hello world'", max_output_bytes=5)- assert result.output == "hello"- assert result.output_complete is False- assert result.incomplete_reason == "output_limit"- assert result.status == "terminated"+ result = await layer.run_remote_script_complete("printf 'hello world'", max_output_bytes=5)+ assert result.output == "hello"+ assert result.output_complete is False+ assert result.incomplete_reason == "output_limit"+ assert result.status == "terminated"asyncio.run(scenario())assert commands.wait_calls == []@@ -1136,16 +971,15 @@ def test_run_remote_script_complete_returns_incomplete_reason_for_timeout()layer, _provider = _layer(commands=commands)_bind_execution_context(layer)- layer.runtime_state = _runtime_state()+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- result = await layer.run_remote_script_complete("sleep 10", timeout=60.0)- assert result.output == "hello"- assert result.output_complete is False- assert result.incomplete_reason == "timeout"- assert result.status == "terminated"- assert result.exit_code == 130+ result = await layer.run_remote_script_complete("sleep 10", timeout=60.0)+ assert result.output == "hello"+ assert result.output_complete is False+ assert result.incomplete_reason == "timeout"+ assert result.status == "terminated"+ assert result.exit_code == 130asyncio.run(scenario())assert commands.wait_calls == []@@ -1158,20 +992,15 @@ def test_run_remote_script_complete_returns_incomplete_reason_for_timeout(def test_shell_layer_rejects_untracked_job_ids_without_provider_calls() -> None:commands = FakeCommands()layer, _provider = _layer(commands=commands)- tools = {tool.name: tool for tool in layer.tools}- layer.runtime_state = _runtime_state()+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- wait_result = await tools["shell_wait"].function_schema.call({"job_id": "missing"}, None) # pyright: ignore[reportArgumentType]- input_result = await tools["shell_input"].function_schema.call(- {"job_id": "missing", "text": "hello"},- None, # pyright: ignore[reportArgumentType]- )- interrupt_result = await tools["shell_interrupt"].function_schema.call({"job_id": "missing"}, None) # pyright: ignore[reportArgumentType]- _assert_error_observation(wait_result, job_id="missing")- _assert_error_observation(input_result, job_id="missing")- _assert_error_observation(interrupt_result, job_id="missing")+ wait_result = await layer._tool_wait(**{"job_id": "missing"}) # pyright: ignore[reportArgumentType]+ input_result = await layer._tool_input(**{"job_id": "missing", "text": "hello"})+ interrupt_result = await layer._tool_interrupt(**{"job_id": "missing"}) # pyright: ignore[reportArgumentType]+ _assert_error_observation(wait_result, job_id="missing")+ _assert_error_observation(input_result, job_id="missing")+ _assert_error_observation(interrupt_result, job_id="missing")asyncio.run(scenario())assert commands.wait_calls == []@@ -1181,19 +1010,18 @@ def test_shell_layer_rejects_untracked_job_ids_without_provider_calls() -> None:def test_shell_layer_hooks_and_tools_fail_clearly_outside_active_resource_context() -> None:layer, _provider = _layer(commands=FakeCommands())- layer.deps.runtime._lease = None- tools = {tool.name: tool for tool in layer.tools}- layer.runtime_state = _runtime_state()+ layer.deps.resources.leases.clear()+ layer.save_state(_runtime_state())async def scenario() -> None:- result = await tools["shell_run"].function_schema.call({"script": "pwd"}, None) # pyright: ignore[reportArgumentType]- _assert_error_observation(result, includes="resource_context")+ result = await layer._tool_run(**{"script": "pwd"}) # pyright: ignore[reportArgumentType]+ _assert_error_observation(result, includes="active Runtime lease")asyncio.run(scenario())def test_shell_runtime_state_validates_offset_keys() -> None:- state = DifyShellRuntimeState.model_validate(+ state = State.model_validate({"job_ids": ['job"bad with spaces'],"job_offsets": {'job"bad with spaces': 0},@@ -1201,7 +1029,7 @@ def test_shell_runtime_state_validates_offset_keys() -> None:)assert state.job_ids == ['job"bad with spaces']with pytest.raises(ValueError, match="unknown job ids"):- _ = DifyShellRuntimeState.model_validate(+ _ = State.model_validate({"job_ids": ["job-1"],"job_offsets": {"job-2": 3},@@ -1220,12 +1048,12 @@ def _layer_with_redaction(config: DifyShellLayerConfig | None = None,shell_redact_patterns: list[str] | None = None,token_value: str = "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0.fake-long-jwe-token-value",-) -> tuple[DifyShellLayer, FakeProvider]:+) -> tuple[ShellSession, FakeLeaseFixture]:"""Create a layer with agent_stub env injection and optional redaction patterns."""layer, provider = _layer(commands=commands, config=config)- layer.shell_redact_patterns = shell_redact_patterns or []- layer.agent_stub_api_base_url = "http://localhost:5050/agent-stub"- layer.agent_stub_token_factory = lambda execution_context, session_id: token_value+ layer.deps.services.shell_redact_patterns = shell_redact_patterns or []+ layer.deps.services.agent_stub_api_base_url = "http://localhost:5050/agent-stub"+ layer.deps.services.agent_stub_token_factory = lambda execution_context, session_id: token_valuereturn layer, provider@@ -1254,17 +1082,15 @@ def test_shell_run_issues_one_jwe_and_redaction_does_not_issue_another() -> Nonecommands = FakeCommands(run_handler=run_handler)layer, _provider = _layer_with_redaction(commands=commands)- layer.agent_stub_token_factory = token_factory+ layer.deps.services.agent_stub_token_factory = token_factory_bind_execution_context(layer)- layer.runtime_state = _runtime_state()- tools = {tool.name: tool for tool in layer.tools}+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- result = await tools["shell_run"].function_schema.call({"script": "env"}, None) # pyright: ignore[reportArgumentType]- _, output = _parse_tagged_observation(result)- assert issued_tokens[0] not in output- assert "DIFY_AGENT_STUB_AUTH_JWE=***" in output+ result = await layer._tool_run(**{"script": "env"}) # pyright: ignore[reportArgumentType]+ _, output = _parse_tagged_observation(result)+ assert issued_tokens[0] not in output+ assert "DIFY_AGENT_STUB_AUTH_JWE=***" in outputasyncio.run(scenario())assert issued_tokens == ["actual-long-jwe-token-1"]@@ -1313,30 +1139,23 @@ def test_two_running_jobs_redact_and_clean_up_their_own_jwes_independently() ->),)layer, _provider = _layer_with_redaction(commands=commands)- layer.agent_stub_token_factory = token_factory+ layer.deps.services.agent_stub_token_factory = token_factory_bind_execution_context(layer)- layer.runtime_state = _runtime_state()- tools = {tool.name: tool for tool in layer.tools}+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- await tools["shell_run"].function_schema.call({"script": "start first"}, None) # pyright: ignore[reportArgumentType]- await tools["shell_run"].function_schema.call({"script": "start second"}, None) # pyright: ignore[reportArgumentType]- assert issued_tokens == tokens- assert layer._job_agent_stub_tokens == {"job-1": tokens[0], "job-2": tokens[1]}-- wait_result = await tools["shell_wait"].function_schema.call({"job_id": "job-1"}, None) # pyright: ignore[reportArgumentType]- _, wait_output = _parse_tagged_observation(wait_result)- assert wait_output == "wait=***\n"- assert layer._job_agent_stub_tokens == {"job-2": tokens[1]}-- input_result = await tools["shell_input"].function_schema.call(- {"job_id": "job-2", "text": "finish\n"},- None, # pyright: ignore[reportArgumentType]- )- _, input_output = _parse_tagged_observation(input_result)- assert input_output == "input=***\n"- assert layer._job_agent_stub_tokens == {}+ await layer._tool_run(**{"script": "start first"}) # pyright: ignore[reportArgumentType]+ await layer._tool_run(**{"script": "start second"}) # pyright: ignore[reportArgumentType]+ assert issued_tokens == tokens++ wait_result = await layer._tool_wait(**{"job_id": "job-1"}) # pyright: ignore[reportArgumentType]+ _, wait_output = _parse_tagged_observation(wait_result)+ assert wait_output == "wait=***\n"++ input_result = await layer._tool_input(**{"job_id": "job-2", "text": "finish\n"})+ _, input_output = _parse_tagged_observation(input_result)+ assert input_output == "input=***\n"+ assert layer._job_agent_stub_tokens == {}asyncio.run(scenario())@@ -1363,15 +1182,13 @@ def test_redact_output_applies_server_level_patterns() -> None:shell_redact_patterns=[r"sk-proj-[A-Za-z0-9]+"],)_bind_execution_context(layer)- layer.runtime_state = _runtime_state()- tools = {tool.name: tool for tool in layer.tools}+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- result = await tools["shell_run"].function_schema.call({"script": "cat .env"}, None) # pyright: ignore[reportArgumentType]- _, output = _parse_tagged_observation(result)- assert "sk-proj-abc123xyz" not in output- assert "api_key=***" in output+ result = await layer._tool_run(**{"script": "cat .env"}) # pyright: ignore[reportArgumentType]+ _, output = _parse_tagged_observation(result)+ assert "sk-proj-abc123xyz" not in output+ assert "api_key=***" in outputasyncio.run(scenario())@@ -1396,15 +1213,13 @@ def test_redact_output_applies_per_agent_config_patterns() -> None:config = DifyShellLayerConfig(redact_patterns=[r"ghp_[A-Za-z0-9]{36}"])layer, _provider = _layer_with_redaction(commands=commands, config=config)_bind_execution_context(layer)- layer.runtime_state = _runtime_state()- tools = {tool.name: tool for tool in layer.tools}+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- result = await tools["shell_run"].function_schema.call({"script": "echo $TOKEN"}, None) # pyright: ignore[reportArgumentType]- _, output = _parse_tagged_observation(result)- assert "ghp_" not in output- assert "token: ***" in output+ result = await layer._tool_run(**{"script": "echo $TOKEN"}) # pyright: ignore[reportArgumentType]+ _, output = _parse_tagged_observation(result)+ assert "ghp_" not in output+ assert "token: ***" in outputasyncio.run(scenario())@@ -1429,13 +1244,11 @@ def test_redact_output_skips_short_jwe_values() -> None:# Token value is short — should NOT be redacted even if it appears in output.layer, _provider = _layer_with_redaction(commands=commands, token_value="short")_bind_execution_context(layer)- layer.runtime_state = _runtime_state()- tools = {tool.name: tool for tool in layer.tools}+ layer.save_state(_runtime_state())async def scenario() -> None:- async with layer.resource_context():- result = await tools["shell_run"].function_schema.call({"script": "echo hi"}, None) # pyright: ignore[reportArgumentType]- _, output = _parse_tagged_observation(result)- assert "short" in output+ result = await layer._tool_run(**{"script": "echo hi"}) # pyright: ignore[reportArgumentType]+ _, output = _parse_tagged_observation(result)+ assert "short" in outputasyncio.run(scenario())diff --git a/dify-agent/tests/local/dify_agent/layers/test_runtime_layer.py b/dify-agent/tests/local/dify_agent/layers/test_runtime_layer.pydeleted file mode 100644index de6ed027b7a..00000000000--- a/dify-agent/tests/local/dify_agent/layers/test_runtime_layer.py+++ /dev/null@@ -1,63 +0,0 @@-from __future__ import annotations--from dataclasses import dataclass, field-from typing import cast--import pytest--from dify_agent.layers.runtime import DifyRuntimeLayer, DifyRuntimeLayerConfig-from dify_agent.runtime_backend import RuntimeLayout, RuntimeLease---@dataclass(slots=True)-class _Backend:- lease: RuntimeLease- acquired: list[str] = field(default_factory=list)- released: list[RuntimeLease] = field(default_factory=list)-- async def acquire(self, binding_ref: str) -> RuntimeLease:- self.acquired.append(binding_ref)- return self.lease-- async def release(self, lease: RuntimeLease) -> None:- self.released.append(lease)---async def test_runtime_layer_acquires_and_releases_operation_scoped_lease() -> None:- lease = cast(- RuntimeLease,- cast(- object,- type(- "Lease",- (),- {- "layout": RuntimeLayout(home_dir="/home/agent", workspace_dir="/workspace"),- "commands": object(),- },- )(),- ),- )- backend = _Backend(lease=lease)- layer = DifyRuntimeLayer.from_config_with_backend(- DifyRuntimeLayerConfig(backend_binding_ref="binding-1"),- backend=backend, # pyright: ignore[reportArgumentType]- )-- async with layer.resource_context():- assert layer.lease is lease- await layer.on_context_create()- await layer.on_context_suspend()- await layer.on_context_delete()-- assert backend.acquired == ["binding-1"]- assert backend.released == [lease]- with pytest.raises(RuntimeError, match="resource_context"):- _ = layer.lease---def test_runtime_layer_config_contains_only_backend_binding_ref() -> None:- config = DifyRuntimeLayerConfig(backend_binding_ref="binding-1")-- assert config.model_dump() == {"backend_binding_ref": "binding-1"}diff --git a/dify-agent/tests/local/dify_agent/layers/user_prompt/test_layer.py b/dify-agent/tests/local/dify_agent/layers/user_prompt/test_layer.pyindex 3c8927bd732..c975b8ef4c4 100644--- a/dify-agent/tests/local/dify_agent/layers/user_prompt/test_layer.py+++ b/dify-agent/tests/local/dify_agent/layers/user_prompt/test_layer.py@@ -7,8 +7,8 @@ from pydantic import ValidationErrorfrom pydantic_ai.messages import BinaryContent, ImageUrlfrom dify_agent.layers.user_prompt import DifyUserPromptLayerConfig-from dify_agent.layers.user_prompt.layer import DifyUserPromptLayer-from dify_agent.runtime.compositor_factory import create_default_layer_providers+from dify_agent.layers.user_prompt.layer import Capability+from tests.local.dify_agent.module_support import deps_for@pytest.mark.parametrize("include_image", [False, True])@@ -59,9 +59,9 @@ def test_user_prompt_layer_injects_file_locators(include_image: bool, download_t],})- layer = DifyUserPromptLayer.from_config(DifyUserPromptLayerConfig.model_validate_json(config.model_dump_json()))+ layer = _content(DifyUserPromptLayerConfig.model_validate_json(config.model_dump_json()))- prompts = layer.user_prompts+ prompts = layerassert prompts[0] == ("Inspect these files.\n"@@ -72,9 +72,8 @@ def test_user_prompt_layer_injects_file_locators(include_image: bool, download_t'{"transfer_method":"tool_file","reference":"dify-file-ref:tool-file-1"},''{"transfer_method":"datasource_file","reference":"dify-file-ref:datasource-file-1"}]')- assert layer.config.text == "Inspect these files."- assert "locators" not in layer.config.model_dump()- assert layer.user_prompts == prompts+ assert config.text == "Inspect these files."+ assert "locators" not in config.model_dump()assert len(prompts) == (2 if include_image else 1)if include_image:assert isinstance(prompts[1], ImageUrl)@@ -103,13 +102,13 @@ def test_user_prompt_layer_rejects_invalid_locators(locator: dict[str, str]) ->def test_user_prompt_layer_preserves_text_without_locators() -> None:- layer = DifyUserPromptLayer.from_config(DifyUserPromptLayerConfig(text=" Original prompt.\n"))+ layer = _content(DifyUserPromptLayerConfig(text=" Original prompt.\n"))- assert layer.user_prompts == [" Original prompt.\n"]+ assert layer == [" Original prompt.\n"]def test_user_prompt_layer_restores_image_url_content() -> None:- layer = DifyUserPromptLayer.from_config(+ layer = _content(DifyUserPromptLayerConfig.model_validate({"text": "What is in this image?",@@ -128,7 +127,7 @@ def test_user_prompt_layer_restores_image_url_content() -> None:))- prompts = layer.user_prompts+ prompts = layerassert prompts[0] == "What is in this image?"assert isinstance(prompts[1], ImageUrl)@@ -139,7 +138,7 @@ def test_user_prompt_layer_restores_image_url_content() -> None:def test_user_prompt_layer_restores_inline_binary_content() -> None:payload = base64.b64encode(b"image-bytes").decode()- layer = DifyUserPromptLayer.from_config(+ layer = _content(DifyUserPromptLayerConfig.model_validate({"text": "Describe it.",@@ -157,7 +156,7 @@ def test_user_prompt_layer_restores_inline_binary_content() -> None:))- content = layer.user_prompts[1]+ content = layer[1]assert isinstance(content, BinaryContent)assert content.data == b"image-bytes"@@ -190,9 +189,5 @@ def test_user_prompt_file_requires_exactly_one_transport(file_payload: dict[str,DifyUserPromptLayerConfig.model_validate({"text": "Describe it.", "files": [file_payload]})-def test_default_compositor_registers_user_prompt_layer() -> None:- provider = next(provider for provider in create_default_layer_providers() if provider.type_id == "dify.user_prompt")-- layer = provider.create_layer({"text": "Describe it."})-- assert isinstance(layer, DifyUserPromptLayer)+def _content(config):+ return Capability("user_prompt").build_user_content(deps_for("user_prompt", config))diff --git a/dify-agent/tests/local/dify_agent/module_support.py b/dify-agent/tests/local/dify_agent/module_support.pynew file mode 100644index 00000000000..18f7f8fa8d6--- /dev/null+++ b/dify-agent/tests/local/dify_agent/module_support.py@@ -0,0 +1,35 @@+"""Data builders for module behavior tests; no legacy runtime is emulated."""++import httpx+from pydantic import BaseModel+from dify_agent.runtime.context import Deps, Services+++def deps_for(name: str, config: BaseModel | dict, state: dict | None = None) -> Deps:+ return Deps(+ layers={+ name: {+ "config": config.model_dump(mode="json") if isinstance(config, BaseModel) else config,+ "state": state or {},+ }+ },+ services=Services(httpx.AsyncClient(), httpx.AsyncClient()),+ run_id="test",+ )+++async def invoke_native_tool(deps, toolset, name, arguments, *, inspect=None):+ """Exercise schema preparation, validation and invocation in the real Agent."""+ from pydantic_ai import Agent+ from pydantic_ai.messages import ModelRequest, ModelResponse, ToolReturnPart, ToolCallPart, TextPart+ from pydantic_ai.models.function import FunctionModel++ async def model(messages, info):+ if inspect is not None:+ inspect(info)+ returns = [p for m in messages if isinstance(m, ModelRequest) for p in m.parts if isinstance(p, ToolReturnPart)]+ if not returns:+ return ModelResponse(parts=[ToolCallPart(name, arguments, tool_call_id="call")])+ return ModelResponse(parts=[TextPart(str(returns[-1].content))])++ return await Agent(FunctionModel(model), deps_type=Deps, toolsets=[toolset]).run("Use the tool", deps=deps)diff --git a/dify-agent/tests/local/dify_agent/protocol/test_protocol_schemas.py b/dify-agent/tests/local/dify_agent/protocol/test_protocol_schemas.pyindex d04611449eb..1aafd7e718a 100644--- a/dify-agent/tests/local/dify_agent/protocol/test_protocol_schemas.py+++ b/dify-agent/tests/local/dify_agent/protocol/test_protocol_schemas.py@@ -4,41 +4,22 @@ import pytestfrom pydantic import ValidationErrorfrom pydantic_ai.messages import FinalResultEvent-from agenton.compositor import CompositorSessionSnapshot-from agenton.layers import ExitIntent-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig+from dify_agent.protocol.snapshot import SessionSnapshotimport dify_agent.protocol as protocol_exports-from dify_agent.layers.ask_human import DifyAskHumanLayerConfig-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig-from dify_agent.layers.dify_plugin import DIFY_PLUGIN_LLM_LAYER_TYPE_ID, DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID-from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfigfrom dify_agent.protocol import DIFY_AGENT_HISTORY_LAYER_ID, DIFY_AGENT_MODEL_LAYER_ID, DIFY_AGENT_OUTPUT_LAYER_IDfrom dify_agent.protocol.schemas import (AgentRunUsage,RUN_EVENT_ADAPTER,CreateRunRequest,- DeferredToolCallPayload,- LayerExitSignals,PydanticAIStreamRunEvent,RunCancelledEvent,RunCancelledEventData,- RunComposition,RunFailedEvent,RunFailedEventData,RunFailureType,- RunLayerSpec,RunStartedEvent,RunSucceededEvent,RunSucceededEventData,- normalize_composition,-)-from dify_agent.layers.dify_plugin.configs import (- DifyPluginLLMLayerConfig,- DifyPluginToolConfig,- DifyPluginToolParameter,- DifyPluginToolParameterForm,- DifyPluginToolParameterType,- DifyPluginToolsLayerConfig,)@@ -54,19 +35,7 @@ def test_run_event_adapter_round_trips_typed_variants() -> None:run_id="run-1",data=RunSucceededEventData(output={"answer": ["done"]},- session_snapshot=CompositorSessionSnapshot(layers=[]),- ),- ),- RunSucceededEvent(- run_id="run-2",- data=RunSucceededEventData(- deferred_tool_call=DeferredToolCallPayload(- tool_call_id="tool-call-1",- tool_name="ask_human",- args={"question": "Need approval"},- metadata={"layer_type": "dify.ask_human"},- ),- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),),RunFailedEvent(@@ -120,7 +89,7 @@ def test_run_failed_event_error_type_is_optional_and_round_trips() -> None:@pytest.mark.parametrize("event_type", ["run_failed", "run_cancelled"])def test_non_success_terminal_event_round_trips_optional_snapshot(event_type: str) -> None:- snapshot = CompositorSessionSnapshot(layers=[])+ snapshot = SessionSnapshot(layers={})event: RunFailedEvent | RunCancelledEventif event_type == "run_failed":event = RunFailedEvent(@@ -169,293 +138,15 @@ def test_protocol_package_no_longer_exports_execution_context_dto() -> None:assert not hasattr(protocol_exports, "RunPurpose")-def test_create_run_request_accepts_dto_first_public_composition_and_normalizes_graph_config() -> None:- prompt_config = PromptLayerConfig(prefix="system", user="hello")- execution_context_config = DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_from="account",- workflow_id="workflow-1",- workflow_run_id="workflow-run-1",- node_id="node-1",- node_execution_id="node-execution-1",- agent_mode="workflow_run",- invoke_from="service-api",- trace_id="trace-1",- )- llm_config = DifyPluginLLMLayerConfig(- plugin_id="langgenius/openai",- model_provider="openai",- model="demo-model",- )- output_config = DifyOutputLayerConfig(- json_schema={- "type": "object",- "properties": {"title": {"type": "string"}},- "required": ["title"],- "additionalProperties": False,- }- )- request = CreateRunRequest(- idempotency_key="workflow-run-1:node-execution-1",- metadata={"source": "unit_test"},- composition=RunComposition(- layers=[- RunLayerSpec(name="prompt", type=PLAIN_PROMPT_LAYER_TYPE_ID, config=prompt_config),- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=execution_context_config,- ),- RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,- deps={"execution_context": "execution_context"},- config=llm_config,- ),- RunLayerSpec(- name=DIFY_AGENT_OUTPUT_LAYER_ID,- type=DIFY_OUTPUT_LAYER_TYPE_ID,- config=output_config,- ),- ]- ),- )-- graph_config, layer_configs = normalize_composition(request.composition)- payload = request.model_dump(mode="json")-- assert payload["composition"]["layers"][1]["config"] == {- "tenant_id": "tenant-1",- "user_id": None,- "user_from": "account",- "app_id": None,- "workflow_id": "workflow-1",- "workflow_run_id": "workflow-run-1",- "node_id": "node-1",- "node_execution_id": "node-execution-1",- "conversation_id": None,- "agent_id": None,- "agent_config_version_id": None,- "agent_config_version_kind": None,- "agent_mode": "workflow_run",- "invoke_from": "service-api",- "trace_id": "trace-1",- }- assert payload["idempotency_key"] == "workflow-run-1:node-execution-1"- assert payload["metadata"] == {"source": "unit_test"}- assert payload["composition"]["layers"][0]["config"] == {"prefix": "system", "user": "hello", "suffix": []}- assert [layer.model_dump(mode="json") for layer in graph_config.layers] == [- {"name": "prompt", "type": PLAIN_PROMPT_LAYER_TYPE_ID, "deps": {}, "metadata": {}},- {- "name": "execution_context",- "type": DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- "deps": {},- "metadata": {},- },- {- "name": DIFY_AGENT_MODEL_LAYER_ID,- "type": DIFY_PLUGIN_LLM_LAYER_TYPE_ID,- "deps": {"execution_context": "execution_context"},- "metadata": {},- },- {- "name": DIFY_AGENT_OUTPUT_LAYER_ID,- "type": DIFY_OUTPUT_LAYER_TYPE_ID,- "deps": {},- "metadata": {},- },- ]- assert layer_configs == {- "prompt": prompt_config,- "execution_context": execution_context_config,- DIFY_AGENT_MODEL_LAYER_ID: llm_config,- DIFY_AGENT_OUTPUT_LAYER_ID: output_config,- }---def test_create_run_request_accepts_deferred_tool_results_payload() -> None:- request = CreateRunRequest.model_validate(- {- "composition": {- "layers": [- {"name": "prompt", "type": PLAIN_PROMPT_LAYER_TYPE_ID, "config": {"user": "hello"}},- {"name": "ask_human", "type": "dify.ask_human", "config": DifyAskHumanLayerConfig().model_dump()},- ]- },- "deferred_tool_results": {- "calls": {- "tool-call-1": {- "status": "submitted",- "action": {"id": "submit", "label": "Submit"},- "values": {"comment": "Looks good."},- }- }- },- }- )-- assert request.deferred_tool_results is not None- assert request.deferred_tool_results.calls["tool-call-1"] == {- "status": "submitted",- "action": {"id": "submit", "label": "Submit"},- "values": {"comment": "Looks good."},- }---def test_create_run_request_accepts_plugin_tools_layer_with_prepared_parameters_and_schema() -> None:- request = CreateRunRequest.model_validate(- {- "composition": {- "layers": [- {"name": "prompt", "type": PLAIN_PROMPT_LAYER_TYPE_ID, "config": {"user": "hello"}},- {- "name": "execution_context",- "type": DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- "config": {- "tenant_id": "tenant-1",- "user_from": "account",- "agent_mode": "workflow_run",- "invoke_from": "service-api",- },- },- {- "name": DIFY_AGENT_MODEL_LAYER_ID,- "type": DIFY_PLUGIN_LLM_LAYER_TYPE_ID,- "deps": {"execution_context": "execution_context"},- "config": {- "plugin_id": "langgenius/openai",- "model_provider": "openai",- "model": "demo-model",- "credentials": {"api_key": "secret"},- },- },- {- "name": "tools",- "type": DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,- "deps": {"execution_context": "execution_context"},- "config": {- "tools": [- {- "plugin_id": "langgenius/search",- "provider": "search",- "tool_name": "web_search",- "credential_type": "api-key",- "runtime_parameters": {"site": "docs.dify.ai"},- "parameters": [- {- "name": "query",- "type": "string",- "form": "llm",- "required": True,- "llm_description": "Search query",- },- {- "name": "site",- "type": "string",- "form": "form",- "required": True,- "llm_description": "Hidden site",- },- ],- "parameters_json_schema": {- "type": "object",- "properties": {"query": {"type": "string", "description": "Search query"}},- "required": ["query"],- },- }- ]- },- },- ]- }- }- )-- graph_config, layer_configs = normalize_composition(request.composition)-- assert [layer.type for layer in graph_config.layers] == [- PLAIN_PROMPT_LAYER_TYPE_ID,- DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,- DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,- ]- assert DifyPluginToolsLayerConfig.model_validate(layer_configs["tools"]) == DifyPluginToolsLayerConfig(- tools=[- DifyPluginToolConfig(- plugin_id="langgenius/search",- provider="search",- tool_name="web_search",- credential_type="api-key",- runtime_parameters={"site": "docs.dify.ai"},- parameters=[- DifyPluginToolParameter(- name="query",- type=DifyPluginToolParameterType.STRING,- form=DifyPluginToolParameterForm.LLM,- required=True,- llm_description="Search query",- ),- DifyPluginToolParameter(- name="site",- type=DifyPluginToolParameterType.STRING,- form=DifyPluginToolParameterForm.FORM,- required=True,- llm_description="Hidden site",- ),- ],- parameters_json_schema={- "type": "object",- "properties": {"query": {"type": "string", "description": "Search query"}},- "required": ["query"],- },- )- ]- )---def test_on_exit_default_to_suspend_and_are_public() -> None:- assert protocol_exports.LayerExitSignals is LayerExitSignals- assert protocol_exports.RunComposition is RunComposition- assert protocol_exports.RunLayerSpec is RunLayerSpec- assert protocol_exports.normalize_composition is normalize_composition- assert protocol_exports.DIFY_AGENT_OUTPUT_LAYER_ID == DIFY_AGENT_OUTPUT_LAYER_ID- request = CreateRunRequest.model_validate({"composition": {"layers": []}})-- assert request.on_exit.default is ExitIntent.SUSPEND- assert request.on_exit.layers == {}---def test_run_succeeded_event_data_requires_exactly_one_result_variant() -> None:- snapshot = CompositorSessionSnapshot(layers=[])-- with pytest.raises(ValidationError, match="Exactly one of output or deferred_tool_call must be set"):- _ = RunSucceededEventData(session_snapshot=snapshot)-- with pytest.raises(ValidationError, match="Exactly one of output or deferred_tool_call must be set"):- _ = RunSucceededEventData(- output="done",- deferred_tool_call=DeferredToolCallPayload(- tool_call_id="tool-call-1",- tool_name="ask_human",- args={"question": "Need approval"},- ),- session_snapshot=snapshot,- )---def test_run_succeeded_event_data_allows_explicit_json_null_output() -> None:- snapshot = CompositorSessionSnapshot(layers=[])-- data = RunSucceededEventData(output=None, session_snapshot=snapshot)-- assert data.output is None- assert data.deferred_tool_call is None+def test_run_succeeded_event_data_requires_output() -> None:+ with pytest.raises(ValidationError, match="output"):+ RunSucceededEventData(session_snapshot=SessionSnapshot())def test_run_succeeded_event_round_trips_explicit_json_null_output() -> None:event = RunSucceededEvent(run_id="run-null-output",- data=RunSucceededEventData(output=None, session_snapshot=CompositorSessionSnapshot(layers=[])),+ data=RunSucceededEventData(output=None, session_snapshot=SessionSnapshot(layers={})),)payload = RUN_EVENT_ADAPTER.dump_json(event)@@ -463,7 +154,6 @@ def test_run_succeeded_event_round_trips_explicit_json_null_output() -> None:assert isinstance(decoded, RunSucceededEvent)assert decoded.data.output is None- assert decoded.data.deferred_tool_call is Noneassert b'"output":null' in payloadassert b'"deferred_tool_call"' not in payload@@ -473,7 +163,7 @@ def test_run_succeeded_event_round_trips_usage() -> None:run_id="run-usage",data=RunSucceededEventData(output="done",- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),usage=AgentRunUsage(prompt_tokens=3, completion_tokens=5),),)@@ -525,7 +215,7 @@ def test_run_succeeded_event_round_trips_complete_pricing_usage() -> None:run_id="run-priced-usage",data=RunSucceededEventData(output="done",- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),usage=AgentRunUsage(prompt_tokens=10,prompt_unit_price=Decimal("5"),@@ -559,21 +249,6 @@ def test_run_succeeded_event_round_trips_complete_pricing_usage() -> None:assert decoded.data.usage.time_to_generate == 0.3-def test_on_exit_accept_layer_overrides() -> None:- request = CreateRunRequest.model_validate(- {- "composition": {"layers": []},- "on_exit": {- "default": "delete",- "layers": {"prompt": "suspend", "llm": "delete"},- },- }- )-- assert request.on_exit.default is ExitIntent.DELETE- assert request.on_exit.layers == {"prompt": ExitIntent.SUSPEND, "llm": ExitIntent.DELETE}--def test_create_run_request_rejects_removed_top_level_execution_context() -> None:with pytest.raises(ValidationError):_ = CreateRunRequest.model_validate(@@ -599,11 +274,6 @@ def test_create_run_request_rejects_removed_top_level_purpose() -> None:)-def test_layer_exit_signals_reject_extra_fields() -> None:- with pytest.raises(ValidationError):- _ = LayerExitSignals.model_validate({"default": "suspend", "unknown": "value"})--@pytest.mark.parametrize("event_type", ["agent_output", "session_snapshot"])def test_removed_non_terminal_payload_events_are_rejected(event_type: str) -> None:with pytest.raises(ValidationError):diff --git a/dify-agent/tests/local/dify_agent/runtime/test_agent_observability.py b/dify-agent/tests/local/dify_agent/runtime/test_agent_observability.pyindex 3a20a40e766..751005137b7 100644--- a/dify-agent/tests/local/dify_agent/runtime/test_agent_observability.py+++ b/dify-agent/tests/local/dify_agent/runtime/test_agent_observability.py@@ -21,6 +21,8 @@ from pydantic_ai.models.test import TestModelimport dify_agent.server.observability as server_observabilityfrom dify_agent.layers.execution_context import DifyExecutionContextLayerConfig+from pydantic_ai.toolsets import FunctionToolset+from dify_agent.runtime.agent_factory import DIFY_AGENT_RUN_NAME, create_agentfrom dify_agent.runtime.observability import (DIFY_TENANT_ID_ATTRIBUTE,@@ -80,7 +82,9 @@ def test_create_agent_instrument_disabled_survives_global_instrument_all() -> Notry:Agent.instrument_all(InstrumentationSettings(tracer_provider=platform_provider))- agent = create_agent(TestModel(custom_output_text="done"), tools=[])+ agent = create_agent(+ TestModel(custom_output_text="done"), toolsets=[FunctionToolset(tools=[])], capabilities=[]+ )assert agent.instrument is False_ = agent.run_sync("test-only input")@@ -99,7 +103,11 @@ def test_agent_observability_runs_agent_spans_to_business_exporter_only() -> Nontry:Agent.instrument_all(InstrumentationSettings(tracer_provider=platform_provider))observability = AgentObservability(client=client)- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])+ agent = create_agent(+ TestModel(custom_output_text="done"),+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],+ capabilities=[],+ )observability.instrument(agent)_ = agent.run_sync("test-only input")@@ -125,7 +133,11 @@ def test_agent_observability_excludes_content_by_default() -> None:client = _local_client(exporter)try:observability = AgentObservability(client=client, include_content=False)- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])+ agent = create_agent(+ TestModel(custom_output_text="done"),+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],+ capabilities=[],+ )observability.instrument(agent)_ = agent.run_sync("content-sentinel-input-1")@@ -145,7 +157,11 @@ def test_agent_observability_includes_content_when_opted_in() -> None:client = _local_client(exporter)try:observability = AgentObservability(client=client, include_content=True)- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])+ agent = create_agent(+ TestModel(custom_output_text="done"),+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],+ capabilities=[],+ )observability.instrument(agent)_ = agent.run_sync("content-sentinel-input-2")@@ -166,7 +182,11 @@ def test_business_agent_root_detaches_from_platform_parent_span() -> None:business_client = _local_client(business_exporter)try:observability = AgentObservability(client=business_client)- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])+ agent = create_agent(+ TestModel(custom_output_text="done"),+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],+ capabilities=[],+ )observability.instrument(agent)with platform_client.span("platform-incoming-request"):@@ -194,7 +214,9 @@ def test_agent_shutdown_does_not_stop_platform_pipeline() -> None:try:Agent.instrument_all(InstrumentationSettings(tracer_provider=platform_client.config.get_tracer_provider()))observability = AgentObservability(client=business_client)- agent = create_agent(TestModel(custom_output_text="done"), tools=[])+ agent = create_agent(+ TestModel(custom_output_text="done"), toolsets=[FunctionToolset(tools=[])], capabilities=[]+ )observability.instrument(agent)_ = agent.run_sync("test-only input")assert business_client.force_flush(timeout_millis=10000)@@ -234,7 +256,11 @@ def test_business_descendants_stay_in_business_trace_and_caller_context_restoredbusiness_client = _local_client(business_exporter)try:observability = AgentObservability(client=business_client)- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])+ agent = create_agent(+ TestModel(custom_output_text="done"),+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],+ capabilities=[],+ )observability.instrument(agent)with platform_client.span("platform-incoming-request") as platform_span:@@ -278,7 +304,9 @@ def test_platform_httpx_client_span_detaches_from_business_parent() -> None:return http.get("http://test-only.local/ping").textobservability = AgentObservability(client=business_client)- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(net_tool)])+ agent = create_agent(+ TestModel(custom_output_text="done"), toolsets=[FunctionToolset(tools=[Tool(net_tool)])], capabilities=[]+ )observability.instrument(agent)with platform_client.span("platform-incoming-request"):@@ -406,7 +434,11 @@ def test_concurrent_agent_runs_have_independent_business_roots() -> None:observability = AgentObservability(client=business_client)agents = []for index in range(2):- agent = create_agent(TestModel(custom_output_text=f"done-{index}"), tools=[Tool(_static_tool)])+ agent = create_agent(+ TestModel(custom_output_text=f"done-{index}"),+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],+ capabilities=[],+ )observability.instrument(agent)agents.append(agent)@@ -494,7 +526,9 @@ def test_shared_trace_context_mode_links_business_run_to_platform_parent() -> Noreturn http.get("http://test-only.local/ping").textobservability = AgentObservability(client=business_client, trace_context_mode="shared")- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(net_tool)])+ agent = create_agent(+ TestModel(custom_output_text="done"), toolsets=[FunctionToolset(tools=[Tool(net_tool)])], capabilities=[]+ )observability.instrument(agent)with platform_client.span("shared-platform-root"):@@ -546,7 +580,11 @@ def test_shared_mode_agent_pipeline_respects_remote_parent_sampling(monkeypatch:observability_instance = server_observability.configure_agent_observability(settings)assert observability_instance is not Nonetry:- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])+ agent = create_agent(+ TestModel(custom_output_text="done"),+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],+ capabilities=[],+ )observability_instance.instrument(agent)unsampled = set_span_in_context(@@ -654,7 +692,11 @@ def test_agent_observability_stamps_dify_context_on_every_run_span(trace_contextclient=client,trace_context_mode=cast(Literal["isolated", "shared"], trace_context_mode),)- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])+ agent = create_agent(+ TestModel(custom_output_text="done"),+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],+ capabilities=[],+ )observability.instrument(agent, execution_context=_workflow_execution_context())_ = agent.run_sync("test-only input")@@ -677,7 +719,11 @@ def test_agent_observability_omits_dify_attributes_without_an_execution_context(client = _local_client(exporter)try:observability = AgentObservability(client=client)- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])+ agent = create_agent(+ TestModel(custom_output_text="done"),+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],+ capabilities=[],+ )observability.instrument(agent)_ = agent.run_sync("test-only input")@@ -700,7 +746,11 @@ def test_dify_attributes_do_not_break_isolated_parent_policy() -> None:business_client = _local_client(business_exporter)try:observability = AgentObservability(client=business_client)- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])+ agent = create_agent(+ TestModel(custom_output_text="done"),+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],+ capabilities=[],+ )observability.instrument(agent, execution_context=_workflow_execution_context())with platform_client.span("platform-incoming-request"):diff --git a/dify-agent/tests/local/dify_agent/runtime/test_compositor_factory.py b/dify-agent/tests/local/dify_agent/runtime/test_compositor_factory.pydeleted file mode 100644index d79e615b73e..00000000000--- a/dify-agent/tests/local/dify_agent/runtime/test_compositor_factory.py+++ /dev/null@@ -1,189 +0,0 @@-import sys-import types-from typing import cast--if "graphon.model_runtime.entities.llm_entities" not in sys.modules:- graphon_module = types.ModuleType("graphon")- model_runtime_module = types.ModuleType("graphon.model_runtime")- entities_module = types.ModuleType("graphon.model_runtime.entities")- llm_entities_module = types.ModuleType("graphon.model_runtime.entities.llm_entities")- message_entities_module = types.ModuleType("graphon.model_runtime.entities.message_entities")-- setattr(llm_entities_module, "LLMResultChunk", type("LLMResultChunk", (), {}))- setattr(llm_entities_module, "LLMUsage", type("LLMUsage", (), {}))-- for name in (- "AssistantPromptMessage",- "AudioPromptMessageContent",- "DocumentPromptMessageContent",- "ImagePromptMessageContent",- "PromptMessage",- "PromptMessageContentUnionTypes",- "PromptMessageTool",- "SystemPromptMessage",- "TextPromptMessageContent",- "ToolPromptMessage",- "UserPromptMessage",- "VideoPromptMessageContent",- ):- setattr(message_entities_module, name, type(name, (), {}))-- sys.modules["graphon"] = graphon_module- sys.modules["graphon.model_runtime"] = model_runtime_module- sys.modules["graphon.model_runtime.entities"] = entities_module- sys.modules["graphon.model_runtime.entities.llm_entities"] = llm_entities_module- sys.modules["graphon.model_runtime.entities.message_entities"] = message_entities_module-- setattr(graphon_module, "model_runtime", model_runtime_module)- setattr(model_runtime_module, "entities", entities_module)- setattr(entities_module, "llm_entities", llm_entities_module)- setattr(entities_module, "message_entities", message_entities_module)--if "jsonschema" not in sys.modules:- jsonschema_module = types.ModuleType("jsonschema")- jsonschema_exceptions_module = types.ModuleType("jsonschema.exceptions")- jsonschema_protocols_module = types.ModuleType("jsonschema.protocols")- jsonschema_validators_module = types.ModuleType("jsonschema.validators")-- class _SchemaError(Exception):- pass-- class _ValidationError(Exception):- path: tuple[object, ...] = ()-- class _Validator:- @staticmethod- def check_schema(schema):- return None-- def __init__(self, schema):- self.schema = schema-- def iter_errors(self, value):- return iter(())-- def _validator_for(schema):- return _Validator-- setattr(jsonschema_module, "SchemaError", _SchemaError)- setattr(jsonschema_exceptions_module, "ValidationError", _ValidationError)- setattr(jsonschema_protocols_module, "Validator", _Validator)- setattr(jsonschema_validators_module, "validator_for", _validator_for)-- sys.modules["jsonschema"] = jsonschema_module- sys.modules["jsonschema.exceptions"] = jsonschema_exceptions_module- sys.modules["jsonschema.protocols"] = jsonschema_protocols_module- sys.modules["jsonschema.validators"] = jsonschema_validators_module--from dify_agent.layers.config import DIFY_CONFIG_LAYER_TYPE_ID, DifyConfigLayerConfig-from dify_agent.layers.config.layer import DifyConfigLayer-from dify_agent.layers.dify_core_tools import DIFY_CORE_TOOLS_LAYER_TYPE_ID, DifyCoreToolsLayerConfig-from dify_agent.layers.dify_core_tools.layer import DifyCoreToolsLayer-from dify_agent.layers.runtime import DIFY_RUNTIME_LAYER_TYPE_ID, DifyRuntimeLayerConfig-from dify_agent.layers.runtime.layer import DifyRuntimeLayer-from dify_agent.layers.shell import DIFY_SHELL_LAYER_TYPE_ID, DifyShellLayerConfig-from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig-from dify_agent.layers.shell.layer import DifyShellLayer-from dify_agent.runtime.compositor_factory import create_default_layer_providers-from dify_agent.runtime_backend import ExecutionBindingBackend, HomeSnapshotBackend, RuntimeBackendProfile---class FakeProvider:- """No-op provider for tests that never actually open a shell resource."""-- async def create(self) -> object:- raise AssertionError("create should not be called by these tests")---def _runtime_backend_profile() -> RuntimeBackendProfile:- return RuntimeBackendProfile(- home_snapshots=cast(HomeSnapshotBackend, cast(object, FakeProvider())),- execution_bindings=cast(ExecutionBindingBackend, cast(object, FakeProvider())),- )---def test_default_layer_providers_register_config_layer() -> None:- providers = create_default_layer_providers()-- config_provider = next(provider for provider in providers if provider.type_id == DIFY_CONFIG_LAYER_TYPE_ID)- config = DifyConfigLayerConfig(agent_id="agent-1")- layer = config_provider.create_layer(config)-- assert isinstance(layer, DifyConfigLayer)- assert layer.type_id == DIFY_CONFIG_LAYER_TYPE_ID- assert layer.config == config---def test_default_layer_providers_register_runtime_layer() -> None:- profile = _runtime_backend_profile()-- providers = create_default_layer_providers(- runtime_backend_profile=profile,- )- shell_provider = next(provider for provider in providers if provider.type_id == DIFY_SHELL_LAYER_TYPE_ID)- shell_layer = shell_provider.create_layer(DifyShellLayerConfig())- runtime_provider = next(provider for provider in providers if provider.type_id == DIFY_RUNTIME_LAYER_TYPE_ID)- runtime_layer = runtime_provider.create_layer(DifyRuntimeLayerConfig(backend_binding_ref="binding-1"))-- assert isinstance(shell_layer, DifyShellLayer)- assert isinstance(runtime_layer, DifyRuntimeLayer)- assert runtime_layer.backend is profile.execution_bindings- assert {provider.type_id for provider in providers} >= {"dify.runtime", "dify.shell"}---def test_default_layer_providers_forward_agent_stub_token_factory() -> None:- captured_calls: list[tuple[DifyExecutionContextLayerConfig, str | None]] = []-- def build_agent_stub_token(- execution_context: DifyExecutionContextLayerConfig,- *,- session_id: str | None,- ) -> str:- captured_calls.append((execution_context, session_id))- return f"token-for:{execution_context.tenant_id}:{session_id}"-- providers = create_default_layer_providers(- runtime_backend_profile=_runtime_backend_profile(),- agent_stub_api_base_url="https://agent.example.com/agent-stub",- agent_stub_token_factory=build_agent_stub_token,- )- shell_provider = next(provider for provider in providers if provider.type_id == DIFY_SHELL_LAYER_TYPE_ID)- shell_layer = shell_provider.create_layer(DifyShellLayerConfig())-- token = shell_layer.agent_stub_token_factory(- DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_id="user-1",- user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- ),- session_id="abc12ff",- )-- assert token == "token-for:tenant-1:abc12ff"- assert captured_calls == [- (- DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_id="user-1",- user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- ),- "abc12ff",- )- ]---def test_default_layer_providers_register_core_tools_layer() -> None:- providers = create_default_layer_providers(inner_api_url="http://dify-api", inner_api_key="inner-secret")-- core_provider = next(provider for provider in providers if provider.type_id == DIFY_CORE_TOOLS_LAYER_TYPE_ID)- layer = core_provider.create_layer(DifyCoreToolsLayerConfig())-- assert isinstance(layer, DifyCoreToolsLayer)- assert layer.type_id == DIFY_CORE_TOOLS_LAYER_TYPE_ID- assert layer.inner_api_url == "http://dify-api"- assert layer.inner_api_key == "inner-secret"- assert layer.config == DifyCoreToolsLayerConfig()diff --git a/dify-agent/tests/local/dify_agent/runtime/test_modules.py b/dify-agent/tests/local/dify_agent/runtime/test_modules.pynew file mode 100644index 00000000000..b54bc6c5dab--- /dev/null+++ b/dify-agent/tests/local/dify_agent/runtime/test_modules.py@@ -0,0 +1,211 @@+"""Native module contracts: canonical JSON data, references and data migration."""++from types import ModuleType++import httpx+import pytest+from pydantic import ValidationError+from pydantic_ai.capabilities import AbstractCapability+from pydantic_ai.messages import ModelRequest, UserPromptPart+from pydantic_ai.toolsets import AbstractToolset++from dify_agent.layers import history+from dify_agent.layers.prompt import layer as prompt+from dify_agent.protocol.schemas import CreateRunRequest, RunComposition, RunLayerSpec+from dify_agent.protocol.snapshot import SessionSnapshot+from dify_agent.runtime.context import Services+from dify_agent.runtime.modules import REGISTRY, create_modules, load_modules, snapshot_modules+++def services():+ return Services(httpx.AsyncClient(), httpx.AsyncClient())+++def request(*extra: RunLayerSpec, snapshot: SessionSnapshot | None = None) -> CreateRunRequest:+ return CreateRunRequest(+ composition=RunComposition(+ layers=[+ RunLayerSpec(+ name="execution_context",+ config={"tenant_id": "tenant", "agent_mode": "agent_app", "invoke_from": "web-app"},+ ),+ RunLayerSpec(name="llm", config={"plugin_id": "openai", "model_provider": "openai", "model": "demo"}),+ *extra,+ ]+ ),+ session_snapshot=snapshot,+ )+++def test_all_registered_modules_export_native_components(services):+ for module in set(REGISTRY.values()):+ assert hasattr(module, "Config") and hasattr(module, "State")+ assert hasattr(module, "Capability") != hasattr(module, "Toolset")+ implementation = module.Capability if hasattr(module, "Capability") else module.Toolset+ native = AbstractCapability if hasattr(module, "Capability") else AbstractToolset+ assert issubclass(implementation, native)+++def test_one_module_registered_twice_has_independent_json_and_fresh_instances(services):+ registry = {**REGISTRY, "first": prompt, "second": prompt}+ incoming = request(+ RunLayerSpec(name="first", config={"user": "first"}),+ RunLayerSpec(name="second", config={"user": "second"}),+ RunLayerSpec(name="history"),+ )+ a = load_modules(incoming, services, "a", registry=registry)+ b = load_modules(incoming, services, "b", registry=registry)+ assert a.layers["first"]["config"]["user"] == "first"+ assert a.layers["second"]["config"]["user"] == "second"+ a.layers["first"]["config"]["user"] = "changed"+ assert b.layers["first"]["config"]["user"] == "first"+ assert incoming.composition.layers[2].config["user"] == "first"+ assert create_modules(a, registry=registry)["first"] is not create_modules(b, registry=registry)["first"]+ assert "config" not in snapshot_modules(a, registry=registry).layers["history"]+++def test_state_requires_explicit_json_writeback(services):+ incoming = request(RunLayerSpec(name="history"))+ deps = load_modules(incoming, services, "test")+ parsed = history.State.model_validate(deps.layers["history"]["state"])+ parsed.messages.append(ModelRequest(parts=[UserPromptPart(content="saved")]))+ assert deps.layers["history"]["state"]["messages"] == []+ deps.layers["history"]["state"] = parsed.model_dump(mode="json")+ # Persistence uses the module-owned dump, independent of current config.+ snap = snapshot_modules(deps)+ again = load_modules(request(RunLayerSpec(name="history"), snapshot=snap), services, "again")+ again.layers["history"]["state"]["messages"].append({"kind": "request", "parts": []})+ assert len(snap.layers["history"]["messages"]) == 1+ assert history.State.model_validate(snap.layers["history"]).messages == parsed.messages+++ "spec,error",+ [+ (RunLayerSpec(name="unknown"), "Unknown registered module"),+ (RunLayerSpec(name="llm"), "unique"),+ (RunLayerSpec(name="tools", config={"execution_context": "missing"}), "reference execution_context"),+ (RunLayerSpec(name="shell", config={"runtime": "execution_context"}), "reference runtime"),+ ],+)+def test_invalid_module_or_reference_is_rejected_before_io(spec, error, services):+ with pytest.raises(ValueError, match=error):+ load_modules(request(spec), services, "test")+++def test_snapshot_uses_current_config_and_drops_removed_optional_slots(services):+ incoming = request(+ RunLayerSpec(name="prompt", config={"user": "current"}),+ snapshot=SessionSnapshot(layers={"prompt": {}, "tools": {}}),+ )+ deps = load_modules(incoming, services, "test")+ assert deps.layers["prompt"]["config"]["user"] == "current"+ assert "tools" not in snapshot_modules(deps).layers+ with pytest.raises(ValueError, match="Unknown snapshot modules"):+ load_modules(request(snapshot=SessionSnapshot(layers={"unregistered": {}})), services, "bad")+++def test_legacy_snapshot_conversion_preserves_only_retained_state():+ snapshot = SessionSnapshot.model_validate(+ {+ "schema_version": 1,+ "layers": [+ {"name": "shell", "lifecycle_state": "suspended", "runtime_state": {"job_ids": [], "job_offsets": {}}},+ {+ "name": "config",+ "lifecycle_state": "new",+ "runtime_state": {+ "pulled_skill_outputs": {"skill": "content"},+ "config_context_json": "obsolete manifest",+ "config_cli_help": {"config": "obsolete help"},+ "push_spec_json_schema": "obsolete",+ },+ },+ {"name": "history", "lifecycle_state": "suspended", "runtime_state": {"messages": []}},+ {"name": "ask_human", "lifecycle_state": "suspended", "runtime_state": {"pending": "obsolete"}},+ ],+ }+ )+ assert snapshot.schema_version == 2+ assert snapshot.layers["shell"]["initialized"] is True+ assert snapshot.layers["config"] == {"initialized": False, "pulled_skill_outputs": {"skill": "content"}}+ assert snapshot.layers["history"] == {"messages": []}+ assert "ask_human" not in snapshot.layers+ assert SessionSnapshot.model_validate_json(snapshot.model_dump_json()) == snapshot+++ "slot",+ [+ {"name": "custom", "lifecycle_state": "suspended", "runtime_state": {}},+ {"name": "shell", "lifecycle_state": "active", "runtime_state": {}},+ {"name": "shell", "lifecycle_state": "suspended", "runtime_state": None},+ ],+)+def test_invalid_legacy_state_is_rejected(slot):+ with pytest.raises(ValidationError):+ SessionSnapshot.model_validate({"schema_version": 1, "layers": [slot]})+++def test_duplicate_removed_legacy_slots_are_rejected():+ slot = {"name": "ask_human", "lifecycle_state": "suspended", "runtime_state": {}}+ with pytest.raises(ValidationError, match="Duplicate"):+ SessionSnapshot.model_validate({"schema_version": 1, "layers": [slot, slot]})+++async def test_native_sequential_tools_commit_json_state_without_lost_updates():+ import asyncio+ from pydantic import BaseModel+ from pydantic_ai import Agent, RunContext+ from pydantic_ai.messages import ModelRequest, ModelResponse, TextPart, ToolCallPart, ToolReturnPart+ from pydantic_ai.models.function import FunctionModel+ from pydantic_ai.toolsets import FunctionToolset+ from dify_agent.runtime.context import Deps++ class Config(BaseModel):+ pass++ class State(BaseModel):+ count: int = 0++ class Toolset(FunctionToolset[Deps]):+ def __init__(self, name):+ super().__init__(id=name, sequential=True)+ self.name = name++ @self.tool+ async def increment(ctx: RunContext[Deps]) -> int:+ """Persist one increment across an async operation."""+ data = ctx.deps.layers[self.name]+ state = State.model_validate(data["state"])+ await asyncio.sleep(0)+ state.count += 1+ data["state"] = state.model_dump(mode="json")+ return state.count++ module = ModuleType("counter")+ module.Config = Config+ module.State = State+ module.Toolset = Toolset+ registry = {**REGISTRY, "counter": module}++ async def model(messages, info):+ parts = [p for m in messages if isinstance(m, ModelRequest) for p in m.parts if isinstance(p, ToolReturnPart)]+ if not parts:+ assert info.function_tools[0].sequential+ return ModelResponse(+ parts=[+ ToolCallPart("increment", {}, tool_call_id="one"),+ ToolCallPart("increment", {}, tool_call_id="two"),+ ]+ )+ assert [p.content for p in parts] == [1, 2]+ return ModelResponse(parts=[TextPart("done")])++ async with httpx.AsyncClient() as client:+ deps = load_modules(request(RunLayerSpec(name="counter")), Services(client, client), "test", registry=registry)+ native = create_modules(deps, registry=registry)["counter"]+ await Agent(FunctionModel(model), deps_type=Deps, toolsets=[native]).run("increment twice", deps=deps)+ assert snapshot_modules(deps, registry=registry).layers["counter"] == {"count": 2}diff --git a/dify-agent/tests/local/dify_agent/runtime/test_run_scheduler.py b/dify-agent/tests/local/dify_agent/runtime/test_run_scheduler.pyindex 71af4d7a3f0..fb43ce70103 100644--- a/dify-agent/tests/local/dify_agent/runtime/test_run_scheduler.py+++ b/dify-agent/tests/local/dify_agent/runtime/test_run_scheduler.py@@ -1,3 +1,4 @@+from dify_agent.runtime.context import Servicesimport asynciofrom collections import defaultdictfrom collections.abc import Mapping@@ -6,12 +7,11 @@ from typing import castimport httpximport pytest-from agenton.compositor import CompositorSessionSnapshot, LayerSessionSnapshot-from agenton.layers import LifecycleState-from agenton_collections.layers.plain import PromptLayerConfig+from dify_agent.protocol.snapshot import SessionSnapshot+from dify_agent.layers.prompt import Config as PromptConfigfrom dify_agent.layers.dify_plugin import DifyPluginLLMLayerConfig-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig-from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig+from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig+from dify_agent.layers.output import DifyOutputLayerConfigfrom dify_agent.protocol import DIFY_AGENT_MODEL_LAYER_ID, DIFY_AGENT_OUTPUT_LAYER_ID, RunFailureTypefrom dify_agent.protocol.schemas import (AgentRunUsage,@@ -47,36 +47,24 @@ def _request(output_config: Mapping[str, object] | DifyOutputLayerConfig | None = None,) -> CreateRunRequest:layers = [- RunLayerSpec(name="prompt", type="plain.prompt", config=PromptLayerConfig(user=user)),+ RunLayerSpec(name="prompt", config=(PromptConfig(user=user)).model_dump(mode="json")),RunLayerSpec(name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- ),+ config=(+ DifyExecutionContextLayerConfig(+ tenant_id="tenant-1", user_from="account", agent_mode="workflow_run", invoke_from="service-api"+ )+ ).model_dump(mode="json"),),RunLayerSpec(name=DIFY_AGENT_MODEL_LAYER_ID,- type="dify.plugin.llm",- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id="langgenius/openai",- model_provider="openai",- model="demo-model",- ),+ config=(+ DifyPluginLLMLayerConfig(plugin_id="langgenius/openai", model_provider="openai", model="demo-model")+ ).model_dump(mode="json"),),]if output_config is not None:- layers.append(- RunLayerSpec(- name=DIFY_AGENT_OUTPUT_LAYER_ID,- type=DIFY_OUTPUT_LAYER_TYPE_ID,- config=output_config,- )- )+ layers.append(RunLayerSpec(name=DIFY_AGENT_OUTPUT_LAYER_ID, config=output_config))return CreateRunRequest(composition=RunComposition(layers=layers))@@ -176,7 +164,7 @@ class FakeStore:run_id: str,intent: RunCancellationIntent,*,- session_snapshot: CompositorSessionSnapshot | None = None,+ session_snapshot: SessionSnapshot | None = None,usage: AgentRunUsage | None = None,) -> RunFinalizationResult:current_status = self.statuses[run_id]@@ -269,7 +257,7 @@ class CancellationDuringShutdownFailureStore(FakeStore):class SnapshotlessRunner:@property- def terminal_session_snapshot(self) -> CompositorSessionSnapshot | None:+ def terminal_session_snapshot(self) -> SessionSnapshot | None:return None@property@@ -281,7 +269,7 @@ class ControlledRunner:started: asyncio.Eventrelease: asyncio.Eventfinished: asyncio.Event | None- _terminal_session_snapshot: CompositorSessionSnapshot+ _terminal_session_snapshot: SessionSnapshot_terminal_usage: AgentRunUsage | Nonedef __init__(@@ -295,11 +283,11 @@ class ControlledRunner:self.started = startedself.release = releaseself.finished = finished- self._terminal_session_snapshot = CompositorSessionSnapshot(layers=[])+ self._terminal_session_snapshot = SessionSnapshot(layers={})self._terminal_usage = usage@property- def terminal_session_snapshot(self) -> CompositorSessionSnapshot:+ def terminal_session_snapshot(self) -> SessionSnapshot:return self._terminal_session_snapshot@property@@ -343,7 +331,7 @@ class SuccessThenWaitRunner(SnapshotlessRunner):self.store,run_id=self.run_id,output="done",- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),)assert result.applied is Trueself.finalized.set()@@ -378,7 +366,7 @@ class IgnoreCancellationThenSucceedRunner(SnapshotlessRunner):self.store,run_id=self.run_id,output="late success",- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),)assert result.applied is Falseassert result.status == "running"@@ -410,7 +398,7 @@ class ReleaseThenSucceedRunner(SnapshotlessRunner):self.store,run_id=self.run_id,output="done",- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),)assert result.applied is Truefinally:@@ -458,7 +446,7 @@ class FinalizeSuccessOnCancellationRunner(SnapshotlessRunner):self.store,run_id=self.run_id,output="completed during shutdown",- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),)assert result.applied is True@@ -470,12 +458,11 @@ def test_default_runner_factory_passes_runtime_limits_to_runner() -> None:async with httpx.AsyncClient() as client:scheduler = RunScheduler(store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,run_timeout_seconds=17,stream_text_delta_coalescing_enabled=False,stream_text_delta_flush_interval_seconds=0.25,stream_text_delta_max_chars=2048,+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),)runner = scheduler._default_runner_factory(record, _request(), is_cancelled=lambda: False)@@ -497,16 +484,13 @@ def test_default_runner_factory_passes_agent_observability_instance() -> None:async with httpx.AsyncClient() as client:scheduler = RunScheduler(store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,agent_observability=sentinel,+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),)runner = scheduler._default_runner_factory(record, _request(), is_cancelled=lambda: False)default_scheduler = RunScheduler(- store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,+ store=store, services=Services(plugin_daemon_http_client=client, dify_api_http_client=client))default_runner = default_scheduler._default_runner_factory(record, _request(), is_cancelled=lambda: False)@@ -526,9 +510,8 @@ def test_create_run_starts_background_task_and_returns_running() -> None:async with httpx.AsyncClient() as client:scheduler = RunScheduler(store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,runner_factory=lambda _record, _request: ControlledRunner(started=started, release=release),+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),)record = await scheduler.create_run(_request())@@ -551,10 +534,9 @@ def test_shutdown_marks_unfinished_runs_failed_and_appends_event() -> None:async with httpx.AsyncClient() as client:scheduler = RunScheduler(store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,shutdown_grace_seconds=0,runner_factory=lambda _record, _request: ControlledRunner(started=started, release=asyncio.Event()),+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),)record = await scheduler.create_run(_request())await asyncio.wait_for(started.wait(), timeout=1)@@ -577,13 +559,9 @@ def test_shutdown_failure_finalization_yields_to_concurrent_cancellation_intent(async with httpx.AsyncClient() as client:scheduler = RunScheduler(store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,shutdown_grace_seconds=0,- runner_factory=lambda _record, _request: ControlledRunner(- started=started,- release=asyncio.Event(),- ),+ runner_factory=lambda _record, _request: ControlledRunner(started=started, release=asyncio.Event()),+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),)record = await scheduler.create_run(_request())await asyncio.wait_for(started.wait(), timeout=1)@@ -596,7 +574,7 @@ def test_shutdown_failure_finalization_yields_to_concurrent_cancellation_intent(terminal = store.events[record.run_id][0]assert isinstance(terminal, RunCancelledEvent)assert terminal.data.reason == "concurrent_shutdown_cancel"- assert terminal.data.session_snapshot == CompositorSessionSnapshot(layers=[])+ assert terminal.data.session_snapshot == SessionSnapshot(layers={})asyncio.run(scenario())@@ -610,13 +588,10 @@ def test_cancellation_observer_failure_stops_runner_and_finalizes_failed() -> Noasync with httpx.AsyncClient() as client:scheduler = RunScheduler(store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,runner_factory=lambda _record, _request: ControlledRunner(- started=runner_started,- release=asyncio.Event(),- finished=runner_finished,+ started=runner_started, release=asyncio.Event(), finished=runner_finished),+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),)record = await scheduler.create_run(_request())supervisor_task = scheduler.active_tasks[record.run_id]@@ -645,13 +620,10 @@ def test_cancellation_observer_failure_finalizes_concurrent_intent_after_runner_async with httpx.AsyncClient() as client:scheduler = RunScheduler(store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,runner_factory=lambda _record, _request: ControlledRunner(- started=runner_started,- release=asyncio.Event(),- finished=runner_finished,+ started=runner_started, release=asyncio.Event(), finished=runner_finished),+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),)record = await scheduler.create_run(_request())supervisor_task = scheduler.active_tasks[record.run_id]@@ -671,7 +643,7 @@ def test_cancellation_observer_failure_finalizes_concurrent_intent_after_runner_assert [event.type for event in store.events[record.run_id]] == ["run_cancelled"]terminal = store.events[record.run_id][0]assert isinstance(terminal, RunCancelledEvent)- assert terminal.data.session_snapshot == CompositorSessionSnapshot(layers=[])+ assert terminal.data.session_snapshot == SessionSnapshot(layers={})asyncio.run(scenario())@@ -684,19 +656,16 @@ def test_non_owner_cancel_run_stops_owner_task_and_persists_cancelled_terminal()async with httpx.AsyncClient() as client:owner_scheduler = RunScheduler(store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,runner_factory=lambda _record, _request: ControlledRunner(started=started,release=asyncio.Event(),finished=runner_finished,usage=AgentRunUsage(prompt_tokens=13, completion_tokens=8),),+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),)remote_scheduler = RunScheduler(- store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,+ store=store, services=Services(plugin_daemon_http_client=client, dify_api_http_client=client))record = await owner_scheduler.create_run(_request())owner_task = owner_scheduler.active_tasks[record.run_id]@@ -716,7 +685,7 @@ def test_non_owner_cancel_run_stops_owner_task_and_persists_cancelled_terminal()assert [event.type for event in store.events[record.run_id]] == ["run_cancelled"]terminal = store.events[record.run_id][0]assert isinstance(terminal, RunCancelledEvent)- assert terminal.data.session_snapshot == CompositorSessionSnapshot(layers=[])+ assert terminal.data.session_snapshot == SessionSnapshot(layers={})assert terminal.data.usage is not Noneassert terminal.data.usage.prompt_tokens == 13assert terminal.data.usage.completion_tokens == 8@@ -738,21 +707,12 @@ def test_pre_enter_cancellation_does_not_copy_input_session_snapshot() -> None:store = FakeStore()started = asyncio.Event()request = _request()- request.session_snapshot = CompositorSessionSnapshot(- layers=[- LayerSessionSnapshot(- name="prior",- lifecycle_state=LifecycleState.SUSPENDED,- runtime_state={"value": "prior"},- )- ]- )+ request.session_snapshot = SessionSnapshot(layers={"prior": {"value": "prior"}})async with httpx.AsyncClient() as client:scheduler = RunScheduler(store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,runner_factory=lambda _record, _request: PreEnterBlockingRunner(started=started),+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),)record = await scheduler.create_run(request)supervisor = scheduler.active_tasks[record.run_id]@@ -777,14 +737,10 @@ def test_cancel_run_does_not_override_successful_terminal() -> None:async with httpx.AsyncClient() as client:scheduler = RunScheduler(store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,runner_factory=lambda record, _request: SuccessThenWaitRunner(- store=store,- run_id=record.run_id,- finalized=finalized,- release=release,+ store=store, run_id=record.run_id, finalized=finalized, release=release),+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),)record = await scheduler.create_run(_request())await asyncio.wait_for(finalized.wait(), timeout=1)@@ -811,16 +767,11 @@ def test_cancelled_terminal_survives_shutdown_while_runner_cleanup_is_pending()async with httpx.AsyncClient() as client:scheduler = RunScheduler(store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,shutdown_grace_seconds=0,runner_factory=lambda record, _request: IgnoreCancellationThenSucceedRunner(- store=store,- run_id=record.run_id,- started=started,- release=release,- finished=runner_finished,+ store=store, run_id=record.run_id, started=started, release=release, finished=runner_finished),+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),)record = await scheduler.create_run(_request())supervisor_task = scheduler.active_tasks[record.run_id]@@ -870,8 +821,6 @@ def test_failure_and_cancellation_keep_the_first_terminal(async with httpx.AsyncClient() as client:scheduler = RunScheduler(store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,runner_factory=lambda record, _request: CompetingFailureRunner(store=store,run_id=record.run_id,@@ -879,6 +828,7 @@ def test_failure_and_cancellation_keep_the_first_terminal(release=release_runner,failure_attempted=failure_attempted,),+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),)record = await scheduler.create_run(_request())supervisor_task = scheduler.active_tasks[record.run_id]@@ -916,8 +866,6 @@ def test_shutdown_grace_allows_runner_first_completion_and_reaps_children() -> Nasync with httpx.AsyncClient() as client:scheduler = RunScheduler(store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,shutdown_grace_seconds=1,runner_factory=lambda record, _request: ReleaseThenSucceedRunner(store=store,@@ -926,6 +874,7 @@ def test_shutdown_grace_allows_runner_first_completion_and_reaps_children() -> Nrelease=release_runner,finished=runner_finished,),+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),)record = await scheduler.create_run(_request())supervisor_task = scheduler.active_tasks[record.run_id]@@ -955,14 +904,11 @@ def test_shutdown_does_not_append_failed_after_success_wins() -> None:async with httpx.AsyncClient() as client:scheduler = RunScheduler(store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,shutdown_grace_seconds=0,runner_factory=lambda record, _request: FinalizeSuccessOnCancellationRunner(- store=store,- run_id=record.run_id,- started=started,+ store=store, run_id=record.run_id, started=started),+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),)record = await scheduler.create_run(_request())await asyncio.wait_for(started.wait(), timeout=1)@@ -979,7 +925,9 @@ def test_cancel_run_rejects_finished_run() -> None:async def scenario() -> None:store = FakeStore()async with httpx.AsyncClient() as client:- scheduler = RunScheduler(store=store, plugin_daemon_http_client=client, dify_api_http_client=client)+ scheduler = RunScheduler(+ store=store, services=Services(plugin_daemon_http_client=client, dify_api_http_client=client)+ )record = await store.create_run()store.statuses[record.run_id] = "succeeded"@@ -993,7 +941,9 @@ def test_create_run_accepts_blank_prompt_and_runner_fails_asynchronously() -> Noasync def scenario() -> None:store = FakeStore()async with httpx.AsyncClient() as client:- scheduler = RunScheduler(store=store, plugin_daemon_http_client=client, dify_api_http_client=client)+ scheduler = RunScheduler(+ store=store, services=Services(plugin_daemon_http_client=client, dify_api_http_client=client)+ )record = await scheduler.create_run(_request(["", " "]))await asyncio.wait_for(scheduler.active_tasks[record.run_id], timeout=1)@@ -1010,7 +960,9 @@ def test_create_run_accepts_invalid_output_schema_and_runner_fails_asynchronouslasync def scenario() -> None:store = FakeStore()async with httpx.AsyncClient() as client:- scheduler = RunScheduler(store=store, plugin_daemon_http_client=client, dify_api_http_client=client)+ scheduler = RunScheduler(+ store=store, services=Services(plugin_daemon_http_client=client, dify_api_http_client=client)+ )record = await scheduler.create_run(_request(@@ -1029,69 +981,12 @@ def test_create_run_accepts_invalid_output_schema_and_runner_fails_asynchronouslasyncio.run(scenario())-def test_create_run_honors_explicit_empty_layer_providers_by_failing_after_persisting() -> None:+def test_create_run_rejects_after_shutdown_starts() -> None:async def scenario() -> None:- store = FakeStore()async with httpx.AsyncClient() as client:scheduler = RunScheduler(- store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,- layer_providers=(),- )-- record = await scheduler.create_run(_request())- await asyncio.wait_for(scheduler.active_tasks[record.run_id], timeout=1)-- assert store.records == {record.run_id: record}- assert [event.type for event in store.events[record.run_id]] == ["run_started", "run_failed"]- assert store.statuses[record.run_id] == "failed"- assert "plain.prompt" in (store.errors[record.run_id] or "")-- asyncio.run(scenario())---def test_create_run_accepts_closed_session_snapshot_and_runner_fails_asynchronously() -> None:- async def scenario() -> None:- store = FakeStore()- async with httpx.AsyncClient() as client:- scheduler = RunScheduler(store=store, plugin_daemon_http_client=client, dify_api_http_client=client)- request = _request()- request.session_snapshot = CompositorSessionSnapshot(- layers=[- LayerSessionSnapshot(- name="prompt",- lifecycle_state=LifecycleState.CLOSED,- runtime_state={},- ),- LayerSessionSnapshot(- name="execution_context",- lifecycle_state=LifecycleState.SUSPENDED,- runtime_state={},- ),- LayerSessionSnapshot(- name=DIFY_AGENT_MODEL_LAYER_ID,- lifecycle_state=LifecycleState.SUSPENDED,- runtime_state={},- ),- ]+ store=FakeStore(), services=Services(plugin_daemon_http_client=client, dify_api_http_client=client))-- record = await scheduler.create_run(request)- await asyncio.wait_for(scheduler.active_tasks[record.run_id], timeout=1)-- assert store.records == {record.run_id: record}- assert [event.type for event in store.events[record.run_id]] == ["run_started", "run_failed"]- assert store.statuses[record.run_id] == "failed"- assert "CLOSED snapshots cannot be entered" in (store.errors[record.run_id] or "")-- asyncio.run(scenario())---def test_create_run_rejects_after_shutdown_starts() -> None:- async def scenario() -> None:- async with httpx.AsyncClient() as client:- scheduler = RunScheduler(store=FakeStore(), plugin_daemon_http_client=client, dify_api_http_client=client)await scheduler.shutdown()with pytest.raises(SchedulerStoppingError):@@ -1104,7 +999,9 @@ def test_create_run_rejects_invalid_request_after_shutdown_without_persisting()async def scenario() -> None:store = FakeStore()async with httpx.AsyncClient() as client:- scheduler = RunScheduler(store=store, plugin_daemon_http_client=client, dify_api_http_client=client)+ scheduler = RunScheduler(+ store=store, services=Services(plugin_daemon_http_client=client, dify_api_http_client=client)+ )await scheduler.shutdown()with pytest.raises(SchedulerStoppingError):@@ -1124,12 +1021,11 @@ def test_shutdown_waits_for_in_flight_create_to_register_before_cancelling() ->async with httpx.AsyncClient() as client:scheduler = RunScheduler(store=store,- plugin_daemon_http_client=client,- dify_api_http_client=client,shutdown_grace_seconds=0,runner_factory=lambda _record, _request: ControlledRunner(started=runner_started, release=asyncio.Event()),+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),)create_task = asyncio.create_task(scheduler.create_run(_request()))diff --git a/dify-agent/tests/local/dify_agent/runtime/test_runner.py b/dify-agent/tests/local/dify_agent/runtime/test_runner.pyindex be963726254..ba869daabe5 100644--- a/dify-agent/tests/local/dify_agent/runtime/test_runner.py+++ b/dify-agent/tests/local/dify_agent/runtime/test_runner.py@@ -1,3478 +1,501 @@+"""Run the real native Agent to verify history, output and cleanup boundaries."""+import asyncio-from collections.abc import AsyncIterator, Generator, Iterable, Mapping-from contextlib import contextmanager-from decimal import Decimal-from typing import Any, ClassVar, cast+from dataclasses import replace+from types import SimpleNamespaceimport httpximport pytest-from graphon.model_runtime.entities.llm_entities import LLMUsage-from pydantic import JsonValue-from pydantic_ai import Tool-from pydantic_ai.exceptions import ModelHTTPError, UnexpectedModelBehavior, UsageLimitExceeded+from pydantic_ai import Agent, Tool+from pydantic_ai.exceptions import ModelHTTPError, UsageLimitExceededfrom pydantic_ai.messages import (- ToolReturnPart,- ModelMessage,+ UserPromptPart,ModelRequest,ModelResponse,- SystemPromptPart,- TextPart,+ RetryPromptPart,ToolCallPart,- UserPromptPart,-)-from pydantic_ai.models import ModelRequestParameters-from pydantic_ai.models.function import DeltaToolCall, DeltaToolCalls, FunctionModel-from pydantic_ai.models.test import TestModel-from pydantic_ai.tools import DeferredToolRequests, DeferredToolResults-from pydantic_ai.usage import UsageLimits-from pydantic_ai.settings import ModelSettings-from pydantic_ai_harness.compaction import TieredCompaction--from agenton.compositor import CompositorSessionSnapshot, LayerProvider, LayerSessionSnapshot-from agenton.layers import ExitIntent, LifecycleState-from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID, PydanticAIHistoryRuntimeState-from agenton_collections.layers.plain import PromptLayerConfig, ToolsLayer-from dify_agent.layers.ask_human import DIFY_ASK_HUMAN_LAYER_TYPE_ID, DifyAskHumanLayerConfig-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig-from dify_agent.layers.runtime import DIFY_RUNTIME_LAYER_TYPE_ID, DifyRuntimeLayerConfig-from dify_agent.layers.shell import DIFY_SHELL_LAYER_TYPE_ID, DifyShellLayerConfig-from dify_agent.layers.dify_plugin.configs import (- DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,- DifyPluginLLMLayerConfig,- DifyPluginToolConfig,- DifyPluginToolParameter,- DifyPluginToolParameterForm,- DifyPluginToolParameterType,- DifyPluginToolsLayerConfig,-)-from dify_agent.layers.dify_plugin.llm_layer import DifyPluginLLMLayer-from dify_agent.layers.dify_plugin.tools_layer import DifyPluginToolsLayer-from dify_agent.layers.dify_core_tools.configs import (- DIFY_CORE_TOOLS_LAYER_TYPE_ID,- DifyCoreToolConfig,- DifyCoreToolsLayerConfig,+ ToolReturnPart,)-from dify_agent.layers.dify_core_tools.layer import DifyCoreToolsLayer-from dify_agent.layers.knowledge.client import DifyKnowledgeBaseClientError-from dify_agent.layers.knowledge.configs import DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID, DifyKnowledgeBaseLayerConfig-from dify_agent.layers.knowledge.layer import DifyKnowledgeBaseLayer-from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig-from dify_agent.protocol import DIFY_AGENT_HISTORY_LAYER_ID, DIFY_AGENT_MODEL_LAYER_ID, DIFY_AGENT_OUTPUT_LAYER_ID+from pydantic_ai.models.function import DeltaToolCall, FunctionModel+from pydantic_ai.tools import DeferredToolRequests++from dify_agent.adapters.shell.protocols import ShellCommandResult+from dify_agent.layers import history+from dify_agent.layers.dify_plugin import llm_layerfrom dify_agent.protocol.schemas import (CreateRunRequest,- DeferredToolResultsPayload,- LayerExitSignals,- PydanticAIStreamRunEvent,RunComposition,RunFailedEvent,- RunFailureType,RunLayerSpec,RunSucceededEvent,+ RunFailureType,)--from dify_agent.runtime.observability import AgentObservability+from dify_agent.protocol.snapshot import SessionSnapshot+from dify_agent.runtime.context import Servicesfrom dify_agent.runtime.event_sink import InMemoryRunEventSink-from dify_agent.runtime.compositor_factory import create_default_layer_providers-from dify_agent.runtime.runner import (- AgentRunRunner,- AgentRunValidationError,- RunSuccessOutcome,- _run_failed_error_payload,-)-from dify_agent.runtime_backend import (- ExecutionBindingAllocation,- ExecutionBindingCreateSpec,- ExecutionBindingDestroySpec,- HomeSnapshotBackend,- RuntimeBackendProfile,- RuntimeLayout,- RuntimeLease,-)-from dify_agent.runtime_backend.shellctl import ShellctlRuntimeLease, create_shellctl_lease-from shellctl.shared import DeleteJobResponse, JobResult, JobStatusName, JobStatusView---class StaticToolsTestLayer(ToolsLayer):- type_id: ClassVar[str | None] = "test.static.tools"---class FakeRunnerShellctlClient:- run_calls: list[tuple[str, str | None, Mapping[str, str] | None, float]]- delete_calls: list[tuple[str, bool, float | None]]- closed: bool-- def __init__(self) -> None:- self.run_calls = []- self.delete_calls = []- self.closed = False-- async def run(- self,- script: str,- *,- cwd: str | None = None,- env: Mapping[str, str] | None = None,- timeout: float = 10.0,- ) -> JobResult:- self.run_calls.append((script, cwd, env, timeout))- return JobResult(- job_id="mkdir-job",- status=JobStatusName.EXITED,- done=True,- exit_code=0,- output_path="/tmp/output.log",- output="",- offset=0,- truncated=False,- )-- async def close(self) -> None:- self.closed = True-- async def wait(self, job_id: str, *, offset: int, timeout: float = 10.0) -> JobResult:- del job_id, offset, timeout- raise AssertionError("wait() should not be called in this test")-- async def input(self, job_id: str, text: str, *, offset: int, timeout: float = 10.0) -> JobResult:- del job_id, text, offset, timeout- raise AssertionError("input() should not be called in this test")-- async def terminate(self, job_id: str, grace_seconds: float = 2.0) -> JobStatusView:- del job_id, grace_seconds- raise AssertionError("terminate() should not be called in this test")-- async def delete(- self,- job_id: str,- *,- force: bool = False,- grace_seconds: float | None = None,- ) -> DeleteJobResponse:- self.delete_calls.append((job_id, force, grace_seconds))- return DeleteJobResponse(job_id=job_id)---class FakeRunnerExecutionBindingBackend:- def __init__(self, client: FakeRunnerShellctlClient) -> None:- self.client = client-- async def create_binding(self, spec: ExecutionBindingCreateSpec) -> ExecutionBindingAllocation:- return ExecutionBindingAllocation(binding_ref=spec.binding_id, workspace_ref=spec.workspace_id)-- async def acquire(self, binding_ref: str) -> RuntimeLease:- return create_shellctl_lease(- handle=binding_ref,- layout=RuntimeLayout(- home_dir="/home/agent-1",- workspace_dir="/home/agent-1/workspace/abc12ff",- ),- entrypoint="http://shellctl",- token="",- client_factory=lambda: self.client, # pyright: ignore[reportArgumentType]- )-- async def release(self, lease: RuntimeLease) -> None:- assert isinstance(lease, ShellctlRuntimeLease)- await lease.close()-- async def destroy_binding(self, spec: ExecutionBindingDestroySpec) -> None:- del spec---def test_run_failed_error_payload_preserves_plugin_rate_limit_error() -> None:- exc = ModelHTTPError(- 429,- "gpt-4o-mini",- {"error_type": "InvokeRateLimitError", "message": "quota exceeded"},- )-- message, error_type, reason = _run_failed_error_payload(exc)-- assert message == "quota exceeded"- assert error_type is None- assert reason == "InvokeRateLimitError"---def test_run_failed_error_payload_infers_rate_limit_reason_from_status_code() -> None:- exc = ModelHTTPError(429, "gpt-4o-mini", {"message": "too many requests"})-- message, error_type, reason = _run_failed_error_payload(exc)-- assert message == "too many requests"- assert error_type is None- assert reason == "InvokeRateLimitError"---def test_run_failed_error_payload_preserves_knowledge_error_code() -> None:- exc = DifyKnowledgeBaseClientError(- "Knowledge base search failed with HTTP 400 (dataset_not_found): Dataset not found",- status_code=400,- error_code="dataset_not_found",- retryable=False,- )-- message, error_type, reason = _run_failed_error_payload(exc)+from dify_agent.runtime.runner import AgentRunRunner+from dify_agent.runtime_backend import RuntimeBackendProfile, RuntimeLayout- assert message == "Knowledge base search failed with HTTP 400 (dataset_not_found): Dataset not found"- assert error_type is None- assert reason == "dataset_not_found"--def test_run_failed_error_payload_classifies_usage_limit() -> None:- exc = UsageLimitExceeded("The next request would exceed the request_limit of 500")-- message, error_type, reason = _run_failed_error_payload(exc)-- assert message.startswith("The next request would exceed the request_limit of 500")- assert error_type is RunFailureType.AGENT_RUN_LIMIT_EXCEEDED- assert reason is None---def test_cancelled_runner_does_not_emit_late_failure(- monkeypatch: pytest.MonkeyPatch,-) -> None:- async def scenario() -> None:- sink = InMemoryRunEventSink()- cancelled = False- async with httpx.AsyncClient() as client:- runner = AgentRunRunner(- sink=sink,- request=_request(),- run_id="run-cancelled",- plugin_daemon_http_client=client,- dify_api_http_client=client,- is_cancelled=lambda: cancelled,- )-- async def fail_after_cancel() -> RunSuccessOutcome:- nonlocal cancelled- cancelled = True- raise RuntimeError("late model failure")-- monkeypatch.setattr(runner, "_run_agent", fail_after_cancel)- await runner.run()-- assert "run-cancelled" not in sink.statuses- assert [event.type for event in sink.events["run-cancelled"]] == ["run_started"]-- asyncio.run(scenario())---def _request(- user: str | list[str] = "hello",- *,- include_history: bool = False,- include_ask_human: bool = False,- ask_human_config: DifyAskHumanLayerConfig | None = None,- llm_layer_name: str = DIFY_AGENT_MODEL_LAYER_ID,- execution_context_layer_name: str = "execution_context",- app_id: str | None = None,- agent_id: str | None = None,- on_exit: LayerExitSignals | None = None,- output_config: Mapping[str, object] | DifyOutputLayerConfig | None = None,- model_settings: ModelSettings | None = None,- context_window_tokens: int | None = None,-) -> CreateRunRequest:- layers = [- RunLayerSpec(- name="prompt",- type="plain.prompt",- config=PromptLayerConfig(prefix="system", user=user),- ),- *(- [RunLayerSpec(name=DIFY_AGENT_HISTORY_LAYER_ID, type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID)]- if include_history- else []- ),- *(- [+def request(*extra, snapshot=None, instruction="Current instruction", user="hello"):+ return CreateRunRequest(+ composition=RunComposition(+ layers=[RunLayerSpec(- name="ask_human",- type=DIFY_ASK_HUMAN_LAYER_TYPE_ID,- config=ask_human_config or DifyAskHumanLayerConfig(),- )+ name="execution_context",+ config={+ "tenant_id": "tenant",+ "user_id": "user",+ "user_from": "account",+ "app_id": "app",+ "agent_mode": "agent_app",+ "invoke_from": "web-app",+ },+ ),+ RunLayerSpec(name="llm", config={"plugin_id": "openai", "model_provider": "openai", "model": "demo"}),+ RunLayerSpec(name="prompt", config={"prefix": instruction, "user": user}),+ RunLayerSpec(name="history"),+ *extra,]- if include_ask_human- else []- ),- RunLayerSpec(- name=execution_context_layer_name,- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- app_id=app_id,- agent_id=agent_id,- user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- ),- ),- RunLayerSpec(- name=llm_layer_name,- type="dify.plugin.llm",- deps={"execution_context": execution_context_layer_name},- config=DifyPluginLLMLayerConfig(- plugin_id="langgenius/openai",- model_provider="openai",- model="demo-model",- model_settings=model_settings,- context_window_tokens=context_window_tokens,- ),),- ]- if output_config is not None:- layers.append(- RunLayerSpec(- name=DIFY_AGENT_OUTPUT_LAYER_ID,- type=DIFY_OUTPUT_LAYER_TYPE_ID,- config=output_config,- )+ session_snapshot=snapshot,+ )+++def run_runner(incoming, services, monkeypatch, stream, *, run_id="test", timeout=10):+ model = FunctionModel(stream_function=stream)+ monkeypatch.setattr(llm_layer.Capability, "build_model", lambda self, deps: model)+ sink = InMemoryRunEventSink()+ runner = AgentRunRunner(sink=sink, request=incoming, run_id=run_id, services=services, run_timeout_seconds=timeout)+ return runner, sink+++async def test_native_run_restores_conversation_but_uses_current_instructions(monkeypatch):+ seen = []++ async def stream(messages, info):+ seen.append((list(messages), info.instructions))+ yield "reply"++ async with httpx.AsyncClient() as client:+ services = Services(client, client)+ first, first_sink = run_runner(request(), services, monkeypatch, stream, run_id="first")+ await first.run()+ terminal = first_sink.events["first"][-1]+ assert isinstance(terminal, RunSucceededEvent)+ assert terminal.data.output == "reply"+ snapshot = terminal.data.session_snapshot+ state = history.State.model_validate(snapshot.layers["history"])+ assert len(state.messages) == 2+ assert all(m.instructions is None for m in state.messages if isinstance(m, ModelRequest))+ second, sink = run_runner(+ request(snapshot=snapshot, instruction="Revised instruction", user="next"),+ services,+ monkeypatch,+ stream,+ run_id="second",)-- return CreateRunRequest(- composition=RunComposition(layers=layers),- on_exit=on_exit or LayerExitSignals(),+ await second.run()+ assert len(seen[1][0]) == 3+ assert seen[1][1] == "Revised instruction"+ assert "Current instruction" not in snapshot.model_dump_json()+ assert isinstance(sink.events["second"][-1], RunSucceededEvent)+ assert not client.is_closed++[email protected]("with_regular_tool", [False, True])+async def test_legacy_ask_human_pause_accepts_first_new_user_turn(monkeypatch, with_regular_tool):+ """Produce real deferred history, migrate only data, then use the new runner."""++ async def ask_human(question: str) -> str:+ pytest.fail("the legacy external tool must never execute")++ async def regular() -> str:+ return "completed regular tool"++ def legacy_model(messages, info):+ calls = [ToolCallPart(tool_name="ask_human", args={"question": "Choose an action"}, tool_call_id="human-1")]+ if with_regular_tool:+ calls.append(ToolCallPart(tool_name="regular", args={}, tool_call_id="regular-1"))+ return ModelResponse(parts=calls)++ legacy_agent = Agent(+ FunctionModel(legacy_model),+ tools=[Tool(ask_human, prepare=lambda ctx, definition: replace(definition, kind="external")), regular],+ output_type=[str, DeferredToolRequests],+ )+ paused = await legacy_agent.run("Original request")+ assert isinstance(paused.output, DeferredToolRequests)+ legacy_state = history.State(messages=paused.all_messages()).model_dump(mode="json")+ assert legacy_state["messages"][-1]["state"] == "complete"+ snapshot = SessionSnapshot.model_validate(+ {+ "schema_version": 1,+ "layers": [+ {"name": "history", "lifecycle_state": "suspended", "runtime_state": legacy_state},+ {"name": "ask_human", "lifecycle_state": "suspended", "runtime_state": {}},+ ],+ })---def _request_with_shell() -> CreateRunRequest:- request = _request()- request.composition.layers[-1:-1] = [- RunLayerSpec(- name="runtime",- type=DIFY_RUNTIME_LAYER_TYPE_ID,- config=DifyRuntimeLayerConfig(backend_binding_ref="binding-1"),- ),- RunLayerSpec(- name="shell",- type=DIFY_SHELL_LAYER_TYPE_ID,- deps={"execution_context": "execution_context", "runtime": "runtime"},- config=DifyShellLayerConfig(),- ),- ]- return request---def _recursive_output_schema() -> dict[str, object]:- return {- "type": "object",- "properties": {"node": {"$ref": "#/$defs/node"}},- "$defs": {- "node": {+ assert "ask_human" not in snapshot.layers+ assert snapshot.layers["history"]["messages"][:-1] == legacy_state["messages"][:-1]+ assert snapshot.layers["history"]["messages"][-1] == {+ **legacy_state["messages"][-1],+ "state": "interrupted",+ }+ # Loading a snapshot must not mutate the stored legacy object.+ assert legacy_state["messages"][-1]["state"] == "complete"+ model_calls = []++ async def stream(messages, info):+ model_calls.append(messages)+ assert any(+ isinstance(part, UserPromptPart) and part.content == "Original request"+ for message in messages+ for part in message.parts+ )+ returns = {+ part.tool_call_id: part.content+ for message in messages+ if isinstance(message, ModelRequest)+ for part in message.parts+ if isinstance(part, ToolReturnPart)+ }+ assert "human-1" in returns+ if with_regular_tool:+ assert returns["regular-1"] == "completed regular tool"+ assert messages[-1].parts[-1].content == "Continue without waiting for human input"+ yield "continued"++ async with httpx.AsyncClient() as client:+ runner, sink = run_runner(+ request(snapshot=snapshot, user="Continue without waiting for human input"),+ Services(client, client),+ monkeypatch,+ stream,+ )+ await runner.run()+ assert len(model_calls) == 1+ terminal = sink.events["test"][-1]+ assert isinstance(terminal, RunSucceededEvent)+ assert terminal.data.output == "continued"+++async def test_failure_saves_user_history_and_classified_event(monkeypatch):+ async def stream(messages, info):+ raise ModelHTTPError(429, "demo", {"error_type": "InvokeRateLimitError", "message": "quota exceeded"})+ yield "unreachable"++ async with httpx.AsyncClient() as client:+ runner, sink = run_runner(request(), Services(client, client), monkeypatch, stream)+ with pytest.raises(ModelHTTPError):+ await runner.run()+ terminal = sink.events["test"][-1]+ assert isinstance(terminal, RunFailedEvent)+ assert terminal.data.error == "quota exceeded"+ assert terminal.data.reason == "InvokeRateLimitError"+ assert terminal.data.session_snapshot is not None+ saved = history.State.model_validate(terminal.data.session_snapshot.layers["history"])+ assert isinstance(saved.messages[0], ModelRequest)+ assert saved.messages[0].instructions is None+ assert saved.messages[-1].state == "interrupted"++[email protected]("invalid_first", [False, True])+async def test_native_structured_output_uses_output_module(monkeypatch, invalid_first):+ attempts = []++ async def stream(messages, info):+ assert len(info.output_tools) == 1+ attempts.append(messages)+ if invalid_first and len(attempts) == 1:+ arguments = '{"answer":42}'+ else:+ if invalid_first:+ assert any(isinstance(part, RetryPromptPart) for message in messages for part in message.parts)+ arguments = '{"answer":"done"}'+ yield {0: DeltaToolCall(name=info.output_tools[0].name, json_args=arguments, tool_call_id="out")}++ spec = RunLayerSpec(+ name="output",+ config={+ "json_schema": {"type": "object",- "properties": {"child": {"$ref": "#/$defs/node"}},+ "properties": {"answer": {"type": "string"}},+ "required": ["answer"],"additionalProperties": False,}},- "additionalProperties": False,- }---def _prepared_plugin_tool_parameters() -> list[DifyPluginToolParameter]:- return [- DifyPluginToolParameter(- name="query",- type=DifyPluginToolParameterType.STRING,- form=DifyPluginToolParameterForm.LLM,- required=True,- llm_description="Search query",- ),- DifyPluginToolParameter(- name="auth_scope",- type=DifyPluginToolParameterType.STRING,- form=DifyPluginToolParameterForm.FORM,- required=True,- llm_description="Hidden auth scope",- ),- ]---def _prepared_plugin_tool_schema() -> dict[str, JsonValue]:- return {- "type": "object",- "properties": {- "query": {"type": "string", "description": "Search query"},- },- "required": ["query"],- }-+ )+ async with httpx.AsyncClient() as client:+ runner, sink = run_runner(request(spec), Services(client, client), monkeypatch, stream)+ await runner.run()+ terminal = sink.events["test"][-1]+ assert isinstance(terminal, RunSucceededEvent)+ assert terminal.data.output == {"answer": "done"}+ assert len(attempts) == (2 if invalid_first else 1)+++class Commands:+ """Remote command protocol double; the Agent and capability scopes stay real."""++ def __init__(self):+ self.deleted = []+ self.scripts = []+ self.tail_started = asyncio.Event()+ self.block_tail = False+ self.bootstrap_failures = 0++ async def run(self, script, *, cwd=None, env=None, timeout=10, mode="pty"):+ self.scripts.append(script)+ if mode == "stdio":+ failed = self.bootstrap_failures > 0+ self.bootstrap_failures = max(0, self.bootstrap_failures - 1)+ return ShellCommandResult("bootstrap", "exited", True, 1 if failed else 0, "", 0, False, "/tmp/output")+ return ShellCommandResult("remote", "running", False, None, "partial", 20, self.block_tail, "/tmp/output")++ async def tail(self, job_id, *, edge_bytes=None):+ self.tail_started.set()+ await asyncio.Event().wait()-class SequenceOutputTestModel(TestModel):- outputs: list[str | dict[str, Any] | None]- request_count: int-- def __init__(self, outputs: list[str | dict[str, Any] | None]) -> None:- super().__init__(call_tools=[])- self.outputs = outputs- self.request_count = 0-- def _request(- self,- messages: list[ModelMessage],- model_settings: ModelSettings | None,- model_request_parameters: ModelRequestParameters,- ) -> ModelResponse:- if not model_request_parameters.output_tools:- return super()._request(messages, model_settings, model_request_parameters)-- output_tool = model_request_parameters.output_tools[0]- next_index = min(self.request_count, len(self.outputs) - 1)- output_args = self.outputs[next_index]- self.request_count += 1- return ModelResponse(- parts=[- ToolCallPart(- output_tool.name,- output_args,- tool_call_id=f"pyd_ai_tool_call_id__{output_tool.name}_{self.request_count}",- )- ],- model_name=self.model_name,- )+ async def delete(self, job_id, *, force=False, grace_seconds=None):+ self.deleted.append(job_id)-class RecordingTestModel(TestModel):- seen_requests: list[list[ModelMessage]]- seen_instructions: list[list[str]]- failure: Exception | None-- def __init__(self, *, custom_output_text: str = "done", failure: Exception | None = None) -> None:- super().__init__(call_tools=[], custom_output_text=custom_output_text)- self.seen_requests = []- self.seen_instructions = []- self.failure = failure-- def _request(- self,- messages: list[ModelMessage],- model_settings: ModelSettings | None,- model_request_parameters: ModelRequestParameters,- ) -> ModelResponse:- self.seen_requests.append(list(messages))- self.seen_instructions.append([part.content for part in model_request_parameters.instruction_parts or []])- if self.failure is not None:- raise self.failure- return super()._request(messages, model_settings, model_request_parameters)---def _history_session_snapshot(- messages: list[ModelMessage],- *,- include_ask_human: bool = False,- include_output: bool = False,-) -> CompositorSessionSnapshot:- layers = [- LayerSessionSnapshot(name="prompt", lifecycle_state=LifecycleState.SUSPENDED, runtime_state={}),- LayerSessionSnapshot(- name=DIFY_AGENT_HISTORY_LAYER_ID,- lifecycle_state=LifecycleState.SUSPENDED,- runtime_state=PydanticAIHistoryRuntimeState(messages=messages).model_dump(mode="json"),- ),- *(- [LayerSessionSnapshot(name="ask_human", lifecycle_state=LifecycleState.SUSPENDED, runtime_state={})]- if include_ask_human- else []- ),- LayerSessionSnapshot(name="execution_context", lifecycle_state=LifecycleState.SUSPENDED, runtime_state={}),- LayerSessionSnapshot(- name=DIFY_AGENT_MODEL_LAYER_ID, lifecycle_state=LifecycleState.SUSPENDED, runtime_state={}- ),- ]- if include_output:- layers.append(- LayerSessionSnapshot(- name=DIFY_AGENT_OUTPUT_LAYER_ID, lifecycle_state=LifecycleState.SUSPENDED, runtime_state={}- )+class Backend:+ def __init__(self, commands):+ self.commands = commands+ self.active = False+ self.acquired = 0+ self.released = 0+ self.lease = SimpleNamespace(+ handle="binding",+ commands=commands,+ layout=RuntimeLayout(home_dir="/home/agent", workspace_dir="/home/agent/workspace/run"),)- return CompositorSessionSnapshot(layers=layers)---def _history_messages_from_snapshot(snapshot: CompositorSessionSnapshot) -> list[ModelMessage]:- history_snapshot = next(layer for layer in snapshot.layers if layer.name == DIFY_AGENT_HISTORY_LAYER_ID)- return PydanticAIHistoryRuntimeState.model_validate(history_snapshot.runtime_state).messages---def _flatten_message_parts(messages: list[ModelMessage]) -> list[object]:- return [part for message in messages for part in message.parts]--def _assert_interrupted_history(- snapshot: CompositorSessionSnapshot,- stored_history: list[ModelMessage],-) -> None:- saved_history = _history_messages_from_snapshot(snapshot)+ async def acquire(self, binding_ref):+ assert binding_ref == "binding"+ self.active = True+ self.acquired += 1+ return self.lease- assert saved_history[: len(stored_history)] == stored_history- assert len(saved_history) == len(stored_history) + 2- current_request = saved_history[-2]- assert isinstance(current_request, ModelRequest)- assert current_request.instructions is None- assert len(current_request.parts) == 1- assert isinstance(current_request.parts[0], UserPromptPart)- assert current_request.parts[0].content == "current user"- partial_response = saved_history[-1]- assert isinstance(partial_response, ModelResponse)- assert partial_response.state == "interrupted"- assert len(partial_response.parts) == 1- assert isinstance(partial_response.parts[0], TextPart)- assert partial_response.parts[0].content == "partial"+ async def release(self, lease):+ assert self.active+ self.active = False+ self.released += 1-def _install_fake_message_capture(monkeypatch: pytest.MonkeyPatch) -> list[ModelMessage]:- captured_messages: list[ModelMessage] = []-- @contextmanager- def fake_capture_run_messages() -> Generator[list[ModelMessage]]:- captured_messages.clear()- yield captured_messages-- monkeypatch.setattr("dify_agent.runtime.runner.capture_run_messages", fake_capture_run_messages)- return captured_messages---class FakeAgentRunResult:- output: object-- def __init__(self, output: object) -> None:- self.output = output---def test_runner_emits_terminal_success_and_snapshot(monkeypatch: pytest.MonkeyPatch) -> None:- seen_clients: list[httpx.AsyncClient] = []-- def fake_get_model(self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert self.config.model == "demo-model"- assert self.config.plugin_id == "langgenius/openai"- seen_clients.append(http_client)- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- request = _request(execution_context_layer_name="renamed-execution-context")- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-1",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()- assert seen_clients == [client]- assert client.is_closed is False-- asyncio.run(scenario())-- event_types = [event.type for event in sink.events["run-1"]]- assert event_types[0] == "run_started"- assert "pydantic_ai_event" in event_types- assert "agent_output" not in event_types- assert "session_snapshot" not in event_types- assert event_types[-1:] == ["run_succeeded"]- pydantic_events = [event for event in sink.events["run-1"] if isinstance(event, PydanticAIStreamRunEvent)]- assert "".join(event.agent_message_delta or "" for event in pydantic_events) == "done"- terminal = sink.events["run-1"][-1]- assert isinstance(terminal, RunSucceededEvent)- assert terminal.data.output == "done"- assert terminal.data.usage is not None- assert terminal.data.usage.total_tokens > 0- assert [layer.name for layer in terminal.data.session_snapshot.layers] == [- "prompt",- "renamed-execution-context",- DIFY_AGENT_MODEL_LAYER_ID,- ]- assert [layer.lifecycle_state for layer in terminal.data.session_snapshot.layers] == [- LifecycleState.SUSPENDED,- LifecycleState.SUSPENDED,- LifecycleState.SUSPENDED,+def runtime_specs(*, bootstrap=False):+ config = {"cli_tools": [{"name": "test", "install_commands": ["install-test"]}]} if bootstrap else {}+ # Request ordering deliberately differs from resource ownership ordering.+ return [+ RunLayerSpec(name="shell", config=config),+ RunLayerSpec(name="runtime", config={"backend_binding_ref": "binding"}),]- assert sink.statuses["run-1"] == "succeeded"---def test_runner_emits_complete_plugin_usage_in_terminal_event(monkeypatch: pytest.MonkeyPatch) -> None:- complete_usage = LLMUsage(- prompt_tokens=10,- prompt_unit_price=Decimal("5"),- prompt_price_unit=Decimal("0.000001"),- prompt_price=Decimal("0.000050"),- completion_tokens=2,- completion_unit_price=Decimal("30"),- completion_price_unit=Decimal("0.000001"),- completion_price=Decimal("0.000060"),- total_tokens=12,- total_price=Decimal("0.000110"),- currency="USD",- latency=0.4,- time_to_first_token=0.1,- time_to_generate=0.3,- )-- class PricedTestModel(TestModel):- @property- def accumulated_usage(self) -> LLMUsage:- return complete_usage-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return PricedTestModel(custom_output_text="done") # pyright: ignore[reportReturnType]-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- await AgentRunRunner(- sink=sink,- request=_request(),- run_id="run-priced",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- terminal = sink.events["run-priced"][-1]- assert isinstance(terminal, RunSucceededEvent)- assert terminal.data.usage is not None- assert terminal.data.usage.prompt_unit_price == Decimal("5")- assert terminal.data.usage.prompt_price == Decimal("0.000050")- assert terminal.data.usage.completion_unit_price == Decimal("30")- assert terminal.data.usage.completion_price == Decimal("0.000060")- assert terminal.data.usage.total_price == Decimal("0.000110")- assert terminal.data.usage.currency == "USD"- assert terminal.data.usage.latency == 0.4- assert terminal.data.usage.time_to_first_token == 0.1- assert terminal.data.usage.time_to_generate == 0.3---def test_runner_preserves_explicit_json_null_output(monkeypatch: pytest.MonkeyPatch) -> None:- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]-- class FakeAgent:- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:- return FakeAgentRunResult(None)-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *_args, **_kwargs: FakeAgent())- request = _request()- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-null-output",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- terminal = sink.events["run-null-output"][-1]- assert isinstance(terminal, RunSucceededEvent)- assert terminal.data.output is None- assert terminal.data.deferred_tool_call is None- assert sink.statuses["run-null-output"] == "succeeded"---def test_runner_passes_explicit_step_limit_to_agent(monkeypatch: pytest.MonkeyPatch) -> None:- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]-- class FakeAgent:- async def run(self, *_args: object, **kwargs: object) -> FakeAgentRunResult:- usage_limits = cast(UsageLimits, kwargs["usage_limits"])- assert usage_limits.request_limit == 500- return FakeAgentRunResult("done")-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *_args, **_kwargs: FakeAgent())- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- await AgentRunRunner(- sink=sink,- request=_request(),- run_id="run-explicit-step-limit",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert sink.statuses["run-explicit-step-limit"] == "succeeded"---def test_runner_passes_context_compaction(monkeypatch: pytest.MonkeyPatch) -> None:- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]-- class FakeAgent:- async def run(self, *_args: object, **kwargs: object) -> FakeAgentRunResult:- capabilities = cast(list[object], kwargs["capabilities"])- assert len(capabilities) == 1- capability = capabilities[0]- assert isinstance(capability, TieredCompaction)- assert capability.target_tokens == 7_000- return FakeAgentRunResult("done")-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *_args, **_kwargs: FakeAgent())- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- await AgentRunRunner(- sink=sink,- request=_request(- model_settings={"max_tokens": 3_000},- context_window_tokens=10_000,- ),- run_id="run-compaction",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert sink.statuses["run-compaction"] == "succeeded"---def test_runner_instruments_agent_with_injected_observability(monkeypatch: pytest.MonkeyPatch) -> None:- class FakeAgentObservability:- def __init__(self) -> None:- self.instrumented: list[tuple[object, DifyExecutionContextLayerConfig | None]] = []-- def instrument(- self,- agent: object,- *,- execution_context: DifyExecutionContextLayerConfig | None = None,- ) -> None:- self.instrumented.append((agent, execution_context))-- class FakeAgent:- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:- return FakeAgentRunResult("done")- observability = FakeAgentObservability()- created_agent = FakeAgent()- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *_args, **_kwargs: created_agent)- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- await AgentRunRunner(- sink=sink,- request=_request(app_id="app-1", agent_id="agent-1"),- run_id="run-observed",- plugin_daemon_http_client=client,- dify_api_http_client=client,- agent_observability=cast(AgentObservability, observability),- ).run()-- asyncio.run(scenario())-- assert sink.statuses["run-observed"] == "succeeded"- # The run's Dify context reaches observability through the model layer's- # execution-context dependency, whose node name the caller chooses.- assert len(observability.instrumented) == 1- instrumented_agent, execution_context = observability.instrumented[0]- assert instrumented_agent is created_agent- assert execution_context is not None- assert (execution_context.tenant_id, execution_context.app_id, execution_context.agent_id) == (- "tenant-1",- "app-1",- "agent-1",- )---def test_runner_rejects_compaction_budget_before_model_resolution_or_invocation(- monkeypatch: pytest.MonkeyPatch,-) -> None:- model_resolution_called = False- agent_creation_called = False- model_invocation_called = False-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- nonlocal model_resolution_called- model_resolution_called = True- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]-- class FakeAgent:- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:- nonlocal model_invocation_called- model_invocation_called = True- return FakeAgentRunResult("unused")-- def fake_create_agent(*_args: object, **_kwargs: object) -> FakeAgent:- nonlocal agent_creation_called- agent_creation_called = True- return FakeAgent()-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(- AgentRunValidationError,- match="Model max_tokens must leave a positive input context budget",- ):- await AgentRunRunner(- sink=sink,- request=_request(- model_settings={"max_tokens": 1_000},- context_window_tokens=1_000,- ),- run_id="run-invalid-compaction-budget",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert model_resolution_called is False- assert agent_creation_called is False- assert model_invocation_called is False- assert [event.type for event in sink.events["run-invalid-compaction-budget"]] == ["run_started", "run_failed"]- assert sink.statuses["run-invalid-compaction-budget"] == "failed"---def test_runner_timeout_excludes_tool_preparation_and_runtime_cleanup(monkeypatch: pytest.MonkeyPatch) -> None:- shell_client = FakeRunnerShellctlClient()- tools_prepared = False-- class SlowLifecycleBackend(FakeRunnerExecutionBindingBackend):- acquired: bool = False- released: bool = False-- async def acquire(self, binding_ref: str) -> RuntimeLease:- await asyncio.sleep(0.01)- lease = await super().acquire(binding_ref)- self.acquired = True- return lease-- async def release(self, lease: RuntimeLease) -> None:- await asyncio.sleep(0.01)- await super().release(lease)- self.released = True-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- assert agent_run_id == "run-lifecycle-outside-timeout"- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]-- class ImmediateAgent:- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:- return FakeAgentRunResult("done")-- async def slow_resolve_run_tools(- _run: object,- *,- plugin_daemon_http_client: httpx.AsyncClient,- dify_api_http_client: httpx.AsyncClient,- ) -> list[Tool[object]]:- nonlocal tools_prepared- assert plugin_daemon_http_client.is_closed is False- assert dify_api_http_client.is_closed is False- await asyncio.sleep(0.01)- tools_prepared = True- return []-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *_args, **_kwargs: ImmediateAgent())- monkeypatch.setattr("dify_agent.runtime.runner._resolve_run_tools", slow_resolve_run_tools)- backend = SlowLifecycleBackend(shell_client)- runtime_backend_profile = RuntimeBackendProfile(- home_snapshots=cast(HomeSnapshotBackend, object()),- execution_bindings=backend,- )- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- await AgentRunRunner(- sink=sink,- request=_request_with_shell(),- run_id="run-lifecycle-outside-timeout",- plugin_daemon_http_client=client,- dify_api_http_client=client,- layer_providers=create_default_layer_providers(runtime_backend_profile=runtime_backend_profile),- run_timeout_seconds=0.001,- ).run()-- asyncio.run(scenario())-- assert sink.statuses["run-lifecycle-outside-timeout"] == "succeeded"- assert tools_prepared is True- assert backend.acquired is True- assert backend.released is True- assert shell_client.closed is True---def test_runner_timeout_cancels_agent_and_releases_runtime_lease(monkeypatch: pytest.MonkeyPatch) -> None:- agent_cancelled = False- shell_client = FakeRunnerShellctlClient()-- class FakeUsageModel(TestModel):- @property- def accumulated_usage(self) -> LLMUsage:- return LLMUsage.from_metadata(- {- "prompt_tokens": 13,- "completion_tokens": 8,- "total_tokens": 21,- "total_price": "0.000210",- "currency": "USD",- }- )-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- assert agent_run_id == "run-timeout"- return FakeUsageModel(custom_output_text="unused") # pyright: ignore[reportReturnType]-- class FakeAgent:- async def run(self, *_args: object, **_kwargs: object) -> None:- nonlocal agent_cancelled- try:- await asyncio.Event().wait()- except asyncio.CancelledError:- agent_cancelled = True- raise-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *_args, **_kwargs: FakeAgent())- runtime_backend_profile = RuntimeBackendProfile(- home_snapshots=cast(HomeSnapshotBackend, object()),- execution_bindings=FakeRunnerExecutionBindingBackend(shell_client),- )- sink = InMemoryRunEventSink()+async def test_cancellation_during_remote_observation_deletes_job_and_releases_lease(monkeypatch):+ commands = Commands()+ commands.block_tail = True+ backend = Backend(commands)++ async def stream(messages, info):+ assert backend.active+ assert {t.name for t in info.function_tools} == {"shell_run", "shell_wait", "shell_input", "shell_interrupt"}+ assert all(t.sequential for t in info.function_tools)+ yield {0: DeltaToolCall(name="shell_run", json_args='{"script":"sleep 100"}', tool_call_id="call")}++ async with httpx.AsyncClient() as client:+ services = Services(client, client, runtime_backend_profile=RuntimeBackendProfile(None, backend))+ runner, sink = run_runner(request(*runtime_specs()), services, monkeypatch, stream)+ task = asyncio.create_task(runner.run())+ await asyncio.wait_for(commands.tail_started.wait(), timeout=3)+ task.cancel()+ with pytest.raises(asyncio.CancelledError):+ await task+ assert commands.deleted == ["remote"]+ assert backend.released == 1 and not backend.active+ snap = runner.terminal_session_snapshot+ assert snap is not None+ assert snap.layers["shell"] == {"initialized": True, "job_ids": [], "job_offsets": {}}+ saved = history.State.model_validate(snap.layers["history"])+ responses = [m for m in saved.messages if isinstance(m, ModelResponse)]+ assert responses[-1].state == "interrupted"+ assert not client.is_closed+++async def test_bootstrap_failure_retries_and_success_is_not_repeated(monkeypatch):+ commands = Commands()+ commands.bootstrap_failures = 1+ backend = Backend(commands)++ async def stream(messages, info):+ assert backend.active+ assert "Workspace" in info.instructions+ yield "done"++ async with httpx.AsyncClient() as client:+ services = Services(client, client, runtime_backend_profile=RuntimeBackendProfile(None, backend))+ runner, sink = run_runner(request(*runtime_specs(bootstrap=True)), services, monkeypatch, stream)+ with pytest.raises(RuntimeError, match="bootstrap"):+ await runner.run()+ assert runner.terminal_session_snapshot.layers["shell"]["initialized"] is False+ second, _ = run_runner(+ request(*runtime_specs(bootstrap=True), snapshot=runner.terminal_session_snapshot),+ services,+ monkeypatch,+ stream,+ run_id="second",+ )+ await second.run()+ assert second.terminal_session_snapshot.layers["shell"]["initialized"] is True+ third, _ = run_runner(+ request(*runtime_specs(bootstrap=True), snapshot=second.terminal_session_snapshot),+ services,+ monkeypatch,+ stream,+ run_id="third",+ )+ await third.run()+ assert len(commands.scripts) == 2+ assert backend.acquired == backend.released == 3- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(UsageLimitExceeded, match="0.01 seconds"):- await AgentRunRunner(- sink=sink,- request=_request_with_shell(),- run_id="run-timeout",- plugin_daemon_http_client=client,- dify_api_http_client=client,- layer_providers=create_default_layer_providers(runtime_backend_profile=runtime_backend_profile),- run_timeout_seconds=0.01,- ).run()-- asyncio.run(scenario())-- terminal = sink.events["run-timeout"][-1]- assert isinstance(terminal, RunFailedEvent)- assert terminal.data.error_type is RunFailureType.AGENT_RUN_LIMIT_EXCEEDED- assert terminal.data.usage is not None- assert terminal.data.usage.prompt_tokens == 13- assert terminal.data.usage.completion_tokens == 8- assert terminal.data.usage.total_tokens == 21- assert terminal.data.usage.total_price == Decimal("0.000210")- assert sink.statuses["run-timeout"] == "failed"- assert agent_cancelled is True- assert shell_client.closed is True---def test_runner_does_not_classify_nested_timeout_as_agent_limit(monkeypatch: pytest.MonkeyPatch) -> None:- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- assert agent_run_id == "run-provider-timeout"- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]-- class FakeAgent:- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:- raise TimeoutError("provider timed out")-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *_args, **_kwargs: FakeAgent())- sink = InMemoryRunEventSink()- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(TimeoutError, match="provider timed out"):- await AgentRunRunner(- sink=sink,- request=_request(),- run_id="run-provider-timeout",- plugin_daemon_http_client=client,- dify_api_http_client=client,- run_timeout_seconds=1,- ).run()-- asyncio.run(scenario())-- terminal = sink.events["run-provider-timeout"][-1]- assert isinstance(terminal, RunFailedEvent)- assert terminal.data.error == "provider timed out"- assert terminal.data.error_type is None- assert sink.statuses["run-provider-timeout"] == "failed"---def test_runner_captures_interrupted_history_when_task_is_cancelled(monkeypatch: pytest.MonkeyPatch) -> None:- partial_streamed = asyncio.Event()- stored_history = [- ModelRequest(parts=[UserPromptPart(content="old user")]),- ModelResponse(parts=[TextPart(content="old assistant")]),- ]+async def test_timeout_releases_resource_and_preserves_snapshot(monkeypatch):+ commands = Commands()+ backend = Backend(commands)- async def stream_response(_messages: list[ModelMessage], _info: object) -> AsyncIterator[str]:- yield "partial"- _ = partial_streamed.set()+ async def stream(messages, info):await asyncio.Event().wait()+ yield "unreachable"- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- return FunctionModel(stream_function=stream_response)-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- request = _request("current user", include_history=True)- request.session_snapshot = _history_session_snapshot(stored_history)- sink = InMemoryRunEventSink()+ async with httpx.AsyncClient() as client:+ services = Services(client, client, runtime_backend_profile=RuntimeBackendProfile(None, backend))+ runner, sink = run_runner(request(*runtime_specs()), services, monkeypatch, stream, timeout=0.05)+ with pytest.raises(UsageLimitExceeded):+ await runner.run()+ assert backend.released == 1+ terminal = sink.events["test"][-1]+ assert isinstance(terminal, RunFailedEvent)+ assert terminal.data.error_type == RunFailureType.AGENT_RUN_LIMIT_EXCEEDED+ assert terminal.data.session_snapshot.layers["shell"]["job_ids"] == []+++async def test_bad_configuration_prevents_resource_acquisition(monkeypatch):+ commands = Commands()+ backend = Backend(commands)++ async def stream(messages, info):+ raise AssertionError("Model I/O must not happen")+ yield "unreachable"++ async with httpx.AsyncClient() as client:+ services = Services(client, client, runtime_backend_profile=RuntimeBackendProfile(None, backend))+ runner, sink = run_runner(+ request(*runtime_specs(), RunLayerSpec(name="tools", config={"execution_context": "missing"})),+ services,+ monkeypatch,+ stream,+ )+ with pytest.raises(ValueError, match="reference"):+ await runner.run()+ assert backend.acquired == 0+ assert isinstance(sink.events["test"][-1], RunFailedEvent)- async def scenario() -> AgentRunRunner:- async with httpx.AsyncClient() as client:- runner = AgentRunRunner(- sink=sink,- request=request,- run_id="run-cancel-history",- plugin_daemon_http_client=client,- dify_api_http_client=client,- )- task = asyncio.create_task(runner.run())- await asyncio.wait_for(partial_streamed.wait(), timeout=1)- task.cancel()- with pytest.raises(asyncio.CancelledError):- await task- return runner-- runner = asyncio.run(scenario())-- assert runner.terminal_session_snapshot is not None- assert all(layer.lifecycle_state is LifecycleState.SUSPENDED for layer in runner.terminal_session_snapshot.layers)- _assert_interrupted_history(runner.terminal_session_snapshot, stored_history)---def test_runner_emits_deferred_tool_call_and_persists_pending_history(monkeypatch: pytest.MonkeyPatch) -> None:- captured_output_types: list[object] = []- captured_user_prompts: list[object] = []- captured_messages = _install_fake_message_capture(monkeypatch)- pending_tool_call = ToolCallPart(- tool_name="ask_human",- args={- "question": "Which deployment window should we use?",- "fields": [{"type": "paragraph", "name": "window", "label": "Deployment window"}],- },- tool_call_id="tool-call-1",- )- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]-- class FakeAgent:- async def run(self, user_prompt: object, **kwargs: object) -> FakeAgentRunResult:- captured_user_prompts.append(user_prompt)- assert kwargs["deferred_tool_results"] is None- messages: list[ModelMessage] = [- ModelRequest(parts=[UserPromptPart(content="current user")]),- ModelResponse(parts=[pending_tool_call]),- ]- captured_messages.extend(messages)- return FakeAgentRunResult(DeferredToolRequests(calls=[pending_tool_call]))+async def test_invalid_output_schema_fails_before_resource_and_model_io(monkeypatch):+ backend = Backend(Commands())- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> FakeAgent:- del model, tools- captured_output_types.append(output_type)- return FakeAgent()+ async def stream(messages, info):+ pytest.fail("invalid output schema must not reach the model")+ yield "unreachable"- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)- request = _request("current user", include_history=True, include_ask_human=True)- sink = InMemoryRunEventSink()+ async with httpx.AsyncClient() as client:+ services = Services(client, client, runtime_backend_profile=RuntimeBackendProfile(None, backend))+ runner, sink = run_runner(+ request(+ *runtime_specs(),+ RunLayerSpec(name="output", config={"json_schema": {"type": "object", "required": "invalid"}}),+ ),+ services,+ monkeypatch,+ stream,+ )+ with pytest.raises(ValueError, match="required"):+ await runner.run()+ assert backend.acquired == 0+ assert isinstance(sink.events["test"][-1], RunFailedEvent)- async def scenario() -> None:- async with httpx.AsyncClient() as client:- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-ask-human",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- terminal = sink.events["run-ask-human"][-1]- assert isinstance(terminal, RunSucceededEvent)- assert captured_user_prompts == ["current user"]- assert any(item is DeferredToolRequests for item in cast(Iterable[object], captured_output_types[0]))- assert terminal.data.output is None- assert terminal.data.deferred_tool_call is not None- assert terminal.data.deferred_tool_call.tool_call_id == "tool-call-1"- assert terminal.data.deferred_tool_call.tool_name == "ask_human"- assert terminal.data.deferred_tool_call.args == {- "title": None,- "question": "Which deployment window should we use?",- "markdown": None,- "fields": [- {- "type": "paragraph",- "name": "window",- "label": "Deployment window",- "required": False,- "placeholder": None,- "default": None,- }- ],- "actions": [{"id": "submit", "label": "Submit", "style": "primary"}],- "urgency": "normal",- }- saved_history = _history_messages_from_snapshot(terminal.data.session_snapshot)- assert isinstance(saved_history[-1], ModelResponse)- assert saved_history[-1].parts == [pending_tool_call]---def test_runner_resumes_with_deferred_tool_results_and_no_user_prompt(monkeypatch: pytest.MonkeyPatch) -> None:- seen_user_prompts: list[object] = []- seen_deferred_results: list[object] = []- captured_messages = _install_fake_message_capture(monkeypatch)- pending_tool_call = ToolCallPart(- tool_name="ask_human",- args={"question": "Need approval"},- tool_call_id="tool-call-1",- )- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]-- class FakeAgent:- async def run(self, user_prompt: object, **kwargs: object) -> FakeAgentRunResult:- seen_user_prompts.append(user_prompt)- seen_deferred_results.append(kwargs.get("deferred_tool_results"))- if kwargs.get("deferred_tool_results") is None:- messages: list[ModelMessage] = [- ModelRequest(parts=[UserPromptPart(content="current user")]),- ModelResponse(parts=[pending_tool_call]),- ]- captured_messages.extend(messages)- return FakeAgentRunResult(DeferredToolRequests(calls=[pending_tool_call]))-- deferred_tool_results = cast(DeferredToolResults, kwargs["deferred_tool_results"])- assert deferred_tool_results is not None- submitted_result = cast(dict[str, object], deferred_tool_results.calls["tool-call-1"])- assert submitted_result["status"] == "submitted"- message_history = cast(list[ModelMessage], kwargs["message_history"])- messages = [- *message_history,- ModelRequest(- parts=[- ToolReturnPart(- tool_name="ask_human",- content={"status": "submitted", "values": {"comment": "Ship it"}},- tool_call_id="tool-call-1",- )- ]- ),- ModelResponse(parts=[TextPart(content="done after human")]),- ]- captured_messages.extend(messages)- return FakeAgentRunResult("done after human")[email protected]("user", ["hello", ""])+async def test_knowledge_user_context_is_captured_in_history_and_restored_cache(monkeypatch, user):+ calls = []- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> FakeAgent:- del model, tools, output_type- return FakeAgent()+ def handler(request):+ calls.append(request)+ return httpx.Response(200, json={"results": [], "usage": {}})- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)- request = _request("current user", include_history=True, include_ask_human=True)- sink = InMemoryRunEventSink()+ async def stream(messages, info):+ user_contents = [+ p.content for m in messages if isinstance(m, ModelRequest) for p in m.parts if isinstance(p, UserPromptPart)+ ]+ assert any("Knowledge retrieval results" in str(content) for content in user_contents)+ yield "done"- async def scenario() -> None:- async with httpx.AsyncClient() as client:- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-ask-human-initial",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- initial_terminal = sink.events["run-ask-human-initial"][-1]- assert isinstance(initial_terminal, RunSucceededEvent)-- resumed_request = request.model_copy(deep=True)- resumed_request.session_snapshot = initial_terminal.data.session_snapshot- resumed_request.deferred_tool_results = DeferredToolResultsPayload.model_validate(+ knowledge = RunLayerSpec(+ name="knowledge",+ config={+ "sets": [{- "calls": {- "tool-call-1": {- "status": "submitted",- "action": {"id": "submit", "label": "Submit"},- "values": {"comment": "Ship it"},- }- }+ "id": "support",+ "name": "Support",+ "datasets": [{"id": "dataset"}],+ "query": {"mode": "user_query", "value": "release"},+ "retrieval": {"mode": "multiple", "top_k": 4},}- )-- await AgentRunRunner(- sink=sink,- request=resumed_request,- run_id="run-ask-human-resume",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- resumed_terminal = sink.events["run-ask-human-resume"][-1]- assert isinstance(resumed_terminal, RunSucceededEvent)- assert resumed_terminal.data.output == "done after human"- assert resumed_terminal.data.deferred_tool_call is None- assert seen_user_prompts == ["current user", None]- assert seen_deferred_results[0] is None- assert seen_deferred_results[1] is not None---def test_runner_can_emit_second_deferred_tool_call_after_resume(monkeypatch: pytest.MonkeyPatch) -> None:- seen_user_prompts: list[object] = []- captured_messages = _install_fake_message_capture(monkeypatch)- first_pending_tool_call = ToolCallPart(- tool_name="ask_human",- args={"question": "Need deployment owner"},- tool_call_id="tool-call-1",- )- second_pending_tool_call = ToolCallPart(- tool_name="ask_human",- args={"question": "Need final go-live confirmation"},- tool_call_id="tool-call-2",- )-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]-- class FakeAgent:- async def run(self, user_prompt: object, **kwargs: object) -> FakeAgentRunResult:- seen_user_prompts.append(user_prompt)- deferred_tool_results = kwargs.get("deferred_tool_results")- if deferred_tool_results is None:- messages: list[ModelMessage] = [- ModelRequest(parts=[UserPromptPart(content="current user")]),- ModelResponse(parts=[first_pending_tool_call]),- ]- captured_messages.extend(messages)- return FakeAgentRunResult(DeferredToolRequests(calls=[first_pending_tool_call]))-- message_history = cast(list[ModelMessage], kwargs["message_history"])- messages = [- *message_history,- ModelRequest(- parts=[- ToolReturnPart(- tool_name="ask_human",- content={"status": "submitted", "values": {"owner": "ops"}},- tool_call_id="tool-call-1",- )- ]- ),- ModelResponse(parts=[second_pending_tool_call]),]- captured_messages.extend(messages)- return FakeAgentRunResult(DeferredToolRequests(calls=[second_pending_tool_call]))-- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> FakeAgent:- del model, tools, output_type- return FakeAgent()-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)- request = _request("current user", include_history=True, include_ask_human=True)- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-ask-human-turn-1",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- first_terminal = sink.events["run-ask-human-turn-1"][-1]- assert isinstance(first_terminal, RunSucceededEvent)-- resumed_request = request.model_copy(deep=True)- resumed_request.session_snapshot = first_terminal.data.session_snapshot- resumed_request.deferred_tool_results = DeferredToolResultsPayload.model_validate(- {- "calls": {- "tool-call-1": {- "status": "submitted",- "action": {"id": "submit", "label": "Submit"},- "values": {"owner": "ops"},- }- }- }- )-- await AgentRunRunner(- sink=sink,- request=resumed_request,- run_id="run-ask-human-turn-2",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- second_terminal = sink.events["run-ask-human-turn-2"][-1]- assert isinstance(second_terminal, RunSucceededEvent)- assert second_terminal.data.output is None- assert second_terminal.data.deferred_tool_call is not None- assert second_terminal.data.deferred_tool_call.tool_call_id == "tool-call-2"- assert seen_user_prompts == ["current user", None]- saved_history = _history_messages_from_snapshot(second_terminal.data.session_snapshot)- assert isinstance(saved_history[1], ModelResponse)- assert saved_history[1].parts == [first_pending_tool_call]- assert isinstance(saved_history[2], ModelRequest)- assert len(saved_history[2].parts) == 1- assert isinstance(saved_history[2].parts[0], ToolReturnPart)- assert saved_history[2].parts[0].tool_name == "ask_human"- assert saved_history[2].parts[0].tool_call_id == "tool-call-1"- assert saved_history[2].parts[0].content == {"status": "submitted", "values": {"owner": "ops"}}- assert isinstance(saved_history[3], ModelResponse)- assert saved_history[3].parts == [second_pending_tool_call]---def test_runner_rejects_deferred_tool_call_without_history_layer(monkeypatch: pytest.MonkeyPatch) -> None:- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]-- class FakeAgent:- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:- return FakeAgentRunResult(- DeferredToolRequests(- calls=[- ToolCallPart(tool_name="ask_human", args={"question": "Need owner"}, tool_call_id="tool-call-1")- ]- )- )-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *args, **kwargs: FakeAgent())- request = _request("current user", include_history=False, include_ask_human=True)- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(- AgentRunValidationError,- match="ask_human deferred tool requests require a 'history' layer so the pending tool call can be resumed",- ):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-ask-human-no-history",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert [event.type for event in sink.events["run-ask-human-no-history"]] == ["run_started", "run_failed"]---def test_runner_rejects_resume_with_deferred_tool_results_without_history_layer(- monkeypatch: pytest.MonkeyPatch,-) -> None:- agent_run_called = False-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]-- class FakeAgent:- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:- nonlocal agent_run_called- agent_run_called = True- return FakeAgentRunResult("unexpected")-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *args, **kwargs: FakeAgent())- request = _request("current user", include_history=False, include_ask_human=True)- request.deferred_tool_results = DeferredToolResultsPayload.model_validate(- {- "calls": {- "tool-call-1": {- "status": "submitted",- "action": {"id": "submit", "label": "Submit"},- "values": {"owner": "ops"},- }- }- }+ },)- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(- AgentRunValidationError,- match="Deferred tool results require a 'history' layer with prior message history",- ):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-ask-human-resume-no-history",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert agent_run_called is False- assert [event.type for event in sink.events["run-ask-human-resume-no-history"]] == ["run_started", "run_failed"]---def test_runner_rejects_multiple_deferred_tool_calls(monkeypatch: pytest.MonkeyPatch) -> None:- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]-- class FakeAgent:- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:- return FakeAgentRunResult(- DeferredToolRequests(- calls=[- ToolCallPart(tool_name="ask_human", args={"question": "One"}, tool_call_id="tool-call-1"),- ToolCallPart(tool_name="ask_human", args={"question": "Two"}, tool_call_id="tool-call-2"),- ]- )- )-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *args, **kwargs: FakeAgent())- request = _request("current user", include_history=True, include_ask_human=True)- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(ValueError, match="supports exactly one deferred call per run"):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-ask-human-multi",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert [event.type for event in sink.events["run-ask-human-multi"]] == ["run_started", "run_failed"]---def test_runner_rejects_deferred_approval_requests(monkeypatch: pytest.MonkeyPatch) -> None:- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]-- class FakeAgent:- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:- return FakeAgentRunResult(- DeferredToolRequests(- approvals=[- ToolCallPart(- tool_name="ask_human", args={"question": "Need approval"}, tool_call_id="tool-call-1"- )- ]- )- )-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *args, **kwargs: FakeAgent())- request = _request("current user", include_history=True, include_ask_human=True)- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(ValueError, match="does not support approval requests"):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-ask-human-approval",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert [event.type for event in sink.events["run-ask-human-approval"]] == ["run_started", "run_failed"]---def test_runner_passes_dynamic_dify_plugin_tools_to_agent(monkeypatch: pytest.MonkeyPatch) -> None:- seen_tools: list[Tool[object]] = []-- async def plugin_tool() -> str:- return "tool"-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]-- async def fake_get_tools(- self: DifyPluginToolsLayer,- *,- http_client: httpx.AsyncClient,- dify_api_http_client: httpx.AsyncClient,- ) -> list[Tool[object]]:- assert self.config.tools[0].tool_name == "web_search"- assert http_client.is_closed is False- assert dify_api_http_client.is_closed is False- return [Tool(plugin_tool, name="web_search")]-- class FakeResult:- output: str = "done"-- class FakeAgent:- async def run(self, *_args: object, **_kwargs: object) -> FakeResult:- return FakeResult()-- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> FakeAgent:- del model, output_type- seen_tools.extend(tools)- return FakeAgent()-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr(DifyPluginToolsLayer, "get_tools", fake_get_tools)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)-- request = CreateRunRequest(- composition=RunComposition(- layers=[- RunLayerSpec(- name="prompt",- type="plain.prompt",- config=PromptLayerConfig(prefix="system", user="hello"),- ),- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- ),- ),- RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type="dify.plugin.llm",- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id="langgenius/openai",- model_provider="openai",- model="demo-model",- ),- ),- RunLayerSpec(- name="tools",- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,- deps={"execution_context": "execution_context"},- config=DifyPluginToolsLayerConfig(- tools=[- DifyPluginToolConfig(- plugin_id="langgenius/tools",- provider="search",- tool_name="web_search",- credential_type="api-key",- parameters=_prepared_plugin_tool_parameters(),- parameters_json_schema=_prepared_plugin_tool_schema(),- )- ]- ),- ),- ]+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:+ services = Services(client, client)+ first, _ = run_runner(request(knowledge, user=user), services, monkeypatch, stream)+ await first.run()+ snapshot = first.terminal_session_snapshot+ saved = history.State.model_validate(snapshot.layers["history"])+ assert any(+ "Knowledge retrieval results" in str(p.content)+ for m in saved.messages+ if isinstance(m, ModelRequest)+ for p in m.parts+ if isinstance(p, UserPromptPart))- )- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-tools",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert [tool.name for tool in seen_tools] == ["web_search"]- terminal = sink.events["run-tools"][-1]- assert isinstance(terminal, RunSucceededEvent)- assert terminal.data.output == "done"---def test_runner_passes_dynamic_dify_knowledge_tools_to_agent(monkeypatch: pytest.MonkeyPatch) -> None:- seen_tools: list[Tool[object]] = []-- async def knowledge_tool() -> str:- return "knowledge"-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]-- async def fake_get_tools(self: DifyKnowledgeBaseLayer, *, http_client: httpx.AsyncClient) -> list[Tool[object]]:- assert self.config.sets[0].dataset_ids == ["dataset-1"]- assert http_client.headers.get("X-Test-Client") == "dify-api"- return [Tool(knowledge_tool, name="knowledge_base_search")]-- class FakeResult:- output: str = "done"-- class FakeAgent:- async def run(self, *_args: object, **_kwargs: object) -> FakeResult:- return FakeResult()-- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> FakeAgent:- del model, output_type- seen_tools.extend(tools)- return FakeAgent()-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr(DifyKnowledgeBaseLayer, "get_tools", fake_get_tools)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)-- request = CreateRunRequest(- composition=RunComposition(- layers=[- RunLayerSpec(- name="prompt",- type="plain.prompt",- config=PromptLayerConfig(prefix="system", user="hello"),- ),- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_id="user-1",- user_from="account",- app_id="app-1",- agent_mode="workflow_run",- invoke_from="service-api",- ),- ),- RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type="dify.plugin.llm",- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id="langgenius/openai",- model_provider="openai",- model="demo-model",- ),- ),- RunLayerSpec(- name="knowledge",- type=DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID,- deps={"execution_context": "execution_context"},- config=DifyKnowledgeBaseLayerConfig.model_validate(- {- "sets": [- {- "id": "support",- "name": "Support KB",- "datasets": [{"id": "dataset-1"}],- "query": {"mode": "generated_query"},- "retrieval": {"mode": "multiple", "top_k": 4},- }- ],- }- ),- ),- ]+ second, _ = run_runner(+ request(knowledge, snapshot=snapshot, user=user), services, monkeypatch, stream, run_id="second")- )- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with (- httpx.AsyncClient() as plugin_client,- httpx.AsyncClient(headers={"X-Test-Client": "dify-api"}) as dify_api_client,- ):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-knowledge-tools",- plugin_daemon_http_client=plugin_client,- dify_api_http_client=dify_api_client,- ).run()-- asyncio.run(scenario())-- assert [tool.name for tool in seen_tools] == ["knowledge_base_search"]---def test_runner_passes_dynamic_dify_core_tools_to_agent(monkeypatch: pytest.MonkeyPatch) -> None:- seen_tools: list[Tool[object]] = []-- async def core_tool() -> str:- return "core"-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]-- async def fake_get_tools(self: DifyCoreToolsLayer, *, http_client: httpx.AsyncClient) -> list[Tool[object]]:- assert self.config.tools[0].provider_type == "builtin"- assert self.config.tools[0].tool_name == "draft_message"- assert http_client.headers.get("X-Test-Client") == "dify-api"- return [Tool(core_tool, name="draft_message")]-- class FakeResult:- output: str = "done"+ await second.run()+ assert len(calls) == 1- class FakeAgent:- async def run(self, *_args: object, **_kwargs: object) -> FakeResult:- return FakeResult()- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> FakeAgent:- del model, output_type- seen_tools.extend(tools)- return FakeAgent()[email protected]("user", ["", ["", " "]])+async def test_empty_current_user_content_fails_before_model_io(monkeypatch, user):+ async def stream(messages, info):+ pytest.fail("blank user input must not reach the model")+ yield "unreachable"- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr(DifyCoreToolsLayer, "get_tools", fake_get_tools)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)-- request = CreateRunRequest(- composition=RunComposition(- layers=[- RunLayerSpec(- name="prompt",- type="plain.prompt",- config=PromptLayerConfig(prefix="system", user="hello"),- ),- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_id="user-1",- user_from="account",- app_id="app-1",- agent_mode="workflow_run",- invoke_from="service-api",- ),- ),- RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type="dify.plugin.llm",- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id="langgenius/openai",- model_provider="openai",- model="demo-model",- ),- ),- RunLayerSpec(- name="core-tools",- type=DIFY_CORE_TOOLS_LAYER_TYPE_ID,- deps={"execution_context": "execution_context"},- config=DifyCoreToolsLayerConfig(- tools=[- DifyCoreToolConfig(- provider_type="builtin",- provider_id="langgenius/dify-gmail/dify-gmail",- tool_name="draft_message",- credential_id="credential-1",- parameters_json_schema={"type": "object", "properties": {}, "required": []},- )- ]- ),- ),- ]- )- )- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with (- httpx.AsyncClient() as plugin_client,- httpx.AsyncClient(headers={"X-Test-Client": "dify-api"}) as dify_api_client,- ):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-core-tools",- plugin_daemon_http_client=plugin_client,- dify_api_http_client=dify_api_client,- ).run()-- asyncio.run(scenario())-- assert [tool.name for tool in seen_tools] == ["draft_message"]---def test_runner_rejects_duplicate_tool_names_across_dynamic_tool_layers(- monkeypatch: pytest.MonkeyPatch,-) -> None:- create_agent_called = False-- async def duplicate_tool() -> str:- return "tool"-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]-- async def fake_get_tools(- _self: DifyPluginToolsLayer,- *,- http_client: httpx.AsyncClient,- dify_api_http_client: httpx.AsyncClient,- ) -> list[Tool[object]]:- assert http_client.is_closed is False- assert dify_api_http_client.is_closed is False- return [Tool(duplicate_tool, name="shared_tool")]-- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> object:- del model, tools, output_type- nonlocal create_agent_called- create_agent_called = True- raise AssertionError("create_agent should not be called when duplicate tool names are detected")-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr(DifyPluginToolsLayer, "get_tools", fake_get_tools)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)-- request = CreateRunRequest(- composition=RunComposition(- layers=[- RunLayerSpec(- name="prompt",- type="plain.prompt",- config=PromptLayerConfig(prefix="system", user="hello"),- ),- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- ),- ),- RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type="dify.plugin.llm",- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id="langgenius/openai",- model_provider="openai",- model="demo-model",- ),- ),- RunLayerSpec(- name="tools-1",- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,- deps={"execution_context": "execution_context"},- config=DifyPluginToolsLayerConfig(- tools=[- DifyPluginToolConfig(- plugin_id="langgenius/tools",- provider="search",- tool_name="web_search",- credential_type="api-key",- parameters=_prepared_plugin_tool_parameters(),- parameters_json_schema=_prepared_plugin_tool_schema(),- )- ]- ),- ),- RunLayerSpec(- name="tools-2",- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,- deps={"execution_context": "execution_context"},- config=DifyPluginToolsLayerConfig(- tools=[- DifyPluginToolConfig(- plugin_id="langgenius/tools",- provider="search",- tool_name="web_search_two",- credential_type="api-key",- parameters=_prepared_plugin_tool_parameters(),- parameters_json_schema=_prepared_plugin_tool_schema(),- )- ]- ),- ),- ]- )- )- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(- AgentRunValidationError,- match="unique tool names across all layers, got duplicates: shared_tool",- ):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-duplicate-tools",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert create_agent_called is False- assert [event.type for event in sink.events["run-duplicate-tools"]] == ["run_started", "run_failed"]- assert sink.statuses["run-duplicate-tools"] == "failed"---def test_runner_rejects_duplicate_tool_names_between_static_and_dynamic_tools(- monkeypatch: pytest.MonkeyPatch,-) -> None:- create_agent_called = False-- def web_search(query: str) -> str:- return query-- async def dynamic_duplicate_tool() -> str:- return "tool"-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]-- async def fake_get_tools(- _self: DifyPluginToolsLayer,- *,- http_client: httpx.AsyncClient,- dify_api_http_client: httpx.AsyncClient,- ) -> list[Tool[object]]:- assert http_client.is_closed is False- assert dify_api_http_client.is_closed is False- return [Tool(dynamic_duplicate_tool, name="web_search")]-- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> object:- del model, tools, output_type- nonlocal create_agent_called- create_agent_called = True- raise AssertionError("create_agent should not be called when duplicate tool names are detected")-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr(DifyPluginToolsLayer, "get_tools", fake_get_tools)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)-- static_tools_provider = LayerProvider.from_factory(- layer_type=StaticToolsTestLayer,- create=lambda _config: StaticToolsTestLayer(tool_entries=(web_search,)),- )- layer_providers = (*create_default_layer_providers(), static_tools_provider)-- request = CreateRunRequest(- composition=RunComposition(- layers=[- RunLayerSpec(- name="prompt",- type="plain.prompt",- config=PromptLayerConfig(prefix="system", user="hello"),- ),- RunLayerSpec(name="static-tools", type=cast(str, StaticToolsTestLayer.type_id)),- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- ),- ),- RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type="dify.plugin.llm",- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id="langgenius/openai",- model_provider="openai",- model="demo-model",- ),- ),- RunLayerSpec(- name="tools",- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,- deps={"execution_context": "execution_context"},- config=DifyPluginToolsLayerConfig(- tools=[- DifyPluginToolConfig(- plugin_id="langgenius/tools",- provider="search",- tool_name="web_search",- credential_type="api-key",- parameters=_prepared_plugin_tool_parameters(),- parameters_json_schema=_prepared_plugin_tool_schema(),- )- ]- ),- ),- ]- )- )- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(- AgentRunValidationError,- match="unique tool names across all layers, got duplicates: web_search",- ):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-static-dynamic-duplicate-tools",- plugin_daemon_http_client=client,- dify_api_http_client=client,- layer_providers=layer_providers,- ).run()-- asyncio.run(scenario())-- assert create_agent_called is False- assert [event.type for event in sink.events["run-static-dynamic-duplicate-tools"]] == ["run_started", "run_failed"]- assert sink.statuses["run-static-dynamic-duplicate-tools"] == "failed"---def test_runner_rejects_duplicate_tool_names_between_shell_and_other_layers(- monkeypatch: pytest.MonkeyPatch,-) -> None:- create_agent_called = False- shell_client = FakeRunnerShellctlClient()-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]-- async def fake_get_tools(- _self: DifyPluginToolsLayer,- *,- http_client: httpx.AsyncClient,- dify_api_http_client: httpx.AsyncClient,- ) -> list[Tool[object]]:- assert http_client.is_closed is False- assert dify_api_http_client.is_closed is False-- async def duplicate_shell_run() -> str:- return "tool"-- return [Tool(duplicate_shell_run, name="shell_run")]-- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> object:- del model, tools, output_type- nonlocal create_agent_called- create_agent_called = True- raise AssertionError("create_agent should not be called when duplicate tool names are detected")-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr(DifyPluginToolsLayer, "get_tools", fake_get_tools)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)-- runtime_backend_profile = RuntimeBackendProfile(- home_snapshots=cast(HomeSnapshotBackend, object()),- execution_bindings=FakeRunnerExecutionBindingBackend(shell_client),- )- layer_providers = create_default_layer_providers(runtime_backend_profile=runtime_backend_profile)-- request = CreateRunRequest(- composition=RunComposition(- layers=[- RunLayerSpec(- name="prompt",- type="plain.prompt",- config=PromptLayerConfig(prefix="system", user="hello"),- ),- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- agent_id="agent-1",- agent_config_version_id="config-1",- user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- ),- ),- RunLayerSpec(- name="runtime",- type=DIFY_RUNTIME_LAYER_TYPE_ID,- config=DifyRuntimeLayerConfig(backend_binding_ref="binding-1"),- ),- RunLayerSpec(- name="shell",- type=DIFY_SHELL_LAYER_TYPE_ID,- deps={"execution_context": "execution_context", "runtime": "runtime"},- config=DifyShellLayerConfig(),- ),- RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type="dify.plugin.llm",- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id="langgenius/openai",- model_provider="openai",- model="demo-model",- ),- ),- RunLayerSpec(- name="tools",- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,- deps={"execution_context": "execution_context"},- config=DifyPluginToolsLayerConfig(- tools=[- DifyPluginToolConfig(- plugin_id="langgenius/tools",- provider="search",- tool_name="web_search",- credential_type="api-key",- parameters=_prepared_plugin_tool_parameters(),- parameters_json_schema=_prepared_plugin_tool_schema(),- )- ]- ),- ),- ]- )- )- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(- AgentRunValidationError,- match="unique tool names across all layers, got duplicates: shell_run",- ):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-shell-duplicate-tools",- plugin_daemon_http_client=client,- dify_api_http_client=client,- layer_providers=layer_providers,- ).run()-- asyncio.run(scenario())-- assert create_agent_called is False- assert shell_client.delete_calls == []- assert shell_client.closed is True- assert [event.type for event in sink.events["run-shell-duplicate-tools"]] == ["run_started", "run_failed"]- assert sink.statuses["run-shell-duplicate-tools"] == "failed"---def test_runner_passes_system_prompt_as_run_instructions_without_history_layer(- monkeypatch: pytest.MonkeyPatch,-) -> None:- model = RecordingTestModel(custom_output_text="done")-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return model # pyright: ignore[reportReturnType]-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- await AgentRunRunner(- sink=sink,- request=_request("current user"),- run_id="run-no-history",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert model.seen_instructions[0] == ["system"]- request_parts = _flatten_message_parts(model.seen_requests[0])- assert len(request_parts) == 1- assert isinstance(request_parts[0], UserPromptPart)- assert request_parts[0].content == "current user"- terminal = sink.events["run-no-history"][-1]- assert isinstance(terminal, RunSucceededEvent)- assert [layer.name for layer in terminal.data.session_snapshot.layers] == [- "prompt",- "execution_context",- DIFY_AGENT_MODEL_LAYER_ID,- ]---def test_runner_passes_stored_history_with_current_instructions_and_replaces_full_history(- monkeypatch: pytest.MonkeyPatch,-) -> None:- model = RecordingTestModel(custom_output_text="done")- stored_history = [- ModelRequest(parts=[UserPromptPart(content="old user")]),- ModelResponse(parts=[TextPart(content="old assistant")]),- ]-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return model # pyright: ignore[reportReturnType]-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- request = _request("current user", include_history=True)- request.session_snapshot = _history_session_snapshot(stored_history)- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-history",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert model.seen_instructions[0] == ["system"]- request_parts = _flatten_message_parts(model.seen_requests[0])- assert isinstance(request_parts[0], UserPromptPart)- assert request_parts[0].content == "old user"- assert isinstance(request_parts[1], TextPart)- assert request_parts[1].content == "old assistant"- assert isinstance(request_parts[2], UserPromptPart)- assert request_parts[2].content == "current user"-- terminal = sink.events["run-history"][-1]- assert isinstance(terminal, RunSucceededEvent)- saved_history = _history_messages_from_snapshot(terminal.data.session_snapshot)- assert saved_history[:2] == stored_history- assert isinstance(saved_history[2], ModelRequest)- assert len(saved_history[2].parts) == 1- assert isinstance(saved_history[2].parts[0], UserPromptPart)- assert saved_history[2].parts[0].content == "current user"- assert isinstance(saved_history[3], ModelResponse)- assert len(saved_history[3].parts) == 1- assert isinstance(saved_history[3].parts[0], TextPart)- assert saved_history[3].parts[0].content == "done"- assert all(not any(isinstance(part, SystemPromptPart) for part in message.parts) for message in saved_history)- assert all(not isinstance(message, ModelRequest) or message.instructions is None for message in saved_history)---def test_runner_with_empty_history_layer_uses_instructions_and_saves_full_history(- monkeypatch: pytest.MonkeyPatch,-) -> None:- model = RecordingTestModel(custom_output_text="done")-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return model # pyright: ignore[reportReturnType]-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- request = _request("current user", include_history=True)- request.session_snapshot = _history_session_snapshot([])- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-empty-history",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert model.seen_instructions[0] == ["system"]- request_parts = _flatten_message_parts(model.seen_requests[0])- assert len(request_parts) == 1- assert isinstance(request_parts[0], UserPromptPart)- assert request_parts[0].content == "current user"-- terminal = sink.events["run-empty-history"][-1]- assert isinstance(terminal, RunSucceededEvent)- saved_history = _history_messages_from_snapshot(terminal.data.session_snapshot)- assert isinstance(saved_history[0], ModelRequest)- assert len(saved_history[0].parts) == 1- assert isinstance(saved_history[0].parts[0], UserPromptPart)- assert saved_history[0].parts[0].content == "current user"- assert isinstance(saved_history[1], ModelResponse)- assert len(saved_history[1].parts) == 1- assert isinstance(saved_history[1].parts[0], TextPart)- assert saved_history[1].parts[0].content == "done"- assert all(not any(isinstance(part, SystemPromptPart) for part in message.parts) for message in saved_history)- assert all(not isinstance(message, ModelRequest) or message.instructions is None for message in saved_history)---def test_runner_failure_with_history_layer_captures_interrupted_history(- monkeypatch: pytest.MonkeyPatch,-) -> None:- stored_history = [- ModelRequest(parts=[UserPromptPart(content="old user")]),- ModelResponse(parts=[TextPart(content="old assistant")]),- ]-- async def stream_response(_messages: list[ModelMessage], _info: object) -> AsyncIterator[str]:- yield "partial"- raise RuntimeError("boom")-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return FunctionModel(stream_function=stream_response)-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- request = _request("current user", include_history=True)- request.session_snapshot = _history_session_snapshot(stored_history)- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(RuntimeError, match="boom"):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-history-failure",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- event_types = [event.type for event in sink.events["run-history-failure"]]- assert event_types[0] == "run_started"- assert sink.statuses["run-history-failure"] == "failed"- terminal = sink.events["run-history-failure"][-1]- assert isinstance(terminal, RunFailedEvent)- assert terminal.data.session_snapshot is not None- _assert_interrupted_history(terminal.data.session_snapshot, stored_history)- assert request.session_snapshot is not None- assert _history_messages_from_snapshot(request.session_snapshot) == stored_history---def test_runner_preserves_history_when_agent_fails_before_capture_is_bound(- monkeypatch: pytest.MonkeyPatch,-) -> None:- stored_history = [- ModelRequest(parts=[UserPromptPart(content="old user")]),- ModelResponse(parts=[TextPart(content="old assistant")]),- ]-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]-- class FakeAgent:- async def run(self, *_args: object, **_kwargs: object) -> None:- raise RuntimeError("boom before capture")-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *_args, **_kwargs: FakeAgent())- request = _request("current user", include_history=True)- request.session_snapshot = _history_session_snapshot(stored_history)- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(RuntimeError, match="boom before capture"):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-history-empty-capture",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- terminal = sink.events["run-history-empty-capture"][-1]- assert isinstance(terminal, RunFailedEvent)- assert terminal.data.session_snapshot is not None- assert _history_messages_from_snapshot(terminal.data.session_snapshot) == stored_history---def test_runner_persists_usage_limit_failure_type_in_event_and_status(- monkeypatch: pytest.MonkeyPatch,-) -> None:- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- runner = AgentRunRunner(- sink=sink,- request=_request(),- run_id="run-limit",- plugin_daemon_http_client=client,- dify_api_http_client=client,- )-- async def exceed_limit() -> RunSuccessOutcome:- raise UsageLimitExceeded("The next request would exceed the request_limit of 500")-- monkeypatch.setattr(runner, "_run_agent", exceed_limit)- with pytest.raises(UsageLimitExceeded):- await runner.run()-- asyncio.run(scenario())-- terminal = sink.events["run-limit"][-1]- assert isinstance(terminal, RunFailedEvent)- assert terminal.data.error_type is RunFailureType.AGENT_RUN_LIMIT_EXCEEDED- assert sink.statuses["run-limit"] == "failed"- assert sink.error_types["run-limit"] is RunFailureType.AGENT_RUN_LIMIT_EXCEEDED---def test_runner_applies_on_exit_overrides_to_success_snapshot(monkeypatch: pytest.MonkeyPatch) -> None:- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- request = _request(- on_exit=LayerExitSignals(- default=ExitIntent.SUSPEND,- layers={"prompt": ExitIntent.DELETE, DIFY_AGENT_MODEL_LAYER_ID: ExitIntent.DELETE},- )- )- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-exit",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- terminal = sink.events["run-exit"][-1]- assert isinstance(terminal, RunSucceededEvent)- assert {layer.name: layer.lifecycle_state for layer in terminal.data.session_snapshot.layers} == {- "prompt": LifecycleState.CLOSED,- "execution_context": LifecycleState.SUSPENDED,- DIFY_AGENT_MODEL_LAYER_ID: LifecycleState.CLOSED,- }---def test_runner_requires_model_layer() -> None:- request = _request(llm_layer_name="not-llm")- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(AgentRunValidationError, match="Missing required"):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-missing-model",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert [event.type for event in sink.events["run-missing-model"]] == ["run_started", "run_failed"]- assert sink.statuses["run-missing-model"] == "failed"---def test_runner_passes_output_layer_spec_to_agent_and_serializes_structured_result(- monkeypatch: pytest.MonkeyPatch,-) -> None:- model = TestModel(- custom_output_args={- "title": "Database outage",- "severity": "high",- "actions": ["page on-call", "open incident bridge"],- }- )-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return model # pyright: ignore[reportReturnType]-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- request = _request(- output_config=DifyOutputLayerConfig(- json_schema={- "type": "object",- "properties": {- "title": {"type": "string"},- "severity": {"type": "string", "enum": ["low", "medium", "high"]},- "actions": {"type": "array", "items": {"type": "string"}},- },- "required": ["title", "severity", "actions"],- "additionalProperties": False,- },- description="Structured incident summary returned by the agent.",- strict=True,- )- )- sink = InMemoryRunEventSink()- expected_snapshot_layer_names = [- "prompt",- "execution_context",- DIFY_AGENT_MODEL_LAYER_ID,- DIFY_AGENT_OUTPUT_LAYER_ID,- ]-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-structured-output",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- first_terminal = sink.events["run-structured-output"][-1]- assert isinstance(first_terminal, RunSucceededEvent)-- resumed_request = request.model_copy(deep=True)- resumed_request.session_snapshot = first_terminal.data.session_snapshot-- await AgentRunRunner(- sink=sink,- request=resumed_request,- run_id="run-structured-output-resume",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert model.last_model_request_parameters is not None- assert len(model.last_model_request_parameters.output_tools) == 1- output_tool = model.last_model_request_parameters.output_tools[0]- assert output_tool.name == "final_output"- assert output_tool.description == "Structured incident summary returned by the agent."- assert output_tool.parameters_json_schema["type"] == "object"- assert output_tool.parameters_json_schema["title"] == "final_output"- assert output_tool.parameters_json_schema["properties"] == {- "title": {"type": "string"},- "severity": {"type": "string", "enum": ["low", "medium", "high"]},- "actions": {"type": "array", "items": {"type": "string"}},- }- assert output_tool.parameters_json_schema["required"] == ["title", "severity", "actions"]- assert output_tool.parameters_json_schema["additionalProperties"] is False- terminal = sink.events["run-structured-output"][-1]- resumed_terminal = sink.events["run-structured-output-resume"][-1]- assert isinstance(terminal, RunSucceededEvent)- assert isinstance(resumed_terminal, RunSucceededEvent)- assert terminal.data.output == {- "title": "Database outage",- "severity": "high",- "actions": ["page on-call", "open incident bridge"],- }- assert resumed_terminal.data.output == terminal.data.output- assert [layer.name for layer in terminal.data.session_snapshot.layers] == expected_snapshot_layer_names- assert [layer.name for layer in resumed_terminal.data.session_snapshot.layers] == expected_snapshot_layer_names- assert all(layer.lifecycle_state is LifecycleState.SUSPENDED for layer in terminal.data.session_snapshot.layers)- assert all(- layer.lifecycle_state is LifecycleState.SUSPENDED for layer in resumed_terminal.data.session_snapshot.layers- )---def test_runner_retries_invalid_structured_output_and_eventually_succeeds(monkeypatch: pytest.MonkeyPatch) -> None:- model = SequenceOutputTestModel(- outputs=[- {"title": "Database outage", "severity": "high", "actions": "page on-call"},- {"title": "Database outage", "severity": "high", "actions": ["page on-call"]},- ]- )-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return model # pyright: ignore[reportReturnType]-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- request = _request(- output_config=DifyOutputLayerConfig(- json_schema={- "type": "object",- "properties": {- "title": {"type": "string"},- "severity": {"type": "string", "enum": ["low", "medium", "high"]},- "actions": {"type": "array", "items": {"type": "string"}},- },- "required": ["title", "severity", "actions"],- "additionalProperties": False,- },- description="Structured incident summary returned by the agent.",- )- )- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-output-retry-success",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- terminal = sink.events["run-output-retry-success"][-1]- assert isinstance(terminal, RunSucceededEvent)- assert terminal.data.output == {- "title": "Database outage",- "severity": "high",- "actions": ["page on-call"],- }- assert model.request_count == 2---def test_runner_fails_when_invalid_structured_output_exhausts_retries(monkeypatch: pytest.MonkeyPatch) -> None:- model = TestModel(- custom_output_args={- "title": "Database outage",- "severity": "high",- "actions": "page on-call",- }- )-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- assert http_client.is_closed is False- return model # pyright: ignore[reportReturnType]-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- request = _request(- output_config=DifyOutputLayerConfig(- json_schema={- "type": "object",- "properties": {- "title": {"type": "string"},- "severity": {"type": "string", "enum": ["low", "medium", "high"]},- "actions": {"type": "array", "items": {"type": "string"}},- },- "required": ["title", "severity", "actions"],- "additionalProperties": False,- },- description="Structured incident summary returned by the agent.",- )- )- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(UnexpectedModelBehavior):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-output-retry-failed",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- event_types = [event.type for event in sink.events["run-output-retry-failed"]]- assert event_types[0] == "run_started"- assert event_types[-1] == "run_failed"- assert "run_succeeded" not in event_types- assert sink.statuses["run-output-retry-failed"] == "failed"---def test_runner_rejects_invalid_output_layer_before_model_resolution(monkeypatch: pytest.MonkeyPatch) -> None:- model_requested = False-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- del http_client- nonlocal model_requested- model_requested = True- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- request = _request(- output_config={- "json_schema": _recursive_output_schema(),- }- )- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(AgentRunValidationError, match=r"Recursive \$defs refs are not supported"):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-invalid-output",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert model_requested is False- assert [event.type for event in sink.events["run-invalid-output"]] == ["run_started", "run_failed"]- assert sink.statuses["run-invalid-output"] == "failed"---def test_runner_rejects_misnamed_output_layer_before_model_resolution(monkeypatch: pytest.MonkeyPatch) -> None:- model_requested = False- request = CreateRunRequest(- composition=RunComposition(- layers=[- RunLayerSpec(- name="prompt",- type="plain.prompt",- config=PromptLayerConfig(prefix="system", user="hello"),- ),- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- ),- ),- RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type="dify.plugin.llm",- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id="langgenius/openai",- model_provider="openai",- model="demo-model",- ),- ),- RunLayerSpec(- name="structured-output",- type=DIFY_OUTPUT_LAYER_TYPE_ID,- config=DifyOutputLayerConfig(- json_schema={- "type": "object",- "properties": {"title": {"type": "string"}},- "required": ["title"],- "additionalProperties": False,- }- ),- ),- ]- ),- on_exit=LayerExitSignals(),- )- sink = InMemoryRunEventSink()-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- del http_client- nonlocal model_requested- model_requested = True- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(AgentRunValidationError, match="must use reserved layer name 'output'"):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-misnamed-output",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert model_requested is False- assert [event.type for event in sink.events["run-misnamed-output"]] == ["run_started", "run_failed"]- assert sink.statuses["run-misnamed-output"] == "failed"---def test_runner_rejects_multiple_output_layers_before_model_resolution(monkeypatch: pytest.MonkeyPatch) -> None:- model_requested = False- request = CreateRunRequest(- composition=RunComposition(- layers=[- RunLayerSpec(- name="prompt",- type="plain.prompt",- config=PromptLayerConfig(prefix="system", user="hello"),- ),- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- ),- ),- RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type="dify.plugin.llm",- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id="langgenius/openai",- model_provider="openai",- model="demo-model",- ),- ),- RunLayerSpec(- name=DIFY_AGENT_OUTPUT_LAYER_ID,- type=DIFY_OUTPUT_LAYER_TYPE_ID,- config=DifyOutputLayerConfig(- json_schema={- "type": "object",- "properties": {"title": {"type": "string"}},- "required": ["title"],- "additionalProperties": False,- }- ),- ),- RunLayerSpec(- name="secondary-output",- type=DIFY_OUTPUT_LAYER_TYPE_ID,- config=DifyOutputLayerConfig(- json_schema={- "type": "object",- "properties": {"summary": {"type": "string"}},- "required": ["summary"],- "additionalProperties": False,- }- ),- ),- ]- ),- on_exit=LayerExitSignals(),- )- sink = InMemoryRunEventSink()-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- del http_client- nonlocal model_requested- model_requested = True- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(AgentRunValidationError, match="Only one 'dify.output' layer is supported"):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-duplicate-output",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert model_requested is False- assert [event.type for event in sink.events["run-duplicate-output"]] == ["run_started", "run_failed"]- assert sink.statuses["run-duplicate-output"] == "failed"---def test_runner_rejects_reserved_output_name_with_wrong_layer_type_before_model_resolution(- monkeypatch: pytest.MonkeyPatch,-) -> None:- model_requested = False-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- del http_client- nonlocal model_requested- model_requested = True- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- request = CreateRunRequest(- composition=RunComposition(- layers=[- RunLayerSpec(- name="prompt",- type="plain.prompt",- config=PromptLayerConfig(prefix="system", user="hello"),- ),- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- ),- ),- RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type="dify.plugin.llm",- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id="langgenius/openai",- model_provider="openai",- model="demo-model",- ),- ),- RunLayerSpec(- name=DIFY_AGENT_OUTPUT_LAYER_ID,- type="plain.prompt",- config=PromptLayerConfig(user="not structured output"),- ),- ]- ),- on_exit=LayerExitSignals(),- )- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(- AgentRunValidationError, match=r"Layer 'output' must be DifyOutputLayer, got PromptLayer"- ):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-wrong-output-type",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert model_requested is False- assert [event.type for event in sink.events["run-wrong-output-type"]] == ["run_started", "run_failed"]- assert sink.statuses["run-wrong-output-type"] == "failed"---def test_runner_rejects_misnamed_output_layer_before_provider_checks() -> None:- request = CreateRunRequest(- composition=RunComposition(- layers=[- RunLayerSpec(- name="prompt",- type="plain.prompt",- config=PromptLayerConfig(prefix="system", user="hello"),- ),- RunLayerSpec(- name="structured-output",- type=DIFY_OUTPUT_LAYER_TYPE_ID,- config=DifyOutputLayerConfig(- json_schema={- "type": "object",- "properties": {"title": {"type": "string"}},- "required": ["title"],- "additionalProperties": False,- }- ),- ),- ]- ),- on_exit=LayerExitSignals(),- )- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(AgentRunValidationError, match="must use reserved layer name 'output'"):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-misnamed-output-before-providers",- plugin_daemon_http_client=client,- dify_api_http_client=client,- layer_providers=(),- ).run()-- asyncio.run(scenario())-- assert [event.type for event in sink.events["run-misnamed-output-before-providers"]] == [- "run_started",- "run_failed",- ]- assert sink.statuses["run-misnamed-output-before-providers"] == "failed"---def test_runner_rejects_unknown_on_exit_layer_id() -> None:- request = _request(on_exit=LayerExitSignals(layers={"missing": ExitIntent.DELETE}))- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(AgentRunValidationError, match="missing"):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-unknown-signal",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert [event.type for event in sink.events["run-unknown-signal"]] == ["run_started", "run_failed"]- assert sink.statuses["run-unknown-signal"] == "failed"---def test_runner_honors_explicit_empty_layer_providers() -> None:- request = _request()- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(AgentRunValidationError, match="plain.prompt"):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-empty-providers",- plugin_daemon_http_client=client,- dify_api_http_client=client,- layer_providers=(),- ).run()-- asyncio.run(scenario())-- assert [event.type for event in sink.events["run-empty-providers"]] == ["run_started", "run_failed"]- assert sink.statuses["run-empty-providers"] == "failed"---def test_runner_fails_empty_user_prompts() -> None:- request = _request("")- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(AgentRunValidationError):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-2",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert [event.type for event in sink.events["run-2"]] == ["run_started", "run_failed"]- assert sink.statuses["run-2"] == "failed"---def test_runner_fails_blank_string_user_prompt_list() -> None:- request = _request(["", " "])- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(AgentRunValidationError):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-3",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert [event.type for event in sink.events["run-3"]] == ["run_started", "run_failed"]- assert sink.statuses["run-3"] == "failed"---def test_runner_rejects_reserved_llm_layer_name_with_wrong_type() -> None:- request = CreateRunRequest(- composition=RunComposition(- layers=[- RunLayerSpec(- name="prompt",- type="plain.prompt",- config=PromptLayerConfig(prefix="system", user="hello"),- ),- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- ),- ),- RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type="plain.prompt",- config=PromptLayerConfig(user="not an llm"),- ),- ]- ),- on_exit=LayerExitSignals(),- )- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(AgentRunValidationError, match="DifyPluginLLMLayer"):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-4",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert [event.type for event in sink.events["run-4"]] == ["run_started", "run_failed"]- assert sink.statuses["run-4"] == "failed"---def test_runner_rejects_closed_session_snapshot_as_validation_error() -> None:- request = _request()- request.session_snapshot = CompositorSessionSnapshot(- layers=[- LayerSessionSnapshot(- name="prompt",- lifecycle_state=LifecycleState.CLOSED,- runtime_state={},- ),- LayerSessionSnapshot(- name="execution_context",- lifecycle_state=LifecycleState.NEW,- runtime_state={},- ),- LayerSessionSnapshot(- name=DIFY_AGENT_MODEL_LAYER_ID,- lifecycle_state=LifecycleState.NEW,- runtime_state={},- ),- ]- )- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(AgentRunValidationError, match="CLOSED snapshots cannot be entered"):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-closed-snapshot",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert [event.type for event in sink.events["run-closed-snapshot"]] == ["run_started", "run_failed"]- assert sink.statuses["run-closed-snapshot"] == "failed"- terminal = sink.events["run-closed-snapshot"][-1]- assert isinstance(terminal, RunFailedEvent)- assert request.session_snapshot is not None- assert terminal.data.session_snapshot is None---def test_runner_treats_missing_runtime_dependency_as_validation_error() -> None:- request = CreateRunRequest(- composition=RunComposition(- layers=[- RunLayerSpec(- name="prompt",- type="plain.prompt",- config=PromptLayerConfig(prefix="system", user="hello"),- ),- RunLayerSpec(name="shell", type=DIFY_SHELL_LAYER_TYPE_ID, config=DifyShellLayerConfig()),- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- ),- ),- RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type="dify.plugin.llm",- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id="langgenius/openai",- model_provider="openai",- model="demo-model",- ),- ),- ]- )- )- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(AgentRunValidationError, match="Dependency 'runtime' is required"):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-missing-shell-entrypoint",- plugin_daemon_http_client=client,- dify_api_http_client=client,- ).run()-- asyncio.run(scenario())-- assert [event.type for event in sink.events["run-missing-shell-entrypoint"]] == ["run_started", "run_failed"]- assert sink.statuses["run-missing-shell-entrypoint"] == "failed"---def test_runner_treats_invalid_shell_snapshot_offsets_as_validation_error() -> None:- request = CreateRunRequest(- composition=RunComposition(- layers=[- RunLayerSpec(- name="prompt",- type="plain.prompt",- config=PromptLayerConfig(prefix="system", user="hello"),- ),- RunLayerSpec(name="shell", type=DIFY_SHELL_LAYER_TYPE_ID, config=DifyShellLayerConfig()),- RunLayerSpec(- name="execution_context",- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,- config=DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- ),- ),- RunLayerSpec(- name=DIFY_AGENT_MODEL_LAYER_ID,- type="dify.plugin.llm",- deps={"execution_context": "execution_context"},- config=DifyPluginLLMLayerConfig(- plugin_id="langgenius/openai",- model_provider="openai",- model="demo-model",- ),- ),- ]- ),- session_snapshot=CompositorSessionSnapshot(- layers=[- LayerSessionSnapshot(name="prompt", lifecycle_state=LifecycleState.SUSPENDED, runtime_state={}),- LayerSessionSnapshot(- name="shell",- lifecycle_state=LifecycleState.SUSPENDED,- runtime_state={- "session_id": "abc12ff",- "workspace_cwd": "~/workspace/abc12ff",- "job_ids": ["job-1"],- "job_offsets": {"job-1": -1},- },- ),- LayerSessionSnapshot(- name="execution_context",- lifecycle_state=LifecycleState.SUSPENDED,- runtime_state={},- ),- LayerSessionSnapshot(- name=DIFY_AGENT_MODEL_LAYER_ID,- lifecycle_state=LifecycleState.SUSPENDED,- runtime_state={},- ),- ]- ),- )- sink = InMemoryRunEventSink()-- async def scenario() -> None:- async with httpx.AsyncClient() as client:- with pytest.raises(AgentRunValidationError, match="job_offsets"):- await AgentRunRunner(- sink=sink,- request=request,- run_id="run-invalid-shell-offset",- plugin_daemon_http_client=client,- dify_api_http_client=client,- layer_providers=create_default_layer_providers(),- ).run()-- asyncio.run(scenario())-- assert [event.type for event in sink.events["run-invalid-shell-offset"]] == ["run_started", "run_failed"]- assert sink.statuses["run-invalid-shell-offset"] == "failed"---def _request_with_tool_layer(user: str) -> CreateRunRequest:- request = _request(user, include_history=True)- request.composition.layers.append(- RunLayerSpec(- name="tools",- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,- deps={"execution_context": "execution_context"},- config=DifyPluginToolsLayerConfig(- tools=[- DifyPluginToolConfig(- plugin_id="langgenius/tools",- provider="search",- tool_name="web_search",- credential_type="api-key",- parameters=_prepared_plugin_tool_parameters(),- parameters_json_schema=_prepared_plugin_tool_schema(),- )- ]- ),- )- )- return request---def _install_tool_calling_model_and_blocking_tool(monkeypatch: pytest.MonkeyPatch, tool_started: asyncio.Event) -> None:- async def blocking_tool(query: str) -> str:- del query- _ = tool_started.set()- await asyncio.Event().wait()- return "unreachable"-- async def call_web_search(_messages: list[ModelMessage], _info: object) -> AsyncIterator[DeltaToolCalls]:- yield {- 0: DeltaToolCall(- name="web_search",- json_args='{"query": "dify"}',- tool_call_id="call-1",- )- }-- async def fake_get_tools(- _self: DifyPluginToolsLayer,- *,- http_client: httpx.AsyncClient,- dify_api_http_client: httpx.AsyncClient,- ) -> list[Tool[object]]:- del http_client, dify_api_http_client- return [Tool(blocking_tool, name="web_search")]-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- del http_client, agent_run_id- return FunctionModel(stream_function=call_web_search)-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- monkeypatch.setattr(DifyPluginToolsLayer, "get_tools", fake_get_tools)---def test_runner_marks_unexecuted_tool_calls_when_run_is_cancelled(monkeypatch: pytest.MonkeyPatch) -> None:- tool_started = asyncio.Event()- _install_tool_calling_model_and_blocking_tool(monkeypatch, tool_started)- sink = InMemoryRunEventSink()-- async def scenario() -> AgentRunRunner:- async with httpx.AsyncClient() as client:- runner = AgentRunRunner(- sink=sink,- request=_request_with_tool_layer("find something"),- run_id="run-cancel-tool-call",- plugin_daemon_http_client=client,- dify_api_http_client=client,- )- task = asyncio.create_task(runner.run())- await asyncio.wait_for(tool_started.wait(), timeout=5)- _ = task.cancel()- with pytest.raises(asyncio.CancelledError):- await task- return runner-- runner = asyncio.run(scenario())-- assert runner.terminal_session_snapshot is not None- saved_history = _history_messages_from_snapshot(runner.terminal_session_snapshot)- pending_response = saved_history[-1]- assert isinstance(pending_response, ModelResponse)- assert pending_response.state == "interrupted"- assert [part.tool_call_id for part in pending_response.tool_calls] == ["call-1"]---def test_runner_continues_conversation_after_a_cancelled_tool_call(monkeypatch: pytest.MonkeyPatch) -> None:- tool_started = asyncio.Event()- _install_tool_calling_model_and_blocking_tool(monkeypatch, tool_started)- sink = InMemoryRunEventSink()-- async def scenario() -> AgentRunRunner:- async with httpx.AsyncClient() as client:- cancelled_runner = AgentRunRunner(- sink=sink,- request=_request_with_tool_layer("find something"),- run_id="run-cancel-first",- plugin_daemon_http_client=client,- dify_api_http_client=client,- )- task = asyncio.create_task(cancelled_runner.run())- await asyncio.wait_for(tool_started.wait(), timeout=5)- _ = task.cancel()- with pytest.raises(asyncio.CancelledError):- await task-- assert cancelled_runner.terminal_session_snapshot is not None-- async def answer(_messages: list[ModelMessage], _info: object) -> AsyncIterator[str]:- yield "second answer"-- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):- del http_client, agent_run_id- return FunctionModel(stream_function=answer)-- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)- follow_up = _request_with_tool_layer("what happened?")- follow_up.session_snapshot = cancelled_runner.terminal_session_snapshot- follow_up_runner = AgentRunRunner(- sink=sink,- request=follow_up,- run_id="run-continue",- plugin_daemon_http_client=client,- dify_api_http_client=client,- )- await follow_up_runner.run()- return follow_up_runner-- follow_up_runner = asyncio.run(scenario())-- terminal = sink.events["run-continue"][-1]- assert isinstance(terminal, RunSucceededEvent)- assert terminal.data.output == "second answer"- assert follow_up_runner.terminal_session_snapshot is not None- saved_history = _history_messages_from_snapshot(follow_up_runner.terminal_session_snapshot)- interrupted_returns = [- part- for part in _flatten_message_parts(saved_history)- if isinstance(part, ToolReturnPart) and part.tool_call_id == "call-1"- ]- assert len(interrupted_returns) == 1- assert interrupted_returns[0].outcome == "interrupted"+ async with httpx.AsyncClient() as client:+ runner, sink = run_runner(request(user=user), Services(client, client), monkeypatch, stream)+ with pytest.raises(ValueError, match="run.user_prompts must not be empty"):+ await runner.run()+ assert isinstance(sink.events["test"][-1], RunFailedEvent)diff --git a/dify-agent/tests/local/dify_agent/runtime/test_runtime_history.py b/dify-agent/tests/local/dify_agent/runtime/test_runtime_history.pydeleted file mode 100644index 43031422715..00000000000--- a/dify-agent/tests/local/dify_agent/runtime/test_runtime_history.py+++ /dev/null@@ -1,169 +0,0 @@-import asyncio--import pytest-from pydantic_ai.messages import (- ModelRequest,- ModelResponse,- SystemPromptPart,- TextPart,- ToolCallPart,- UserPromptPart,-)--from agenton.compositor import Compositor, LayerNode-from agenton_collections.layers.pydantic_ai import (- PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,- PydanticAIHistoryLayer,-)-from dify_agent.protocol import DIFY_AGENT_HISTORY_LAYER_ID-from dify_agent.protocol.schemas import RunComposition, RunLayerSpec-from dify_agent.runtime.compositor_factory import create_default_layer_providers-from dify_agent.runtime.history import (- get_history_layer,- replace_run_history,- validate_history_layer_composition,-)---def test_default_layer_providers_include_pydantic_ai_history_layer() -> None:- providers = create_default_layer_providers()-- assert PYDANTIC_AI_HISTORY_LAYER_TYPE_ID in {provider.type_id for provider in providers}---def test_validate_history_layer_composition_accepts_absent_or_reserved_history_layer() -> None:- validate_history_layer_composition(RunComposition(layers=[]))- validate_history_layer_composition(- RunComposition(- layers=[- RunLayerSpec(- name=DIFY_AGENT_HISTORY_LAYER_ID,- type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,- )- ]- )- )---def test_validate_history_layer_composition_rejects_multiple_history_layers() -> None:- composition = RunComposition(- layers=[- RunLayerSpec(name=DIFY_AGENT_HISTORY_LAYER_ID, type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID),- RunLayerSpec(name="secondary-history", type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID),- ]- )-- with pytest.raises(ValueError, match="Only one 'pydantic_ai.history' layer is supported"):- validate_history_layer_composition(composition)---def test_validate_history_layer_composition_rejects_misnamed_history_layer() -> None:- composition = RunComposition(- layers=[- RunLayerSpec(name="chat-history", type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID),- ]- )-- with pytest.raises(ValueError, match="must use reserved layer name 'history'"):- validate_history_layer_composition(composition)---def test_validate_history_layer_composition_rejects_history_layer_dependencies() -> None:- composition = RunComposition(- layers=[- RunLayerSpec(- name=DIFY_AGENT_HISTORY_LAYER_ID,- type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,- deps={"prompt": "prompt"},- )- ]- )-- with pytest.raises(ValueError, match="does not support dependencies"):- validate_history_layer_composition(composition)---def test_get_history_layer_returns_optional_active_history_layer() -> None:- compositor = Compositor([LayerNode(DIFY_AGENT_HISTORY_LAYER_ID, PydanticAIHistoryLayer)])-- async def scenario() -> None:- async with compositor.enter() as run:- history_layer = get_history_layer(run)-- assert isinstance(history_layer, PydanticAIHistoryLayer)-- asyncio.run(scenario())---def test_replace_run_history_persists_full_history_without_instructions() -> None:- history_layer = PydanticAIHistoryLayer()- history_layer.replace_messages([ModelRequest(parts=[UserPromptPart(content="stale")])])- messages = [- ModelRequest(- parts=[SystemPromptPart(content="Summary of previous conversation:\n\nsummary")],- instructions="current instructions",- ),- ModelRequest(parts=[UserPromptPart(content="new user")]),- ModelResponse(parts=[TextPart(content="new assistant")]),- ]-- replace_run_history(history_layer, messages)-- persisted = history_layer.message_history- assert len(persisted) == 3- persisted_request = persisted[0]- assert isinstance(persisted_request, ModelRequest)- assert persisted_request.instructions is None- assert persisted_request.parts == messages[0].parts- assert persisted[1:] == messages[1:]- source_request = messages[0]- assert isinstance(source_request, ModelRequest)- assert source_request.instructions == "current instructions"---def test_replace_run_history_marks_unexecuted_tool_calls_of_an_interrupted_run() -> None:- history_layer = PydanticAIHistoryLayer()- messages = [- ModelRequest(parts=[UserPromptPart(content="run a search")]),- ModelResponse(parts=[ToolCallPart(tool_name="search", args={}, tool_call_id="call-1")]),- ]-- replace_run_history(history_layer, messages, interrupted=True)-- persisted = history_layer.message_history- assert len(persisted) == 2- persisted_response = persisted[-1]- assert isinstance(persisted_response, ModelResponse)- assert persisted_response.state == "interrupted"- assert persisted_response.parts == messages[1].parts- source_response = messages[1]- assert isinstance(source_response, ModelResponse)- assert source_response.state == "complete"---def test_replace_run_history_keeps_open_tool_calls_of_a_finished_run() -> None:- history_layer = PydanticAIHistoryLayer()- messages = [- ModelRequest(parts=[UserPromptPart(content="ask me something")]),- ModelResponse(parts=[ToolCallPart(tool_name="ask_human", args={}, tool_call_id="call-1")]),- ]-- replace_run_history(history_layer, messages)-- persisted_response = history_layer.message_history[-1]- assert isinstance(persisted_response, ModelResponse)- assert persisted_response.state == "complete"---def test_replace_run_history_leaves_an_interrupted_run_without_tool_calls_alone() -> None:- history_layer = PydanticAIHistoryLayer()- messages = [- ModelRequest(parts=[UserPromptPart(content="hello")]),- ModelResponse(parts=[TextPart(content="partial")]),- ]-- replace_run_history(history_layer, messages, interrupted=True)-- persisted_response = history_layer.message_history[-1]- assert isinstance(persisted_response, ModelResponse)- assert persisted_response.state == "complete"diff --git a/dify-agent/tests/local/dify_agent/server/test_app.py b/dify-agent/tests/local/dify_agent/server/test_app.pyindex 8bab0a95bf2..3841cd7c662 100644--- a/dify-agent/tests/local/dify_agent/server/test_app.py+++ b/dify-agent/tests/local/dify_agent/server/test_app.py@@ -6,24 +6,15 @@ import timefrom typing import ClassVarimport httpx+from dify_agent.runtime.context import Servicesimport pytestfrom fastapi.testclient import TestClientimport dify_agent.server.app as app_moduleimport dify_agent.server.observability as server_observabilityfrom dify_agent.layers.execution_context import DifyExecutionContextLayerConfig-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer-from dify_agent.layers.knowledge.configs import DifyKnowledgeBaseLayerConfig-from dify_agent.layers.knowledge.layer import DifyKnowledgeBaseLayer-from dify_agent.layers.shell import DifyShellLayerConfig-from dify_agent.layers.shell.layer import DifyShellLayer-from dify_agent.layers.runtime import DifyRuntimeLayerConfig-from dify_agent.layers.runtime.layer import DifyRuntimeLayer-from dify_agent.runtime_backend.local import LocalExecutionBindingBackend-from dify_agent.runtime.compositor_factory import DifyAgentLayerProviderfrom dify_agent.server.app import create_app, create_dify_api_inner_http_client, create_plugin_daemon_http_clientfrom dify_agent.server.settings import ServerSettings-from dify_agent.storage.redis_run_store import RedisRunStore@pytest.fixture(autouse=True)@@ -92,7 +83,7 @@ class FakeRunScheduler:stream_text_delta_coalescing_enabled: boolstream_text_delta_flush_interval_seconds: floatstream_text_delta_max_chars: int- layer_providers: tuple[DifyAgentLayerProvider, ...]+ services: Servicesplugin_daemon_http_client: FakePluginDaemonHttpClientdify_api_http_client: FakePluginDaemonHttpClientshutdown_called: bool@@ -101,14 +92,12 @@ class FakeRunScheduler:self,*,store: object,- plugin_daemon_http_client: FakePluginDaemonHttpClient,- dify_api_http_client: FakePluginDaemonHttpClient,+ services: Services,shutdown_grace_seconds: float,run_timeout_seconds: float,stream_text_delta_coalescing_enabled: bool,stream_text_delta_flush_interval_seconds: float,stream_text_delta_max_chars: int,- layer_providers: tuple[DifyAgentLayerProvider, ...],agent_observability: object | None = None,) -> None:self.store = store@@ -117,9 +106,9 @@ class FakeRunScheduler:self.stream_text_delta_coalescing_enabled = stream_text_delta_coalescing_enabledself.stream_text_delta_flush_interval_seconds = stream_text_delta_flush_interval_secondsself.stream_text_delta_max_chars = stream_text_delta_max_chars- self.layer_providers = layer_providers- self.plugin_daemon_http_client = plugin_daemon_http_client- self.dify_api_http_client = dify_api_http_client+ self.services = services+ self.plugin_daemon_http_client = services.plugin_daemon_http_client+ self.dify_api_http_client = services.dify_api_http_clientself.agent_observability = agent_observabilityself.shutdown_called = Falseself.created.append(self)@@ -210,143 +199,6 @@ def test_create_app_authenticates_control_plane_routes(assert client.post(path, headers={"Authorization": "Bearer secret-token"}, json={}).status_code != 401-def test_create_app_creates_scheduler_and_closes_after_shutdown(monkeypatch: pytest.MonkeyPatch) -> None:- fake_redis = FakeRedis()- fake_http_client = FakePluginDaemonHttpClient()- fake_dify_api_http_client = FakePluginDaemonHttpClient()- FakeRunScheduler.created.clear()- FakeRedisModule.fake_redis = fake_redis- monkeypatch.setattr(app_module, "Redis", FakeRedisModule)- monkeypatch.setattr(app_module, "RunScheduler", FakeRunScheduler)-- def fake_create_plugin_daemon_http_client(_settings: ServerSettings) -> FakePluginDaemonHttpClient:- return fake_http_client-- def fake_create_dify_api_inner_http_client(_settings: ServerSettings) -> FakePluginDaemonHttpClient:- return fake_dify_api_http_client-- monkeypatch.setattr(app_module, "create_plugin_daemon_http_client", fake_create_plugin_daemon_http_client)- monkeypatch.setattr(app_module, "create_dify_api_inner_http_client", fake_create_dify_api_inner_http_client)-- settings = ServerSettings(- redis_url="redis://example.invalid/0",- redis_prefix="test",- shutdown_grace_seconds=5,- run_timeout_seconds=17,- run_retention_seconds=7,- run_event_stream_max_length=23,- stream_text_delta_coalescing_enabled=False,- stream_text_delta_flush_interval_ms=250,- stream_text_delta_max_chars=2048,- plugin_daemon_url="http://plugin-daemon",- plugin_daemon_api_key="daemon-secret",- inner_api_url="http://dify-api",- inner_api_key="inner-secret",- sandbox_files_base_url="http://api:5001",- local_sandbox_endpoint="http://shellctl",- local_sandbox_auth_token="shell-secret",- agent_stub_api_base_url="https://agent.example.com/agent-stub",- server_secret_key=_base64url_secret(b"1" * 32),- outbound_http_connect_timeout=1,- outbound_http_read_timeout=2,- outbound_http_write_timeout=3,- outbound_http_pool_timeout=4,- outbound_http_max_connections=5,- outbound_http_max_keepalive_connections=3,- outbound_http_keepalive_expiry=6,- )-- with TestClient(create_app(settings)):- assert len(FakeRunScheduler.created) == 1- scheduler = FakeRunScheduler.created[0]- assert scheduler.shutdown_grace_seconds == 5- assert scheduler.run_timeout_seconds == 17- assert scheduler.stream_text_delta_coalescing_enabled is False- assert scheduler.stream_text_delta_flush_interval_seconds == 0.25- assert scheduler.stream_text_delta_max_chars == 2048- layer_providers = scheduler.layer_providers- assert isinstance(layer_providers, tuple)- execution_context_provider = next(- provider for provider in layer_providers if provider.type_id == "dify.execution_context"- )- execution_context_layer = execution_context_provider.create_layer(- DifyExecutionContextLayerConfig(- tenant_id="tenant-1",- user_from="account",- agent_mode="workflow_run",- invoke_from="service-api",- )- )- shell_provider = next(provider for provider in layer_providers if provider.type_id == "dify.shell")- shell_layer = shell_provider.create_layer(DifyShellLayerConfig())- assert isinstance(execution_context_layer, DifyExecutionContextLayer)- assert isinstance(shell_layer, DifyShellLayer)- assert execution_context_layer.daemon_url == "http://plugin-daemon"- assert execution_context_layer.daemon_api_key == "daemon-secret"- assert shell_layer.agent_stub_token_factory is not None- token = shell_layer.agent_stub_token_factory(_execution_context(), session_id="abc12ff")- token_codec = settings.create_agent_stub_token_codec()- assert token_codec is not None- decoded = token_codec.decode_token(token)- assert decoded.execution_context == _execution_context()- assert decoded.session_id == "abc12ff"- knowledge_provider = next(provider for provider in layer_providers if provider.type_id == "dify.knowledge_base")- knowledge_layer = knowledge_provider.create_layer(- DifyKnowledgeBaseLayerConfig.model_validate(- {- "sets": [- {- "id": "support",- "name": "Support KB",- "datasets": [{"id": "dataset-1"}],- "query": {"mode": "generated_query"},- "retrieval": {"mode": "multiple", "top_k": 2},- }- ],- }- )- )- assert isinstance(knowledge_layer, DifyKnowledgeBaseLayer)- assert knowledge_layer.inner_api_url == "http://dify-api"- assert knowledge_layer.inner_api_key == "inner-secret"- runtime_provider = next(provider for provider in layer_providers if provider.type_id == "dify.runtime")- runtime_layer = runtime_provider.create_layer(DifyRuntimeLayerConfig(backend_binding_ref="binding-1"))- assert isinstance(runtime_layer, DifyRuntimeLayer)- assert isinstance(runtime_layer.backend, LocalExecutionBindingBackend)- assert shell_layer.agent_stub_api_base_url == "https://agent.example.com/agent-stub"- http_client = scheduler.plugin_daemon_http_client- assert http_client is fake_http_client- assert http_client.is_closed is False- assert scheduler.dify_api_http_client is fake_dify_api_http_client- assert scheduler.dify_api_http_client.is_closed is False- store = scheduler.store- assert isinstance(store, RedisRunStore)- assert store.run_retention_seconds == 7- assert store.run_event_stream_max_length == 23- assert any(getattr(route, "path", None) == "/agent-stub/connections" for route in create_app(settings).routes)- assert any(- getattr(route, "path", None) == "/agent-stub/files/upload-request" for route in create_app(settings).routes- )- assert any(- getattr(route, "path", None) == "/agent-stub/files/download-request"- for route in create_app(settings).routes- )- route_paths = create_app(settings).openapi()["paths"]- assert {- "/execution-bindings/files/list",- "/execution-bindings/files/read",- "/execution-bindings/files/download",- }.issubset(route_paths)- assert "/workspace/files/list" not in route_paths- assert "/workspace/files/read" not in route_paths- assert "/workspace/files/upload" not in route_paths-- assert FakeRunScheduler.created[0].shutdown_called is True- assert FakeRunScheduler.created[0].dify_api_http_client.is_closed is True- assert FakeRunScheduler.created[0].plugin_daemon_http_client.is_closed is True- assert fake_redis.closed is True--def test_create_app_wires_authenticated_agent_stub_connection_route(monkeypatch: pytest.MonkeyPatch) -> None:fake_redis, fake_http_client = _patch_app_lifecycle(monkeypatch)settings = ServerSettings(diff --git a/dify-agent/tests/local/dify_agent/server/test_observability_isolation.py b/dify-agent/tests/local/dify_agent/server/test_observability_isolation.pyindex 7d48d45fd2e..28f493c45bb 100644--- a/dify-agent/tests/local/dify_agent/server/test_observability_isolation.py+++ b/dify-agent/tests/local/dify_agent/server/test_observability_isolation.py@@ -21,6 +21,8 @@ from pydantic_ai import Agent, Toolfrom pydantic_ai.models.test import TestModelimport dify_agent.server.observability as observability+from pydantic_ai.toolsets import FunctionToolset+from dify_agent.runtime.agent_factory import create_agentfrom dify_agent.runtime.observability import IsolatedTracerProviderfrom dify_agent.server.observability import configure_agent_observability@@ -156,7 +158,11 @@ def test_agent_pipeline_is_isolated_from_platform_endpoint_and_credentials(agent_observability = configure_agent_observability(settings)assert agent_observability is not None- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])+ agent = create_agent(+ TestModel(custom_output_text="done"),+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],+ capabilities=[],+ )assert agent.instrument is Falseagent_observability.instrument(agent)@@ -203,7 +209,9 @@ def test_agent_pipeline_empty_headers_send_no_platform_credentials(agent_observability = configure_agent_observability(settings)assert agent_observability is not None- agent = create_agent(TestModel(custom_output_text="done"), tools=[])+ agent = create_agent(+ TestModel(custom_output_text="done"), toolsets=[FunctionToolset(tools=[])], capabilities=[]+ )agent_observability.instrument(agent)_ = agent.run_sync("business-marker-input")assert agent_observability.client.force_flush(timeout_millis=10000)@@ -228,7 +236,9 @@ def test_agent_observability_disabled_creates_no_instance_or_export()assert configure_agent_observability(settings) is None- agent = create_agent(TestModel(custom_output_text="done"), tools=[])+ agent = create_agent(+ TestModel(custom_output_text="done"), toolsets=[FunctionToolset(tools=[])], capabilities=[]+ )assert agent.instrument is False_ = agent.run_sync("business-marker-input")diff --git a/dify-agent/tests/local/dify_agent/server/test_runs_routes.py b/dify-agent/tests/local/dify_agent/server/test_runs_routes.pyindex ce2c6247a7c..c39fed9fddd 100644--- a/dify-agent/tests/local/dify_agent/server/test_runs_routes.py+++ b/dify-agent/tests/local/dify_agent/server/test_runs_routes.py@@ -57,8 +57,8 @@ def test_create_run_accepts_effectively_blank_user_prompt_list() -> None:"/runs",json={"composition": {- "schema_version": 1,- "layers": [{"name": "prompt", "type": "plain.prompt", "config": {"user": ["", " "]}}],+ "schema_version": 2,+ "layers": [{"name": "prompt", "config": {"user": ["", " "]}}],}},)@@ -85,8 +85,8 @@ def test_create_run_returns_running_from_scheduler() -> None:"/runs",json={"composition": {- "schema_version": 1,- "layers": [{"name": "prompt", "type": "plain.prompt", "config": {"user": "hello"}}],+ "schema_version": 2,+ "layers": [{"name": "prompt", "config": {"user": "hello"}}],}},)@@ -168,12 +168,11 @@ def test_create_run_accepts_valid_full_plugin_graph() -> None:"/runs",json={"composition": {- "schema_version": 1,+ "schema_version": 2,"layers": [- {"name": "prompt", "type": "plain.prompt", "config": {"user": "hello"}},+ {"name": "prompt", "config": {"user": "hello"}},{"name": "execution-context-renamed",- "type": "dify.execution_context","config": {"tenant_id": "tenant-1","user_from": "account",@@ -183,8 +182,6 @@ def test_create_run_accepts_valid_full_plugin_graph() -> None:},{"name": DIFY_AGENT_MODEL_LAYER_ID,- "type": "dify.plugin.llm",- "deps": {"execution_context": "execution-context-renamed"},"config": {"plugin_id": "langgenius/openai","model_provider": "openai",@@ -202,7 +199,7 @@ def test_create_run_accepts_valid_full_plugin_graph() -> None:assert response.json() == {"run_id": "run-1", "status": "running"}-def test_create_run_accepts_unknown_layer_exit_signal_request() -> None:+def test_create_run_rejects_removed_layer_exit_signal_request() -> None:from fastapi import FastAPIapp = FastAPI()@@ -215,15 +212,14 @@ def test_create_run_accepts_unknown_layer_exit_signal_request() -> None:"/runs",json={"composition": {- "schema_version": 1,- "layers": [{"name": "prompt", "type": "plain.prompt", "config": {"user": "hello"}}],+ "schema_version": 2,+ "layers": [{"name": "prompt", "config": {"user": "hello"}}],},"on_exit": {"layers": {"missing": "delete"}},},)- assert response.status_code == 202- assert response.json() == {"run_id": "run-1", "status": "running"}+ assert response.status_code == 422def test_create_run_accepts_closed_session_snapshot_request() -> None:@@ -239,8 +235,8 @@ def test_create_run_accepts_closed_session_snapshot_request() -> None:"/runs",json={"composition": {- "schema_version": 1,- "layers": [{"name": "prompt", "type": "plain.prompt", "config": {"user": "hello"}}],+ "schema_version": 2,+ "layers": [{"name": "prompt", "config": {"user": "hello"}}],},"session_snapshot": {"schema_version": 1,@@ -277,8 +273,8 @@ def test_create_run_returns_503_when_scheduler_is_stopping() -> None:"/runs",json={"composition": {- "schema_version": 1,- "layers": [{"name": "prompt", "type": "plain.prompt", "config": {"user": "hello"}}],+ "schema_version": 2,+ "layers": [{"name": "prompt", "config": {"user": "hello"}}],}},)@@ -305,8 +301,8 @@ def test_create_run_does_not_map_infrastructure_failure_to_422() -> None:"/runs",json={"composition": {- "schema_version": 1,- "layers": [{"name": "prompt", "type": "plain.prompt", "config": {"user": "hello"}}],+ "schema_version": 2,+ "layers": [{"name": "prompt", "config": {"user": "hello"}}],}},)diff --git a/dify-agent/tests/local/dify_agent/storage/test_redis_run_store.py b/dify-agent/tests/local/dify_agent/storage/test_redis_run_store.pyindex 68641aa7a10..33e5da1192f 100644--- a/dify-agent/tests/local/dify_agent/storage/test_redis_run_store.py+++ b/dify-agent/tests/local/dify_agent/storage/test_redis_run_store.py@@ -6,8 +6,7 @@ from typing import castimport pytestfrom pydantic import JsonValue-from agenton.compositor import CompositorSessionSnapshot, LayerSessionSnapshot-from agenton.layers import LifecycleState+from dify_agent.protocol.snapshot import SessionSnapshotfrom dify_agent.protocol.schemas import (AgentRunUsage,RUN_EVENT_ADAPTER,@@ -189,7 +188,7 @@ def _terminal_event(run_id=run_id,data=RunSucceededEventData(output="done",- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),),)if event_type == "run_failed":@@ -277,7 +276,7 @@ def test_finalize_cancellation_maps_eval_result_and_arguments() -> None:store.finalize_cancellation("run-1",intent,- session_snapshot=CompositorSessionSnapshot(layers=[]),+ session_snapshot=SessionSnapshot(layers={}),usage=AgentRunUsage(prompt_tokens=13, completion_tokens=8),))@@ -295,7 +294,7 @@ def test_finalize_cancellation_maps_eval_result_and_arguments() -> None:assert payload["type"] == "run_cancelled"assert payload["data"]["reason"] == "workflow_aborted"assert payload["data"]["message"] == "workflow stopped"- assert payload["data"]["session_snapshot"] == {"schema_version": 1, "layers": []}+ assert payload["data"]["session_snapshot"] == {"schema_version": 2, "layers": {}}assert payload["data"]["usage"]["prompt_tokens"] == 13assert payload["data"]["usage"]["completion_tokens"] == 8assert payload["data"]["usage"]["total_tokens"] == 21@@ -444,15 +443,7 @@ def test_get_events_round_trips_run_succeeded_output_and_session_snapshot() -> Nredis = FakeRedis()store = RedisRunStore(redis, prefix="test", run_retention_seconds=60) # pyright: ignore[reportArgumentType]output = cast(JsonValue, {"answer": ["done", 1], "ok": True})- session_snapshot = CompositorSessionSnapshot(- layers=[- LayerSessionSnapshot(- name="prompt",- lifecycle_state=LifecycleState.SUSPENDED,- runtime_state={"resource_id": "abc"},- )- ]- )+ session_snapshot = SessionSnapshot(layers={"prompt": {"resource_id": "abc"}})async def scenario() -> tuple[str, RunSucceededEvent]:record = await store.create_run()diff --git a/dify-agent/tests/local/dify_agent/test_client_safe_exports.py b/dify-agent/tests/local/dify_agent/test_client_safe_exports.pyindex ec4ca696882..4cff38d7f13 100644--- a/dify-agent/tests/local/dify_agent/test_client_safe_exports.py+++ b/dify-agent/tests/local/dify_agent/test_client_safe_exports.py@@ -56,11 +56,6 @@ def test_client_public_exports_work_with_default_dependencies_only(tmp_path: Pat}server_only_dependency_names = server_dependency_names - default_dependency_names- agenton_layers = importlib.import_module("agenton.layers")- agenton_compositor = importlib.import_module("agenton.compositor")- agenton_collections = importlib.import_module("agenton_collections")- plain_layers = importlib.import_module("agenton_collections.layers.plain")- pydantic_ai_layers = importlib.import_module("agenton_collections.layers.pydantic_ai")dify_agent = importlib.import_module("dify_agent")client_module = importlib.import_module("dify_agent.client")protocol_module = importlib.import_module("dify_agent.protocol")@@ -70,16 +65,9 @@ def test_client_public_exports_work_with_default_dependencies_only(tmp_path: Patshell_module = importlib.import_module("dify_agent.layers.shell")execution_context_module = importlib.import_module("dify_agent.layers.execution_context")plugin_module = importlib.import_module("dify_agent.layers.dify_plugin")- ask_human_module = importlib.import_module("dify_agent.layers.ask_human")output_module = importlib.import_module("dify_agent.layers.output")user_prompt_module = importlib.import_module("dify_agent.layers.user_prompt")- assert agenton_layers.ExitIntent is not None- assert agenton_layers.LayerConfig is not None- assert agenton_compositor.CompositorSessionSnapshot is not None- assert agenton_collections.PromptLayer is plain_layers.PromptLayer- assert plain_layers.PromptLayerConfig is not None- assert pydantic_ai_layers.PydanticAIHistoryLayer is not Noneassert dify_agent.Client is client_module.Clientassert protocol_module.CreateRunRequest is not Noneassert protocol_module.RunComposition is not None@@ -92,7 +80,6 @@ def test_client_public_exports_work_with_default_dependencies_only(tmp_path: Patassert shell_module.DifyShellLayerConfig is not Noneassert execution_context_module.DifyExecutionContextLayerConfig is not Noneassert plugin_module.DifyPluginLLMLayerConfig is not None- assert ask_human_module.DifyAskHumanLayerConfig is not Noneassert output_module.DifyOutputLayerConfig is not Noneassert user_prompt_module.DifyUserPromptLayerConfig is not Noneassert user_prompt_module.DifyUserPromptFileConfig is not Nonediff --git a/dify-agent/tests/local/dify_agent/test_import_boundaries.py b/dify-agent/tests/local/dify_agent/test_import_boundaries.pyindex f23233aa3a2..42438e2adda 100644--- a/dify-agent/tests/local/dify_agent/test_import_boundaries.py+++ b/dify-agent/tests/local/dify_agent/test_import_boundaries.py@@ -105,7 +105,6 @@ def test_protocol_and_dify_plugin_exports_do_not_import_server_only_modules() ->"anthropic","dify_agent.adapters.llm","dify_agent.layers.execution_context.layer",- "dify_agent.layers.ask_human.layer","dify_agent.layers.dify_plugin.llm_layer","dify_agent.layers.dify_plugin.tools_layer","dify_agent.layers.knowledge.client",@@ -125,7 +124,6 @@ def test_protocol_and_dify_plugin_exports_do_not_import_server_only_modules() ->imports=["dify_agent.protocol","dify_agent.layers.execution_context",- "dify_agent.layers.ask_human","dify_agent.layers.dify_plugin","dify_agent.layers.knowledge","dify_agent.layers.output",@@ -134,7 +132,6 @@ def test_protocol_and_dify_plugin_exports_do_not_import_server_only_modules() ->assertions=["assert hasattr(dify_agent_protocol, 'CreateRunRequest')","assert hasattr(dify_agent_layers_execution_context, 'DifyExecutionContextLayerConfig')",- "assert hasattr(dify_agent_layers_ask_human, 'DifyAskHumanLayerConfig')","assert hasattr(dify_agent_layers_dify_plugin, 'DifyPluginLLMLayerConfig')","assert hasattr(dify_agent_layers_knowledge, 'DifyKnowledgeBaseLayerConfig')","assert hasattr(dify_agent_layers_output, 'DifyOutputLayerConfig')",@@ -158,14 +155,12 @@ def test_agent_cli_help_import_is_client_safe() -> None:"dify_agent.layers._agent_cli_help","dify_agent.agent_stub.shell_env","dify_agent.layers.shell.layer",- "dify_agent.runtime.compositor_factory",],assertions=["assert hasattr(dify_agent_agent_stub_protocol, 'AgentStubConnectRequest')","assert hasattr(dify_agent_layers__agent_cli_help, 'render_agent_stub_cli_help')","assert hasattr(dify_agent_agent_stub_shell_env, 'build_shell_agent_stub_env')",- "assert hasattr(dify_agent_layers_shell_layer, 'DifyShellLayer')",- "assert hasattr(dify_agent_runtime_compositor_factory, 'create_default_layer_providers')",+ "assert hasattr(dify_agent_layers_shell_layer, 'Capability')",],bootstrap=["import types",@@ -279,17 +274,3 @@ def test_server_settings_import_does_not_import_agent_stub_app() -> None:imports=["dify_agent.server.settings"],assertions=["assert hasattr(dify_agent_server_settings, 'ServerSettings')"],)---def test_agenton_collection_roots_do_not_eagerly_import_pydantic_ai_implementations() -> None:- _run_import_check(- blocked_imports=[- "agenton_collections.layers.pydantic_ai",- "agenton_collections.transformers.pydantic_ai",- ],- imports=["agenton_collections", "agenton_collections.transformers"],- assertions=[- "assert 'PydanticAIBridgeLayer' not in agenton_collections.__all__",- "assert agenton_collections_transformers.__all__ == []",- ],- )diff --git a/dify-agent/tests/local/examples/test_agenton_examples.py b/dify-agent/tests/local/examples/test_agenton_examples.pydeleted file mode 100644index 2b0b63a573e..00000000000--- a/dify-agent/tests/local/examples/test_agenton_examples.py+++ /dev/null@@ -1,59 +0,0 @@-import os-import subprocess-import sys-from pathlib import Path---PROJECT_ROOT = Path(__file__).resolve().parents[3]---def _run_example(path: str) -> subprocess.CompletedProcess[str]:- env = os.environ.copy()- _ = env.pop("OPENAI_API_KEY", None)- python_path = os.pathsep.join(- [- str(PROJECT_ROOT / "src"),- str(PROJECT_ROOT / "examples" / "agenton"),- str(PROJECT_ROOT / "examples" / "dify_agent"),- env.get("PYTHONPATH", ""),- ]- )- env["PYTHONPATH"] = python_path-- return subprocess.run(- [sys.executable, "-m", path],- cwd=PROJECT_ROOT,- env=env,- text=True,- capture_output=True,- check=False,- )---def test_agenton_basics_example_smoke() -> None:- result = _run_example("agenton_examples.basics")-- assert result.returncode == 0, result.stderr- assert "Prompts:" in result.stdout- assert "User prompts:" in result.stdout- assert "Tools:" in result.stdout- assert "Lifecycle: ['create', 'suspend', 'resume', 'delete']" in result.stdout---def test_agenton_pydantic_ai_example_smoke() -> None:- result = _run_example("agenton_examples.pydantic_ai_bridge")-- assert result.returncode == 0, result.stderr- assert "SystemPromptPart(content='Prefer concrete details.'," in result.stdout- assert "UserPromptPart(content=[\"Use the tools for 'layer composition'.\"]," in result.stdout- assert "ToolCallPart(tool_name='count_words'" in result.stdout- assert "ToolCallPart(tool_name='write_tagline'" in result.stdout- assert "TextPart(content=" in result.stdout---def test_agenton_session_snapshot_example_smoke() -> None:- result = _run_example("agenton_examples.session_snapshot")-- assert result.returncode == 0, result.stderr- assert "Snapshot:" in result.stdout- assert "Rehydrated external handle: restored:demo-connection" in result.stdoutdiff --git a/dify-agent/tests/local/test_packaging.py b/dify-agent/tests/local/test_packaging.pyindex ee54057fcc6..ab2d0f96cac 100644--- a/dify-agent/tests/local/test_packaging.py+++ b/dify-agent/tests/local/test_packaging.py@@ -11,7 +11,7 @@ CLIENT_SHARED_DTO_DEPENDENCIES = {"httpx2>=2.5.0,<3.0.0","pydantic>=2.12.5,<2.13","pydantic-ai-harness>=0.20.0,<0.21.0",- "pydantic-ai-slim>=2.30.0,<3.0.0",+ "pydantic-ai-slim==2.31.0","typing-extensions>=4.12.2,<5.0.0",}@@ -24,7 +24,7 @@ SERVER_RUNTIME_DEPENDENCIES = {"jwcrypto>=1.5.6,<2","logfire[fastapi,httpx,redis]>=4.37.0,<5.0.0","openshell>=0.0.106,<0.1.0",- "pydantic-ai-slim[anthropic,google,openai]>=2.30.0,<3.0.0",+ "pydantic-ai-slim[anthropic,google,openai]==2.31.0","pydantic-settings>=2.12.0,<3.0.0","redis>=7.4.0,<8.0.0","uvicorn[standard]==0.46.0",diff --git a/dify-agent/uv.lock b/dify-agent/uv.lockindex d5b4d754623..060ab961211 100644--- a/dify-agent/uv.lock+++ b/dify-agent/uv.lock@@ -1,5 +1,5 @@version = 1-revision = 3+revision = 5requires-python = ">=3.13, <4.0"resolution-markers = ["python_full_version >= '3.14' and sys_platform == 'win32'",@@ -590,8 +590,8 @@ requires-dist = [{ name = "openshell", marker = "extra == 'server'", specifier = ">=0.0.106,<0.1.0" },{ name = "pydantic", specifier = ">=2.12.5,<2.13" },{ name = "pydantic-ai-harness", specifier = ">=0.20.0,<0.21.0" },- { name = "pydantic-ai-slim", specifier = ">=2.30.0,<3.0.0" },- { name = "pydantic-ai-slim", extras = ["anthropic", "google", "openai"], marker = "extra == 'server'", specifier = ">=2.30.0,<3.0.0" },+ { name = "pydantic-ai-slim", specifier = "==2.31.0" },+ { name = "pydantic-ai-slim", extras = ["anthropic", "google", "openai"], marker = "extra == 'server'", specifier = "==2.31.0" },{ name = "pydantic-settings", marker = "extra == 'server'", specifier = ">=2.12.0,<3.0.0" },{ name = "redis", marker = "extra == 'server'", specifier = ">=7.4.0,<8.0.0" },{ name = "typing-extensions", specifier = ">=4.12.2,<5.0.0" },