Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
"""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.
**In a v1 generation** (``approval_wait_version`` 1, RFC-0007 §4.3) the
workflow's mode and the call's class (services/approvals/classes.py) decide,
for every tool an agent calls, spec or not:
- A read runs. So does a call whose class the mode does not ask, or that an
always-allow rule matches (services/approvals/allows.py); one that reaches
out (send, money) and answers the owner in the chat is recorded.
- An asked call is held, on a generic card when its tool has no spec, and
Stripe is held instead of refused. A restricted tool (the Browser) is held
only when it fetches a URL, and runs restricted otherwise.
- A call its turn waits on (``approval_wait``) is a turn row (``runtime:
turn``); any other is a draft.
- A rule that cannot be read asks before everything.
**Agents outside AgentWorkflow** (rlm, claude_code, or every agent
with AgentWorkflow off) reach plugins through ``services/handlers/tools.py``,
which calls :func:`check_in_process`. In a v0 generation such a call cannot
wait as a draft, so while the workflow asks first a call that sends is
refused (a restricted tool runs restricted); no row is written. In a v1
generation it asks as :func:`check` decides, and a held call is a draft
keyed by its call id (an MCP call's request digest); a call with no id is
refused.
**At most once.** Temporal runs an activity again only when an attempt
broke off (the worker stopped, a timeout): a failure the node reports comes
back as a result and is not retried. The attempt that broke off may have done
what it was asked, so a later attempt runs only a call that is safe to repeat
(services/approvals/repeats.py); any other call answers that it may already
have happened (:func:`redo_refusal`), and the owner gets a card
(:func:`record_unknown`, ``outcome: unknown``): "May have sent" for a send
the card can show, with Send again behind a confirmation, else "May have
happened" (an ``effect`` row) with Dismiss. A graph node's answer needs the
owner (``requires_user_action``), so its employee pauses at once; a graph
node's send keeps what it sent, without secrets, for Send again. The owner's
approved sends run with no retry
(services/temporal/approved_tool_call_workflow.py), and the workflow that
claimed one records how it went.
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.
For the same reason a call is judged on what it runs with
(:func:`as_it_runs`): a locked field the model set is put back to the node's
setting first, so it can never talk a call out of being held.
"""
from __future__ import annotations
import json
import uuid
from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
from typing import Any, Awaitable, Callable, Dict, List, 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."
)
#: The same in a v1 generation, where the card's button is Allow.
WAITING_MESSAGE = (
"Not done yet: it waits for the owner's OK on a card in the chat, and runs only if they allow it. "
"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."
)
RESEND_MESSAGE = (
"Not sent again: the first try at this broke off, and it may already have gone out. "
"Do not send it again unless the owner asks; tell them it may or may not have gone out."
)
REDO_MESSAGE = (
"Not run again: the first try at this broke off midway, and it may already have happened. "
"Do not run it again unless the owner asks; tell them it may or may not have happened."
)
#: What a graph node's answer adds: no model reads it, the owner does.
REDO_HINT = "The first try broke off midway, so it may already have happened. Check before you resume the employee."
#: The most of a graph node's send a card keeps for Send again.
MAX_KEPT_SEND = 64 * 1024
@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}
async def as_it_runs(context: Mapping[str, Any], node_cls: Any) -> Dict[str, Any]:
"""The call's ``node_data`` as the node will run with it: each locked
field the model set put back to the node's saved setting (NodeExecutor's
rule). :func:`check` judges the call on this."""
from services.plugin.base import restore_locked_fields, saved_settings
node_data = dict(context.get("node_data") or {})
tool_args = context.get("tool_args")
if not isinstance(tool_args, Mapping) or not (_locked(node_cls) & tool_args.keys()):
return node_data
saved = await saved_settings(_database(), str(context.get("node_id") or ""), context.get("parameter_snapshot"))
return restore_locked_fields(node_cls, node_data, tool_args, saved)
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], message: str = HELD_MESSAGE) -> 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": 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 _asks_first(database: Any, workflow_id: Any) -> Optional[bool]:
"""The workflow's Ask first rule (None: no rule). True when it cannot be
read: hold or refuse the call rather than send it unasked."""
try:
return await rules.ask_first(database, workflow_id)
except Exception:
logger.warning("Could not read the Ask first rule; acting as if it is on", workflow_id=workflow_id, exc_info=True)
return True
async def _ask_mode(database: Any, workflow_id: Any) -> Optional[str]:
"""The workflow's mode (None: no rule). The strictest when it cannot be
read: hold the call rather than run it unasked."""
try:
return await rules.ask_mode(database, workflow_id)
except Exception:
logger.warning("Could not read the Ask first mode; asking before everything", workflow_id=workflow_id, exc_info=True)
return "everything"
async def _allowed(database: Any, context: Mapping[str, Any], node_cls: Any, node_data: Mapping[str, Any]) -> bool:
"""Whether an always-allow rule, or the binding's own Ask first switch,
lets the call run (services/approvals/allows.py). When the rules cannot
be read, the call asks."""
from services.approvals import allows
try:
return await allows.allowed(database, context.get("workflow_id"), node_cls, node_data, context.get("tool_args"))
except Exception:
logger.warning("Could not read the always-allow rules; asking", workflow_id=context.get("workflow_id"), exc_info=True)
return False
def _restricted(spec: Any, node_data: Mapping[str, Any], context: Mapping[str, Any]) -> Checked:
"""Run with the spec's restrictions instead of holding (the Browser,
read-only); the model's arguments cannot lift them."""
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)
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 context.get("approval_wait_version") == 1:
return await _check_by_class(context, node_cls, spec)
if spec is None or not is_agent_tool_call(context):
return RUN
node_data = await as_it_runs(context, node_cls)
if not spec.sends(node_data):
return RUN
database = _database()
asking = await _asks_first(database, context.get("workflow_id"))
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:
return _restricted(spec, node_data, context)
row = await hold(database, context, node_cls, spec, node_data)
return Checked(result=_held(row, node_cls, context))
async def _check_by_class(context: Mapping[str, Any], node_cls: Any, spec: Any) -> Checked:
""":func:`check` in a v1 generation (see the module docstring)."""
from services.approvals.classes import MONEY, READ, SEND, call_data, class_of, fetched_url
if not is_agent_tool_call(context):
return RUN
node_data = await as_it_runs(context, node_cls)
judged = call_data(node_cls, node_data, context.get("tool_args"))
klass = class_of(node_cls, judged, tool_call=True)
if klass == READ:
return RUN
database = _database()
mode = await _ask_mode(database, context.get("workflow_id"))
if mode is None:
return RUN
if klass not in rules.ASKS[mode] or await _allowed(database, context, node_cls, node_data):
if klass in (SEND, MONEY) and isinstance(context.get("chat_stream"), Mapping):
return Checked(record=_auto_recorder(database, context, node_cls, spec, node_data))
return RUN
if spec is not None and spec.restrict_while_asking and not fetched_url(node_cls, judged):
return _restricted(spec, node_data, context)
row = await hold(database, context, node_cls, spec, node_data)
return Checked(result=_held(row, node_cls, context, WAITING_MESSAGE))
async def check_in_process(
context: Mapping[str, Any],
node_cls: Any,
params: Mapping[str, Any],
tool_args: Mapping[str, Any],
) -> Checked:
""":func:`check` for an agent's tool call that reaches the plugin in
process (see the module docstring). ``result`` is the flat answer the
model reads, as ``execute_as_tool`` gives one."""
from services.plugin.approval import approval_spec
from services.plugin.base import restore_locked_fields
spec = approval_spec(node_cls)
if context.get("approval_wait_version") == 1:
return await _check_in_process_by_class(context, node_cls, spec, params, tool_args)
if spec is None or not context.get("parent_node_id"):
return RUN
# Judged on what runs: a locked field comes from the node's settings.
if not spec.sends(restore_locked_fields(node_cls, {**dict(params or {}), **dict(tool_args or {})}, tool_args, params or {})):
return RUN
if not await _asks_first(_database(), context.get("workflow_id")):
return RUN
if spec.restrict_while_asking:
restricted = {**dict(params or {}), **dict(spec.restrict_while_asking)}
args = {k: v for k, v in dict(tool_args or {}).items() if k not in spec.restrict_while_asking}
return Checked(node_data=restricted, tool_args=args)
return Checked(result={"status": "not_run", "message": REFUSED_MESSAGE.format(channel=spec.channel)})
async def _check_in_process_by_class(
context: Mapping[str, Any], node_cls: Any, spec: Any, params: Mapping[str, Any], tool_args: Mapping[str, Any]
) -> Checked:
""":func:`check_in_process` in a v1 generation (RFC-0007 §4.9): the order
of :func:`check`, and a held call is a draft keyed by its call id, which
the owner's Send runs through the node's own activity. A call with no
id is refused: a retry could not find its draft."""
from services.approvals.classes import READ, call_data, class_of, fetched_url
from services.plugin.base import restore_locked_fields
if not context.get("parent_node_id"):
return RUN
# Judged on what runs: a locked field comes from the node's settings.
node_data = restore_locked_fields(node_cls, {**dict(params or {}), **dict(tool_args or {})}, tool_args, params or {})
judged = call_data(node_cls, node_data, tool_args)
klass = class_of(node_cls, judged, tool_call=True)
if klass == READ:
return RUN
database = _database()
mode = await _ask_mode(database, context.get("workflow_id"))
held = {**context, "node_data": node_data, "tool_args": dict(tool_args or {})}
if mode is None or klass not in rules.ASKS[mode] or await _allowed(database, held, node_cls, node_data):
return RUN
if spec is not None and spec.restrict_while_asking and not fetched_url(node_cls, judged):
return _restricted(spec, params or {}, held)
if not context.get("tool_call_id"):
channel = spec.channel if spec is not None else _tool_name(node_cls, getattr(node_cls, "type", ""))
return Checked(result={"status": "not_run", "message": REFUSED_MESSAGE.format(channel=channel)})
row = await hold(database, held, node_cls, spec, node_data)
return Checked(result=_held(row, node_cls, held, WAITING_MESSAGE)["result"])
def _preview(node_cls: Any, spec: Any, data: Mapping[str, Any], args: Mapping[str, Any]) -> Dict[str, Any]:
"""What the card shows: the spec's view of the call, or, for a tool with
no spec, its name and up to six of what it runs with, the call's own
arguments first. A call that fetches a URL shows it."""
from services.approvals.classes import call_data, fetched_url
own = call_data(node_cls, data, args)
if spec is not None:
preview = spec.preview(data)
url = fetched_url(node_cls, own)[:300]
if url and all(line.get("value") != url for line in preview["details"]):
preview["details"] = [{"label": "Address", "value": url}, *preview["details"]]
return preview
node_type = getattr(node_cls, "type", "")
name = _tool_name(node_cls, node_type)
values = {**args, **{key: value for key, value in data.items() if key not in args}}
return {"channel": name, "action": _action(name, node_type, own), "details": _argument_lines(node_cls, values)}
def _tool_name(node_cls: Any, node_type: str) -> str:
return str(getattr(node_cls, "display_name", None) or node_type or "a tool")
def _action(name: str, node_type: str, data: Mapping[str, Any]) -> str:
""""Use {tool}", with the operation the call names, as the class and
repeat tables name each node's operation field."""
from services.approvals.classes import CLASSES_WHEN
from services.approvals.repeats import REPEATABLE_WHEN
field = (CLASSES_WHEN.get(node_type) or REPEATABLE_WHEN.get(node_type) or ("",))[0]
operation = data.get(field) if field else None
return f"Use {name} ({operation})" if isinstance(operation, str) and operation else f"Use {name}"
def _run_id(context: Mapping[str, Any]) -> Optional[str]:
"""The chat run the call was made in: its stream's, else its run scope's
(a CLI or in-process agent's call has no stream)."""
from services.chat.stream import chat_run_id_of
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") or chat_run_id_of(context)
return run_id if isinstance(run_id, str) and run_id else None
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 = _preview(node_cls, spec, data, args)
run_id = _run_id(context)
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,
"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. ``spec``
is None for a tool with no spec (a v1 generation's generic card)."""
fields = _row_fields(context, node_cls, spec, node_data)
if context.get("approval_wait"):
# Its turn waits on it (RFC-0007 §4.6): a turn row, not a draft.
fields["runtime"] = "turn"
fields["expires_at"] = _utcnow() + timedelta(hours=DEFAULT_TIMEOUT_HOURS)
fields["ui_part_id"] = await _ui_part(database, fields.get("run_id"))
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 _ui_part(database: Any, run_id: Any) -> Any:
"""The interface whose button started the run, for "Linked to the form
above" on the card."""
if not isinstance(run_id, str) or not run_id:
return None
try:
from services.chat.ledger import ui_part_of_run
return await ui_part_of_run(database, run_id)
except Exception: # noqa: BLE001 - the card shows without the link
logger.warning("Could not read which interface started a run", run_id=run_id, exc_info=True)
return None
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], *, unknown: bool = False) -> None:
"""Record how the call went; ``unknown``: it may have gone out
(an attempt broke off, see :func:`redo_refusal`). The card words
that itself, so it keeps no error then."""
try:
success = not unknown and 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 ("unknown" if unknown else "not_sent"),
outcome_error=None if success or unknown 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 _attempt() -> int:
"""This activity attempt's number (1 outside an activity)."""
try:
from temporalio import activity
return int(activity.info().attempt)
except Exception: # noqa: BLE001 - not in an activity
return 1
def _sends(spec: Any, data: Mapping[str, Any]) -> bool:
"""A send the card can show, and send again. The browser restricts
instead of holding, and a page action is not one."""
return spec is not None and not spec.restrict_while_asking and spec.sends(data)
async def repeatable_call(context: Mapping[str, Any], node_cls: Any, node_data: Mapping[str, Any]) -> bool:
"""Whether a call may run again after an attempt broke off
(services/approvals/repeats.py), judged on what it runs with: the node's
settings with the call's data over them, locked fields put back. Not
safe when the settings cannot be read."""
from services.approvals.repeats import REPEATABLE, REPEATABLE_WHEN, repeatable
from services.plugin.base import restore_locked_fields, saved_settings
node_type = getattr(node_cls, "type", "")
if node_type in REPEATABLE or node_type not in REPEATABLE_WHEN:
return node_type in REPEATABLE
try:
saved = await saved_settings(_database(), str(context.get("node_id") or ""), context.get("parameter_snapshot"))
except Exception:
logger.warning("Could not read a node's settings; the call will not run again", node_id=context.get("node_id"), exc_info=True)
return False
data = restore_locked_fields(node_cls, {**saved, **dict(node_data or {})}, context.get("tool_args"), saved)
return repeatable(node_cls, data, tool_call=is_agent_tool_call(context))
def unknown_answer(context: Mapping[str, Any], node_cls: Any, node_data: Mapping[str, Any]) -> Dict[str, Any]:
"""What a call that may already have happened answers instead of
running. A graph node's answer needs the owner, so its employee pauses
(MachinaWorkflow reads ``requires_user_action``)."""
from services.plugin.approval import approval_spec
sends = _sends(approval_spec(node_cls), node_data)
answer: Dict[str, Any] = {
"success": False,
"error": RESEND_MESSAGE if sends else REDO_MESSAGE,
"error_type": "SendOutcomeUnknown" if sends else "OutcomeUnknown",
}
if context.get("approval_execution") is None and not is_agent_tool_call(context):
answer.update(hint=REDO_HINT, requires_user_action=True, retryable=False)
return answer
async def redo_refusal(context: Mapping[str, Any], node_cls: Any, node_data: Mapping[str, Any]) -> Optional[Dict[str, Any]]:
"""What a later attempt answers instead of running a call that is not
safe to repeat (see the module docstring), or None to run it."""
if _attempt() <= 1 or await repeatable_call(context, node_cls, node_data):
return None
return unknown_answer(context, node_cls, node_data)
async def record_unknown(
context: Mapping[str, Any],
node_cls: Any,
node_data: Mapping[str, Any],
result: Mapping[str, Any],
*,
checked: Optional[Checked] = None,
) -> None:
"""Leave the owner a card for a call that may already have happened,
best-effort (see the module docstring). A send the owner approved is
recorded by the workflow that claimed it."""
if context.get("approval_execution") is not None:
return
try:
if checked is not None and checked.record is not None:
await checked.record(dict(result), unknown=True)
return
await _record_unknown(context, node_cls, node_data)
except Exception: # noqa: BLE001 - the answer stands without its card
logger.warning("Could not record a call that may have happened", node_id=context.get("node_id"), exc_info=True)
async def _record_unknown(context: Mapping[str, Any], node_cls: Any, node_data: Mapping[str, Any]) -> None:
from services.plugin.approval import approval_spec
database = _database()
spec = approval_spec(node_cls)
fields: Optional[Dict[str, Any]] = None
key = ""
if _sends(spec, node_data):
if is_agent_tool_call(context):
fields, key = _row_fields(context, node_cls, spec, node_data), call_key(context)
else:
sent = await _graph_send(context, node_cls, node_data)
if sent is not None:
fields, key = _row_fields(context, node_cls, spec, sent), _unknown_key("u", context)
if fields is None:
fields, key = _effect_fields(context, node_cls, node_data), _unknown_key("e", context)
now = _utcnow()
fields.update(
status="failed",
approved_by="auto",
decided_at=now,
consumed_at=now,
outcome="unknown",
outcome_at=now,
final_text=fields.get("draft_text"),
)
row, created = await store.get_or_create(database, idempotency_key=key, fields=fields)
if created:
logger.info("A call may have happened", approval_id=row.id, workflow_id=row.workflow_id, kind=row.kind)
await notify_approval_changed(change_of(row, "failed"))
if not row.tool_call_id:
# No model read the answer: a graph node's employee hears it.
from services.approvals.execution import tell_employee
await tell_employee(database, row)
await _show_in_chat(database, context, row)
def _unknown_key(prefix: str, context: Mapping[str, Any]) -> str:
"""One card per call: an agent's call by its id, a graph node's by its
activity, which every attempt shares."""
if is_agent_tool_call(context):
return f"{prefix}:{context.get('workflow_id') or ''}:{context.get('execution_id') or ''}:{context.get('tool_call_id')}"
try:
from temporalio import activity
info = activity.info()
return f"{prefix}:{info.workflow_id}:{info.workflow_run_id}:{info.activity_id}"
except Exception: # noqa: BLE001 - not in an activity
return f"{prefix}:{context.get('workflow_id') or ''}:{context.get('execution_id') or ''}:{context.get('node_id') or ''}"
async def _graph_send(context: Mapping[str, Any], node_cls: Any, node_data: Mapping[str, Any]) -> Optional[Dict[str, Any]]:
"""A graph node's send as it ran, its templates resolved (NodeExecutor's
own steps), without secrets or locked fields: Send again resends it, and
the node's settings put those back. None when it cannot be rebuilt or is
too big to keep."""
from core.container import container
from services.workflow_sanitizer import sanitize_runtime_payload
try:
resolved = await container.workflow_service().prepare_node_parameters(
node_id=str(context.get("node_id") or ""),
node_type=node_cls.type,
parameters=dict(node_data or {}),
nodes=context.get("nodes", []),
edges=context.get("edges", []),
session_id=context.get("session_id", "default"),
execution_id=context.get("execution_id"),
workflow_id=context.get("workflow_id"),
outputs=context.get("inputs", {}),
user_id=str(context.get("user_id") or "owner"),
)
except Exception: # noqa: BLE001 - the card shows what was tried instead
logger.warning("Could not rebuild what a node sent", node_id=context.get("node_id"), exc_info=True)
return None
locked = _locked(node_cls)
kept = {key: value for key, value in sanitize_runtime_payload(dict(resolved or {})).items() if key not in locked}
try:
size = len(json.dumps(kept, default=str))
except (TypeError, ValueError):
return None
return kept if size <= MAX_KEPT_SEND else None
def _effect_fields(context: Mapping[str, Any], node_cls: Any, node_data: Mapping[str, Any]) -> Dict[str, Any]:
"""An ``effect`` row: what was tried and what it ran with (no secrets),
for a card the owner checks and dismisses."""
node_type = getattr(node_cls, "type", None) or str(context.get("node_type") or "")
name = _tool_name(node_cls, node_type)
tool_args = context.get("tool_args")
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": "effect",
"channel": name[:60],
"action": _action(name, node_type, node_data)[:200],
"details": _argument_lines(node_cls, tool_args if isinstance(tool_args, Mapping) else node_data),
"node_type": node_type or 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(context),
}
def _argument_lines(node_cls: Any, values: Mapping[str, Any]) -> List[Dict[str, str]]:
"""Up to six of what a call ran with, each cut at 300 characters, with
secrets and locked fields left out."""
from services.workflow_sanitizer import sanitize_runtime_payload
locked = _locked(node_cls)
lines: List[Dict[str, str]] = []
for key, value in sanitize_runtime_payload(dict(values or {})).items():
if key in locked or value in (None, "", [], {}):
continue
text = value if isinstance(value, str) else json.dumps(value, ensure_ascii=False, default=str)
lines.append({"label": str(key)[:60], "value": text[:300]})
if len(lines) == 6:
break
return lines
def claim_token() -> str:
return uuid.uuid4().hex
__all__ = [
"Checked",
"HELD_MESSAGE",
"REDO_HINT",
"REDO_MESSAGE",
"RESEND_MESSAGE",
"RUN",
"WAITING_MESSAGE",
"as_it_runs",
"call_key",
"check",
"check_in_process",
"claim_token",
"hold",
"is_agent_tool_call",
"record_unknown",
"redo_refusal",
"repeatable_call",
"unknown_answer",
]