Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
feat(approvals): hold sending tool calls for the owner, live Ask first
trohitg7c38f6c5b9ee
diff --git a/server/core/database.py b/server/core/database.pyindex 173192db..7a26e363 100644--- a/server/core/database.py+++ b/server/core/database.py@@ -56,7 +56,9 @@ from models.employees import ( # noqa: F401 - registers SQLModel tablesWorkflowRunRecord,)from models.approvals import ( # noqa: F401 - registers SQLModel tables+ ApprovalDecision,ApprovalRequest,+ WorkflowRule,)from models.chat import ( # noqa: F401 - registers SQLModel tablesChatNote,@@ -140,6 +142,7 @@ class Database:await self._migrate_generation_scoped_runtime_data()await self._migrate_chat_messages()await self._migrate_chat_runs()+ await self._migrate_approvals()logger.info("Database initialized successfully")@@ -546,6 +549,55 @@ class Database:except Exception as exc:logger.warning(f"Chat run migration check failed: {exc}")+ async def _migrate_approvals(self):+ """Give an older ``approval_requests`` table the columns approvals v2+ added (held tool calls, Undo and Restore, outcomes). A draft approved+ before them was handed on when it was decided, so it gets that as+ ``consumed_at`` and never reads as still undoable."""+ columns_added = {+ "kind": "VARCHAR(20) NOT NULL DEFAULT 'gate'",+ "action": "VARCHAR(200)",+ "details": "JSON",+ "node_type": "VARCHAR(100)",+ "tool_node_id": "VARCHAR(255)",+ "tool_call_id": "VARCHAR(255)",+ "agent_node_id": "VARCHAR(255)",+ "run_id": "VARCHAR(64)",+ "ui_part_id": "VARCHAR(64)",+ "node_data": "JSON",+ "args": "JSON",+ "original_args": "JSON",+ "body_field": "VARCHAR(100)",+ "subject_field": "VARCHAR(100)",+ "approved_by": "VARCHAR(20)",+ "grace_until": "DATETIME",+ "restore_until": "DATETIME",+ "consumed_at": "DATETIME",+ "claim_token": "VARCHAR(64)",+ "outcome": "VARCHAR(20)",+ "outcome_error": "VARCHAR(1000)",+ "outcome_at": "DATETIME",+ }+ try:+ async with self.engine.begin() as conn:+ result = await conn.execute(text("PRAGMA table_info(approval_requests)"))+ columns = {row[1] for row in result.fetchall()}+ if not columns:+ return+ for column, definition in columns_added.items():+ if column not in columns:+ await conn.execute(text(f"ALTER TABLE approval_requests ADD COLUMN {column} {definition}"))+ if "consumed_at" not in columns:+ await conn.execute(text(+ "UPDATE approval_requests SET consumed_at = COALESCE(decided_at, updated_at) WHERE status = 'approved'"+ ))+ if "run_id" not in columns:+ await conn.execute(text(+ "CREATE INDEX IF NOT EXISTS ix_approval_requests_run_id ON approval_requests(run_id)"+ ))+ except Exception as exc:+ logger.warning(f"Approval migration check failed: {exc}")+async def _migrate_chat_messages(self):"""Give older chat rows the columns chat runs need.diff --git a/server/main.py b/server/main.pyindex bd4492e0..b62760a0 100644--- a/server/main.py+++ b/server/main.py@@ -171,6 +171,11 @@ async def lifespan(app: FastAPI):# disconnect listener that drops a closed socket's run subscriptions.import services.chat # noqa: F401+ # services/approvals/__init__.py self-registers the approval commands+ # (list_approvals / decide_approval / set_ask_first / ...), the+ # approval_lifecycle broadcast and the cleanup on workflow delete.+ import services.approvals # noqa: F401+# Wave 13.8: services/pricing_handlers.py self-registers the 3# pricing handlers (get_pricing_config / save_pricing_config /# get_api_usage_summary). Flat module (sibling to services/pricing.py)diff --git a/server/models/approvals.py b/server/models/approvals.pyindex c5756131..c84cd5cc 100644--- a/server/models/approvals.py+++ b/server/models/approvals.py@@ -1,20 +1,45 @@-"""Drafts waiting for the owner: one row per approval-gate wait.+"""What waits for the owner's OK, and what the owner decided.-A gate creates its row the first time it runs and finds the same row on-every retry (``idempotency_key`` is unique: ``t:<temporal workflow>:<run>:-<activity>`` on Temporal, ``p:<execution>:<node>`` in-process). The row is-the whole state of the wait; the node only watches it.+``ApprovalRequest`` is one thing to send, of one of two kinds (``kind``):-``status``: pending -> approved | discarded | expired | cancelled, each-move a compare-and-swap on ``revision``.+- ``gate``: an approvalGate node holds its run until the owner decides. It+ creates its row the first time it runs and finds the same row on every+ retry (``idempotency_key``: ``t:<temporal workflow>:<run>:<activity>`` on+ Temporal, ``p:<execution>:<node>:<inputs>`` in-process). The gate lets the+ draft (or the owner's edit) through to the reply node after it.+- ``tool_call``: a call the employee made to a tool that sends (a plugin's+ ``approval`` spec, services/plugin/approval.py) while Ask first was on. The+ call was answered "waiting for the owner" and the run went on; Send runs it+ later (``ApprovedToolCallWorkflow``), once. Its key is+ ``c:<workflow>:<execution>:<tool call id>``. With Ask first off the call+ runs at once, and a Talk call still leaves a row (``approved_by: auto``) so+ the owner sees what went out.++``status``::++ pending -> approved -> (gate) let through: approved, consumed_at set+ -> (tool call) sending -> sent | failed+ approved -> pending Undo, before grace_until+ pending -> discarded Discard+ discarded -> pending Restore, before restore_until+ failed -> approved Retry (asks to confirm when the outcome is unknown)+ pending | approved | discarded -> expired | cancelled++Every move is a compare-and-swap on ``revision``. ``ApprovalDecision`` keeps+the owner's decisions; the same ``decision_key`` again is a no-op.++``WorkflowRule`` is a workflow's Ask first rule, read when something would+send: one row per workflow, seeded from an employee's ground rules, changed+from the chat's Ask first chip (``set_ask_first``). A workflow without a row+(the editor's own workflows) gates no tool calls."""from __future__ import annotationsfrom datetime import datetime, timezone-from typing import Optional+from typing import Any, Dict, List, Optional-from sqlalchemy import Column, DateTime+from sqlalchemy import JSON, Column, DateTime, UniqueConstraintfrom sqlmodel import Field, SQLModel@@ -35,9 +60,13 @@ class ApprovalRequest(SQLModel, table=True):#: ``temporal`` or ``local``: a local wait cannot outlive its process.runtime: str = Field(default="local", max_length=20)status: str = Field(default="pending", index=True, max_length=20)+ #: ``gate`` or ``tool_call`` (see the module docstring).+ kind: str = Field(default="gate", max_length=20)- #: The app the reply goes out through ("WhatsApp").+ #: The app it goes out through ("WhatsApp").channel: str = Field(default="", max_length=60)+ #: What the card says it does ("Send a WhatsApp message").+ action: Optional[str] = Field(default=None, max_length=200)recipient: str = Field(default="", max_length=500)recipient_label: str = Field(default="", max_length=200)subject: Optional[str] = Field(default=None, max_length=500)@@ -50,14 +79,81 @@ class ApprovalRequest(SQLModel, table=True):context_excerpt: Optional[str] = Field(default=None, max_length=2000)#: The channel's limit for an edited draft.max_length: int = Field(default=20000)- #: The decide request that settled it: the same key again is a no-op.+ #: The card's other lines: [{label, value}].+ details: List[Dict[str, Any]] = Field(default_factory=list, sa_column=Column(JSON, nullable=True))+ #: The decide request that settled it last (kept for older readers;+ #: ``approval_decisions`` holds them all).decision_key: Optional[str] = Field(default=None, max_length=128)revision: int = Field(default=0)+ # ---- a held tool call ----+ node_type: Optional[str] = Field(default=None, max_length=100)+ tool_node_id: Optional[str] = Field(default=None, max_length=255)+ tool_call_id: Optional[str] = Field(default=None, max_length=255)+ agent_node_id: Optional[str] = Field(default=None, max_length=255)+ #: The chat run the call was made in, and the interface it came from.+ run_id: Optional[str] = Field(default=None, index=True, max_length=64)+ ui_part_id: Optional[str] = Field(default=None, max_length=64)+ #: What runs on Send: the node's parameters with the call's arguments+ #: over them, and the arguments alone. An edit lands in both.+ node_data: Dict[str, Any] = Field(default_factory=dict, sa_column=Column(JSON, nullable=True))+ args: Dict[str, Any] = Field(default_factory=dict, sa_column=Column(JSON, nullable=True))+ #: The arguments as the employee wrote them.+ original_args: Dict[str, Any] = Field(default_factory=dict, sa_column=Column(JSON, nullable=True))+ #: The arguments the owner may edit on the card.+ body_field: Optional[str] = Field(default=None, max_length=100)+ subject_field: Optional[str] = Field(default=None, max_length=100)++ # ---- the decision and what came of it ----+ #: ``owner``, or ``auto`` when Ask first was off.+ approved_by: Optional[str] = Field(default=None, max_length=20)+ #: Undo works until this; then it goes.+ grace_until: Optional[datetime] = Field(default=None, sa_column=Column(DateTime(timezone=True), nullable=True))+ #: A discarded draft can be restored until this.+ restore_until: Optional[datetime] = Field(default=None, sa_column=Column(DateTime(timezone=True), nullable=True))+ #: When it was handed on: the gate let it through, or a send claimed it.+ consumed_at: Optional[datetime] = Field(default=None, sa_column=Column(DateTime(timezone=True), nullable=True))+ claim_token: Optional[str] = Field(default=None, max_length=64)+ #: How the send went: ``sent``, ``not_sent`` or ``unknown`` (the call+ #: broke off mid-way; it may have gone out).+ outcome: Optional[str] = Field(default=None, max_length=20)+ outcome_error: Optional[str] = Field(default=None, max_length=1000)+ outcome_at: Optional[datetime] = Field(default=None, sa_column=Column(DateTime(timezone=True), nullable=True))+created_at: datetime = Field(default_factory=_utcnow, sa_column=Column(DateTime(timezone=True), nullable=False))updated_at: datetime = Field(default_factory=_utcnow, sa_column=Column(DateTime(timezone=True), nullable=False))decided_at: Optional[datetime] = Field(default=None, sa_column=Column(DateTime(timezone=True), nullable=True))expires_at: Optional[datetime] = Field(default=None, sa_column=Column(DateTime(timezone=True), nullable=True))-__all__ = ["ApprovalRequest"]+class ApprovalDecision(SQLModel, table=True):+ """One decision the owner made on a row: what, under which key, and the+ revision it left the row at."""++ __tablename__ = "approval_decisions"+ __table_args__ = (UniqueConstraint("approval_id", "decision_key", name="uq_approval_decisions_key"),)++ id: Optional[int] = Field(default=None, primary_key=True)+ approval_id: str = Field(index=True, max_length=64)+ #: send | undo | discard | restore | retry+ decision: str = Field(max_length=20)+ decision_key: str = Field(max_length=128)+ actor: str = Field(default="owner", max_length=255)+ revision: int = Field(default=0)+ created_at: datetime = Field(default_factory=_utcnow, sa_column=Column(DateTime(timezone=True), nullable=False))+++class WorkflowRule(SQLModel, table=True):+ """A workflow's Ask first rule (see the module docstring)."""++ __tablename__ = "workflow_rules"++ workflow_id: str = Field(primary_key=True, max_length=255)+ ask_first: bool = Field(default=True)+ revision: int = Field(default=0)+ #: ``hire`` (seeded from the employee's ground rules) or ``owner``.+ source: str = Field(default="owner", max_length=20)+ updated_at: datetime = Field(default_factory=_utcnow, sa_column=Column(DateTime(timezone=True), nullable=False))+++__all__ = ["ApprovalDecision", "ApprovalRequest", "WorkflowRule"]diff --git a/server/nodes/browser/browser/__init__.py b/server/nodes/browser/browser/__init__.pyindex 7e7ade44..ff83d531 100644--- a/server/nodes/browser/browser/__init__.py+++ b/server/nodes/browser/browser/__init__.py@@ -32,6 +32,7 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_serialfrom core.logging import get_loggerfrom services.plugin import NodeContext, Operation, TaskQueue, ToolNode+from services.plugin.approval import ApprovalSpecfrom services.plugin.base import NodeUserErrorfrom services.plugin.scaling import RetryPolicy@@ -352,6 +353,13 @@ class BrowserNode(ToolNode):ui_hints = {"isBrowserPanel": True, "isConfigNode": False}annotations = {"destructive": True, "readonly": False, "open_world": True}task_queue = TaskQueue.BROWSER+ # A page can do anything its logins allow; while the owner asks first+ # it only reads, and hands changes to them (request_user).+ approval = ApprovalSpec(+ channel="Web browser",+ action="Use the web browser",+ restrict_while_asking={"interaction": "read_only"},+ )retry_policy = RetryPolicy(maximum_attempts=3)# Long enough for request_user on a workflow node (up to 30 min); also# turns on the base 30 s heartbeat loop while a step runs.diff --git a/server/nodes/discord/discord_send.py b/server/nodes/discord/discord_send.pyindex 4cfba27f..8d7a073c 100644--- a/server/nodes/discord/discord_send.py+++ b/server/nodes/discord/discord_send.py@@ -14,6 +14,7 @@ from typing import Any, Dict, List, Literal, Optionalfrom pydantic import BaseModel, ConfigDict, Fieldfrom services.plugin import NodeContext, NodeUserError, Operation, TaskQueue+from services.plugin.approval import ApprovalSpecfrom . import _basefrom ._accounts import DEFAULT_ACCOUNT@@ -140,6 +141,13 @@ class DiscordSendNode(AccountScopedNode):# Which bot sends is operator configuration, not a model decision.# AccountScopedNode is what enforces this on the tool path.server_controlled_fields = frozenset({"account_id"})+ approval = ApprovalSpec(+ channel="Discord",+ action="Send a Discord message",+ recipient=("channel_id", "user_id"),+ body=("message",),+ max_length=2000,+ )# Canvas handles are auto-hidden for usable_as_tool nodes; this one is# meant to be wired into a workflow as well.hide_input_handle = Falsediff --git a/server/nodes/email/email_send/__init__.py b/server/nodes/email/email_send/__init__.pyindex eea05ed3..9913f86c 100644--- a/server/nodes/email/email_send/__init__.py+++ b/server/nodes/email/email_send/__init__.py@@ -7,6 +7,7 @@ from typing import Any, Literal, Optionalfrom pydantic import BaseModel, ConfigDict, Fieldfrom services.plugin import ActionNode, NodeContext, Operation, TaskQueue+from services.plugin.approval import ApprovalSpecclass EmailSendParams(BaseModel):@@ -52,6 +53,16 @@ class EmailSendNode(ActionNode):annotations = {"destructive": False, "readonly": False, "open_world": True}task_queue = TaskQueue.MESSAGINGusable_as_tool = True+ # Which account sends is the node's setting, never the model's choice.+ server_controlled_fields = frozenset({"provider"})+ approval = ApprovalSpec(+ channel="Email",+ action="Send an email",+ recipient=("to",),+ body=("body",),+ subject="subject",+ details=(("Cc", "cc"), ("Bcc", "bcc")),+ )Params = EmailSendParamsOutput = EmailSendOutputdiff --git a/server/nodes/google/calendar/__init__.py b/server/nodes/google/calendar/__init__.pyindex bed282ec..f1cafdcf 100644--- a/server/nodes/google/calendar/__init__.py+++ b/server/nodes/google/calendar/__init__.py@@ -8,6 +8,7 @@ from typing import List, Literal, Optionalfrom pydantic import BaseModel, ConfigDict, Fieldfrom services.plugin import ActionNode, NodeContext, Operation, TaskQueue+from services.plugin.approval import ApprovalSpecfrom .._credentials import GoogleCredential@@ -111,6 +112,18 @@ class CalendarNode(ActionNode):credentials = (GoogleCredential,)task_queue = TaskQueue.REST_APIusable_as_tool = True+ # An event change that notifies its guests reaches people outside.+ approval = ApprovalSpec(+ channel="Google Calendar",+ action="Send calendar invites",+ operations=frozenset({"create", "update", "delete"}),+ when=lambda data: (data.get("send_updates") or "all") != "none"+ and (bool(str(data.get("attendees") or "").strip()) or data.get("operation") in ("update", "delete")),+ recipient=("attendees",),+ recipient_otherwise="the event's guests",+ body=("description", "update_description"),+ details=(("Event", "title"), ("Starts", "start_time"), ("Ends", "end_time"), ("Where", "location")),+ )Params = CalendarParamsOutput = CalendarOutputdiff --git a/server/nodes/google/drive/__init__.py b/server/nodes/google/drive/__init__.pyindex addc04b0..142b395d 100644--- a/server/nodes/google/drive/__init__.py+++ b/server/nodes/google/drive/__init__.py@@ -11,6 +11,7 @@ from googleapiclient.http import MediaIoBaseDownload, MediaIoBaseUploadfrom pydantic import BaseModel, ConfigDict, Fieldfrom services.plugin import ActionNode, NodeContext, Operation, TaskQueue+from services.plugin.approval import ApprovalSpecfrom .._credentials import GoogleCredential@@ -110,6 +111,14 @@ class DriveNode(ActionNode):credentials = (GoogleCredential,)task_queue = TaskQueue.REST_APIusable_as_tool = True+ approval = ApprovalSpec(+ channel="Google Drive",+ action="Share a file",+ operations=frozenset({"share"}),+ recipient=("email",),+ body=("message",),+ details=(("File", "file_id"), ("Access", "role")),+ )Params = DriveParamsOutput = DriveOutputdiff --git a/server/nodes/google/gmail/__init__.py b/server/nodes/google/gmail/__init__.pyindex 88633545..bbdbb5ca 100644--- a/server/nodes/google/gmail/__init__.py+++ b/server/nodes/google/gmail/__init__.py@@ -10,6 +10,7 @@ from typing import List, Literal, Optionalfrom pydantic import BaseModel, ConfigDict, Fieldfrom services.plugin import ActionNode, NodeContext, Operation, TaskQueue+from services.plugin.approval import ApprovalSpecfrom .._credentials import GoogleCredential@@ -113,6 +114,15 @@ class GmailNode(ActionNode):annotations = {"destructive": False, "readonly": False, "open_world": True}task_queue = TaskQueue.REST_APIusable_as_tool = True+ approval = ApprovalSpec(+ channel="Gmail",+ action="Send an email",+ operations=frozenset({"send"}),+ recipient=("to",),+ body=("body",),+ subject="subject",+ details=(("Cc", "cc"), ("Bcc", "bcc")),+ )Params = GmailParamsOutput = GmailOutputdiff --git a/server/nodes/microsoft/calendar/__init__.py b/server/nodes/microsoft/calendar/__init__.pyindex 300d9c74..2f2edb68 100644--- a/server/nodes/microsoft/calendar/__init__.py+++ b/server/nodes/microsoft/calendar/__init__.py@@ -18,6 +18,7 @@ from typing import List, Literal, Optionalfrom pydantic import BaseModel, ConfigDict, Fieldfrom services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueue+from services.plugin.approval import ApprovalSpecfrom .._base import graph_request, mailbox_base, track_microsoft_usagefrom .._credentials import MicrosoftCredential@@ -136,6 +137,16 @@ class CalendarNode(ActionNode):annotations = {"destructive": False, "readonly": False, "open_world": True}task_queue = TaskQueue.REST_APIusable_as_tool = True+ # An event with attendees sends them invites.+ approval = ApprovalSpec(+ channel="Outlook Calendar",+ action="Send meeting invites",+ operations=frozenset({"create", "update"}),+ when=lambda data: bool(str(data.get("attendees") or "").strip()),+ recipient=("attendees",),+ body=("body", "update_body"),+ details=(("Event", "title"), ("Starts", "start_time"), ("Ends", "end_time"), ("Where", "location")),+ )Params = CalendarParamsOutput = CalendarOutputdiff --git a/server/nodes/microsoft/mail/__init__.py b/server/nodes/microsoft/mail/__init__.pyindex 5e816160..242ba342 100644--- a/server/nodes/microsoft/mail/__init__.py+++ b/server/nodes/microsoft/mail/__init__.py@@ -23,6 +23,7 @@ from typing import List, Literal, Optionalfrom pydantic import BaseModel, ConfigDict, Fieldfrom services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueue+from services.plugin.approval import ApprovalSpecfrom .._base import graph_request, mailbox_base, track_microsoft_usage, write_attachment_bytesfrom .._credentials import MicrosoftCredential@@ -166,6 +167,18 @@ class MailNode(ActionNode):annotations = {"destructive": False, "readonly": False, "open_world": True}task_queue = TaskQueue.REST_APIusable_as_tool = True+ # Which mailbox sends is the node's setting, never the model's choice.+ server_controlled_fields = frozenset({"mailbox"})+ approval = ApprovalSpec(+ channel="Outlook",+ action="Send an email",+ operations=frozenset({"send", "reply"}),+ recipient=("to",),+ recipient_otherwise="the sender",+ body=("body", "comment"),+ subject="subject",+ details=(("Cc", "cc"), ("Bcc", "bcc")),+ )Params = MailParamsOutput = MailOutputdiff --git a/server/nodes/stripe/stripe_action.py b/server/nodes/stripe/stripe_action.pyindex 3d0d3362..ce273d1f 100644--- a/server/nodes/stripe/stripe_action.py+++ b/server/nodes/stripe/stripe_action.py@@ -9,6 +9,7 @@ from pydantic import BaseModel, ConfigDict, Fieldfrom services.events import run_cli_commandfrom services.plugin import ActionNode, NodeContext, Operation, TaskQueue+from services.plugin.approval import ApprovalSpecfrom ._credentials import StripeCredential@@ -53,6 +54,13 @@ class StripeActionNode(ActionNode):credentials = (StripeCredential,)task_queue = TaskQueue.REST_APIusable_as_tool = True+ # Money cannot wait for a card: refused while the owner asks first.+ approval = ApprovalSpec(+ channel="Stripe",+ action="Run a Stripe command",+ refuse_while_asking=True,+ details=(("Command", "command"),),+ )Params = StripeActionParamsOutput = StripeActionOutputdiff --git a/server/nodes/telegram/telegram_send.py b/server/nodes/telegram/telegram_send.pyindex 73cb0f97..bf291e42 100644--- a/server/nodes/telegram/telegram_send.py+++ b/server/nodes/telegram/telegram_send.py@@ -14,6 +14,7 @@ from typing import Any, List, Literal, Optionalfrom pydantic import BaseModel, ConfigDict, Field, field_validatorfrom services.plugin import ActionNode, NodeContext, Operation, TaskQueue+from services.plugin.approval import ApprovalSpecfrom ._credentials import TelegramCredential@@ -187,6 +188,24 @@ class TelegramSendNode(ActionNode):annotations = {"destructive": False, "readonly": False, "open_world": True}credentials = (TelegramCredential,)task_queue = TaskQueue.MESSAGING+ # Employees may send from Talk too: a tool, held for the owner's OK+ # while they ask first (services/approvals/tool_calls.py).+ usable_as_tool = True+ tool_name = "telegram_send"+ tool_description = "Send a Telegram message (text, photo, document, location or contact) through the connected bot."+ # Canvas handles are auto-hidden for usable_as_tool nodes; this one is+ # wired into workflows as well.+ hide_input_handle = False+ hide_output_handle = False+ approval = ApprovalSpec(+ channel="Telegram",+ action="Send a Telegram message",+ recipient=("chat_id",),+ to_owner=lambda data: (data.get("recipient_type") or "self") == "self",+ body=("text", "caption"),+ details=(("Link", "media_url"),),+ max_length=4096,+ )Params = TelegramSendParamsOutput = TelegramSendOutputdiff --git a/server/nodes/whatsapp/whatsapp_send.py b/server/nodes/whatsapp/whatsapp_send.pyindex dddd4a23..999f725a 100644--- a/server/nodes/whatsapp/whatsapp_send.py+++ b/server/nodes/whatsapp/whatsapp_send.py@@ -13,6 +13,7 @@ from typing import Any, Literal, Optionalfrom pydantic import BaseModel, ConfigDict, Fieldfrom services.plugin import ActionNode, NodeContext, Operation, TaskQueue+from services.plugin.approval import ApprovalSpecclass WhatsAppSendParams(BaseModel):@@ -278,6 +279,17 @@ class WhatsAppSendNode(ActionNode):annotations = {"destructive": False, "readonly": False, "open_world": True}task_queue = TaskQueue.MESSAGINGusable_as_tool = True+ # While the owner asks first, a message the employee sends as a tool+ # call waits for their OK on a card (services/approvals/tool_calls.py).+ approval = ApprovalSpec(+ channel="WhatsApp",+ action="Send a WhatsApp message",+ recipient=("phone", "group_id", "channel_jid"),+ to_owner=lambda data: (data.get("recipient_type") or "self") == "self",+ body=("message", "caption"),+ details=(("File", "file_path"), ("Link", "media_url")),+ max_length=4096,+ )Params = WhatsAppSendParamsOutput = WhatsAppSendOutputdiff --git a/server/nodes/whatsapp_business/whatsapp_business_send.py b/server/nodes/whatsapp_business/whatsapp_business_send.pyindex 99c2e90f..a19da99d 100644--- a/server/nodes/whatsapp_business/whatsapp_business_send.py+++ b/server/nodes/whatsapp_business/whatsapp_business_send.py@@ -22,6 +22,7 @@ from typing import Any, Dict, List, Literal, Optionalfrom pydantic import BaseModel, ConfigDict, Field, field_validatorfrom services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueue+from services.plugin.approval import ApprovalSpecfrom ._base import (graph_get,@@ -403,6 +404,27 @@ class WhatsAppBusinessSendNode(ActionNode):annotations = {"destructive": False, "readonly": False, "open_world": True}task_queue = TaskQueue.MESSAGINGusable_as_tool = True+ approval = ApprovalSpec(+ channel="WhatsApp Business",+ action="Send a WhatsApp message",+ operations=frozenset(+ {+ "send_text",+ "send_media",+ "send_template",+ "send_buttons",+ "send_list",+ "send_cta_url",+ "send_reaction",+ "send_location",+ "send_contacts",+ }+ ),+ recipient=("to",),+ body=("text", "body", "caption"),+ details=(("Template", "template_name"), ("Link", "media_url")),+ max_length=4096,+ )# ToolInput / server_controlled_fields are deliberately NOT declared.# They are ToolNode extensions; on a dual-purpose ActionNode they arediff --git a/server/nodes/workflow/approval_gate/__init__.py b/server/nodes/workflow/approval_gate/__init__.pyindex bad0920c..62ef8716 100644--- a/server/nodes/workflow/approval_gate/__init__.py+++ b/server/nodes/workflow/approval_gate/__init__.py@@ -1,10 +1,15 @@"""Approval gate: hold a draft until the owner sends or discards it.-An employee that asks before sending anything answers through ``agent ->-approvalGate -> reply``. The gate records the agent's draft (who it goes-to, what it says), shows it on the employee's card, and waits. Send lets-the draft (or the owner's edit of it) through; Discard, an expired draft-or a Reset lets nothing through.+An employee answers through ``agent -> approvalGate -> reply``. The gate+records the agent's draft (who it goes to, what it says), shows it on the+employee's card, and waits. Send lets the draft (or the owner's edit of it)+through once the Undo window has passed; Discard (once Restore can no longer+bring it back), an expired draft or a Reset lets nothing through.++The workflow's Ask first rule is read live (services/approvals/rules.py):+with it off, the draft goes straight through and its row records that it+went without asking (``approved_by: auto``), so the owner still sees it. A+workflow with no rule (one built in the editor) always asks.The wait is durable. Its whole state is one ``approval_requests`` row,found again by an idempotency key on every attempt: on Temporal the@@ -30,7 +35,7 @@ from typing import Any, Optional, Tuplefrom pydantic import BaseModel, ConfigDict, Field, field_validatorfrom core.logging import get_logger-from services.approvals import store, waiter+from services.approvals import rules, store, waiterfrom services.approvals.contract import APPROVAL_GATE_TYPE, DEFAULT_TIMEOUT_HOURS, NO_REPLYfrom services.approvals.listeners import change_of, notify_approval_changedfrom services.plugin import ActionNode, NodeContext, Operation, TaskQueue@@ -89,7 +94,7 @@ class ApprovalGateParams(BaseModel):class ApprovalGateOutput(BaseModel):approved: bool = False- #: pending | approved | discarded | expired | cancelled | skipped+ #: approved | discarded | expired | cancelled | skippedstatus: str = "skipped"skipped: bool = Falsetext: str = ""@@ -98,6 +103,8 @@ class ApprovalGateOutput(BaseModel):recipient_label: str = ""approval_id: Optional[str] = Noneedited: bool = False+ #: It went without asking: Ask first was off.+ automatic: bool = Falsedef _identity(ctx: NodeContext) -> Tuple[str, str]:@@ -127,9 +134,14 @@ def _outcome(row: Any) -> ApprovalGateOutput:recipient_label=row.recipient_label if approved else "",approval_id=row.id,edited=bool(row.edited) if approved else False,+ automatic=approved and row.approved_by == "auto",)+def _utcnow() -> datetime:+ return datetime.now(timezone.utc)++def _worker_shutting_down() -> bool:try:from temporalio import activity@@ -185,47 +197,84 @@ class ApprovalGateNode(ActionNode):database = container.database()runtime, key = _identity(ctx)- now = datetime.now(timezone.utc)- row, created = await store.get_or_create(- database,- idempotency_key=key,- fields={- "owner_id": ctx.user_id or "owner",- "workflow_id": ctx.workflow_id or "",- "node_id": ctx.node_id,- "generation": int(ctx.raw.get("generation") or 0),- "execution_id": ctx.execution_id,- "runtime": runtime,- "channel": params.channel,- "recipient": params.recipient,- "recipient_label": params.recipient_label,- "subject": params.subject or None,- "draft_text": draft[: params.max_length],- "context_excerpt": params.context_excerpt or None,- "max_length": params.max_length,- "expires_at": now + timedelta(hours=params.timeout_hours),- },- )+ now = _utcnow()+ fields = {+ "owner_id": ctx.user_id or "owner",+ "workflow_id": ctx.workflow_id or "",+ "node_id": ctx.node_id,+ "generation": int(ctx.raw.get("generation") or 0),+ "execution_id": ctx.execution_id,+ "runtime": runtime,+ "channel": params.channel,+ "recipient": params.recipient,+ "recipient_label": params.recipient_label,+ "subject": params.subject or None,+ "draft_text": draft[: params.max_length],+ "context_excerpt": params.context_excerpt or None,+ "max_length": params.max_length,+ "expires_at": now + timedelta(hours=params.timeout_hours),+ }+ if await store.get_by_key(database, key) is None and await rules.ask_first(database, ctx.workflow_id) is False:+ # Ask first is off: it goes now, and the card says it went.+ fields.update(+ status="approved",+ approved_by="auto",+ decided_at=now,+ consumed_at=now,+ final_text=draft[: params.max_length],+ final_subject=params.subject or None,+ )+ row, created = await store.get_or_create(database, idempotency_key=key, fields=fields)if created:- await notify_approval_changed(change_of(row, "requested"))+ await notify_approval_changed(change_of(row, "decided" if row.status == "approved" else "requested"))if row.status == "pending":await _show_waiting(ctx, row)- while row.status == "pending":- expires = row.expires_at- if expires is not None:- expires = expires if expires.tzinfo else expires.replace(tzinfo=timezone.utc)- if expires is not None and datetime.now(timezone.utc) >= expires:- try:- row = await store.settle(database, row.id, expected_revision=row.revision, status="expired")- await notify_approval_changed(change_of(row, "expired"))- except store.ApprovalConflict:- row = await store.get(database, row.id) or row- continue+ row = await self._wait(database, row)+ return _outcome(row)++ async def _wait(self, database: Any, row: Any) -> Any:+ """Wait until the row settles for this gate: approved and past its+ Undo window (then it is handed on), discarded past Restore, expired+ or cancelled."""+ while True:+ now = _utcnow()+ if row.status == "pending":+ expires = store.aware(row.expires_at)+ if expires is not None and now >= expires:+ try:+ row = await store.settle(database, row.id, expected_revision=row.revision, status="expired")+ await notify_approval_changed(change_of(row, "expired"))+ except store.ApprovalConflict:+ row = await store.get(database, row.id) or row+ continue+ wait = POLL_SECONDS+ elif row.status == "approved" and row.consumed_at is None:+ grace = store.aware(row.grace_until)+ if grace is None or now >= grace:+ try:+ return await store.transition(+ database,+ row.id,+ expected_revision=row.revision,+ from_statuses=("approved",),+ status="approved",+ values={"consumed_at": now},+ )+ except store.ApprovalConflict:+ row = await store.get(database, row.id) or row+ continue+ wait = min(POLL_SECONDS, (grace - now).total_seconds())+ elif row.status == "discarded":+ restore = store.aware(row.restore_until)+ if restore is None or now >= restore:+ return row+ wait = min(POLL_SECONDS, (restore - now).total_seconds())+ else:+ return rowif _worker_shutting_down():raise NodeWaitInterrupted("worker shutting down while a draft waits")- await waiter.wait_for_change(row.id, POLL_SECONDS)+ await waiter.wait_for_change(row.id, max(0.01, wait))row = await store.get(database, row.id) or row- return _outcome(row)@classmethodasync def reset_execution_state(@@ -251,15 +300,5 @@ class ApprovalGateNode(ActionNode):__all__ = ["ApprovalGateNode", "ApprovalGateOutput", "ApprovalGateParams"]-# Plugin-owned side channels: the owner's list and decisions, and the-# broadcast every change produces.-from services.approvals.listeners import register_approval_listener # noqa: E402-from services.workflow_storage.hooks import register_workflow_deleted_hook # noqa: E402-from services.ws_handler_registry import register_ws_handlers # noqa: E402--from ._events import broadcast_approval_change # noqa: E402-from ._handlers import WS_HANDLERS, on_workflow_deleted # noqa: E402--register_ws_handlers(WS_HANDLERS)-register_approval_listener(broadcast_approval_change)-register_workflow_deleted_hook(on_workflow_deleted)+# The owner's side (listing and deciding drafts, the approval_lifecycle+# broadcast, the cleanup on workflow delete) lives in services/approvals.diff --git a/server/nodes/workflow/approval_gate/_events.py b/server/nodes/workflow/approval_gate/_events.pydeleted file mode 100644index 33863986..00000000--- a/server/nodes/workflow/approval_gate/_events.py+++ /dev/null@@ -1,41 +0,0 @@-"""``approval_lifecycle``: a draft was requested, decided, expired or cancelled.--Type ``com.opencompany.approval.{requested|decided|expired|cancelled}``,-subject = the approval id. Identity only: never the message, never who it-goes to. The client refetches the drafts it shows (``list_approvals``)-through the authorized handler.--Broadcast directly: no Temporal consumer listens for these.-"""--from __future__ import annotations--from services.approvals.listeners import ApprovalChange-from services.events.envelope import WorkflowEvent--WIRE_KEY = "approval_lifecycle"-SOURCE = "opencompany://nodes/approval_gate"---def approval_lifecycle_event(change: ApprovalChange) -> WorkflowEvent:- return WorkflowEvent(- source=SOURCE,- type=f"com.opencompany.approval.{change.stage}",- subject=change.approval_id,- data={- "approval_id": change.approval_id,- "workflow_id": change.workflow_id,- "status": change.status,- "revision": change.revision,- },- )---async def broadcast_approval_change(change: ApprovalChange) -> None:- from services.status_broadcaster import get_status_broadcaster-- event = approval_lifecycle_event(change)- await get_status_broadcaster().broadcast({"type": WIRE_KEY, "data": event.model_dump(mode="json", exclude_none=True)})---__all__ = ["WIRE_KEY", "approval_lifecycle_event", "broadcast_approval_change"]diff --git a/server/nodes/workflow/approval_gate/_handlers.py b/server/nodes/workflow/approval_gate/_handlers.pydeleted file mode 100644index 29c8d679..00000000--- a/server/nodes/workflow/approval_gate/_handlers.py+++ /dev/null@@ -1,143 +0,0 @@-"""The owner's side of the approval step: see drafts, send or discard them.--``list_approvals {workflow_id?, status?: "pending", limit <= 100}`` ->-``{approvals: ApprovalSummary[], counts: {workflow_id: pending}, server_time}``.--``decide_approval {approval_id, decision: "send" | "discard", text?,-subject?, decision_key}`` -> ``{approval, will_send_on_resume}``. A decision-is a compare-and-swap on the pending row, so two clicks (or two tabs)-settle it once; the same ``decision_key`` again returns the settled row.-An edited text must fit the channel (``max_length``). Errors:-``already_decided``, ``expired``, ``cancelled``, ``not_found``,-``invalid_request``.--Only the owner's own drafts are visible or decidable; any other id reads-as not found.-"""--from __future__ import annotations--from datetime import datetime, timezone-from typing import Any, Dict--from fastapi import WebSocket--from core.logging import get_logger-from services.approvals import store, waiter-from services.approvals.listeners import change_of, notify_approval_changed-from services.approvals.reconcile import reconcile_once-from services.authz.ws_surface import execution_principal-from services.plugin.ws import ws_response--logger = get_logger(__name__)--MAX_LIST = 100-_SETTLED_ERRORS = {"approved": "already_decided", "discarded": "already_decided", "expired": "expired", "cancelled": "cancelled"}---async def _deployment_state(database: Any, workflow_id: str) -> str | None:- try:- control = await database.get_latest_workflow_control(workflow_id)- except Exception:- return None- return getattr(control, "status", None)---@ws_response-async def handle_list_approvals(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:- from core.container import container-- database = container.database()- await reconcile_once(database)- owner = execution_principal(data, websocket)- workflow_id = str(data.get("workflow_id") or "").strip() or None- status = data.get("status")- status = status if status in ("pending", "approved", "discarded", "expired", "cancelled") else "pending"- try:- limit = max(1, min(int(data.get("limit") or 50), MAX_LIST))- except (TypeError, ValueError):- limit = 50- rows = await store.list_approvals(database, owner_id=owner, workflow_id=workflow_id, status=status, limit=limit)- states: Dict[str, Any] = {}- approvals = []- for row in rows:- if row.workflow_id not in states:- states[row.workflow_id] = await _deployment_state(database, row.workflow_id)- approvals.append(store.summary(row, deployment_state=states[row.workflow_id]))- counts: Dict[str, int] = {}- for row in rows:- if row.status == "pending":- counts[row.workflow_id] = counts.get(row.workflow_id, 0) + 1- return {- "success": True,- "approvals": approvals,- "counts": counts,- "server_time": datetime.now(timezone.utc).isoformat(),- }---@ws_response-async def handle_decide_approval(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:- from core.container import container-- approval_id = str(data.get("approval_id") or "").strip()- decision = data.get("decision")- decision_key = str(data.get("decision_key") or "").strip()[:128]- if not approval_id or decision not in ("send", "discard") or not decision_key:- return {"success": False, "error": "invalid_request"}- database = container.database()- owner = execution_principal(data, websocket)- row = await store.get(database, approval_id)- if row is None or row.owner_id != owner:- return {"success": False, "error": "not_found", "approval_id": approval_id}- if row.decision_key and row.decision_key == decision_key:- return {"success": True, "idempotent": True, "approval": store.summary(row), "will_send_on_resume": False}- if row.status != "pending":- return {"success": False, "error": _SETTLED_ERRORS.get(row.status, "already_decided"), "approval": store.summary(row)}-- values: Dict[str, Any] = {"decision_key": decision_key}- if decision == "send":- text = data.get("text")- final = row.draft_text if text is None else str(text).strip()- if not final:- return {"success": False, "error": "invalid_request", "detail": "The message is empty."}- if len(final) > row.max_length:- return {"success": False, "error": "invalid_request", "detail": f"Keep it under {row.max_length} characters."}- subject = data.get("subject")- final_subject = row.subject if subject is None else (str(subject).strip()[:500] or row.subject)- values.update({"final_text": final, "final_subject": final_subject, "edited": final != row.draft_text})- status = "approved"- else:- status = "discarded"- try:- settled = await store.settle(database, row.id, expected_revision=row.revision, status=status, values=values)- except store.ApprovalConflict:- current = await store.get(database, row.id) or row- if current.decision_key == decision_key:- return {"success": True, "idempotent": True, "approval": store.summary(current), "will_send_on_resume": False}- return {"success": False, "error": _SETTLED_ERRORS.get(current.status, "already_decided"), "approval": store.summary(current)}- waiter.notify(settled.id)- await notify_approval_changed(change_of(settled, "decided"))- state = await _deployment_state(database, settled.workflow_id)- logger.info("Draft decided", approval_id=settled.id, workflow_id=settled.workflow_id, status=settled.status, edited=settled.edited)- return {- "success": True,- "approval": store.summary(settled, deployment_state=state),- # A paused employee's run holds the approved draft until Resume.- "will_send_on_resume": settled.status == "approved" and state in ("paused", "pausing"),- }---async def on_workflow_deleted(database: Any, workflow_id: str) -> None:- removed = await store.delete_for_workflow(database, workflow_id)- if removed:- logger.info("Removed a deleted workflow's drafts", workflow_id=workflow_id, count=removed)---WS_HANDLERS: Dict[str, Any] = {- "list_approvals": handle_list_approvals,- "decide_approval": handle_decide_approval,-}---__all__ = ["WS_HANDLERS", "handle_decide_approval", "handle_list_approvals", "on_workflow_deleted"]diff --git a/server/services/approvals/__init__.py b/server/services/approvals/__init__.pyindex 6f894ec9..cdb1d91f 100644--- a/server/services/approvals/__init__.py+++ b/server/services/approvals/__init__.py@@ -1,10 +1,52 @@-"""Drafts waiting for the owner's Send or Discard (the approval step).+"""What waits for the owner's OK before it goes out.-The rows and the rules live here; the ``approvalGate`` node that waits on-them, its WebSocket handlers and its broadcasts live in-``nodes/workflow/approval_gate``. This package never imports ``nodes/``.+- ``contract``: the gate's contract with graphs (conditions, NO_REPLY, the+ statuses and the Undo and Restore windows).+- ``store``: the rows (models/approvals.py), moved by compare-and-swap.+- ``decisions``: the owner's send, undo, discard, restore and retry.+- ``rules``: a workflow's live Ask first rule.+- ``tool_calls``: holding a tool call that sends (``BaseNode.as_activity``).+- ``execution`` / ``activities``: sending a held call once the owner+ pressed Send (``ApprovedToolCallWorkflow``).+- ``waiter``: wakes a waiting approval gate at once.+- ``reconcile``: ends what nothing waits for any more, and restarts sends+ that never started.+- ``events`` / ``listeners``: the ``approval_lifecycle`` broadcast and who+ else hears about changes.+- ``handlers``: the WebSocket commands.++The ``approvalGate`` node that waits on a row lives in+``nodes/workflow/approval_gate``; this package never imports ``nodes/``.++Importing the package registers the WebSocket commands, the broadcast and+the cleanup that runs when a workflow is deleted."""from __future__ import annotations-__all__ = ["contract", "listeners", "queries", "reconcile", "store", "waiter"]+from services.workflow_storage.hooks import register_workflow_deleted_hook as _register_workflow_deleted_hook+from services.ws_handler_registry import register_ws_handlers as _register_ws_handlers++from .events import broadcast_approval_change as _broadcast_approval_change+from .handlers import WS_HANDLERS as _APPROVAL_WS_HANDLERS+from .handlers import on_workflow_deleted as _on_workflow_deleted+from .listeners import register_approval_listener as _register_approval_listener++_register_ws_handlers(_APPROVAL_WS_HANDLERS)+_register_approval_listener(_broadcast_approval_change)+_register_workflow_deleted_hook(_on_workflow_deleted)++__all__ = [+ "contract",+ "decisions",+ "events",+ "execution",+ "handlers",+ "listeners",+ "queries",+ "reconcile",+ "rules",+ "store",+ "tool_calls",+ "waiter",+]diff --git a/server/services/approvals/activities.py b/server/services/approvals/activities.pynew file mode 100644index 00000000..40a4b728--- /dev/null+++ b/server/services/approvals/activities.py@@ -0,0 +1,54 @@+"""The Temporal activities ``ApprovedToolCallWorkflow`` sends a held tool call+through (services/approvals/execution.py).++Both are safe to retry: a claim retried by the same workflow run finds its+own claim (the token is the run's), and an outcome is recorded once (only a+row still ``sending`` under that claim moves).+"""++from __future__ import annotations++from typing import Any, Dict++from temporalio import activity++[email protected](name="approvals.claim_send")+async def claim_send_activity(payload: Dict[str, Any]) -> Dict[str, Any]:+ """Payload ``{approval_id, revision, claim_token}``. Returns ``{claimed,+ reason?, activity?, context?}``: the node activity to run and its+ input."""+ from core.container import container+ from services.approvals.execution import claim_send++ return await claim_send(+ container.database(),+ str(payload.get("approval_id") or ""),+ int(payload.get("revision") or 0),+ str(payload.get("claim_token") or ""),+ )++[email protected](name="approvals.record_outcome")+async def record_outcome_activity(payload: Dict[str, Any]) -> Dict[str, Any]:+ """Payload ``{approval_id, claim_token, success?, error?, broke_off?}``.+ Returns ``{recorded, status, outcome}``."""+ from core.container import container+ from services.approvals.execution import outcome_of, record_outcome++ error = str(payload.get("error") or "It broke off.") if payload.get("broke_off") else None+ result = {"success": payload.get("success", True) is not False, "error": payload.get("error")}+ outcome = outcome_of(result, error)+ settled = await record_outcome(+ container.database(),+ str(payload.get("approval_id") or ""),+ str(payload.get("claim_token") or ""),+ outcome["outcome"],+ outcome.get("error"),+ )+ return {"recorded": settled is not None, "status": getattr(settled, "status", None), "outcome": outcome["outcome"]}+++APPROVAL_ACTIVITIES = [claim_send_activity, record_outcome_activity]++__all__ = ["APPROVAL_ACTIVITIES", "claim_send_activity", "record_outcome_activity"]diff --git a/server/services/approvals/contract.py b/server/services/approvals/contract.pyindex e38eaa5e..91866924 100644--- a/server/services/approvals/contract.py+++ b/server/services/approvals/contract.py@@ -1,4 +1,4 @@-"""The approval step's contract with the graphs that use it.+"""The approval step's contract with the graphs and tools that use it.An employee that asks before sending gets ``agent -> approvalGate ->reply``: the gate holds the agent's draft until the owner presses Send or@@ -7,6 +7,9 @@ nothing to send (NO_REPLY); the edge out only fires for an approved draft.The gate's output fails closed: ``text``, ``subject`` and ``recipient`` areempty unless the draft was approved, so a mis-wired graph sends nothing.++A tool call that sends is held the same way (``services/approvals/+tool_calls.py``), as a row of kind ``tool_call``."""from __future__ import annotations@@ -21,8 +24,19 @@ NO_REPLY = "NO_REPLY"#: How long a draft waits for the owner before it expires.DEFAULT_TIMEOUT_HOURS = 168-APPROVAL_STATUSES = ("pending", "approved", "discarded", "expired", "cancelled")-FINAL_STATUSES = frozenset({"approved", "discarded", "expired", "cancelled"})+APPROVAL_KINDS = ("gate", "tool_call")+APPROVAL_STATUSES = ("pending", "approved", "sending", "sent", "failed", "discarded", "expired", "cancelled")+#: Nothing moves a row out of these.+FINAL_STATUSES = frozenset({"sent", "expired", "cancelled"})+#: A send's outcome: it went, it did not, or it broke off and may have.+OUTCOMES = ("sent", "not_sent", "unknown")++#: How long Undo works after Send. The send waits this long.+UNDO_SECONDS = 5.0+#: How long Restore works after Discard on a gate's draft (its run waits+#: this long before it goes on without it). A held tool call can be+#: restored until it expires.+RESTORE_SECONDS = 5.0def send_condition() -> Dict[str, Any]:@@ -37,10 +51,14 @@ def approved_edge_condition() -> Dict[str, Any]:__all__ = ["APPROVAL_GATE_TYPE",+ "APPROVAL_KINDS","APPROVAL_STATUSES","DEFAULT_TIMEOUT_HOURS","FINAL_STATUSES","NO_REPLY",+ "OUTCOMES",+ "RESTORE_SECONDS",+ "UNDO_SECONDS","approved_edge_condition","send_condition",]diff --git a/server/services/approvals/decisions.py b/server/services/approvals/decisions.pynew file mode 100644index 00000000..3418583d--- /dev/null+++ b/server/services/approvals/decisions.py@@ -0,0 +1,200 @@+"""The owner's decisions on a draft (``decide_approval``).++- **send** (pending -> approved): the draft, or the owner's edit of its text+ and subject, goes after ``UNDO_SECONDS`` (``grace_until``). A gate lets it+ through then; a held tool call is sent then (``execution.py``).+- **undo** (approved -> pending): before ``grace_until``, and only while+ nothing has taken it on.+- **discard** (pending -> discarded): restorable until ``restore_until``+ (``RESTORE_SECONDS`` for a gate's draft, whose run waits that long; until+ it expires for a held call, which nothing waits on).+- **restore** (discarded -> pending): before ``restore_until``.+- **retry** (failed -> approved): a held call whose send failed goes again+ after a new grace. When it broke off mid-way it may have gone out already,+ so a retry then needs ``confirm``.++Each decision is a compare-and-swap on the row's revision, recorded with its+``decision_key`` in the same transaction (``approval_decisions``): the same+key again returns the row as it is. Never imports ``nodes/``.+"""++from __future__ import annotations++from datetime import datetime, timedelta, timezone+from typing import Any, Dict, Optional, Tuple++from models.approvals import ApprovalRequest+from services.approvals import store+from services.approvals.contract import DEFAULT_TIMEOUT_HOURS, RESTORE_SECONDS, UNDO_SECONDS++DECISIONS = ("send", "undo", "discard", "restore", "retry")+#: Why a decision on a row that already moved on was refused.+SETTLED_ERRORS = {+ "approved": "already_decided",+ "sending": "already_decided",+ "sent": "already_decided",+ "failed": "already_decided",+ "discarded": "already_decided",+ "expired": "expired",+ "cancelled": "cancelled",+}+++class DecisionRefused(ValueError):+ """A decision that does not apply to the row as it is."""++ def __init__(self, code: str, detail: Optional[str] = None) -> None:+ super().__init__(code)+ self.code = code+ self.detail = detail+++def _utcnow() -> datetime:+ return datetime.now(timezone.utc)+++def _settled(row: ApprovalRequest) -> DecisionRefused:+ return DecisionRefused(SETTLED_ERRORS.get(row.status, "already_decided"))+++async def _expire_if_due(database: Any, row: ApprovalRequest, now: datetime) -> ApprovalRequest:+ """A pending row past its expiry ends ``expired`` (expiry is lazy)."""+ expires = store.aware(row.expires_at)+ if row.status != "pending" or expires is None or expires > now:+ return row+ try:+ return await store.settle(database, row.id, expected_revision=row.revision, status="expired")+ except store.ApprovalConflict:+ return await store.get(database, row.id) or row+++def _send_values(row: ApprovalRequest, text: Any, subject: Any, now: datetime) -> Dict[str, Any]:+ final = row.draft_text if text is None else str(text).strip()+ editable_body = (row.kind or "gate") == "gate" or bool(row.body_field)+ if text is not None and not editable_body:+ raise DecisionRefused("invalid_request", "This one cannot be edited.")+ if editable_body and not final:+ raise DecisionRefused("invalid_request", "The message is empty.")+ if len(final) > row.max_length:+ raise DecisionRefused("invalid_request", f"Keep it under {row.max_length} characters.")+ final_subject = row.subject if subject is None else (str(subject).strip()[:500] or row.subject)+ values: Dict[str, Any] = {+ "final_text": final,+ "final_subject": final_subject,+ "edited": final != row.draft_text or (final_subject or None) != (row.subject or None),+ "approved_by": "owner",+ "decided_at": now,+ "grace_until": now + timedelta(seconds=UNDO_SECONDS),+ "restore_until": None,+ }+ if (row.kind or "gate") == "tool_call":+ args = dict(row.args or {})+ node_data = dict(row.node_data or {})+ if row.body_field and text is not None:+ args[row.body_field] = final+ node_data[row.body_field] = final+ if row.subject_field and subject is not None and final_subject:+ args[row.subject_field] = final_subject+ node_data[row.subject_field] = final_subject+ values.update(args=args, node_data=node_data)+ return values+++async def decide(+ database: Any,+ row: ApprovalRequest,+ *,+ decision: str,+ decision_key: str,+ actor: str = "owner",+ text: Any = None,+ subject: Any = None,+ confirm: bool = False,+ now: Optional[datetime] = None,+) -> Tuple[ApprovalRequest, bool]:+ """Apply a decision. Returns ``(row, idempotent)``; raises+ :class:`DecisionRefused` when it does not apply."""+ if decision not in DECISIONS or not decision_key:+ raise DecisionRefused("invalid_request")+ if await store.find_decision(database, row.id, decision_key) is not None:+ return (await store.get(database, row.id)) or row, True+ now = now or _utcnow()+ row = await _expire_if_due(database, row, now)+ record = (decision, decision_key, actor)+ kind = row.kind or "gate"+ if decision == "send":+ if row.status != "pending":+ raise _settled(row)+ values = _send_values(row, text, subject, now)+ values["decision_key"] = decision_key+ moved = await _move(database, row, ("pending",), "approved", values, record)+ elif decision == "undo":+ grace = store.aware(row.grace_until)+ if row.status != "approved" or row.consumed_at is not None or row.claim_token or grace is None or grace <= now:+ raise DecisionRefused("too_late", "It has already gone.")+ values = {"grace_until": None, "decided_at": None, "approved_by": None, "final_text": None, "final_subject": None, "edited": False}+ moved = await _move(database, row, ("approved",), "pending", values, record)+ elif decision == "discard":+ if row.status != "pending":+ raise _settled(row)+ if kind == "gate":+ restore = now + timedelta(seconds=RESTORE_SECONDS)+ else:+ restore = store.aware(row.expires_at) or now + timedelta(hours=DEFAULT_TIMEOUT_HOURS)+ values = {"decided_at": now, "restore_until": restore, "decision_key": decision_key}+ moved = await _move(database, row, ("pending",), "discarded", values, record)+ elif decision == "restore":+ restore = store.aware(row.restore_until)+ if row.status != "discarded" or restore is None or restore <= now:+ raise DecisionRefused("too_late", "It can no longer be restored.")+ moved = await _move(database, row, ("discarded",), "pending", {"restore_until": None, "decided_at": None}, record)+ else: # retry+ if kind != "tool_call" or row.status != "failed":+ raise DecisionRefused("invalid_request", "Only a send that failed can be tried again.")+ if row.outcome == "unknown" and not confirm:+ raise DecisionRefused("confirm_required", "It may have gone out already. Send it again anyway?")+ values = {+ "grace_until": now + timedelta(seconds=UNDO_SECONDS),+ "claim_token": None,+ "consumed_at": None,+ "outcome": None,+ "outcome_error": None,+ "outcome_at": None,+ "decided_at": now,+ "approved_by": "owner",+ }+ moved = await _move(database, row, ("failed",), "approved", values, record)+ return moved, False+++async def _move(database: Any, row: ApprovalRequest, from_statuses, status: str, values: Dict[str, Any], record) -> ApprovalRequest:+ try:+ return await store.transition(+ database, row.id, expected_revision=row.revision, from_statuses=from_statuses, status=status, values=values, decision=record+ )+ except store.ApprovalConflict:+ current = await store.get(database, row.id) or row+ found = await store.find_decision(database, row.id, record[1])+ if found is not None:+ # A concurrent request with the same key got there first.+ raise _Idempotent(current)+ if current.status == row.status:+ raise DecisionRefused("approval_conflict", "It changed meanwhile; look again.")+ raise _settled(current)+++class _Idempotent(Exception):+ def __init__(self, row: ApprovalRequest) -> None:+ super().__init__("idempotent")+ self.row = row+++async def apply(database: Any, row: ApprovalRequest, **kwargs: Any) -> Tuple[ApprovalRequest, bool]:+ """:func:`decide`, with a same-key race answered as a repeat."""+ try:+ return await decide(database, row, **kwargs)+ except _Idempotent as same:+ return same.row, True+++__all__ = ["DECISIONS", "DecisionRefused", "SETTLED_ERRORS", "apply", "decide"]diff --git a/server/services/approvals/events.py b/server/services/approvals/events.pynew file mode 100644index 00000000..8439c576--- /dev/null+++ b/server/services/approvals/events.py@@ -0,0 +1,45 @@+"""``approval_lifecycle``: something happened to a draft.++Type ``com.opencompany.approval.<stage>``: ``requested``, ``decided`` (sent+or discarded), ``undone``, ``restored``, ``sending``, ``sent``, ``failed``,+``expired``, ``cancelled``. Subject = the approval id. Identity only: never+the message, never who it goes to. The client refetches the drafts it shows+(``list_approvals`` / ``get_approvals``) through the authorized handlers.++Broadcast directly: no Temporal consumer listens for these.+"""++from __future__ import annotations++from services.approvals.listeners import ApprovalChange+from services.events.envelope import WorkflowEvent++WIRE_KEY = "approval_lifecycle"+SOURCE = "opencompany://services/approvals"+++def approval_lifecycle_event(change: ApprovalChange) -> WorkflowEvent:+ data = {+ "approval_id": change.approval_id,+ "workflow_id": change.workflow_id,+ "status": change.status,+ "revision": change.revision,+ }+ if change.run_id:+ data["run_id"] = change.run_id+ return WorkflowEvent(+ source=SOURCE,+ type=f"com.opencompany.approval.{change.stage}",+ subject=change.approval_id,+ data=data,+ )+++async def broadcast_approval_change(change: ApprovalChange) -> None:+ from services.status_broadcaster import get_status_broadcaster++ event = approval_lifecycle_event(change)+ await get_status_broadcaster().broadcast({"type": WIRE_KEY, "data": event.model_dump(mode="json", exclude_none=True)})+++__all__ = ["SOURCE", "WIRE_KEY", "approval_lifecycle_event", "broadcast_approval_change"]diff --git a/server/services/approvals/execution.py b/server/services/approvals/execution.pynew file mode 100644index 00000000..f69a5e72--- /dev/null+++ b/server/services/approvals/execution.py@@ -0,0 +1,237 @@+"""Sending a held tool call once the owner pressed Send.++``start_send(row)`` starts ``ApprovedToolCallWorkflow`` (services/temporal/+approved_tool_call_workflow.py) for the row's current revision. The workflow+sleeps until ``grace_until`` (Undo works until then), claims the row+(``approvals.claim_send``: approved -> sending, only at the revision it was+started for, so an Undo, a newer Send or a cancel ends it quietly), runs the+node's own activity (``node.<type>.v<n>``) once, with no retry, and records+how it went (``approvals.record_outcome``): sent, not sent, or ``unknown``+when the call broke off and may have gone out. The employee learns it at the+start of its next turn in the chat (an ``[update]`` note), the card through+``approval_lifecycle``.++The node runs with the call's arguments over its own settings, as the+employee made it (with the owner's edits); what it sends as (its locked+fields) comes from its settings. Its activity checks that the row it+carries is the one being sent (``tool_calls.check``).+"""++from __future__ import annotations++import json+from datetime import datetime, timezone+from typing import Any, Dict, Optional++from core.logging import get_logger+from services.approvals import store+from services.approvals.listeners import change_of, notify_approval_changed++logger = get_logger(__name__)++WORKFLOW_NAME = "ApprovedToolCallWorkflow"+PAYLOAD_VERSION = 1+++class SendUnavailable(RuntimeError):+ """The workflow engine is not there to send it."""+++def _utcnow() -> datetime:+ return datetime.now(timezone.utc)+++def send_workflow_id(row: Any) -> str:+ return f"approval-send-{row.id}-r{row.revision}"+++def send_payload(row: Any) -> Dict[str, Any]:+ grace = store.aware(row.grace_until)+ return {+ "payload_version": PAYLOAD_VERSION,+ "approval_id": row.id,+ "revision": row.revision,+ "grace_until": grace.isoformat() if grace is not None else None,+ }+++async def start_send(row: Any) -> None:+ """Start the workflow that sends ``row`` after its grace."""+ from core.container import container++ wrapper = container.temporal_client()+ if wrapper is None or getattr(wrapper, "client", None) is None:+ raise SendUnavailable("send_unavailable")+ await wrapper.client.start_workflow(+ WORKFLOW_NAME,+ args=[send_payload(row)],+ id=send_workflow_id(row),+ task_queue=container.settings().temporal_task_queue,+ )+++def node_activity_name(node_type: str) -> Optional[str]:+ from services.node_registry import get_node_class++ node_cls = get_node_class(node_type)+ if node_cls is None:+ return None+ return f"node.{node_cls.type}.v{getattr(node_cls, 'version', 1)}"+++def node_context(row: Any, token: str) -> Dict[str, Any]:+ """What the node's activity runs with."""+ return {+ "node_id": row.tool_node_id or row.node_id,+ "node_type": row.node_type,+ "node_data": dict(row.node_data or {}),+ "tool_args": dict(row.args or {}),+ "inputs": {},+ "nodes": [],+ "edges": [],+ "workflow_id": row.workflow_id,+ "session_id": row.workflow_id,+ "execution_id": row.execution_id,+ "generation": row.generation,+ "user_id": row.owner_id,+ "approval_execution": {"approval_id": row.id, "claim_token": token},+ }+++async def claim_send(database: Any, approval_id: str, revision: int, token: str) -> Dict[str, Any]:+ """Take the row on for sending: ``{claimed, reason?, activity?,+ context?}``. A retry with the same token finds its own claim."""+ row = await store.get(database, approval_id)+ if row is None:+ return {"claimed": False, "reason": "not_found"}+ if row.status == "sending" and row.claim_token == token:+ activity_name = node_activity_name(row.node_type or "")+ return {"claimed": True, "activity": activity_name, "context": node_context(row, token)}+ if (row.kind or "gate") != "tool_call" or row.status != "approved" or row.revision != revision:+ return {"claimed": False, "reason": "changed"}+ activity_name = node_activity_name(row.node_type or "")+ if activity_name is None:+ failed = await _fail_unclaimed(database, row, "The tool it uses is no longer installed.")+ return {"claimed": False, "reason": "unknown_tool", "status": getattr(failed, "status", None)}+ try:+ claimed = await store.transition(+ database,+ row.id,+ expected_revision=row.revision,+ from_statuses=("approved",),+ status="sending",+ values={"claim_token": token, "consumed_at": _utcnow()},+ )+ except store.ApprovalConflict:+ return {"claimed": False, "reason": "changed"}+ await notify_approval_changed(change_of(claimed, "sending"))+ return {"claimed": True, "activity": activity_name, "context": node_context(claimed, token)}+++async def _fail_unclaimed(database: Any, row: Any, error: str) -> Any:+ try:+ failed = await store.transition(+ database,+ row.id,+ expected_revision=row.revision,+ from_statuses=("approved",),+ status="failed",+ values={"outcome": "not_sent", "outcome_error": error[:1000], "outcome_at": _utcnow()},+ )+ except store.ApprovalConflict:+ return None+ await notify_approval_changed(change_of(failed, "failed"))+ await tell_employee(database, failed)+ return failed+++def outcome_of(result: Any, error: Optional[str]) -> Dict[str, Any]:+ """``{outcome, error?}`` from what the node's activity returned (or the+ error it broke off with)."""+ if error is not None:+ return {"outcome": "unknown", "error": error}+ if isinstance(result, dict) and result.get("success") is False:+ return {"outcome": "not_sent", "error": str(result.get("error") or "It did not go out.")}+ return {"outcome": "sent"}+++async def record_outcome(database: Any, approval_id: str, token: str, outcome: str, error: Optional[str]) -> Optional[Any]:+ """Record how the send went. None when the row is not this claim's."""+ row = await store.get(database, approval_id)+ if row is None or row.status != "sending" or row.claim_token != token:+ return None+ status = "sent" if outcome == "sent" else "failed"+ try:+ settled = await store.transition(+ database,+ row.id,+ expected_revision=row.revision,+ from_statuses=("sending",),+ status=status,+ values={+ "outcome": outcome,+ "outcome_error": (error or None) and str(error)[:1000],+ "outcome_at": _utcnow(),+ },+ )+ except store.ApprovalConflict:+ return None+ logger.info("Sent a held call" if status == "sent" else "A held call did not go out", approval_id=row.id, outcome=outcome)+ await notify_approval_changed(change_of(settled, status))+ await tell_employee(database, settled)+ return settled+++def update_note(row: Any) -> Optional[str]:+ """The ``[update]`` line the employee reads about one of its drafts."""+ result = {+ "sent": "sent",+ "failed": "not sent" if row.outcome == "not_sent" else "may or may not have gone out",+ "discarded": "discarded by the owner",+ "expired": "expired unsent",+ "cancelled": "cancelled unsent",+ }.get(row.status)+ if result is None:+ return None+ payload: Dict[str, Any] = {+ "approval_id": row.id,+ "what": row.action or f"{row.channel} message",+ "to": row.recipient_label or row.recipient or None,+ "result": result,+ }+ if row.edited and row.status == "sent":+ payload["edited_by_owner"] = True+ if row.status == "failed" and row.outcome_error:+ payload["error"] = row.outcome_error[:300]+ return f"[update]{json.dumps(payload, ensure_ascii=False, separators=(', ', ': '))}[/update]"+++async def tell_employee(database: Any, row: Any) -> None:+ """Leave the outcome for the employee's next turn in the chat (its+ session is the workflow's)."""+ text = update_note(row)+ if text is None or not row.workflow_id:+ return+ try:+ from services.chat.notes import upsert_note++ await upsert_note(database, session_id=row.workflow_id, key=f"approval:{row.id}", kind="update", text=text)+ except Exception: # noqa: BLE001 - the card shows it either way+ logger.warning("Could not leave the employee a note about a draft", approval_id=row.id, exc_info=True)+++__all__ = [+ "PAYLOAD_VERSION",+ "SendUnavailable",+ "WORKFLOW_NAME",+ "claim_send",+ "node_activity_name",+ "node_context",+ "outcome_of",+ "record_outcome",+ "send_payload",+ "send_workflow_id",+ "start_send",+ "tell_employee",+ "update_note",+]diff --git a/server/services/approvals/handlers.py b/server/services/approvals/handlers.pynew file mode 100644index 00000000..85775fb0--- /dev/null+++ b/server/services/approvals/handlers.py@@ -0,0 +1,309 @@+"""The owner's side of approvals: see drafts, decide them, and the Ask first+rule (docs-internal/chat_protocol.md, "Approvals").++``list_approvals {workflow_id?, status?, run_id?, kind?, limit <= 100}`` ->+``{approvals: ApprovalSummary[], counts: {workflow_id: pending}, server_time}``.+``status`` is a row status, ``open`` (what the owner may still act on, or is+on its way) or ``recent`` (everything, newest first); default ``pending``.++``get_approvals {approval_ids: [...]}`` -> ``{approvals, server_time}``.++``decide_approval {approval_id, decision, decision_key, text?, subject?,+confirm?}`` -> ``{approval, idempotent?, will_send_on_resume}``. Decisions:+``send``, ``undo``, ``discard``, ``restore``, ``retry``+(services/approvals/decisions.py). Sending a held tool call starts its send+(services/approvals/execution.py). Errors: ``already_decided``,+``expired``, ``cancelled``, ``too_late``, ``confirm_required``,+``approval_conflict``, ``send_unavailable``, ``not_found``,+``invalid_request``.++``get_ask_first {workflow_id}`` -> ``{ask_first, revision}`` (``ask_first``+is null for a workflow with no rule). ``set_ask_first {workflow_id,+ask_first, expected_revision?}`` -> ``{ask_first, revision, replies_gated,+needs_apply}``; ``rule_conflict`` when it moved.++Only the owner's own drafts and workflows are visible; any other id reads as+not found.+"""++from __future__ import annotations++from datetime import datetime, timezone+from typing import Any, Dict, List++from fastapi import WebSocket++from core.logging import get_logger+from services.approvals import decisions, execution, rules, store, waiter+from services.approvals.listeners import change_of, notify_approval_changed+from services.approvals.reconcile import reconcile_once+from services.authz.ws_surface import execution_principal+from services.plugin.ws import ws_response++logger = get_logger(__name__)++MAX_LIST = 100+_ROW_STATUSES = ("pending", "approved", "sending", "sent", "failed", "discarded", "expired", "cancelled")+#: The lifecycle stage each decision announces.+_STAGES = {"send": "decided", "discard": "decided", "undo": "undone", "restore": "restored", "retry": "decided"}+++def _now() -> str:+ return datetime.now(timezone.utc).isoformat()+++async def _deployment_state(database: Any, workflow_id: str) -> str | None:+ try:+ control = await database.get_latest_workflow_control(workflow_id)+ except Exception:+ return None+ return getattr(control, "status", None)+++async def _summaries(database: Any, rows: List[Any]) -> List[Dict[str, Any]]:+ states: Dict[str, Any] = {}+ out = []+ for row in rows:+ if row.workflow_id not in states:+ states[row.workflow_id] = await _deployment_state(database, row.workflow_id)+ out.append(store.summary(row, deployment_state=states[row.workflow_id]))+ return out+++def _limit(data: Dict[str, Any]) -> int:+ try:+ return max(1, min(int(data.get("limit") or 50), MAX_LIST))+ except (TypeError, ValueError):+ return 50+++@ws_response+async def handle_list_approvals(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:+ from core.container import container++ database = container.database()+ await reconcile_once(database)+ owner = execution_principal(data, websocket)+ workflow_id = str(data.get("workflow_id") or "").strip() or None+ run_id = str(data.get("run_id") or "").strip() or None+ kind = data.get("kind") if data.get("kind") in ("gate", "tool_call") else None+ status = data.get("status")+ limit = _limit(data)+ if status == "open":+ rows = await store.list_open(database, owner_id=owner, workflow_id=workflow_id, limit=limit)+ rows = [row for row in rows if (run_id is None or row.run_id == run_id) and (kind is None or (row.kind or "gate") == kind)]+ else:+ filters: Dict[str, Any] = {}+ if status in _ROW_STATUSES:+ filters["status"] = status+ elif status != "recent":+ filters["status"] = "pending"+ rows = await store.list_approvals(database, owner_id=owner, workflow_id=workflow_id, run_id=run_id, kind=kind, limit=limit, **filters)+ counts: Dict[str, int] = {}+ for row in rows:+ if row.status == "pending":+ counts[row.workflow_id] = counts.get(row.workflow_id, 0) + 1+ return {"success": True, "approvals": await _summaries(database, rows), "counts": counts, "server_time": _now()}+++@ws_response+async def handle_get_approvals(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:+ from core.container import container++ ids = data.get("approval_ids")+ if not isinstance(ids, list) or not ids or len(ids) > MAX_LIST:+ return {"success": False, "error": "invalid_request"}+ database = container.database()+ owner = execution_principal(data, websocket)+ rows = await store.list_approvals(database, owner_id=owner, ids=[str(item) for item in ids], limit=MAX_LIST)+ return {"success": True, "approvals": await _summaries(database, rows), "server_time": _now()}+++_RESTORED_FIELDS = (+ "grace_until",+ "decided_at",+ "approved_by",+ "final_text",+ "final_subject",+ "edited",+ "args",+ "node_data",+ "claim_token",+ "consumed_at",+ "outcome",+ "outcome_error",+ "outcome_at",+)+++async def _start_or_revert(database: Any, row: Any, original: Any) -> Any:+ """Start a held call's send; put the row back as it was when nothing+ can send it."""+ try:+ await execution.start_send(row)+ return row+ except Exception as exc:+ logger.warning("Could not start a send", approval_id=row.id, error=str(exc))+ try:+ reverted = await store.transition(+ database,+ row.id,+ expected_revision=row.revision,+ from_statuses=("approved",),+ status=original.status,+ values={name: getattr(original, name) for name in _RESTORED_FIELDS},+ )+ await notify_approval_changed(change_of(reverted, "undone"))+ except store.ApprovalConflict:+ pass+ raise execution.SendUnavailable("send_unavailable") from exc+++@ws_response+async def handle_decide_approval(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:+ from core.container import container++ approval_id = str(data.get("approval_id") or "").strip()+ decision = data.get("decision")+ decision_key = str(data.get("decision_key") or "").strip()[:128]+ if not approval_id or decision not in decisions.DECISIONS or not decision_key:+ return {"success": False, "error": "invalid_request"}+ database = container.database()+ owner = execution_principal(data, websocket)+ row = await store.get(database, approval_id)+ if row is None or row.owner_id != owner:+ return {"success": False, "error": "not_found", "approval_id": approval_id}+ try:+ decided, idempotent = await decisions.apply(+ database,+ row,+ decision=decision,+ decision_key=decision_key,+ actor=owner,+ text=data.get("text"),+ subject=data.get("subject"),+ confirm=bool(data.get("confirm")),+ )+ except decisions.DecisionRefused as refused:+ current = await store.get(database, approval_id) or row+ out: Dict[str, Any] = {"success": False, "error": refused.code, "approval": store.summary(current)}+ if refused.detail:+ out["detail"] = refused.detail+ return out+ if idempotent:+ return {"success": True, "idempotent": True, "approval": store.summary(decided), "will_send_on_resume": False}+ waiter.notify(decided.id)+ await notify_approval_changed(change_of(decided, _STAGES.get(decision, "decided")))+ if decided.status == "discarded":+ await execution.tell_employee(database, decided)+ if (decided.kind or "gate") == "tool_call" and decision in ("send", "retry"):+ try:+ decided = await _start_or_revert(database, decided, row)+ except execution.SendUnavailable:+ current = await store.get(database, approval_id) or decided+ return {+ "success": False,+ "error": "send_unavailable",+ "detail": "Nothing can send it right now. Try again in a moment.",+ "approval": store.summary(current),+ }+ state = await _deployment_state(database, decided.workflow_id)+ logger.info("Draft decided", approval_id=decided.id, workflow_id=decided.workflow_id, decision=decision, status=decided.status)+ return {+ "success": True,+ "approval": store.summary(decided, deployment_state=state),+ # A paused employee's run holds the approved draft until Resume.+ "will_send_on_resume": (decided.kind or "gate") == "gate" and decided.status == "approved" and state in ("paused", "pausing"),+ }+++async def _authorize_workflow(database: Any, websocket: Any, workflow_id: str) -> bool:+ from services.chat.access import ChatAccessDenied, authorize_session++ try:+ await authorize_session(database, websocket, workflow_id)+ except ChatAccessDenied:+ return False+ return True+++@ws_response+async def handle_get_ask_first(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:+ from core.container import container++ workflow_id = str(data.get("workflow_id") or "").strip()+ if not workflow_id:+ return {"success": False, "error": "invalid_request"}+ database = container.database()+ if not await _authorize_workflow(database, websocket, workflow_id):+ return {"success": False, "error": "not_found"}+ rule = await rules.get_rule(database, workflow_id)+ return {+ "success": True,+ "workflow_id": workflow_id,+ "ask_first": None if rule is None else bool(rule.ask_first),+ "revision": 0 if rule is None else rule.revision,+ }+++@ws_response+async def handle_set_ask_first(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:+ from core.container import container++ workflow_id = str(data.get("workflow_id") or "").strip()+ value = data.get("ask_first")+ if not workflow_id or not isinstance(value, bool):+ return {"success": False, "error": "invalid_request"}+ expected = data.get("expected_revision")+ if expected is not None and not isinstance(expected, int):+ return {"success": False, "error": "invalid_request"}+ database = container.database()+ if not await _authorize_workflow(database, websocket, workflow_id):+ return {"success": False, "error": "not_found"}+ try:+ rule = await rules.set_ask_first(database, workflow_id, value, expected_revision=expected)+ except rules.RuleConflict as conflict:+ current = conflict.rule+ return {+ "success": False,+ "error": "rule_conflict",+ "ask_first": None if current is None else bool(current.ask_first),+ "revision": 0 if current is None else current.revision,+ }+ effects = await rules.notify_rule_changed(database, workflow_id, rule)+ logger.info("Ask first changed", workflow_id=workflow_id, ask_first=rule.ask_first)+ return {+ "success": True,+ "workflow_id": workflow_id,+ "ask_first": bool(rule.ask_first),+ "revision": rule.revision,+ "replies_gated": bool(effects.get("replies_gated", False)),+ "needs_apply": bool(effects.get("needs_apply", False)),+ }+++async def on_workflow_deleted(database: Any, workflow_id: str) -> None:+ removed = await store.delete_for_workflow(database, workflow_id)+ await rules.delete_rule(database, workflow_id)+ if removed:+ logger.info("Removed a deleted workflow's drafts", workflow_id=workflow_id, count=removed)+++WS_HANDLERS: Dict[str, Any] = {+ "list_approvals": handle_list_approvals,+ "get_approvals": handle_get_approvals,+ "decide_approval": handle_decide_approval,+ "get_ask_first": handle_get_ask_first,+ "set_ask_first": handle_set_ask_first,+}+++__all__ = [+ "WS_HANDLERS",+ "handle_decide_approval",+ "handle_get_approvals",+ "handle_get_ask_first",+ "handle_list_approvals",+ "handle_set_ask_first",+ "on_workflow_deleted",+]diff --git a/server/services/approvals/listeners.py b/server/services/approvals/listeners.pyindex c44b7968..15bfffb1 100644--- a/server/services/approvals/listeners.py+++ b/server/services/approvals/listeners.py@@ -1,15 +1,16 @@"""Who hears about approval changes, without this package knowing them.-The approval-gate plugin registers the ``approval_lifecycle`` broadcast;-the employees package registers the summary refresh (its pending count).-A failing listener is logged and never fails the change.+This package registers the ``approval_lifecycle`` broadcast+(``services/approvals/__init__.py``); the employees package registers the+summary refresh (its pending count). A failing listener is logged and never+fails the change."""from __future__ import annotationsimport inspectfrom dataclasses import dataclass-from typing import Any, Callable, List+from typing import Any, Callable, List, Optionalfrom core.logging import get_logger@@ -18,12 +19,15 @@ logger = get_logger(__name__)@dataclass(frozen=True)class ApprovalChange:- #: requested | decided | expired | cancelled+ #: requested | decided | undone | restored | sending | sent | failed |+ #: expired | cancelledstage: strapproval_id: strworkflow_id: strstatus: strrevision: int+ #: The chat run a held tool call was made in.+ run_id: Optional[str] = NoneApprovalListener = Callable[[ApprovalChange], Any]@@ -46,7 +50,14 @@ async def notify_approval_changed(change: ApprovalChange) -> None:def change_of(row: Any, stage: str) -> ApprovalChange:- return ApprovalChange(stage=stage, approval_id=row.id, workflow_id=row.workflow_id, status=row.status, revision=row.revision)+ return ApprovalChange(+ stage=stage,+ approval_id=row.id,+ workflow_id=row.workflow_id,+ status=row.status,+ revision=row.revision,+ run_id=getattr(row, "run_id", None) or None,+ )__all__ = ["ApprovalChange", "change_of", "notify_approval_changed", "register_approval_listener"]diff --git a/server/services/approvals/reconcile.py b/server/services/approvals/reconcile.pyindex 43bff16e..0cf29a60 100644--- a/server/services/approvals/reconcile.py+++ b/server/services/approvals/reconcile.py@@ -1,20 +1,29 @@-"""Cancel drafts nothing is waiting for any more.+"""End what nothing waits for any more, and finish sends nothing finished.-A pending row outlives its wait when:+A gate's pending row outlives its wait when:- it came from an in-process run (``runtime == "local"``) and the processthat ran it has since stopped: in-process runs are not resumed;- its generation was reset or failed: the run it belonged to is over.Temporal waits survive restarts (the activity retries and finds its row),-so a Temporal row is kept while its generation is live. Runs once per-process, the first time the drafts are listed; local rows created by this-process are never touched.+so a Temporal gate row is kept while its generation is live. A held tool+call waits on nothing (its run already went on), so only expiry or a cancel+ends it.++Sends: an approved held call whose send never started (the server stopped+between the decision and the workflow) is started again; the claim at its+revision makes a second start harmless. A send claimed long ago that never+reported broke off somewhere: it ends ``failed`` with an unknown outcome,+since it may have gone out.++Runs once per process, the first time the drafts are listed; local rows+created by this process are never touched."""from __future__ import annotations-from datetime import datetime, timezone+from datetime import datetime, timedelta, timezonefrom typing import Any, Listfrom core.logging import get_logger@@ -25,6 +34,10 @@ logger = get_logger(__name__)PROCESS_STARTED = datetime.now(timezone.utc)_LIVE_STATUSES = frozenset({"starting", "running", "pausing", "paused", "resuming"})+#: How long after its grace an approved send may still be on its way.+_START_GRACE = timedelta(seconds=60)+#: How long a claimed send may run before it counts as broken off.+_SEND_DEADLINE = timedelta(minutes=30)_done = False@@ -35,6 +48,8 @@ def _aware(moment: datetime) -> datetime:async def cancel_orphaned_pending(database: Any, *, started_at: datetime = PROCESS_STARTED) -> List[str]:cancelled: List[str] = []for row in await store.list_pending(database):+ if (row.kind or "gate") != "gate":+ continueorphaned = Falseif row.runtime == "local":orphaned = _aware(row.created_at) < started_at@@ -54,6 +69,43 @@ async def cancel_orphaned_pending(database: Any, *, started_at: datetime = PROCEreturn cancelled+async def recover_sends(database: Any, *, now: datetime | None = None) -> List[str]:+ """Restart sends that never started; end sends that never reported."""+ from services.approvals import execution++ now = now or datetime.now(timezone.utc)+ touched: List[str] = []+ for row in await store.list_unfinished_sends(database):+ if row.status == "approved" and row.consumed_at is None:+ grace = store.aware(row.grace_until)+ if grace is None or now - grace < _START_GRACE:+ continue+ try:+ await execution.start_send(row)+ touched.append(row.id)+ except Exception:+ logger.warning("Could not restart a send", approval_id=row.id, exc_info=True)+ elif row.status == "sending":+ claimed = store.aware(row.consumed_at) or store.aware(row.updated_at)+ if claimed is None or now - claimed < _SEND_DEADLINE:+ continue+ try:+ failed = await store.transition(+ database,+ row.id,+ expected_revision=row.revision,+ from_statuses=("sending",),+ status="failed",+ values={"outcome": "unknown", "outcome_error": "The send never reported back.", "outcome_at": now},+ )+ except store.ApprovalConflict:+ continue+ touched.append(failed.id)+ await notify_approval_changed(change_of(failed, "failed"))+ await execution.tell_employee(database, failed)+ return touched++async def reconcile_once(database: Any) -> None:global _doneif _done:@@ -61,6 +113,7 @@ async def reconcile_once(database: Any) -> None:_done = Truetry:await cancel_orphaned_pending(database)+ await recover_sends(database)except Exception:_done = Falselogger.warning("Could not reconcile waiting drafts", exc_info=True)@@ -71,4 +124,4 @@ def reset_for_tests() -> None:_done = False-__all__ = ["PROCESS_STARTED", "cancel_orphaned_pending", "reconcile_once"]+__all__ = ["PROCESS_STARTED", "cancel_orphaned_pending", "reconcile_once", "recover_sends"]diff --git a/server/services/approvals/rules.py b/server/services/approvals/rules.pynew file mode 100644index 00000000..e86a74ed--- /dev/null+++ b/server/services/approvals/rules.py@@ -0,0 +1,166 @@+"""A workflow's Ask first rule (``workflow_rules``), read when something would+send.++One row per workflow. An employee's row is seeded from its ground rules the+first time anything asks (``register_rule_seeder``: the employees package+registers how; this package never imports it), and the chat's Ask first chip+changes it (``set_ask_first``, a compare-and-swap on ``revision``), with no+restart: approval gates and held tool calls read it each time.++A workflow with no row and no seed (one built in the editor) has no rule:+its tool calls are never held, and its approval gates wait for the owner as+they always did.+"""++from __future__ import annotations++import inspect+from datetime import datetime, timezone+from typing import Any, Awaitable, Callable, Dict, List, Optional, Union++from sqlalchemy import update+from sqlalchemy.exc import IntegrityError++from core.logging import get_logger+from models.approvals import WorkflowRule++logger = get_logger(__name__)++#: ``seed(database, workflow_id)`` -> the workflow's Ask first value when it+#: has a default (an employee's ground rules), else None.+RuleSeeder = Callable[[Any, str], Union[Optional[bool], Awaitable[Optional[bool]]]]+_SEEDERS: List[RuleSeeder] = []+#: ``listener(database, workflow_id, rule)``, told when the owner changes a+#: rule; it may answer what the change means for the workflow+#: (``{replies_gated, needs_apply}``).+RuleListener = Callable[[Any, str, Any], Union[Optional[Dict[str, Any]], Awaitable[Optional[Dict[str, Any]]]]]+_LISTENERS: List[RuleListener] = []+++class RuleConflict(ValueError):+ """The rule changed since the caller read it."""++ def __init__(self, rule: Optional[WorkflowRule]) -> None:+ super().__init__("rule_conflict")+ self.rule = rule+++def _utcnow() -> datetime:+ return datetime.now(timezone.utc)+++def register_rule_seeder(seeder: RuleSeeder) -> None:+ if seeder not in _SEEDERS:+ _SEEDERS.append(seeder)+++def register_rule_listener(listener: RuleListener) -> None:+ if listener not in _LISTENERS:+ _LISTENERS.append(listener)+++async def notify_rule_changed(database: Any, workflow_id: str, rule: Any) -> Dict[str, Any]:+ """Tell the listeners; returns what they answered, merged. A failing+ listener is logged and never undoes the change."""+ effects: Dict[str, Any] = {}+ for listener in list(_LISTENERS):+ try:+ answer = listener(database, workflow_id, rule)+ if inspect.isawaitable(answer):+ answer = await answer+ except Exception:+ logger.warning("Ask first listener failed", workflow_id=workflow_id, exc_info=True)+ continue+ if isinstance(answer, dict):+ effects.update(answer)+ return effects+++async def get_rule(database: Any, workflow_id: str) -> Optional[WorkflowRule]:+ """The workflow's rule row, seeding it when it has a default."""+ if not workflow_id:+ return None+ async with database.get_session() as session:+ rule = await session.get(WorkflowRule, workflow_id)+ if rule is not None:+ return rule+ for seeder in list(_SEEDERS):+ try:+ value = seeder(database, workflow_id)+ if inspect.isawaitable(value):+ value = await value+ except Exception:+ logger.warning("Could not read a workflow's default Ask first rule", workflow_id=workflow_id, exc_info=True)+ continue+ if value is None:+ continue+ return await _insert(database, workflow_id, bool(value), source="hire")+ return None+++async def ask_first(database: Any, workflow_id: Optional[str]) -> Optional[bool]:+ """Whether the workflow asks before sending: True, False, or None when+ it has no rule."""+ rule = await get_rule(database, workflow_id or "")+ return None if rule is None else bool(rule.ask_first)+++async def _insert(database: Any, workflow_id: str, value: bool, *, source: str) -> WorkflowRule:+ row = WorkflowRule(workflow_id=workflow_id, ask_first=value, revision=0, source=source, updated_at=_utcnow())+ try:+ async with database.get_session() as session:+ session.add(row)+ await session.commit()+ return row+ except IntegrityError:+ async with database.get_session() as session:+ existing = await session.get(WorkflowRule, workflow_id)+ if existing is None:+ raise+ return existing+++async def set_ask_first(database: Any, workflow_id: str, value: bool, *, expected_revision: Optional[int] = None) -> WorkflowRule:+ """Change the rule. ``expected_revision`` (the revision the caller read)+ makes it a compare-and-swap; :class:`RuleConflict` when it moved."""+ current = await get_rule(database, workflow_id)+ if current is None:+ if expected_revision not in (None, 0):+ raise RuleConflict(None)+ return await _insert(database, workflow_id, bool(value), source="owner")+ if expected_revision is not None and current.revision != expected_revision:+ raise RuleConflict(current)+ async with database.get_session() as session:+ result = await session.execute(+ update(WorkflowRule)+ .where(WorkflowRule.workflow_id == workflow_id, WorkflowRule.revision == current.revision)+ .values(ask_first=bool(value), revision=current.revision + 1, source="owner", updated_at=_utcnow())+ )+ await session.commit()+ if not result.rowcount:+ async with database.get_session() as again:+ raise RuleConflict(await again.get(WorkflowRule, workflow_id))+ async with database.get_session() as session:+ updated = await session.get(WorkflowRule, workflow_id)+ assert updated is not None+ return updated+++async def delete_rule(database: Any, workflow_id: str) -> None:+ from sqlalchemy import delete++ async with database.get_session() as session:+ await session.execute(delete(WorkflowRule).where(WorkflowRule.workflow_id == workflow_id))+ await session.commit()+++__all__ = [+ "RuleConflict",+ "ask_first",+ "delete_rule",+ "get_rule",+ "notify_rule_changed",+ "register_rule_listener",+ "register_rule_seeder",+ "set_ask_first",+]diff --git a/server/services/approvals/store.py b/server/services/approvals/store.pyindex 6e38c38a..a2ac8137 100644--- a/server/services/approvals/store.py+++ b/server/services/approvals/store.py@@ -1,5 +1,5 @@-"""Approval rows (models.approvals.ApprovalRequest): create once per wait,-read, move with a compare-and-swap, cancel, count, delete.+"""Approval rows (models.approvals.ApprovalRequest): create once per wait or+held call, read, move with a compare-and-swap, cancel, count, delete.Functions take the ``Database`` and open their own session, likeservices.employees.store. They never import ``nodes/``.@@ -9,16 +9,16 @@ from __future__ import annotationsimport uuidfrom datetime import datetime, timezone-from typing import Any, Dict, Iterable, List, Optional, Tuple+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple-from sqlalchemy import delete, func, update+from sqlalchemy import delete, func, or_, updatefrom sqlalchemy.exc import IntegrityErrorfrom sqlmodel import select-from models.approvals import ApprovalRequest+from models.approvals import ApprovalDecision, ApprovalRequestfrom services.approvals.contract import FINAL_STATUSES-#: Fields a gate may set when it creates its row.+#: Fields a row may be created with.CREATE_FIELDS = frozenset({"owner_id",@@ -27,17 +27,43 @@ CREATE_FIELDS = frozenset("generation","execution_id","runtime",+ "kind",+ "status","channel",+ "action","recipient","recipient_label","subject","draft_text",+ "final_text",+ "final_subject","context_excerpt","max_length",+ "details","expires_at",+ "node_type",+ "tool_node_id",+ "tool_call_id",+ "agent_node_id",+ "run_id",+ "ui_part_id",+ "node_data",+ "args",+ "original_args",+ "body_field",+ "subject_field",+ "approved_by",+ "decided_at",+ "consumed_at",+ "outcome",+ "outcome_error",+ "outcome_at",})+#: Rows the owner may still act on, or that are on their way.+_OPEN_CANDIDATES = ("pending", "approved", "sending", "failed", "discarded")+class ApprovalConflict(ValueError):"""The row moved first (someone else decided, or it expired)."""@@ -47,6 +73,12 @@ def _utcnow() -> datetime:return datetime.now(timezone.utc)+def aware(moment: Optional[datetime]) -> Optional[datetime]:+ if moment is None:+ return None+ return moment if moment.tzinfo else moment.replace(tzinfo=timezone.utc)++async def get(database: Any, approval_id: str) -> Optional[ApprovalRequest]:async with database.get_session() as session:return await session.get(ApprovalRequest, approval_id)@@ -59,14 +91,16 @@ async def get_by_key(database: Any, idempotency_key: str) -> Optional[ApprovalReasync def get_or_create(database: Any, *, idempotency_key: str, fields: Dict[str, Any]) -> Tuple[ApprovalRequest, bool]:- """The wait's row: created the first time, found on every retry."""+ """The wait's (or the held call's) row: created the first time, found on+ every retry."""unknown = set(fields) - CREATE_FIELDSif unknown:raise ValueError(f"not approval fields: {sorted(unknown)}")existing = await get_by_key(database, idempotency_key)if existing is not None:return existing, False- row = ApprovalRequest(id=uuid.uuid4().hex, idempotency_key=idempotency_key, status="pending", **fields)+ values = {"status": "pending", **fields}+ row = ApprovalRequest(id=uuid.uuid4().hex, idempotency_key=idempotency_key, **values)try:async with database.get_session() as session:session.add(row)@@ -79,59 +113,158 @@ async def get_or_create(database: Any, *, idempotency_key: str, fields: Dict[strreturn existing, False-async def settle(+async def transition(database: Any,approval_id: str,*,expected_revision: int,+ from_statuses: Sequence[str],status: str,values: Optional[Dict[str, Any]] = None,+ decision: Optional[Tuple[str, str, str]] = None,) -> ApprovalRequest:- """Move a pending row to a final status, if nobody moved it first."""- if status not in FINAL_STATUSES:- raise ValueError(f"not a final approval status: {status}")+ """Move a row that is in one of ``from_statuses`` at ``expected_revision``+ to ``status``, if nobody moved it first. ``decision`` (``(decision,+ decision_key, actor)``) is recorded in the same transaction, so a+ decision is kept exactly when it took effect."""now = _utcnow()- changes = {"status": status, "revision": expected_revision + 1, "updated_at": now, "decided_at": now, **(values or {})}+ changes = {"status": status, "revision": expected_revision + 1, "updated_at": now, **(values or {})}async with database.get_session() as session:result = await session.execute(update(ApprovalRequest).where(ApprovalRequest.id == approval_id,ApprovalRequest.revision == expected_revision,- ApprovalRequest.status == "pending",+ ApprovalRequest.status.in_(tuple(from_statuses)),).values(**changes))- await session.commit()if not result.rowcount:+ await session.rollback()+ raise ApprovalConflict("approval_conflict")+ if decision is not None:+ kind, key, actor = decision+ session.add(ApprovalDecision(approval_id=approval_id, decision=kind, decision_key=key, actor=actor, revision=expected_revision + 1))+ try:+ await session.commit()+ except IntegrityError:+ # The same decision key, recorded by a concurrent request first.+ await session.rollback()raise ApprovalConflict("approval_conflict")row = await get(database, approval_id)assert row is not Nonereturn row-async def cancel_pending(database: Any, *, workflow_id: str, generation: Optional[int] = None) -> List[ApprovalRequest]:- """Cancel a workflow's waiting drafts (all generations, or one)."""+async def settle(+ database: Any,+ approval_id: str,+ *,+ expected_revision: int,+ status: str,+ values: Optional[Dict[str, Any]] = None,+) -> ApprovalRequest:+ """Move a pending row to a final status (expired, cancelled), if nobody+ moved it first."""+ if status not in FINAL_STATUSES:+ raise ValueError(f"not a final approval status: {status}")+ return await transition(+ database,+ approval_id,+ expected_revision=expected_revision,+ from_statuses=("pending",),+ status=status,+ values={"decided_at": _utcnow(), **(values or {})},+ )+++async def find_decision(database: Any, approval_id: str, decision_key: str) -> Optional[ApprovalDecision]:+ async with database.get_session() as session:+ result = await session.execute(+ select(ApprovalDecision).where(ApprovalDecision.approval_id == approval_id, ApprovalDecision.decision_key == decision_key)+ )+ return result.scalar_one_or_none()+++def is_open(row: ApprovalRequest, now: Optional[datetime] = None) -> bool:+ """Still the owner's to act on, or on its way: waiting, sent but+ undoable, sending, failed (to retry), or discarded and restorable."""+ now = now or _utcnow()+ if row.status in ("pending", "sending", "failed"):+ return True+ if row.status == "approved":+ return row.consumed_at is None+ if row.status == "discarded":+ restore = aware(row.restore_until)+ return restore is not None and restore > now+ return False+++def cancellable(row: ApprovalRequest, now: Optional[datetime] = None) -> bool:+ """What a Reset, a branch or a deleted run cancels: everything open+ except a send already under way and a failure (nothing left to stop)."""+ return row.status not in ("sending", "failed") and is_open(row, now)+++async def cancel_open(+ database: Any,+ *,+ workflow_id: str,+ generation: Optional[int] = None,+ run_ids: Optional[Iterable[str]] = None,+) -> List[ApprovalRequest]:+ """Cancel a workflow's drafts that still wait (all generations, one, or+ those of some chat runs): waiting, approved but not handed on yet, or+ discarded and restorable."""async with database.get_session() as session:- query = select(ApprovalRequest).where(ApprovalRequest.workflow_id == workflow_id, ApprovalRequest.status == "pending")+ query = select(ApprovalRequest).where(+ ApprovalRequest.workflow_id == workflow_id,+ ApprovalRequest.status.in_(("pending", "approved", "discarded")),+ )if generation is not None:query = query.where(ApprovalRequest.generation == generation)+ if run_ids is not None:+ ids = [run_id for run_id in run_ids if run_id]+ if not ids:+ return []+ query = query.where(ApprovalRequest.run_id.in_(ids))rows = list((await session.execute(query)).scalars().all())+ now = _utcnow()cancelled: List[ApprovalRequest] = []for row in rows:+ if not cancellable(row, now):+ continuetry:- cancelled.append(await settle(database, row.id, expected_revision=row.revision, status="cancelled"))+ cancelled.append(+ await transition(+ database,+ row.id,+ expected_revision=row.revision,+ from_statuses=(row.status,),+ status="cancelled",+ values={"decided_at": now, "grace_until": None, "restore_until": None},+ )+ )except ApprovalConflict:continuereturn cancelled+async def cancel_pending(database: Any, *, workflow_id: str, generation: Optional[int] = None) -> List[ApprovalRequest]:+ """Older name for :func:`cancel_open`."""+ return await cancel_open(database, workflow_id=workflow_id, generation=generation)++async def list_approvals(database: Any,*,owner_id: Optional[str] = None,workflow_id: Optional[str] = None,status: Optional[str] = None,+ statuses: Optional[Sequence[str]] = None,+ run_id: Optional[str] = None,+ kind: Optional[str] = None,+ ids: Optional[Sequence[str]] = None,limit: int = 50,) -> List[ApprovalRequest]:"""Newest first."""@@ -142,12 +275,28 @@ async def list_approvals(query = query.where(ApprovalRequest.workflow_id == workflow_id)if status is not None:query = query.where(ApprovalRequest.status == status)+ if statuses is not None:+ query = query.where(ApprovalRequest.status.in_(tuple(statuses)))+ if run_id is not None:+ query = query.where(ApprovalRequest.run_id == run_id)+ if kind is not None:+ query = query.where(or_(ApprovalRequest.kind == kind, ApprovalRequest.kind.is_(None)) if kind == "gate" else ApprovalRequest.kind == kind)+ if ids is not None:+ query = query.where(ApprovalRequest.id.in_(tuple(ids)))query = query.order_by(ApprovalRequest.created_at.desc()).limit(max(1, min(int(limit), 100)))async with database.get_session() as session:return list((await session.execute(query)).scalars().all())+async def list_open(database: Any, *, owner_id: Optional[str] = None, workflow_id: Optional[str] = None, limit: int = 50) -> List[ApprovalRequest]:+ """What the owner may still act on (``is_open``), newest first."""+ rows = await list_approvals(database, owner_id=owner_id, workflow_id=workflow_id, statuses=_OPEN_CANDIDATES, limit=100)+ now = _utcnow()+ return [row for row in rows if is_open(row, now)][: max(1, min(int(limit), 100))]++async def pending_counts(database: Any, workflow_ids: Iterable[str]) -> Dict[str, int]:+ """Drafts waiting for the owner, per workflow."""ids = [str(workflow_id) for workflow_id in workflow_ids if workflow_id]if not ids:return {}@@ -166,26 +315,40 @@ async def list_pending(database: Any) -> List[ApprovalRequest]:return list(result.scalars().all())+async def list_unfinished_sends(database: Any) -> List[ApprovalRequest]:+ """Approved held calls not handed on, and sends that never reported."""+ async with database.get_session() as session:+ result = await session.execute(+ select(ApprovalRequest).where(ApprovalRequest.kind == "tool_call", ApprovalRequest.status.in_(("approved", "sending")))+ )+ return list(result.scalars().all())++async def delete_for_workflow(database: Any, workflow_id: str) -> int:async with database.get_session() as session:+ ids = select(ApprovalRequest.id).where(ApprovalRequest.workflow_id == workflow_id)+ await session.execute(delete(ApprovalDecision).where(ApprovalDecision.approval_id.in_(ids)))result = await session.execute(delete(ApprovalRequest).where(ApprovalRequest.workflow_id == workflow_id))await session.commit()return int(result.rowcount or 0)def _iso(moment: Optional[datetime]) -> Optional[str]:- if moment is None:- return None- return (moment if moment.tzinfo else moment.replace(tzinfo=timezone.utc)).isoformat()+ moment = aware(moment)+ return moment.isoformat() if moment is not None else None-def summary(row: ApprovalRequest, *, deployment_state: Optional[str] = None) -> Dict[str, Any]:- """What the employee card shows for one draft (``ApprovalSummary``)."""- decided = row.status == "approved"+def summary(row: ApprovalRequest, *, deployment_state: Optional[str] = None, now: Optional[datetime] = None) -> Dict[str, Any]:+ """What a card shows for one row (``ApprovalSummary``,+ docs-internal/chat_protocol.md)."""+ now = now or _utcnow()+ decided = row.status in ("approved", "sending", "sent", "failed")+ kind = row.kind or "gate"out: Dict[str, Any] = {"approval_id": row.id,"workflow_id": row.workflow_id,"node_id": row.node_id,+ "kind": kind,"status": row.status,"channel": row.channel,"channel_label": row.channel,@@ -196,12 +359,39 @@ def summary(row: ApprovalRequest, *, deployment_state: Optional[str] = None) ->"expires_at": _iso(row.expires_at),"revision": row.revision,"max_length": row.max_length,+ "editable": row.status == "pending" and (kind == "gate" or bool(row.body_field)),+ "details": [dict(item) for item in (row.details or []) if isinstance(item, dict)],}+ if row.action:+ out["action"] = row.actionsubject = row.final_subject if decided and row.final_subject else row.subjectif subject:out["subject"] = subjectif row.context_excerpt:out["context_excerpt"] = row.context_excerpt+ if row.approved_by:+ out["approved_by"] = row.approved_by+ if row.edited:+ out["edited"] = True+ grace = aware(row.grace_until)+ if row.status == "approved" and row.consumed_at is None and grace is not None:+ out["undo_until"] = grace.isoformat()+ restore = aware(row.restore_until)+ if row.status == "discarded" and restore is not None and restore > now:+ out["restore_until"] = restore.isoformat()+ if row.consumed_at is not None:+ out["consumed_at"] = _iso(row.consumed_at)+ if row.outcome:+ outcome: Dict[str, Any] = {"certainty": row.outcome}+ if row.outcome_error:+ outcome["error"] = row.outcome_error+ if row.outcome_at:+ outcome["at"] = _iso(row.outcome_at)+ out["outcome"] = outcome+ for key in ("run_id", "tool_call_id", "ui_part_id", "agent_node_id"):+ value = getattr(row, key, None)+ if value:+ out[key] = valueif deployment_state:out["deployment_state"] = deployment_statereturn out@@ -209,14 +399,22 @@ def summary(row: ApprovalRequest, *, deployment_state: Optional[str] = None) ->__all__ = ["ApprovalConflict",+ "aware",+ "cancel_open","cancel_pending",+ "cancellable","delete_for_workflow",+ "find_decision","get","get_by_key","get_or_create",+ "is_open","list_approvals",+ "list_open","list_pending",+ "list_unfinished_sends","pending_counts","settle","summary",+ "transition",]diff --git a/server/services/approvals/tool_calls.py b/server/services/approvals/tool_calls.pynew file mode 100644index 00000000..2b71df2c--- /dev/null+++ b/server/services/approvals/tool_calls.py@@ -0,0 +1,274 @@+"""A tool call that sends, held for the owner when the workflow asks first.++``BaseNode.as_activity`` calls :func:`check` before it runs a tool call an+agent made (``tool_call_id`` and ``parent_node_id`` in its context) of a+plugin that declares an ``approval`` spec (services/plugin/approval.py):++- **No rule** (a workflow built in the editor): the call runs.+- **Ask first on**, and the call sends: it does not run. A ``tool_call``+ row keeps what would run and what the card shows, and the model reads+ that it waits for the owner. A ``refuse_while_asking`` tool is refused+ instead; a ``restrict_while_asking`` tool runs with those settings.+- **Ask first off**: the call runs. When it answers the owner in the chat+ (the call carries a ``chat_stream``), a row records it (``approved_by:+ auto``) with how it went, so the owner sees what went out.++A call that comes back to run because the owner pressed Send carries+``approval_execution`` (services/approvals/execution.py): it runs only when+its row is the one being sent, and is never held again.++What a node sends as (its locked ``server_controlled_fields``: the account,+the mailbox) never comes from the model, so the row keeps the call's+arguments without them; the node's own settings supply them when it runs.+"""++from __future__ import annotations++import uuid+from dataclasses import dataclass+from datetime import datetime, timedelta, timezone+from typing import Any, Awaitable, Callable, Dict, Mapping, Optional++from core.logging import get_logger+from services.approvals import rules, store+from services.approvals.contract import DEFAULT_TIMEOUT_HOURS+from services.approvals.listeners import change_of, notify_approval_changed++logger = get_logger(__name__)++MAX_DRAFT = 20000++HELD_MESSAGE = (+ "Not sent yet: it waits for the owner's OK on a card in the chat. It goes out only if they press Send, "+ "so do not call this again for it. Tell them it is ready for them to check."+)+REFUSED_MESSAGE = (+ "Not run: {channel} cannot wait for the owner's OK, and they ask to approve everything first. "+ "Tell them what you would do; they can turn Ask first off to let you."+)+++@dataclass+class Checked:+ #: Answer with this instead of running.+ result: Optional[Dict[str, Any]] = None+ #: Run with these instead (a tool restricted while Ask first is on).+ node_data: Optional[Dict[str, Any]] = None+ tool_args: Optional[Dict[str, Any]] = None+ #: After running: record how it went (``await record(result)``).+ record: Optional[Callable[[Dict[str, Any]], Awaitable[None]]] = None+++RUN = Checked()+++def _utcnow() -> datetime:+ return datetime.now(timezone.utc)+++def _database() -> Any:+ from core.container import container++ return container.database()+++def is_agent_tool_call(context: Mapping[str, Any]) -> bool:+ return bool(context.get("tool_call_id")) and bool(context.get("parent_node_id"))+++def call_key(context: Mapping[str, Any]) -> str:+ return f"c:{context.get('workflow_id') or ''}:{context.get('execution_id') or ''}:{context.get('tool_call_id')}"+++def _locked(node_cls: Any) -> frozenset:+ from services.plugin.base import locked_tool_fields++ return locked_tool_fields(node_cls)+++def _clean_args(node_cls: Any, args: Mapping[str, Any]) -> Dict[str, Any]:+ locked = _locked(node_cls)+ return {key: value for key, value in dict(args or {}).items() if key not in locked}+++def _clean_node_data(node_cls: Any, node_data: Mapping[str, Any], args: Mapping[str, Any]) -> Dict[str, Any]:+ """The node's settings with the call's arguments over them, minus the+ locked fields the model set (the node's own value comes back when it+ runs)."""+ locked = _locked(node_cls)+ return {key: value for key, value in dict(node_data or {}).items() if not (key in locked and key in (args or {}))}+++def _held(row: Any, node_cls: Any, context: Mapping[str, Any]) -> Dict[str, Any]:+ from datetime import datetime as _dt++ return {+ "success": True,+ "node_id": context.get("node_id"),+ "node_type": getattr(node_cls, "type", ""),+ "result": {+ "status": "waiting_for_owner",+ "approval_id": row.id,+ "channel": row.channel,+ "to": row.recipient_label or row.recipient,+ "message": HELD_MESSAGE,+ },+ "approval_id": row.id,+ "execution_id": context.get("execution_id"),+ "timestamp": _dt.now().isoformat(),+ }+++async def _execution_allowed(database: Any, context: Mapping[str, Any]) -> bool:+ execution = context.get("approval_execution")+ if not isinstance(execution, Mapping):+ return False+ row = await store.get(database, str(execution.get("approval_id") or ""))+ return bool(row is not None and row.status == "sending" and row.claim_token and row.claim_token == execution.get("claim_token"))+++async def check(context: Mapping[str, Any], node_cls: Any) -> Checked:+ """What to do with a tool call before it runs (see the module docstring)."""+ from services.plugin.approval import approval_spec++ spec = approval_spec(node_cls)+ if context.get("approval_execution") is not None:+ database = _database()+ if await _execution_allowed(database, context):+ return RUN+ return Checked(+ result={+ "success": False,+ "node_id": context.get("node_id"),+ "node_type": getattr(node_cls, "type", ""),+ "error": "This send is no longer the one approved.",+ "error_type": "ApprovalNotClaimed",+ }+ )+ if spec is None or not is_agent_tool_call(context):+ return RUN+ node_data = dict(context.get("node_data") or {})+ if not spec.sends(node_data):+ return RUN+ database = _database()+ try:+ asking = await rules.ask_first(database, context.get("workflow_id"))+ except Exception:+ # The rule could not be read: hold it rather than send unasked.+ logger.warning("Could not read the Ask first rule; holding the call", workflow_id=context.get("workflow_id"), exc_info=True)+ asking = True+ if asking is None:+ return RUN+ if not asking:+ if not isinstance(context.get("chat_stream"), Mapping):+ return RUN+ return Checked(record=_auto_recorder(database, context, node_cls, spec, node_data))+ if spec.refuse_while_asking:+ return Checked(+ result={+ "success": True,+ "node_id": context.get("node_id"),+ "node_type": getattr(node_cls, "type", ""),+ "result": {"status": "not_run", "message": REFUSED_MESSAGE.format(channel=spec.channel)},+ "execution_id": context.get("execution_id"),+ }+ )+ if spec.restrict_while_asking:+ restricted = {**node_data, **dict(spec.restrict_while_asking)}+ tool_args = {k: v for k, v in dict(context.get("tool_args") or {}).items() if k not in spec.restrict_while_asking}+ return Checked(node_data=restricted, tool_args=tool_args)+ row = await hold(database, context, node_cls, spec, node_data)+ return Checked(result=_held(row, node_cls, context))+++def _row_fields(context: Mapping[str, Any], node_cls: Any, spec: Any, node_data: Mapping[str, Any]) -> Dict[str, Any]:+ args = _clean_args(node_cls, context.get("tool_args") or {})+ data = _clean_node_data(node_cls, node_data, context.get("tool_args") or {})+ preview = spec.preview(data)+ stream = context.get("chat_stream") if isinstance(context.get("chat_stream"), Mapping) else {}+ run_id = context.get("chat_run_id") or (stream or {}).get("run_id")+ return {+ "owner_id": str(context.get("user_id") or "owner"),+ "workflow_id": str(context.get("workflow_id") or ""),+ "node_id": str(context.get("node_id") or ""),+ "generation": int(context.get("generation") or 0),+ "execution_id": context.get("execution_id"),+ "runtime": "temporal",+ "kind": "tool_call",+ "channel": preview["channel"][:60],+ "action": preview["action"][:200],+ "recipient": str(preview.get("recipient") or "")[:500],+ "recipient_label": str(preview.get("recipient_label") or "")[:200],+ "subject": (preview.get("subject") or None),+ "draft_text": str(preview.get("body") or "")[:MAX_DRAFT],+ "max_length": int(preview.get("max_length") or MAX_DRAFT),+ "details": list(preview.get("details") or []),+ "node_type": getattr(node_cls, "type", None),+ "tool_node_id": str(context.get("node_id") or ""),+ "tool_call_id": str(context.get("tool_call_id") or ""),+ "agent_node_id": str(context.get("parent_node_id") or ""),+ "run_id": run_id if isinstance(run_id, str) and run_id else None,+ "node_data": data,+ "args": args,+ "original_args": dict(context.get("tool_args") or {}),+ "body_field": preview.get("body_field"),+ "subject_field": preview.get("subject_field"),+ }+++async def hold(database: Any, context: Mapping[str, Any], node_cls: Any, spec: Any, node_data: Mapping[str, Any]) -> Any:+ """The held call's row: created once, found again on a retry."""+ fields = _row_fields(context, node_cls, spec, node_data)+ fields["expires_at"] = _utcnow() + timedelta(hours=DEFAULT_TIMEOUT_HOURS)+ row, created = await store.get_or_create(database, idempotency_key=call_key(context), fields=fields)+ if created:+ logger.info("Held a call for the owner", approval_id=row.id, workflow_id=row.workflow_id, channel=row.channel)+ await notify_approval_changed(change_of(row, "requested"))+ await _show_in_chat(database, context, row)+ return row+++async def _show_in_chat(database: Any, context: Mapping[str, Any], row: Any) -> None:+ """A call made answering the owner shows its card in that answer."""+ stream = context.get("chat_stream")+ if not isinstance(stream, Mapping) or not isinstance(stream.get("run_id"), str):+ return+ try:+ from services.chat.parts import show_approval++ await show_approval(database, stream, approval_id=row.id, tool_call_id=row.tool_call_id)+ except Exception: # noqa: BLE001 - the draft waits either way+ logger.warning("Could not show a draft in the chat", approval_id=row.id, exc_info=True)+++def _auto_recorder(database: Any, context: Mapping[str, Any], node_cls: Any, spec: Any, node_data: Mapping[str, Any]):+ async def record(result: Dict[str, Any]) -> None:+ try:+ success = bool(isinstance(result, dict) and result.get("success", True) is not False)+ now = _utcnow()+ fields = _row_fields(context, node_cls, spec, node_data)+ fields.update(+ status="sent" if success else "failed",+ approved_by="auto",+ decided_at=now,+ consumed_at=now,+ outcome="sent" if success else "not_sent",+ outcome_error=None if success else str((result or {}).get("error") or "It did not go out.")[:1000],+ outcome_at=now,+ final_text=fields.get("draft_text"),+ )+ row, created = await store.get_or_create(database, idempotency_key=call_key(context), fields=fields)+ if created:+ await notify_approval_changed(change_of(row, "sent" if success else "failed"))+ await _show_in_chat(database, context, row)+ except Exception:+ logger.warning("Could not record a send made without asking", tool_call_id=context.get("tool_call_id"), exc_info=True)++ return record+++def claim_token() -> str:+ return uuid.uuid4().hex+++__all__ = ["Checked", "HELD_MESSAGE", "RUN", "call_key", "check", "claim_token", "hold", "is_agent_tool_call"]diff --git a/server/services/chat/ledger.py b/server/services/chat/ledger.pyindex d0d5937f..2e5843cb 100644--- a/server/services/chat/ledger.py+++ b/server/services/chat/ledger.py@@ -160,6 +160,13 @@ async def runs_by_id(database: Any, run_ids: List[str]) -> Dict[str, ChatRun]:return {run.run_id: run for run in result.scalars().all()}+async def session_run_ids(database: Any, session_id: str) -> List[str]:+ """Every run of a session, live or ended."""+ async with database.get_session() as session:+ result = await session.execute(select(ChatRun.run_id).where(ChatRun.session_id == session_id))+ return [str(run_id) for run_id in result.scalars().all()]++async def live_runs(database: Any, session_id: Optional[str] = None) -> List[ChatRun]:"""Live runs, oldest first: one session's, or every session's."""async with database.get_session() as session:@@ -713,6 +720,7 @@ __all__ = ["reply_uid","request_stop","runs_by_id",+ "session_run_ids","start_run","sweep",]diff --git a/server/services/chat/parts.py b/server/services/chat/parts.pyindex e4804144..3a2f40cf 100644--- a/server/services/chat/parts.py+++ b/server/services/chat/parts.py@@ -8,13 +8,15 @@ first kind: ``show_ui`` saves the checked spec and publishes it as an empty``activity.snapshot`` followed by one ``activity.delta`` per patch(``services/genui/patches.py``); the client paces what arrives.-Sources are the other kind (``services/chat/sources.py``): the numbered-results of a search the answering agent ran.+Sources (``services/chat/sources.py``) are the numbered results of a search+the answering agent ran. Approvals name the drafts it made that wait for the+owner (``services/approvals/tool_calls.py``): the card reads them live from+the approvals store, so the part only names them.When the run ends, ``seal_parts`` copies its parts into the reply message's-``parts`` (``{"ui": [...], "sources": [...]}``), creating an empty reply when-the run showed something but wrote nothing, so a reload draws what the run-showed. Every write here is best effort for the run: a part that cannot be+``parts`` (``{"ui": [...], "sources": [...], "approvals": [...]}``), creating+an empty reply when the run showed an interface or made a draft but wrote+nothing, so a reload draws what the run showed. Every write here is best effort for the run: a part that cannot besaved is logged, and the run goes on."""@@ -36,7 +38,7 @@ logger = get_logger(__name__)#: The ``activity_type`` of a generated UI's events.JSON_RENDER = "json_render"#: The kinds of part a run collects for its reply.-PART_KINDS = ("ui", "sources")+PART_KINDS = ("ui", "sources", "approvals")def ui_part_id(run_id: str, tool_call_id: str) -> str:@@ -123,13 +125,26 @@ async def show_ui(database: Any, stream: Mapping[str, Any], *, tool_call_id: strreturn part_id+async def show_approval(database: Any, stream: Mapping[str, Any], *, approval_id: str, tool_call_id: Optional[str]) -> None:+ """Name a draft the run made on its reply, and show its card live."""+ payload = {"approval_id": approval_id, "tool_call_id": tool_call_id}+ await record_part(database, stream["run_id"], kind="approvals", key=f"approval:{approval_id}", payload=payload)+ _publish(+ stream,+ "activity.snapshot",+ {"message_id": approval_id, "activity_type": "approval", "content": payload, "replace": True},+ f"{approval_id}:approval",+ )++#: What names one item of each kind, for merging a run's parts into a reply.-_ITEM_KEYS = {"ui": "part_id", "sources": "n"}+_ITEM_KEYS = {"ui": "part_id", "sources": "n", "approvals": "approval_id"}def grouped_parts(parts: List[ChatRunPart]) -> Dict[str, List[Dict[str, Any]]]:"""A run's parts as a reply's ``parts`` holds them: ``{"ui": [payload],- "sources": [item]}`` (a sources part holds one tool call's items)."""+ "sources": [item], "approvals": [{approval_id, tool_call_id}]}`` (a+ sources part holds one tool call's items)."""grouped: "OrderedDict[str, List[Dict[str, Any]]]" = OrderedDict()for part in parts:if part.kind not in PART_KINDS:@@ -176,7 +191,7 @@ async def seal_parts(database: Any, run: ChatRun) -> bool:else:# Sources show only where a reply cites them: alone they# are no reason to make one.- if not grouped.get("ui"):+ if not (grouped.get("ui") or grouped.get("approvals")):return Falsecurrent = await session.get(ChatRun, run.run_id)stopped = current is not None and current.state in ("stopping", "stopped")@@ -379,6 +394,7 @@ __all__ = ["record_part","run_parts","seal_parts",+ "show_approval","show_ui","ui_event_message","ui_part_id",diff --git a/server/services/chat_thread.py b/server/services/chat_thread.pyindex 9ded1787..3253a9ad 100644--- a/server/services/chat_thread.py+++ b/server/services/chat_thread.py@@ -20,7 +20,8 @@ Talk, and the editor shows it in its chat pane.which announces them the same way.- ``clear_chat_thread``: delete the session's rows, every generation, andits chat runs, then announce it when there were any. Subscribers watching- a run that was still live are told it ended (``reset``).+ a run that was still live are told it ended (``reset``), and drafts the+ runs made that still wait for the owner are cancelled.- ``clear_chat_session``: the owner's Clear. The thread goes (live runs endwith ``cleared``), and the listeners registered with``register_chat_cleared_listener`` forget what it held: the Context plugin@@ -155,6 +156,7 @@ async def clear_chat_thread(database: Any, session_id: str, *, reason: str = "reexcept Exception:logger.warning("Could not read live chat runs before a clear", session_id=session_id, exc_info=True)live = []+ await _cancel_drafts(database, session_id)count = await database.clear_chat_messages(session_id)ledger.publish_cleared(live, code=reason)if count:@@ -162,6 +164,25 @@ async def clear_chat_thread(database: Any, session_id: str, *, reason: str = "rereturn count+async def _cancel_drafts(database: Any, session_id: str) -> None:+ """Drafts the conversation's runs made that still wait go with it: a+ send nobody can see any more must not go out later."""+ from services.chat import ledger++ try:+ from services.approvals import store, waiter+ from services.approvals.listeners import change_of, notify_approval_changed++ run_ids = await ledger.session_run_ids(database, session_id)+ if not run_ids:+ return+ for row in await store.cancel_open(database, workflow_id=session_id, run_ids=run_ids):+ waiter.notify(row.id)+ await notify_approval_changed(change_of(row, "cancelled"))+ except Exception:+ logger.warning("Could not cancel a cleared conversation's drafts", session_id=session_id, exc_info=True)++def register_chat_cleared_listener(listener: ChatClearedListener) -> None:"""Run ``await listener(database=..., workflow_id=...)`` after the ownerclears a workflow's chat. Registering the same listener twice is adiff --git a/server/services/employees/__init__.py b/server/services/employees/__init__.pyindex 2b275ecd..71e678c8 100644--- a/server/services/employees/__init__.py+++ b/server/services/employees/__init__.py@@ -15,6 +15,8 @@ import timefrom typing import Anyfrom services.approvals.listeners import register_approval_listener as _register_approval_listener+from services.approvals.rules import register_rule_listener as _register_rule_listener+from services.approvals.rules import register_rule_seeder as _register_rule_seederfrom services.deployment.control import register_control_listener as _register_control_listenerfrom services.workflow_storage.hooks import register_workflow_deleted_hook as _register_deleted_hookfrom services.workflow_storage.listeners import register_graph_listener as _register_graph_listener@@ -37,6 +39,38 @@ async def _on_workflow_deleted(database: Any, workflow_id: str) -> None:)+async def _seed_ask_first(database: Any, workflow_id: str):+ """An employee's Ask first rule starts as its ground rules said at hire+ (services/approvals/rules.py seeds the workflow's rule from this)."""+ from . import store++ employee = await store.get_by_workflow(database, workflow_id)+ if employee is None:+ return None+ return bool(dict(employee.rules or {}).get("ask_first", True))+++async def _on_ask_first_changed(database: Any, workflow_id: str, rule: Any):+ """Keep the employee's ground rules in step with the live rule, show it+ on the card, and say what the change means for this employee: whether+ its app replies wait for the owner (a gate is wired), and whether its+ graph predates the live rule (Apply rebuilds it)."""+ from . import store+ from .builder import LIVE_RULE_BUILDER_VERSION++ employee = await store.get_by_workflow(database, workflow_id)+ if employee is None:+ return None+ rules = {**dict(employee.rules or {}), "ask_first": bool(rule.ask_first)}+ await store.update_employee(database, workflow_id, {"rules": rules})+ _events.employee_changed_now(workflow_id)+ roles = dict(employee.node_roles or {})+ return {+ "replies_gated": bool(roles.get("gate")),+ "needs_apply": int(employee.builder_version or 1) < LIVE_RULE_BUILDER_VERSION,+ }++async def _build_summary(workflow_id: str):from core.container import container@@ -54,6 +88,10 @@ _register_control_listener(_events.employee_changed_now)_events.set_summary_builder(_build_summary)# A draft waiting, sent or discarded changes the employee's pending count._register_approval_listener(lambda change: _events.employee_changed(change.workflow_id))+# An employee's Ask first rule starts from its ground rules; the chat's Ask+# first chip changes both.+_register_rule_seeder(_seed_ask_first)+_register_rule_listener(_on_ask_first_changed)# A saved graph can change the summary (a new tool, a change waiting for a# restart). The editor autosaves often, so this takes the coalesced path._register_graph_listener(_events.employee_changed)diff --git a/server/services/employees/builder.py b/server/services/employees/builder.pyindex 20e4e406..a3ba5fc8 100644--- a/server/services/employees/builder.py+++ b/server/services/employees/builder.py@@ -90,6 +90,10 @@ from services.graph_build import ()BUILDER_VERSION = 2+#: The first builder whose graphs follow the live Ask first rule (every app+#: reply behind a gate, sending tools attached and held per call). Older+#: graphs need Apply for a changed rule to take full effect.+LIVE_RULE_BUILDER_VERSION = 3AGENT_TYPE = "aiAgent"CHAT_TRIGGER_TYPE = "chatTrigger"@@ -806,6 +810,7 @@ def build_employee_graph(inputs: BuildInputs) -> BuiltEmployee:__all__ = ["APPROVED_CONDITION","BUILDER_VERSION",+ "LIVE_RULE_BUILDER_VERSION","BuildError","BuildInputs","BuiltEmployee",diff --git a/server/services/plugin/approval.py b/server/services/plugin/approval.pynew file mode 100644index 00000000..22520365--- /dev/null+++ b/server/services/plugin/approval.py@@ -0,0 +1,126 @@+"""Which tool calls send, and how a card shows them: a plugin's ``approval``.++A plugin whose tool reaches someone outside (a message, an email, an invite,+a share) declares an :class:`ApprovalSpec` on its class. When the workflow+asks first (services/approvals/rules.py), an agent's call of that tool is+held as a draft for the owner instead of running (services/approvals/+tool_calls.py); the spec says which calls count, what the card shows and+which arguments the owner may edit. Two other answers exist for tools that+cannot wait: ``refuse_while_asking`` (Stripe: refused while Ask first is on)+and ``restrict_while_asking`` (the browser: runs read-only).++The spec reads the call's arguments over the node's settings (``data``), the+dict the node runs with.+"""++from __future__ import annotations++from dataclasses import dataclass, field+from typing import Any, Callable, Dict, FrozenSet, List, Mapping, Optional, Tuple++Predicate = Callable[[Mapping[str, Any]], bool]++_MAX_DETAIL = 300+++def _text(value: Any) -> str:+ if value is None or isinstance(value, bool):+ return ""+ if isinstance(value, (list, tuple)):+ return ", ".join(_text(item) for item in value if _text(item))+ if isinstance(value, dict):+ return ""+ return str(value).strip()+++@dataclass(frozen=True)+class ApprovalSpec:+ #: The app it goes out through ("WhatsApp").+ channel: str+ #: What the card says it does ("Send a WhatsApp message").+ action: str+ #: Which calls send: values of ``operation_field``; None means every call.+ operations: Optional[FrozenSet[str]] = None+ operation_field: str = "operation"+ #: A further test: the call sends only when this returns True. A test+ #: that raises counts as sending (held, never let through by mistake).+ when: Optional[Predicate] = None+ #: Arguments naming who it goes to; the first with a value wins.+ recipient: Tuple[str, ...] = ()+ #: Who it goes to when none of those has a value ("the sender").+ recipient_otherwise: str = ""+ #: The call goes to the owner themself.+ to_owner: Optional[Predicate] = None+ #: Arguments holding the message, the first with a value wins; the+ #: owner may edit it on the card.+ body: Tuple[str, ...] = ()+ #: The argument holding a subject line, editable too.+ subject: Optional[str] = None+ #: Other lines on the card: (label, argument).+ details: Tuple[Tuple[str, str], ...] = ()+ #: The longest edit the channel accepts.+ max_length: int = 20000+ #: Never runs while Ask first is on: the call is refused, saying so.+ refuse_while_asking: bool = False+ #: While Ask first is on, runs with these settings instead of being held.+ restrict_while_asking: Mapping[str, Any] = field(default_factory=dict)++ def sends(self, data: Mapping[str, Any]) -> bool:+ """Whether this call reaches someone (and so waits for the owner)."""+ if self.operations is not None and str(data.get(self.operation_field) or "") not in self.operations:+ return False+ if self.when is not None:+ try:+ return bool(self.when(data))+ except Exception:+ return True+ return True++ def body_field(self, data: Mapping[str, Any]) -> Optional[str]:+ for name in self.body:+ if _text(data.get(name)):+ return name+ return self.body[0] if self.body else None++ def preview(self, data: Mapping[str, Any]) -> Dict[str, Any]:+ """What the card shows: ``{channel, action, recipient,+ recipient_label, body, body_field, subject?, subject_field?,+ details: [{label, value}], max_length}``."""+ recipient = next((_text(data.get(name)) for name in self.recipient if _text(data.get(name))), "")+ owner = False+ if self.to_owner is not None:+ try:+ owner = bool(self.to_owner(data))+ except Exception:+ owner = False+ label = "you" if owner else (recipient or self.recipient_otherwise)+ body_field = self.body_field(data)+ out: Dict[str, Any] = {+ "channel": self.channel,+ "action": self.action,+ "recipient": "" if owner else recipient,+ "recipient_label": label,+ "body": _text(data.get(body_field)) if body_field else "",+ "body_field": body_field,+ "max_length": self.max_length,+ }+ if self.subject:+ out["subject_field"] = self.subject+ subject = _text(data.get(self.subject))+ if subject:+ out["subject"] = subject+ details: List[Dict[str, str]] = []+ for label_text, name in self.details:+ value = _text(data.get(name))+ if value:+ details.append({"label": label_text, "value": value[:_MAX_DETAIL]})+ out["details"] = details+ return out+++def approval_spec(node_cls: Any) -> Optional[ApprovalSpec]:+ spec = getattr(node_cls, "approval", None) if node_cls is not None else None+ return spec if isinstance(spec, ApprovalSpec) else None+++__all__ = ["ApprovalSpec", "approval_spec"]diff --git a/server/services/plugin/base.py b/server/services/plugin/base.pyindex 39501272..577610bf 100644--- a/server/services/plugin/base.py+++ b/server/services/plugin/base.py@@ -288,6 +288,13 @@ class BaseNode:chat_step_hidden: ClassVar[bool] = Falsechat_sources: ClassVar[bool] = False+ # ``approval``: an ``ApprovalSpec`` (services/plugin/approval.py) for a+ # tool that reaches someone outside: which calls send, and what the+ # owner's card shows. While the workflow asks first, an agent's call+ # that sends is held for the owner instead of running+ # (services/approvals/tool_calls.py).+ approval: ClassVar[Optional[Any]] = None+# Set by __init_subclass__: {op_name: OperationSpec}_operations: ClassVar[Dict[str, OperationSpec]] = {}# Flag so concrete subclasses auto-register; abstract kinds don't.@@ -1123,6 +1130,36 @@ class BaseNode:return resultchat_step = chat_steps.begin(context, cls)+ # Approvals (services/approvals/tool_calls.py): a tool call that+ # sends waits for the owner while the workflow asks first, and a+ # send the owner approved runs only under its claim.+ from services.approvals import tool_calls as approval_calls++ checked = await approval_calls.check(context, cls)+ if checked.result is not None:+ result = {+ "node_id": node_id,+ "node_type": cls.type,+ "execution_id": execution_id,+ "timestamp": datetime.now().isoformat(),+ **checked.result,+ }+ held = result.get("success") is not False+ await chat_steps.end(chat_step, state="done" if held else "failed", detail="Waiting for your OK" if result.get("approval_id") else None)+ await broadcaster.update_node_status(+ node_id,+ "success" if held else "error",+ {"held": bool(result.get("approval_id")), "execution_id": execution_id}+ if held+ else {"error": result.get("error"), "execution_id": execution_id},+ workflow_id=workflow_id,+ )+ return result+ if checked.node_data is not None:+ node_data = checked.node_data+ if checked.tool_args is not None:+ context = {**context, "tool_args": checked.tool_args}+# Broadcast executing — UI cyan-glow.await broadcaster.update_node_status(node_id,@@ -1225,6 +1262,8 @@ class BaseNode:success, payload, error = cls.interpret_result(result)if success:await chat_steps.number_sources(context, cls, result)+ if checked.record is not None:+ await checked.record(result)if chat_step is not None and not (not success and result.get("error_type") == NODE_WAIT_INTERRUPTED):diff --git a/server/services/temporal/approved_tool_call_workflow.py b/server/services/temporal/approved_tool_call_workflow.pynew file mode 100644index 00000000..8cf85c19--- /dev/null+++ b/server/services/temporal/approved_tool_call_workflow.py@@ -0,0 +1,83 @@+"""Send a tool call the owner approved (services/approvals/execution.py).++One run per Send (its id names the approval and the revision Send left it+at). It sleeps until the Undo window closes, claims the row at that+revision (an Undo, a newer Send or a cancel moved it, and the run ends with+nothing sent), runs the node's own activity once with no retry, since a+message must never go twice, and records how it went: ``sent``, ``not_sent``+(the node said it did not go out) or ``unknown`` (the activity broke off,+so it may have).++``payload_version`` 1: ``{approval_id, revision, grace_until}``.+"""++from __future__ import annotations++import hashlib+from datetime import datetime, timedelta+from typing import Any, Dict++from temporalio import workflow+from temporalio.common import RetryPolicy+from temporalio.exceptions import ActivityError++BOOKKEEPING_TIMEOUT = timedelta(seconds=30)+#: Bookkeeping retries until it lands: the row must not stay "sending".+BOOKKEEPING_RETRY = RetryPolicy(initial_interval=timedelta(seconds=1), maximum_interval=timedelta(seconds=30), maximum_attempts=0)+SEND_TIMEOUT = timedelta(minutes=10)+SEND_HEARTBEAT = timedelta(minutes=2)+#: Never retried: a retry could send it twice.+SEND_ONCE = RetryPolicy(maximum_attempts=1)++[email protected](name="ApprovedToolCallWorkflow", sandboxed=False)+class ApprovedToolCallWorkflow:+ @workflow.run+ async def run(self, payload: Dict[str, Any]) -> Dict[str, Any]:+ approval_id = str(payload.get("approval_id") or "")+ info = workflow.info()+ token = hashlib.sha256(f"{info.workflow_id}:{info.run_id}".encode()).hexdigest()[:32]++ grace_until = payload.get("grace_until")+ if grace_until:+ due = datetime.fromisoformat(str(grace_until))+ wait = (due - workflow.now()).total_seconds()+ if wait > 0:+ await workflow.sleep(timedelta(seconds=wait))++ claim = await workflow.execute_activity(+ "approvals.claim_send",+ {"approval_id": approval_id, "revision": int(payload.get("revision") or 0), "claim_token": token},+ start_to_close_timeout=BOOKKEEPING_TIMEOUT,+ retry_policy=BOOKKEEPING_RETRY,+ )+ if not claim.get("claimed"):+ return {"sent": False, "reason": claim.get("reason")}++ report: Dict[str, Any] = {"approval_id": approval_id, "claim_token": token}+ try:+ result = await workflow.execute_activity(+ str(claim["activity"]),+ claim["context"],+ start_to_close_timeout=SEND_TIMEOUT,+ heartbeat_timeout=SEND_HEARTBEAT,+ retry_policy=SEND_ONCE,+ )+ if isinstance(result, dict) and result.get("success") is False:+ report.update(success=False, error=str(result.get("error") or "It did not go out."))+ else:+ report.update(success=True)+ except ActivityError as exc:+ cause = exc.cause if exc.cause is not None else exc+ report.update(broke_off=True, error=f"{type(cause).__name__}: {cause}")++ recorded = await workflow.execute_activity(+ "approvals.record_outcome",+ report,+ start_to_close_timeout=BOOKKEEPING_TIMEOUT,+ retry_policy=BOOKKEEPING_RETRY,+ )+ return {"sent": recorded.get("status") == "sent", "outcome": recorded.get("outcome")}+++__all__ = ["ApprovedToolCallWorkflow"]diff --git a/server/services/temporal/worker.py b/server/services/temporal/worker.pyindex 3ef70d79..151bb2b0 100644--- a/server/services/temporal/worker.py+++ b/server/services/temporal/worker.py@@ -55,8 +55,10 @@ def _framework_workflows() -> list:from services.temporal.node_invocation import NodeInvocationWorkflowfrom services.temporal.workspace_tasks_workflow import WorkspaceTaskControllerWorkflow+ from services.temporal.approved_tool_call_workflow import ApprovedToolCallWorkflowreturn [+ ApprovedToolCallWorkflow,NodeInvocationWorkflow,WorkspaceTaskControllerWorkflow,MachinaWorkflow,@@ -227,6 +229,7 @@ class TemporalWorkerManager:from services.temporal.agent_activities import collect_agent_activitiesfrom services.temporal.workspace_task_activities import reset_workspace_task_runtimefrom services.chat.activities import CHAT_RUN_ACTIVITIES+ from services.approvals.activities import APPROVAL_ACTIVITIESfrom services.temporal.activities import (broadcast_trigger_status_activity,evaluate_trigger_filter_activity,@@ -284,6 +287,7 @@ class TemporalWorkerManager:record_run_completion_activity,reset_workspace_task_runtime,*CHAT_RUN_ACTIVITIES,+ *APPROVAL_ACTIVITIES,store_node_output_activity,*per_type,*agent_activities,@@ -744,6 +748,7 @@ async def run_standalone_worker(from services.temporal.agent_activities import collect_agent_activitiesfrom services.temporal.workspace_task_activities import reset_workspace_task_runtimefrom services.chat.activities import CHAT_RUN_ACTIVITIES+ from services.approvals.activities import APPROVAL_ACTIVITIESfrom services.temporal.agent_workflow import (AgentWorkflow,DelegatedTaskWorkflow,@@ -771,6 +776,7 @@ async def run_standalone_worker(record_run_completion_activity,reset_workspace_task_runtime,*CHAT_RUN_ACTIVITIES,+ *APPROVAL_ACTIVITIES,store_node_output_activity,*registered_plugin_activities,*registered_agent_activities,@@ -829,6 +835,7 @@ async def create_worker(from services.temporal.agent_activities import collect_agent_activitiesfrom services.temporal.workspace_task_activities import reset_workspace_task_runtimefrom services.chat.activities import CHAT_RUN_ACTIVITIES+ from services.approvals.activities import APPROVAL_ACTIVITIESfrom services.temporal.agent_workflow import (AgentWorkflow,DelegatedTaskWorkflow,@@ -855,6 +862,7 @@ async def create_worker(record_run_completion_activity,reset_workspace_task_runtime,*CHAT_RUN_ACTIVITIES,+ *APPROVAL_ACTIVITIES,store_node_output_activity,*registered_plugin_activities,*registered_agent_activities,diff --git a/server/tests/services/approvals/conftest.py b/server/tests/services/approvals/conftest.pyindex 04ce8b4a..328c53df 100644--- a/server/tests/services/approvals/conftest.py+++ b/server/tests/services/approvals/conftest.py@@ -56,7 +56,7 @@ class FakeBroadcaster:def harness(monkeypatch, real_database):import core.container as container_moduleimport services.status_broadcaster as status_broadcaster- from services.approvals import reconcile, waiter+ from services.approvals import decisions, reconcile, waiterimport nodes.workflow.approval_gate as gate@@ -64,6 +64,9 @@ def harness(monkeypatch, real_database):monkeypatch.setattr(container_module, "container", SimpleNamespace(database=lambda: real_database))monkeypatch.setattr(status_broadcaster, "get_status_broadcaster", lambda: broadcaster)monkeypatch.setattr(gate, "POLL_SECONDS", 0.02)+ # Undo and Restore windows short enough for a test to wait them out.+ monkeypatch.setattr(decisions, "UNDO_SECONDS", 0.2)+ monkeypatch.setattr(decisions, "RESTORE_SECONDS", 0.2)waiter.reset_for_tests()reconcile.reset_for_tests()yield SimpleNamespace(database=real_database, broadcaster=broadcaster, gate=gate)diff --git a/server/tests/services/approvals/test_approval_gate.py b/server/tests/services/approvals/test_approval_gate.pyindex 7a203f4e..970f3b94 100644--- a/server/tests/services/approvals/test_approval_gate.py+++ b/server/tests/services/approvals/test_approval_gate.py@@ -67,7 +67,7 @@ async def until_waiting(approval_id):async def decide(harness, approval_id, decision, key="d1", **extra):- from nodes.workflow.approval_gate._handlers import handle_decide_approval+ from services.approvals.handlers import handle_decide_approvalreturn await handle_decide_approval({"approval_id": approval_id, "decision": decision, "decision_key": key, **extra}, SOCKET)@@ -183,7 +183,7 @@ async def test_reset_cancels_waiting_drafts(harness):async def test_the_list_shows_only_the_owner_drafts(harness):- from nodes.workflow.approval_gate._handlers import handle_list_approvals+ from services.approvals.handlers import handle_list_approvalstask = asyncio.ensure_future(run_gate(harness))(row,) = await pending(harness)diff --git a/server/tests/services/approvals/test_decisions.py b/server/tests/services/approvals/test_decisions.pynew file mode 100644index 00000000..f9800e98--- /dev/null+++ b/server/tests/services/approvals/test_decisions.py@@ -0,0 +1,114 @@+"""The owner's decisions after Send and Discard: Undo brings a draft back+while its window is open and the gate waits through it; Restore brings a+discarded draft back while it can; a repeated decision is a no-op; and the+live Ask first rule lets a gate's draft go without asking, recorded."""++from __future__ import annotations++import asyncio+from types import SimpleNamespace++import pytest++from services.approvals import rules, store+from tests.services.approvals.test_approval_gate import PARAMS, ctx, decide, pending, run_gate, until_waiting++pytestmark = pytest.mark.asyncio+++async def test_undo_brings_a_sent_draft_back_and_the_gate_keeps_waiting(harness):+ task = asyncio.ensure_future(run_gate(harness))+ (row,) = await pending(harness)+ sent = await decide(harness, row.id, "send", key="s1")+ assert sent["approval"]["status"] == "approved" and "undo_until" in sent["approval"]+ undone = await decide(harness, row.id, "undo", key="u1")+ assert undone["success"] is True and undone["approval"]["status"] == "pending"+ await asyncio.sleep(0.3)+ assert not task.done(), "the gate let an undone draft through"+ await until_waiting(row.id)+ await decide(harness, row.id, "send", key="s2", text="Saturday at 10, see you.")+ result = (await asyncio.wait_for(task, 5))["result"]+ assert result["approved"] is True and result["text"] == "Saturday at 10, see you."+++async def test_undo_is_too_late_once_the_draft_went(harness):+ task = asyncio.ensure_future(run_gate(harness))+ (row,) = await pending(harness)+ await decide(harness, row.id, "send", key="s1")+ result = (await asyncio.wait_for(task, 5))["result"]+ assert result["approved"] is True+ late = await decide(harness, row.id, "undo", key="u1")+ assert late == {**late, "success": False, "error": "too_late"}+ stored = await store.get(harness.database, row.id)+ assert stored.consumed_at is not None and stored.status == "approved"+++async def test_restore_brings_a_discarded_draft_back_while_it_can(harness):+ task = asyncio.ensure_future(run_gate(harness))+ (row,) = await pending(harness)+ discarded = await decide(harness, row.id, "discard", key="d1")+ assert discarded["approval"]["status"] == "discarded" and "restore_until" in discarded["approval"]+ restored = await decide(harness, row.id, "restore", key="r1")+ assert restored["approval"]["status"] == "pending"+ assert not task.done()+ await until_waiting(row.id)+ await decide(harness, row.id, "discard", key="d2")+ result = (await asyncio.wait_for(task, 5))["result"]+ assert result["approved"] is False and result["status"] == "discarded"+ late = await decide(harness, row.id, "restore", key="r2")+ assert late == {**late, "success": False, "error": "too_late"}+++async def test_a_repeated_decision_key_changes_nothing(harness):+ task = asyncio.ensure_future(run_gate(harness))+ (row,) = await pending(harness)+ await decide(harness, row.id, "send", key="same")+ await decide(harness, row.id, "undo", key="undo")+ # The send's key again: no new send, the draft stays waiting.+ again = await decide(harness, row.id, "send", key="same")+ assert again["idempotent"] is True and again["approval"]["status"] == "pending"+ await decide(harness, row.id, "discard", key="end")+ await asyncio.wait_for(task, 5)+++async def test_a_gate_goes_without_asking_when_ask_first_is_off(harness):+ await rules.set_ask_first(harness.database, "7", False)+ result = (await asyncio.wait_for(run_gate(harness), 5))["result"]+ assert result["approved"] is True and result["automatic"] is True and result["text"] == PARAMS["draft"]+ (row,) = await store.list_approvals(harness.database, status="approved")+ assert row.approved_by == "auto" and row.consumed_at is not None+ lifecycle = [frame["data"]["type"] for frame in harness.broadcaster.frames if frame["type"] == "approval_lifecycle"]+ assert lifecycle == ["com.opencompany.approval.decided"]+ # Turned back on: the next draft waits.+ await rules.set_ask_first(harness.database, "7", True)+ task = asyncio.ensure_future(run_gate(harness, context=ctx({"t": {"text": "another"}})))+ (waiting,) = await pending(harness)+ assert waiting.status == "pending"+ await decide(harness, waiting.id, "discard", key="k")+ await asyncio.wait_for(task, 5)+++async def test_the_rule_is_a_compare_and_swap_and_seeds_from_a_default(harness, monkeypatch):+ assert await rules.ask_first(harness.database, "nobody") is None+ monkeypatch.setattr(rules, "_SEEDERS", [lambda database, workflow_id: workflow_id == "hired" or None])+ seeded = await rules.get_rule(harness.database, "hired")+ assert (seeded.ask_first, seeded.revision, seeded.source) == (True, 0, "hire")+ changed = await rules.set_ask_first(harness.database, "hired", False, expected_revision=0)+ assert (changed.ask_first, changed.revision, changed.source) == (False, 1, "owner")+ with pytest.raises(rules.RuleConflict):+ await rules.set_ask_first(harness.database, "hired", True, expected_revision=0)+++async def test_set_ask_first_answers_what_it_means(harness, monkeypatch):+ from services.approvals.handlers import handle_get_ask_first, handle_set_ask_first++ monkeypatch.setattr(rules, "_LISTENERS", [lambda database, workflow_id, rule: {"replies_gated": True, "needs_apply": not rule.ask_first}])+ socket = SimpleNamespace(scope={"path": "/ws/status"}, state=SimpleNamespace(user_id="owner"))+ assert (await handle_get_ask_first({"workflow_id": "7"}, socket))["ask_first"] is None+ answer = await handle_set_ask_first({"workflow_id": "7", "ask_first": False}, socket)+ assert answer == {**answer, "success": True, "ask_first": False, "revision": 0, "replies_gated": True, "needs_apply": True}+ stale = await handle_set_ask_first({"workflow_id": "7", "ask_first": True, "expected_revision": 5}, socket)+ assert stale == {**stale, "success": False, "error": "rule_conflict", "ask_first": False}+ assert (await handle_set_ask_first({"workflow_id": "7", "ask_first": "yes"}, socket))["error"] == "invalid_request"+ internal = SimpleNamespace(scope={"path": "/ws/internal"}, state=SimpleNamespace(user_id="owner"))+ assert (await handle_set_ask_first({"workflow_id": "7", "ask_first": True}, internal))["error"] == "not_found"diff --git a/server/tests/services/approvals/test_held_activity.py b/server/tests/services/approvals/test_held_activity.pynew file mode 100644index 00000000..6c1f7a72--- /dev/null+++ b/server/tests/services/approvals/test_held_activity.py@@ -0,0 +1,91 @@+"""A sending tool call through the node's own Temporal activity+(``BaseNode.as_activity``): held, it never reaches the node and the model+reads that it waits; with Ask first off it runs and is recorded; a send+the owner approved runs under its claim."""++from __future__ import annotations++from types import SimpleNamespace+from unittest.mock import AsyncMock, MagicMock++import pytest+from temporalio.testing import ActivityEnvironment++import nodes # noqa: F401 -- populate plugin registry+from services.approvals import rules, store+from services.node_registry import get_node_class++pytestmark = pytest.mark.asyncio++ARGS = {"recipient_type": "phone", "phone": "447700900123", "message": "On my way."}+++def context(**extra):+ return {+ "node_id": "wf:whatsappSend:1",+ "workflow_id": "wf",+ "execution_id": "wf:execution:1",+ "user_id": "owner",+ "parent_node_id": "wf:aiAgent:1",+ "tool_call_id": "call_1",+ "node_data": {"message_type": "text", **ARGS},+ "tool_args": dict(ARGS),+ **extra,+ }+++def service(monkeypatch, harness):+ import core.container as container_module++ workflow_service = MagicMock()+ workflow_service.execute_node = AsyncMock(return_value={"success": True, "result": {"message_id": "m1"}})+ monkeypatch.setattr(+ container_module,+ "container",+ SimpleNamespace(database=lambda: harness.database, workflow_service=lambda: workflow_service),+ )+ harness.broadcaster.update_node_output = AsyncMock()+ return workflow_service+++async def test_a_held_call_never_reaches_the_node(harness, service):+ await rules.set_ask_first(harness.database, "wf", True)+ activity_fn = get_node_class("whatsappSend").as_activity()+ result = await ActivityEnvironment().run(activity_fn, context())+ service.execute_node.assert_not_awaited()+ assert result["success"] is True and result["result"]["status"] == "waiting_for_owner"+ (row,) = await store.list_approvals(harness.database, status="pending")+ assert result["approval_id"] == row.id+ assert ("wf:whatsappSend:1", "success") in [(node_id, status) for node_id, status, *_ in harness.broadcaster.statuses]+++async def test_with_ask_first_off_the_call_runs(harness, service):+ await rules.set_ask_first(harness.database, "wf", False)+ activity_fn = get_node_class("whatsappSend").as_activity()+ result = await ActivityEnvironment().run(activity_fn, context())+ service.execute_node.assert_awaited_once()+ assert result["success"] is True and result["result"] == {"message_id": "m1"}+ # Outside a chat nothing is recorded.+ assert await store.list_approvals(harness.database) == []+++async def test_an_approved_send_runs_only_under_its_claim(harness, service):+ await rules.set_ask_first(harness.database, "wf", True)+ activity_fn = get_node_class("whatsappSend").as_activity()+ await ActivityEnvironment().run(activity_fn, context())+ (row,) = await store.list_approvals(harness.database, status="pending")+ approved = await store.transition(harness.database, row.id, expected_revision=row.revision, from_statuses=("pending",), status="approved")+ sending = await store.transition(+ harness.database, row.id, expected_revision=approved.revision, from_statuses=("approved",), status="sending", values={"claim_token": "t1"}+ )+ from services.approvals.execution import node_context++ send = node_context(sending, "t1")+ result = await ActivityEnvironment().run(activity_fn, send)+ service.execute_node.assert_awaited_once()+ assert service.execute_node.await_args.kwargs["extras"]["tool_args"] == {"recipient_type": "phone", "phone": "447700900123", "message": "On my way."}+ assert result["success"] is True+ stale = await ActivityEnvironment().run(activity_fn, node_context(sending, "someone-else"))+ assert stale["success"] is False and stale["error_type"] == "ApprovalNotClaimed"+ service.execute_node.assert_awaited_once()diff --git a/server/tests/services/approvals/test_tool_calls.py b/server/tests/services/approvals/test_tool_calls.pynew file mode 100644index 00000000..c608a772--- /dev/null+++ b/server/tests/services/approvals/test_tool_calls.py@@ -0,0 +1,237 @@+"""A tool call that sends, while the workflow asks first: held as a draft+(once, however often the activity retries), shown in the chat it was made+in, never with the identity the model chose; run as usual with no rule, run+and recorded with Ask first off; refused or restricted for tools that+cannot wait; sent after Send, once, under its claim."""++from __future__ import annotations++from types import SimpleNamespace++import pytest++from services.approvals import execution, rules, store, tool_calls+from services.approvals.handlers import handle_decide_approval+from services.node_registry import get_node_class++pytestmark = pytest.mark.asyncio++SOCKET = SimpleNamespace(scope={"path": "/ws/status"}, state=SimpleNamespace(user_id="owner"))+++def call(node_type="whatsappSend", tool_args=None, node_data=None, **extra):+ args = tool_args if tool_args is not None else {"recipient_type": "phone", "phone": "447700900123", "message": "Running late, there at 10."}+ return {+ "node_id": f"wf:{node_type}:1",+ "node_type": node_type,+ "workflow_id": "wf",+ "execution_id": "wf:execution:1",+ "user_id": "owner",+ "parent_node_id": "wf:aiAgent:1",+ "tool_call_id": "call_1",+ "node_data": {**(node_data or {"message_type": "text"}), **args},+ "tool_args": args,+ **extra,+ }+++def nodes_loaded():+ import nodes # noqa: F401 - the plugin registry++ return get_node_class+++async def test_a_workflow_without_a_rule_runs_its_calls(harness, nodes_loaded):+ checked = await tool_calls.check(call(), get_node_class("whatsappSend"))+ assert checked is tool_calls.RUN+ assert await store.list_approvals(harness.database, status="pending") == []+++async def test_asking_first_holds_the_call_once(harness, nodes_loaded):+ await rules.set_ask_first(harness.database, "wf", True)+ node_cls = get_node_class("whatsappSend")+ first = await tool_calls.check(call(), node_cls)+ again = await tool_calls.check(call(), node_cls)+ assert first.result["result"]["status"] == "waiting_for_owner"+ assert first.result["approval_id"] == again.result["approval_id"]+ (row,) = await store.list_approvals(harness.database, status="pending")+ assert (row.kind, row.channel, row.recipient, row.draft_text, row.body_field) == (+ "tool_call",+ "WhatsApp",+ "447700900123",+ "Running late, there at 10.",+ "message",+ )+ assert row.tool_call_id == "call_1" and row.agent_node_id == "wf:aiAgent:1" and row.node_type == "whatsappSend"+ # Only calls that send are held, and only an agent's.+ assert await tool_calls.check({**call(), "tool_call_id": None}, node_cls) is tool_calls.RUN+ assert await tool_calls.check(call("googleGmail", {"operation": "search", "query": "x"}), get_node_class("googleGmail")) is tool_calls.RUN+++async def test_the_model_never_chooses_who_sends(harness, nodes_loaded):+ await rules.set_ask_first(harness.database, "wf", True)+ args = {"operation": "send", "to": "[email protected]", "subject": "Hi", "body": "Hello", "mailbox": "[email protected]"}+ await tool_calls.check(call("msMail", args, node_data={"mailbox": "[email protected]"}), get_node_class("msMail"))+ (row,) = await store.list_approvals(harness.database, status="pending")+ assert "mailbox" not in row.args and "mailbox" not in row.node_data+ assert row.original_args["mailbox"] == "[email protected]"+ assert (row.subject, row.subject_field) == ("Hi", "subject")+++async def test_a_call_in_the_chat_shows_its_card_there(harness, nodes_loaded, monkeypatch):+ from services.chat import parts++ shown = []++ async def show_approval(database, stream, *, approval_id, tool_call_id):+ shown.append((stream["run_id"], approval_id, tool_call_id))++ monkeypatch.setattr(parts, "show_approval", show_approval)+ await rules.set_ask_first(harness.database, "wf", True)+ stream = {"run_id": "r_1", "session_id": "wf", "workflow_id": "wf"}+ checked = await tool_calls.check(call(chat_stream=stream, chat_run_id="r_1"), get_node_class("whatsappSend"))+ (row,) = await store.list_approvals(harness.database, status="pending")+ assert row.run_id == "r_1" and shown == [("r_1", checked.result["approval_id"], "call_1")]+++async def test_with_ask_first_off_a_chat_call_runs_and_is_recorded(harness, nodes_loaded, monkeypatch):+ from services.chat import parts++ async def show_approval(database, stream, **_):+ return None++ monkeypatch.setattr(parts, "show_approval", show_approval)+ await rules.set_ask_first(harness.database, "wf", False)+ node_cls = get_node_class("whatsappSend")+ assert await tool_calls.check(call(), node_cls) is tool_calls.RUN+ stream = {"run_id": "r_1", "session_id": "wf", "workflow_id": "wf"}+ checked = await tool_calls.check(call(chat_stream=stream), node_cls)+ assert checked.result is None and checked.record is not None+ await checked.record({"success": True, "result": {"sent": True}})+ (row,) = await store.list_approvals(harness.database, status="sent")+ assert (row.approved_by, row.outcome) == ("auto", "sent")+++async def test_tools_that_cannot_wait_are_refused_or_restricted(harness, nodes_loaded):+ await rules.set_ask_first(harness.database, "wf", True)+ refused = await tool_calls.check(call("stripeAction", {"command": "refunds create --charge ch_1"}), get_node_class("stripeAction"))+ assert refused.result["result"]["status"] == "not_run"+ browsing = call("browser", {"operation": "click", "ref": "e3", "interaction": "full"}, node_data={"interaction": "full"})+ restricted = await tool_calls.check(browsing, get_node_class("browser"))+ assert restricted.result is None+ assert restricted.node_data["interaction"] == "read_only" and "interaction" not in restricted.tool_args+ assert await store.list_approvals(harness.database) == []+++async def test_send_starts_the_send_and_puts_it_back_when_nothing_can(harness, nodes_loaded, monkeypatch):+ await rules.set_ask_first(harness.database, "wf", True)+ await tool_calls.check(call(), get_node_class("whatsappSend"))+ (row,) = await store.list_approvals(harness.database, status="pending")+ started = []++ async def start_send(approved):+ started.append((approved.id, approved.revision))++ monkeypatch.setattr(execution, "start_send", start_send)+ sent = await handle_decide_approval(+ {"approval_id": row.id, "decision": "send", "decision_key": "k1", "text": "Running late, there at 10:15."}, SOCKET+ )+ assert sent["success"] is True and sent["approval"]["status"] == "approved"+ stored = await store.get(harness.database, row.id)+ assert started == [(row.id, stored.revision)]+ assert stored.args["message"] == "Running late, there at 10:15." == stored.node_data["message"]++ async def unavailable(approved):+ raise RuntimeError("no engine")++ undone = await handle_decide_approval({"approval_id": row.id, "decision": "undo", "decision_key": "k2"}, SOCKET)+ assert undone["approval"]["status"] == "pending"+ monkeypatch.setattr(execution, "start_send", unavailable)+ failed = await handle_decide_approval({"approval_id": row.id, "decision": "send", "decision_key": "k3"}, SOCKET)+ assert failed["error"] == "send_unavailable" and failed["approval"]["status"] == "pending"+++async def test_a_send_runs_once_under_its_claim(harness, nodes_loaded, monkeypatch):+ await rules.set_ask_first(harness.database, "wf", True)+ stream = {"run_id": "r_1", "session_id": "wf", "workflow_id": "wf"}+ from services.chat import parts++ async def show_approval(database, stream, **_):+ return None++ monkeypatch.setattr(parts, "show_approval", show_approval)+ await tool_calls.check(call(chat_stream=stream), get_node_class("whatsappSend"))+ (row,) = await store.list_approvals(harness.database, status="pending")++ async def start_send(approved):+ return None++ monkeypatch.setattr(execution, "start_send", start_send)+ await handle_decide_approval({"approval_id": row.id, "decision": "send", "decision_key": "k1"}, SOCKET)+ approved = await store.get(harness.database, row.id)++ # A claim for an older revision (an Undo and a new Send came after it) is refused.+ assert (await execution.claim_send(harness.database, row.id, approved.revision - 1, "t-old"))["claimed"] is False+ claim = await execution.claim_send(harness.database, row.id, approved.revision, "t-1")+ assert claim["claimed"] is True and claim["activity"] == f"node.whatsappSend.v{get_node_class('whatsappSend').version}"+ assert claim["context"]["approval_execution"] == {"approval_id": row.id, "claim_token": "t-1"}+ assert claim["context"]["tool_args"]["phone"] == "447700900123"+ # The same claim again (an activity retry) finds itself; another does not.+ assert (await execution.claim_send(harness.database, row.id, approved.revision, "t-1"))["claimed"] is True+ assert (await execution.claim_send(harness.database, row.id, approved.revision, "t-2"))["claimed"] is False++ # The node runs only under that claim.+ node_cls = get_node_class("whatsappSend")+ assert await tool_calls.check(claim["context"], node_cls) is tool_calls.RUN+ other = {**claim["context"], "approval_execution": {"approval_id": row.id, "claim_token": "t-2"}}+ assert (await tool_calls.check(other, node_cls)).result["error_type"] == "ApprovalNotClaimed"++ settled = await execution.record_outcome(harness.database, row.id, "t-1", "sent", None)+ assert settled.status == "sent" and settled.outcome == "sent"+ assert await execution.record_outcome(harness.database, row.id, "t-1", "sent", None) is None+ from services.chat import notes++ (note,) = await notes.claim_notes(harness.database, session_id="wf", run_id="r_next")+ assert note.kind == "update" and '"result": "sent"' in note.text+++async def test_a_send_that_broke_off_asks_before_trying_again(harness, nodes_loaded, monkeypatch):+ await rules.set_ask_first(harness.database, "wf", True)+ await tool_calls.check(call(), get_node_class("whatsappSend"))+ (row,) = await store.list_approvals(harness.database, status="pending")++ async def start_send(approved):+ return None++ monkeypatch.setattr(execution, "start_send", start_send)+ await handle_decide_approval({"approval_id": row.id, "decision": "send", "decision_key": "k1"}, SOCKET)+ approved = await store.get(harness.database, row.id)+ await execution.claim_send(harness.database, row.id, approved.revision, "t-1")+ failed = await execution.record_outcome(harness.database, row.id, "t-1", "unknown", "TimeoutError: no answer")+ assert failed.status == "failed" and failed.outcome == "unknown"+ ask = await handle_decide_approval({"approval_id": row.id, "decision": "retry", "decision_key": "k2"}, SOCKET)+ assert ask["error"] == "confirm_required"+ again = await handle_decide_approval({"approval_id": row.id, "decision": "retry", "decision_key": "k3", "confirm": True}, SOCKET)+ assert again["success"] is True and again["approval"]["status"] == "approved" and "outcome" not in again["approval"]+++async def test_clearing_the_chat_cancels_its_drafts(harness, nodes_loaded, monkeypatch):+ from services.chat import ledger, parts+ from services.chat_thread import clear_chat_thread++ async def show_approval(database, stream, **_):+ return None++ monkeypatch.setattr(parts, "show_approval", show_approval)+ monkeypatch.setattr(ledger, "session_run_ids", lambda database, session_id: _async(["r_1"]))+ await rules.set_ask_first(harness.database, "wf", True)+ await tool_calls.check(call(chat_stream={"run_id": "r_1", "session_id": "wf"}, chat_run_id="r_1"), get_node_class("whatsappSend"))+ await tool_calls.check({**call(), "tool_call_id": "call_2"}, get_node_class("whatsappSend"))+ await clear_chat_thread(harness.database, "wf")+ statuses = sorted((row.tool_call_id, row.status) for row in await store.list_approvals(harness.database))+ assert statuses == [("call_1", "cancelled"), ("call_2", "pending")]+++async def _async(value):+ return valuediff --git a/server/tests/temporal/test_approved_tool_call_workflow.py b/server/tests/temporal/test_approved_tool_call_workflow.pynew file mode 100644index 00000000..b7bb8ce0--- /dev/null+++ b/server/tests/temporal/test_approved_tool_call_workflow.py@@ -0,0 +1,116 @@+"""``ApprovedToolCallWorkflow`` on Temporal's time-skipping test server: it+sends only after the Undo window, never when its claim is refused (the+owner undid or sent again), runs the node's activity exactly once even when+it fails, and records a send that broke off as ``unknown``.++Runs in a clean process (valid Windows I/O handles), like the other SDK+gates."""++from __future__ import annotations++import asyncio+import subprocess+import sys+from datetime import datetime, timedelta, timezone+from pathlib import Path+from typing import Any, Dict, List+from uuid import uuid4++TASK_QUEUE = "approved-send-test"+++async def _scenarios() -> None:+ from temporalio import activity+ from temporalio.testing import WorkflowEnvironment+ from temporalio.worker import Worker++ from services.temporal.approved_tool_call_workflow import ApprovedToolCallWorkflow++ calls: Dict[str, List[Dict[str, Any]]] = {"claim": [], "send": [], "record": []}+ behaviour: Dict[str, Any] = {"claimed": True, "send": "ok"}++ @activity.defn(name="approvals.claim_send")+ async def claim(payload: Dict[str, Any]) -> Dict[str, Any]:+ calls["claim"].append({**payload, "at": activity.info().current_attempt_scheduled_time})+ if not behaviour["claimed"]:+ return {"claimed": False, "reason": "changed"}+ return {"claimed": True, "activity": "node.fakeSend.v1", "context": {"node_id": "n", "approval_execution": {"approval_id": payload["approval_id"]}}}++ @activity.defn(name="node.fakeSend.v1")+ async def send(context: Dict[str, Any]) -> Dict[str, Any]:+ calls["send"].append(context)+ if behaviour["send"] == "raise":+ raise RuntimeError("connection reset")+ if behaviour["send"] == "refused":+ return {"success": False, "error": "Recipient not on WhatsApp"}+ return {"success": True, "result": {"message_id": "m1"}}++ @activity.defn(name="approvals.record_outcome")+ async def record(payload: Dict[str, Any]) -> Dict[str, Any]:+ calls["record"].append(payload)+ if payload.get("broke_off"):+ return {"recorded": True, "status": "failed", "outcome": "unknown"}+ if payload.get("success") is False:+ return {"recorded": True, "status": "failed", "outcome": "not_sent"}+ return {"recorded": True, "status": "sent", "outcome": "sent"}++ async with await WorkflowEnvironment.start_time_skipping() as environment:+ async with Worker(environment.client, task_queue=TASK_QUEUE, workflows=[ApprovedToolCallWorkflow], activities=[claim, send, record]):++ async def run(grace_seconds: float = 5.0) -> Dict[str, Any]:+ now = await environment.get_current_time()+ grace = (now + timedelta(seconds=grace_seconds)).astimezone(timezone.utc).isoformat()+ handle = await environment.client.start_workflow(+ ApprovedToolCallWorkflow.run,+ {"payload_version": 1, "approval_id": "a1", "revision": 3, "grace_until": grace},+ id=f"approval-send-{uuid4()}",+ task_queue=TASK_QUEUE,+ )+ return await handle.result()++ # Sent after the grace, once.+ started = await environment.get_current_time()+ result = await run()+ assert result == {"sent": True, "outcome": "sent"}, result+ assert len(calls["claim"]) == 1 and calls["claim"][0]["revision"] == 3+ claimed_at = calls["claim"][0]["at"]+ assert claimed_at - started >= timedelta(seconds=4.9), (started, claimed_at)+ assert len(calls["send"]) == 1 and len(calls["record"]) == 1++ # Claim refused (Undo, or a newer Send): nothing runs.+ for bucket in calls.values():+ bucket.clear()+ behaviour["claimed"] = False+ result = await run()+ assert result == {"sent": False, "reason": "changed"}+ assert calls["send"] == [] and calls["record"] == []++ # The node refuses: not sent, never retried.+ behaviour.update(claimed=True, send="refused")+ result = await run(0)+ assert result == {"sent": False, "outcome": "not_sent"}+ assert len(calls["send"]) == 1 and calls["record"][-1]["error"] == "Recipient not on WhatsApp"++ # The node breaks off: unknown, never retried.+ calls["send"].clear()+ behaviour["send"] = "raise"+ result = await run(0)+ assert result == {"sent": False, "outcome": "unknown"}+ assert len(calls["send"]) == 1 and calls["record"][-1]["broke_off"] is True+++def test_the_send_workflow_on_temporal() -> None:+ completed = subprocess.run(+ [sys.executable, "-m", "tests.temporal.test_approved_tool_call_workflow"],+ cwd=Path(__file__).parents[2],+ stdin=subprocess.DEVNULL,+ stdout=subprocess.PIPE,+ stderr=subprocess.STDOUT,+ timeout=180,+ check=False,+ )+ assert completed.returncode == 0, completed.stdout.decode(errors="replace")[-3000:]+++if __name__ == "__main__":+ asyncio.run(_scenarios())