Skip to content

Self-improving AI Employees for everyone

feat(approvals): hold sending tool calls for the owner, live Ask first

trohitg7c38f6c5b9ee
diff --git a/server/core/database.py b/server/core/database.py
index 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 tables
WorkflowRunRecord,
)
from models.approvals import ( # noqa: F401 - registers SQLModel tables
+ ApprovalDecision,
ApprovalRequest,
+ WorkflowRule,
)
from models.chat import ( # noqa: F401 - registers SQLModel tables
ChatNote,
@@ -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.py
index 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.py
index 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 annotations
from 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, UniqueConstraint
from 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__.py
index 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_serial
from core.logging import get_logger
from services.plugin import NodeContext, Operation, TaskQueue, ToolNode
+from services.plugin.approval import ApprovalSpec
from services.plugin.base import NodeUserError
from 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.py
index 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, Optional
from pydantic import BaseModel, ConfigDict, Field
from services.plugin import NodeContext, NodeUserError, Operation, TaskQueue
+from services.plugin.approval import ApprovalSpec
from . import _base
from ._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 = False
diff --git a/server/nodes/email/email_send/__init__.py b/server/nodes/email/email_send/__init__.py
index 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, Optional
from pydantic import BaseModel, ConfigDict, Field
from services.plugin import ActionNode, NodeContext, Operation, TaskQueue
+from services.plugin.approval import ApprovalSpec
class EmailSendParams(BaseModel):
@@ -52,6 +53,16 @@ class EmailSendNode(ActionNode):
annotations = {"destructive": False, "readonly": False, "open_world": True}
task_queue = TaskQueue.MESSAGING
usable_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 = EmailSendParams
Output = EmailSendOutput
diff --git a/server/nodes/google/calendar/__init__.py b/server/nodes/google/calendar/__init__.py
index 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, Optional
from pydantic import BaseModel, ConfigDict, Field
from services.plugin import ActionNode, NodeContext, Operation, TaskQueue
+from services.plugin.approval import ApprovalSpec
from .._credentials import GoogleCredential
@@ -111,6 +112,18 @@ class CalendarNode(ActionNode):
credentials = (GoogleCredential,)
task_queue = TaskQueue.REST_API
usable_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 = CalendarParams
Output = CalendarOutput
diff --git a/server/nodes/google/drive/__init__.py b/server/nodes/google/drive/__init__.py
index 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, MediaIoBaseUpload
from pydantic import BaseModel, ConfigDict, Field
from services.plugin import ActionNode, NodeContext, Operation, TaskQueue
+from services.plugin.approval import ApprovalSpec
from .._credentials import GoogleCredential
@@ -110,6 +111,14 @@ class DriveNode(ActionNode):
credentials = (GoogleCredential,)
task_queue = TaskQueue.REST_API
usable_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 = DriveParams
Output = DriveOutput
diff --git a/server/nodes/google/gmail/__init__.py b/server/nodes/google/gmail/__init__.py
index 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, Optional
from pydantic import BaseModel, ConfigDict, Field
from services.plugin import ActionNode, NodeContext, Operation, TaskQueue
+from services.plugin.approval import ApprovalSpec
from .._credentials import GoogleCredential
@@ -113,6 +114,15 @@ class GmailNode(ActionNode):
annotations = {"destructive": False, "readonly": False, "open_world": True}
task_queue = TaskQueue.REST_API
usable_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 = GmailParams
Output = GmailOutput
diff --git a/server/nodes/microsoft/calendar/__init__.py b/server/nodes/microsoft/calendar/__init__.py
index 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, Optional
from pydantic import BaseModel, ConfigDict, Field
from services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueue
+from services.plugin.approval import ApprovalSpec
from .._base import graph_request, mailbox_base, track_microsoft_usage
from .._credentials import MicrosoftCredential
@@ -136,6 +137,16 @@ class CalendarNode(ActionNode):
annotations = {"destructive": False, "readonly": False, "open_world": True}
task_queue = TaskQueue.REST_API
usable_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 = CalendarParams
Output = CalendarOutput
diff --git a/server/nodes/microsoft/mail/__init__.py b/server/nodes/microsoft/mail/__init__.py
index 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, Optional
from pydantic import BaseModel, ConfigDict, Field
from services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueue
+from services.plugin.approval import ApprovalSpec
from .._base import graph_request, mailbox_base, track_microsoft_usage, write_attachment_bytes
from .._credentials import MicrosoftCredential
@@ -166,6 +167,18 @@ class MailNode(ActionNode):
annotations = {"destructive": False, "readonly": False, "open_world": True}
task_queue = TaskQueue.REST_API
usable_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 = MailParams
Output = MailOutput
diff --git a/server/nodes/stripe/stripe_action.py b/server/nodes/stripe/stripe_action.py
index 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, Field
from services.events import run_cli_command
from services.plugin import ActionNode, NodeContext, Operation, TaskQueue
+from services.plugin.approval import ApprovalSpec
from ._credentials import StripeCredential
@@ -53,6 +54,13 @@ class StripeActionNode(ActionNode):
credentials = (StripeCredential,)
task_queue = TaskQueue.REST_API
usable_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 = StripeActionParams
Output = StripeActionOutput
diff --git a/server/nodes/telegram/telegram_send.py b/server/nodes/telegram/telegram_send.py
index 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, Optional
from pydantic import BaseModel, ConfigDict, Field, field_validator
from services.plugin import ActionNode, NodeContext, Operation, TaskQueue
+from services.plugin.approval import ApprovalSpec
from ._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 = TelegramSendParams
Output = TelegramSendOutput
diff --git a/server/nodes/whatsapp/whatsapp_send.py b/server/nodes/whatsapp/whatsapp_send.py
index 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, Optional
from pydantic import BaseModel, ConfigDict, Field
from services.plugin import ActionNode, NodeContext, Operation, TaskQueue
+from services.plugin.approval import ApprovalSpec
class WhatsAppSendParams(BaseModel):
@@ -278,6 +279,17 @@ class WhatsAppSendNode(ActionNode):
annotations = {"destructive": False, "readonly": False, "open_world": True}
task_queue = TaskQueue.MESSAGING
usable_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 = WhatsAppSendParams
Output = WhatsAppSendOutput
diff --git a/server/nodes/whatsapp_business/whatsapp_business_send.py b/server/nodes/whatsapp_business/whatsapp_business_send.py
index 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, Optional
from pydantic import BaseModel, ConfigDict, Field, field_validator
from services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueue
+from services.plugin.approval import ApprovalSpec
from ._base import (
graph_get,
@@ -403,6 +404,27 @@ class WhatsAppBusinessSendNode(ActionNode):
annotations = {"destructive": False, "readonly": False, "open_world": True}
task_queue = TaskQueue.MESSAGING
usable_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 are
diff --git a/server/nodes/workflow/approval_gate/__init__.py b/server/nodes/workflow/approval_gate/__init__.py
index 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, Tuple
from pydantic import BaseModel, ConfigDict, Field, field_validator
from core.logging import get_logger
-from services.approvals import store, waiter
+from services.approvals import rules, store, waiter
from services.approvals.contract import APPROVAL_GATE_TYPE, DEFAULT_TIMEOUT_HOURS, NO_REPLY
from services.approvals.listeners import change_of, notify_approval_changed
from 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 | skipped
status: str = "skipped"
skipped: bool = False
text: str = ""
@@ -98,6 +103,8 @@ class ApprovalGateOutput(BaseModel):
recipient_label: str = ""
approval_id: Optional[str] = None
edited: bool = False
+ #: It went without asking: Ask first was off.
+ automatic: bool = False
def _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 row
if _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)
@classmethod
async 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.py
deleted file mode 100644
index 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.py
deleted file mode 100644
index 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__.py
index 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.py
new file mode 100644
index 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.py
index 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`` are
empty 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.0
def 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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 annotations
import inspect
from dataclasses import dataclass
-from typing import Any, Callable, List
+from typing import Any, Callable, List, Optional
from 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 | cancelled
stage: str
approval_id: str
workflow_id: str
status: str
revision: int
+ #: The chat run a held tool call was made in.
+ run_id: Optional[str] = None
ApprovalListener = 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.py
index 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 process
that 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, timezone
from typing import Any, List
from 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":
+ continue
orphaned = False
if row.runtime == "local":
orphaned = _aware(row.created_at) < started_at
@@ -54,6 +69,43 @@ async def cancel_orphaned_pending(database: Any, *, started_at: datetime = PROCE
return 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 _done
if _done:
@@ -61,6 +113,7 @@ async def reconcile_once(database: Any) -> None:
_done = True
try:
await cancel_orphaned_pending(database)
+ await recover_sends(database)
except Exception:
_done = False
logger.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.py
new file mode 100644
index 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.py
index 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, like
services.employees.store. They never import ``nodes/``.
@@ -9,16 +9,16 @@ from __future__ import annotations
import uuid
from 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_, update
from sqlalchemy.exc import IntegrityError
from sqlmodel import select
-from models.approvals import ApprovalRequest
+from models.approvals import ApprovalDecision, ApprovalRequest
from 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[ApprovalRe
async 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_FIELDS
if 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[str
return 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 None
return 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):
+ continue
try:
- 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:
continue
return 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.action
subject = row.final_subject if decided and row.final_subject else row.subject
if subject:
out["subject"] = subject
if 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] = value
if deployment_state:
out["deployment_state"] = deployment_state
return 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.py
new file mode 100644
index 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.py
index 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.py
index 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 be
saved 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: str
return 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 False
current = 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.py
index 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, and
its 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 end
with ``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 = "re
except 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 = "re
return 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 owner
clears a workflow's chat. Registering the same listener twice is a
diff --git a/server/services/employees/__init__.py b/server/services/employees/__init__.py
index 2b275ecd..71e678c8 100644
--- a/server/services/employees/__init__.py
+++ b/server/services/employees/__init__.py
@@ -15,6 +15,8 @@ import time
from typing import Any
from 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_seeder
from services.deployment.control import register_control_listener as _register_control_listener
from services.workflow_storage.hooks import register_workflow_deleted_hook as _register_deleted_hook
from 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.py
index 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 = 3
AGENT_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.py
new file mode 100644
index 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.py
index 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] = False
chat_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 result
chat_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.py
new file mode 100644
index 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.py
index 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 NodeInvocationWorkflow
from services.temporal.workspace_tasks_workflow import WorkspaceTaskControllerWorkflow
+ from services.temporal.approved_tool_call_workflow import ApprovedToolCallWorkflow
return [
+ ApprovedToolCallWorkflow,
NodeInvocationWorkflow,
WorkspaceTaskControllerWorkflow,
MachinaWorkflow,
@@ -227,6 +229,7 @@ class TemporalWorkerManager:
from services.temporal.agent_activities import collect_agent_activities
from services.temporal.workspace_task_activities import reset_workspace_task_runtime
from services.chat.activities import CHAT_RUN_ACTIVITIES
+ from services.approvals.activities import APPROVAL_ACTIVITIES
from 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_activities
from services.temporal.workspace_task_activities import reset_workspace_task_runtime
from services.chat.activities import CHAT_RUN_ACTIVITIES
+ from services.approvals.activities import APPROVAL_ACTIVITIES
from 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_activities
from services.temporal.workspace_task_activities import reset_workspace_task_runtime
from services.chat.activities import CHAT_RUN_ACTIVITIES
+ from services.approvals.activities import APPROVAL_ACTIVITIES
from 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.py
index 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_module
import services.status_broadcaster as status_broadcaster
- from services.approvals import reconcile, waiter
+ from services.approvals import decisions, reconcile, waiter
import 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.py
index 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_approval
return 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_approvals
task = 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 value
diff --git a/server/tests/temporal/test_approved_tool_call_workflow.py b/server/tests/temporal/test_approved_tool_call_workflow.py
new file mode 100644
index 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())