Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
"""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``.
Nothing goes while its employee is stopped (:func:`send_state`): the claim
refuses, the row stays approved (Undo still works), and the chat watchdog's
round starts the send again after Resume (``reconcile.recover_sends``). A
send whose generation ended is cancelled, and the employee told
(:func:`cancel_ended`). A call its turn waits on is its turn's: the turn
waited for Resume before it claims.
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
#: A generation's control states while it lives, and those in which its
#: employee is stopped.
LIVE_STATES = frozenset({"starting", "running", "pausing", "paused", "resuming"})
STOPPED_STATES = frozenset({"pausing", "paused", "resuming"})
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. A graph node's card (no agent)
keeps what it sent with its templates already resolved: it runs with no
graph, so nothing resolves again and blanks it, and with no tool
arguments, so a tool node keeps the saved operation."""
graph = not row.agent_node_id
return {
"node_id": row.tool_node_id or row.node_id,
"node_type": row.node_type,
"node_data": dict(row.node_data or {}),
**({} if graph else {"tool_args": dict(row.args or {})}),
"inputs": {},
"nodes": None if graph else [],
"edges": None if graph else [],
"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"}
if row.runtime != "turn":
state = send_state(row, await database.get_latest_workflow_control(row.workflow_id))
if state == "wait":
return {"claimed": False, "reason": "stopped"}
if state == "ended":
await cancel_ended(database, row)
return {"claimed": False, "reason": "cancelled"}
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)}
def send_state(row: Any, control: Any) -> str:
"""Whether an approved draft may go now, given its workflow's latest
control row: ``send``; ``wait`` while its employee is stopped; ``ended``
when its generation is over (no control, a newer generation, or one
that no longer lives). A manual run's draft (generation 0) always goes."""
if not row.generation:
return "send"
if control is None or control.generation != row.generation or control.status not in LIVE_STATES:
return "ended"
return "wait" if control.status in STOPPED_STATES else "send"
async def cancel_ended(database: Any, row: Any) -> Optional[Any]:
"""Cancel an approved draft whose generation ended: it never goes, and
the employee hears so. None when the row moved meanwhile."""
try:
cancelled = await store.transition(
database,
row.id,
expected_revision=row.revision,
from_statuses=("approved",),
status="cancelled",
values={"decided_at": _utcnow(), "grace_until": None},
)
except store.ApprovalConflict:
return None
logger.info("Cancelled a send whose generation ended", approval_id=row.id, workflow_id=row.workflow_id)
await notify_approval_changed(change_of(cancelled, "cancelled"))
await tell_employee(database, cancelled)
return cancelled
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."""
maybe = "may or may not have happened" if row.kind == "effect" else "may or may not have gone out"
result = {
"sent": "sent",
"failed": "not sent" if row.outcome == "not_sent" else maybe,
"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]
if row.status == "discarded" and row.note:
payload["owner_note"] = row.note
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). A call its turn waits on hears it there."""
text = update_note(row)
if text is None or not row.workflow_id or row.runtime == "turn":
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__ = [
"LIVE_STATES",
"PAYLOAD_VERSION",
"STOPPED_STATES",
"SendUnavailable",
"WORKFLOW_NAME",
"cancel_ended",
"claim_send",
"node_activity_name",
"node_context",
"outcome_of",
"record_outcome",
"send_payload",
"send_state",
"send_workflow_id",
"start_send",
"tell_employee",
"update_note",
]