Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs: server_controlled_fields holds on every tool path
trohitg5f1bc5cac7e0
diff --git a/docs-internal/discord_service.md b/docs-internal/discord_service.mdindex 405e481a..fd5a50d4 100644--- a/docs-internal/discord_service.md+++ b/docs-internal/discord_service.md@@ -65,16 +65,18 @@ exists to keep them apart.## Security invariants-**`account_id` is stripped from model arguments.** `server_controlled_fields`-is enforced only in `BaseNode.execute_as_tool`'s ToolNode branch; a dual-purpose-ActionNode takes an earlier return that merges `{**node_params, **tool_args}`-with model arguments winning (the non-`ToolNode` branch of-[`BaseNode.execute_as_tool`](../server/services/plugin/base.py)).-Since inbound Discord messages are the realistic source of hostile tool-arguments and `account_id` selects which bot identity sends, `AccountScopedNode`-in [`_base.py`](../server/nodes/discord/_base.py) removes locked fields before-the merge. A test drives the real tool path rather than asserting the-declaration.+**`account_id` is stripped from model arguments.** Inbound Discord messages are+the realistic source of hostile tool arguments and `account_id` selects which+bot identity sends, so both nodes list it in `server_controlled_fields`. The+framework enforces that on every tool path: in process,+[`BaseNode.execute_as_tool`](../server/services/plugin/base.py) drops locked+fields from the model's arguments before its `{**node_params, **tool_args}`+merge; on Temporal, where the agent workflow has already merged the arguments,+[`NodeExecutor`](../server/services/node_executor.py) puts back the saved value+(or the default). `AccountScopedNode` in+[`_base.py`](../server/nodes/discord/_base.py) strips locked fields again as+defence in depth; it runs only in process, since the per-type activity calls+`execute` for an ActionNode. Tests drive both paths with a hostile `account_id`.**The interaction token never leaves the server.** It is a 15-minute bearercredential that can post as the app, and trigger output is persisted three ways,diff --git a/docs-internal/node-logic-flows/discord/discordSend.md b/docs-internal/node-logic-flows/discord/discordSend.mdindex 6c226df2..7985ddcf 100644--- a/docs-internal/node-logic-flows/discord/discordSend.md+++ b/docs-internal/node-logic-flows/discord/discordSend.md@@ -105,8 +105,9 @@ flowchart TD- One attachment per message. Discord allows 10; multiple would need a listparam and multi-file panel support.-- `account_id` is removed from tool arguments by `AccountScopedNode` —- `server_controlled_fields` alone does nothing on a dual-purpose ActionNode.+- `account_id` is in `server_controlled_fields`, which the framework enforces on+ every tool path (`BaseNode.execute_as_tool` in process, `NodeExecutor` on+ Temporal); `AccountScopedNode` strips it again as defence in depth.- A 429 over ~30s raises a retryable `RuntimeError` so Temporal re-dispatchesrather than pinning a worker slot.diff --git a/docs-internal/node-logic-flows/whatsapp_business/whatsappBusinessSend.md b/docs-internal/node-logic-flows/whatsapp_business/whatsappBusinessSend.mdindex dbeea744..bdc096fb 100644--- a/docs-internal/node-logic-flows/whatsapp_business/whatsappBusinessSend.md+++ b/docs-internal/node-logic-flows/whatsapp_business/whatsappBusinessSend.md@@ -137,11 +137,11 @@ flowchart TD## Edge cases & known limits- **`phone_number_id` is intentionally absent from `Params`.** It selects which- business identity a message is sent *from*. On a dual-purpose `ActionNode`- there is no way to protect a declared field: `BaseNode.execute_as_tool` sends- `{**node_params, **tool_args}`, so model arguments win, and- `ctx.raw["_raw_parameters"]` is that same merged dict. Sourcing it from the- credential is the only place the model cannot reach. Locked by+ business identity a message is sent *from*. `server_controlled_fields` would+ keep a model-set value out on every tool path, but a dual-purpose+ `ActionNode`'s tool schema is its whole `Params`, so a declared field would+ still be offered to the model. Sourcing it from the credential keeps it out of+ the schema and out of every parameter merge. Locked by`TestModelCannotChooseTheSendingNumber`, which drives the real tool path witha hostile value.- The upload posts **bytes, not a file handle** — `Connection.request` replaysdiff --git a/docs-internal/whatsapp_business_service.md b/docs-internal/whatsapp_business_service.mdindex 235347ae..aaaefa3e 100644--- a/docs-internal/whatsapp_business_service.md+++ b/docs-internal/whatsapp_business_service.md@@ -63,14 +63,15 @@ validates the WABA id at the same time, returning discovered numbers with theirThere is deliberately **no `phone_number_id` parameter** on any node. It selectswhich business identity a message is sent *from*, which is exactly what a prompt-injection in an inbound message would want to set. On a dual-purpose-`ActionNode` a declared field cannot be protected: the split-schema machinery-(`ToolInput` / `server_controlled_fields`) is a `ToolNode` extension, and-`BaseNode.execute_as_tool` sends `{**node_params, **tool_args}` for everything-else — model arguments win, and `ctx.raw["_raw_parameters"]` is that same merged-dict. Sourcing it from the credential puts it somewhere model arguments cannot-reach. Locked by `TestModelCannotChooseTheSendingNumber`, which drives the real-tool path with a hostile `phone_number_id`.+injection in an inbound message would want to set. Listing a declared field in+`server_controlled_fields` would keep the model's value out on every tool path+(`BaseNode.execute_as_tool` in process, `NodeExecutor` on Temporal), but the+model would still be offered the field: `ToolInput` is a `ToolNode` extension,+so the tool schema of a dual-purpose `ActionNode` is its whole `Params`.+Sourcing the number from the credential keeps it out of the schema, and out of+every parameter merge as defence in depth. Locked by `TestParamsShape` and+`TestModelCannotChooseTheSendingNumber`, which drives the real tool path with a+hostile `phone_number_id`.## Webhookdiff --git a/server/nodes/discord/discord_send.py b/server/nodes/discord/discord_send.pyindex 8d7a073c..fa0d919f 100644--- a/server/nodes/discord/discord_send.py+++ b/server/nodes/discord/discord_send.py@@ -138,8 +138,8 @@ class DiscordSendNode(AccountScopedNode):annotations = {"destructive": False, "readonly": False, "open_world": True}task_queue = TaskQueue.MESSAGINGusable_as_tool = True- # Which bot sends is operator configuration, not a model decision.- # AccountScopedNode is what enforces this on the tool path.+ # Which bot sends is operator configuration, not a model decision: every+ # tool path keeps it from the model (AccountScopedNode strips it again).server_controlled_fields = frozenset({"account_id"})approval = ApprovalSpec(channel="Discord",diff --git a/server/nodes/whatsapp_business/_base.py b/server/nodes/whatsapp_business/_base.pyindex 3fab6cb6..18f7bac0 100644--- a/server/nodes/whatsapp_business/_base.py+++ b/server/nodes/whatsapp_business/_base.py@@ -211,11 +211,10 @@ async def resolve_phone_number_id(ctx: NodeContext) -> str:"""The business number to send from — credential-sourced only.Deliberately takes no node-level override. This value selects which- business identity a message is sent *from*, and on a dual-purpose- ActionNode any declared parameter is reachable by model arguments:- ``BaseNode.execute_as_tool`` sends ``{**node_params, **tool_args}`` for- anything that is not a ToolNode, so the model wins. Sourcing it from the- credential puts it somewhere model arguments cannot reach.+ business identity a message is sent *from*. A declared parameter would+ appear in the model's tool schema (a dual-purpose ActionNode's schema is+ its whole Params), even locked with ``server_controlled_fields``; sourcing+ it from the credential keeps it out of the schema and every merge.A per-node override belongs with multi-number support, which needs thedeployed-trigger filtering that is currently deferred.diff --git a/server/nodes/whatsapp_business/whatsapp_business_send.py b/server/nodes/whatsapp_business/whatsapp_business_send.pyindex a19da99d..6e77f5bc 100644--- a/server/nodes/whatsapp_business/whatsapp_business_send.py+++ b/server/nodes/whatsapp_business/whatsapp_business_send.py@@ -311,16 +311,16 @@ class WhatsAppBusinessSendParams(BaseModel):## It selects which business identity a message is sent *from*, so it is# exactly the field a prompt injection in an inbound message would want to- # set. On a dual-purpose ActionNode there is no way to protect it: the- # split-schema machinery (ToolInput / server_controlled_fields) is a- # ToolNode extension, and BaseNode.execute_as_tool sends- # ``{**node_params, **tool_args}`` for everything else -- model arguments- # win, and ctx.raw["_raw_parameters"] is that same merged dict, so reading- # from it protects nothing.+ # set. Listed in server_controlled_fields, a declared field would be kept+ # from the model on every tool path (BaseNode.execute_as_tool strips it in+ # process; NodeExecutor restores the saved value on Temporal), but it would+ # still appear in the tool schema: ToolInput is a ToolNode extension, so+ # this ActionNode's schema is its whole Params, and the model would be+ # offered a field it cannot set.#- # The sending number therefore comes only from the credential, where the- # model cannot reach it. A per-node override belongs with multi-number- # support, which is deferred.+ # The sending number therefore comes only from the credential, which keeps+ # it out of the schema and out of every parameter merge. A per-node+ # override belongs with multi-number support, which is deferred.model_config = ConfigDict(extra="ignore")@@ -427,10 +427,10 @@ class WhatsAppBusinessSendNode(ActionNode):)# ToolInput / server_controlled_fields are deliberately NOT declared.- # They are ToolNode extensions; on a dual-purpose ActionNode they are- # silently inert (BaseNode.execute_as_tool short-circuits before reading- # them), so declaring them would advertise a protection that does not- # exist. Fields the model must not control are kept out of Params instead.+ # ToolInput is a ToolNode extension; nothing reads it on an ActionNode.+ # server_controlled_fields would work here (every tool path honours it),+ # but no field in Params needs it: the one field the model must not+ # control, the sending number, is kept out of Params (see above).Params = WhatsAppBusinessSendParamsOutput = WhatsAppBusinessSendOutputdiff --git a/server/tests/nodes/test_discord.py b/server/tests/nodes/test_discord.pyindex 248af025..4ab3e30c 100644--- a/server/tests/nodes/test_discord.py+++ b/server/tests/nodes/test_discord.py@@ -1,9 +1,8 @@"""Contract for the Discord plugin.-The security-relevant test is ``TestModelCannotChooseTheAccount``. On a-dual-purpose ActionNode ``BaseNode.execute_as_tool`` merges-``{**node_params, **tool_args}`` with model arguments winning, so the only-thing standing between a prompt injection in an inbound Discord message and+The security-relevant test is ``TestModelCannotChooseTheAccount``. A+dual-purpose ActionNode's tool call merges ``{**node_params, **tool_args}``,+so what stands between a prompt injection in an inbound Discord message andsending as a different bot is ``server_controlled_fields``. This asserts itactually holds through the real tool path, not just the schema."""@@ -382,9 +381,9 @@ class TestToolSchema:@pytest.mark.parametrize("node_cls", [DiscordSendNode, DiscordActionNode])def test_locked_fields_are_stripped_from_model_arguments(self, node_cls):- """The guarantee AccountScopedNode exists to provide, at the class- level: every locked field must be removed from tool_args before the- merge that would otherwise let the model win."""+ """AccountScopedNode strips every locked field from tool_args before+ the merge, again, behind the framework's own strip (defence in+ depth)."""assert node_cls.server_controlled_fieldsassert node_cls.execute_as_tool is not _base.ActionNode.execute_as_tooldiff --git a/server/tests/nodes/test_whatsapp_business.py b/server/tests/nodes/test_whatsapp_business.pyindex d25cef57..3b3f25c3 100644--- a/server/tests/nodes/test_whatsapp_business.py+++ b/server/tests/nodes/test_whatsapp_business.py@@ -1,10 +1,9 @@"""Contract for the official Meta WhatsApp Cloud API plugin.The security-relevant test here is ``TestModelCannotChooseTheSendingNumber``.-On a dual-purpose ActionNode the split-schema machinery does not apply ---``BaseNode.execute_as_tool`` merges ``{**node_params, **tool_args}`` for-anything that is not a ToolNode -- so the only way to keep a field away from-the model is to keep it out of Params entirely. This asserts that holds.+A dual-purpose ActionNode's tool schema is its whole Params, so the way to keep+a field away from the model entirely, schema included, is to keep it out of+Params. This asserts that holds."""from __future__ import annotations@@ -513,8 +512,9 @@ class TestParamsShape:def test_phone_number_id_is_not_a_parameter(self):"""It selects the business identity a message is sent FROM.- Declaring it would make it model-settable on this node kind, so it is- credential-sourced instead. If someone adds it back, this fails.+ Declaring it would put it in the model's tool schema on this node+ kind, so it is credential-sourced instead. If someone adds it back,+ this fails."""assert "phone_number_id" not in WhatsAppBusinessSendParams.model_fields