Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
"""Durable, execution-scoped task control for agent team leads."""
from __future__ import annotations
from typing import Any, Dict, List, Literal, Optional
from pydantic import BaseModel, ConfigDict, Field
from services.plugin import NodeContext, Operation, TaskQueue, ToolNode
TaskOperation = Literal[
"submit_job",
"assign_task", "list_tasks", "get_task", "modify_task", "cancel_task",
"retry_task", "reassign_task", "accept_task", "finish_team", "mark_done",
"inspect_task_trace",
]
class TaskManagerParams(BaseModel):
operation: TaskOperation = "list_tasks"
task_id: Optional[str] = None
title: Optional[str] = Field(default=None, max_length=500)
mission: Optional[str] = Field(default=None, max_length=10000)
context: Optional[Dict[str, Any]] = None
acceptance_criteria: Optional[Dict[str, Any]] = None
depends_on: Optional[List[str]] = None
assignee_node_id: Optional[str] = None
delegate_name: Optional[str] = None
expected_revision: Optional[int] = Field(default=None, ge=0)
reason: Optional[str] = Field(default=None, max_length=2000)
status_filter: Optional[str] = None
include_history: bool = False
attempt: Optional[int] = Field(default=None, ge=0)
cursor: Optional[str] = None
limit: int = Field(default=50, ge=1, le=100)
detail: Literal["summary", "failures", "timeline", "search"] = "summary"
query: Optional[str] = Field(default=None, max_length=200)
search_mode: Literal["literal", "all_terms", "any_terms"] = "literal"
case_sensitive: bool = False
context_lines: int = Field(default=2, ge=0, le=5)
scan_limit: int = Field(default=250, ge=1, le=500)
categories: Optional[List[Literal["failure", "activity", "child", "signal", "timer", "workflow"]]] = None
model_config = ConfigDict(extra="allow")
class TaskManagerOutput(BaseModel):
success: bool = True
operation: Optional[str] = None
task: Optional[dict] = None
tasks: Optional[list] = None
team: Optional[dict] = None
model_config = ConfigDict(extra="allow")
class TaskManagerNode(ToolNode):
type = "taskManager"
display_name = "Task Manager"
subtitle = "Durable Team Tasks"
group = ("tool", "ai")
description = "Assign, review, retry, reassign, cancel, and accept durable teammate tasks"
component_kind = "tool"
tool_name = "task_manager"
tool_description = (
"Manage the current lead execution's durable team tasks. Assign only connected "
"teammates, inspect submitted work, then accept, retry, reassign, or cancel it. "
"Use list_tasks with include_history=true to consult prior executions. "
"An employee's conversational contact uses submit_job with mission to admit substantive work "
"for its configured team and receive a prompt acknowledgement; reviewed delivery follows separately."
)
handles = (
{"name": "input-main", "kind": "input", "position": "left", "label": "Input", "role": "main"},
{"name": "output-tool", "kind": "output", "position": "top", "label": "Tool", "role": "tools"},
)
ui_hints = {
"isTaskManagerPanel": True,
"hideInputSection": True,
"hideOutputSection": True,
"hideRunButton": True,
}
annotations = {"destructive": True, "readonly": False, "open_world": False}
task_queue = TaskQueue.DEFAULT
needs_canvas = True
Params = TaskManagerParams
Output = TaskManagerOutput
@Operation("manage")
async def manage(self, ctx: NodeContext, params: TaskManagerParams) -> Any:
config = {
**ctx.raw,
"node_id": ctx.node_id,
"workflow_id": ctx.workflow_id or ctx.raw.get("workflow_id"),
"execution_id": ctx.execution_id or ctx.raw.get("execution_id"),
"nodes": ctx.nodes,
"edges": ctx.edges,
}
return await _execute_task_manager(params.model_dump(exclude_none=True), config)
def _scope(config: Dict[str, Any]) -> Dict[str, Any]:
workflow_id = str(config.get("workflow_id") or "")
lead_id = str(config.get("parent_node_id") or config.get("team_lead_node_id") or "")
if not workflow_id or not lead_id:
raise ValueError("Task Manager requires trusted workflow and team-lead execution context")
execution_id = config.get("team_execution_id") if config.get("employee_job_id") else None
return {"workflow_id": workflow_id, "team_lead_node_id": lead_id, "execution_id": execution_id or config.get("execution_id")}
def _resolve_teammate(config: Dict[str, Any], args: Dict[str, Any]) -> Dict[str, Any]:
from services.plugin.edge_walker import build_teammate_descriptors
lead_id = str(config.get("parent_node_id") or config.get("team_lead_node_id") or "")
descriptors = build_teammate_descriptors(lead_id, config)
node_id, delegate_name = args.get("assignee_node_id"), args.get("delegate_name")
matches = [d for d in descriptors if (node_id and d["node_id"] == node_id) or (delegate_name and d["delegate_tool_name"] == delegate_name)]
if len(matches) != 1:
available = [{"node_id": d["node_id"], "delegate_name": d["delegate_tool_name"], "label": d["label"]} for d in descriptors]
raise ValueError(f"Assignee must resolve to exactly one connected teammate; available={available}")
return matches[0]
async def _execute_task_manager(args: Dict[str, Any], config: Dict[str, Any]) -> Dict[str, Any]:
from services.agent_team import get_agent_team_service
service = get_agent_team_service()
operation = str(args.get("operation") or "list_tasks")
allowed_operations = {
"submit_job",
"assign_task", "list_tasks", "get_task", "modify_task", "cancel_task",
"retry_task", "reassign_task", "accept_task", "finish_team", "mark_done",
"inspect_task_trace",
}
if operation not in allowed_operations:
raise ValueError(f"Unknown Task Manager operation: {operation}")
if operation == "submit_job":
from services.plugin.deps import get_database
from services.employees.team_runtime import employee_runtime_plan
from services.employees.jobs import create_job, dispatch_job
database = get_database()
talk_id = str(config.get("parent_node_id") or "")
plan = await employee_runtime_plan(database, {**config, "node_id": talk_id})
if not plan or plan.get("talk_node_id") != talk_id:
raise ValueError("submit_job is available only to this employee's conversational contact")
mission = str(args.get("mission") or "").strip()
if not mission:
raise ValueError("submit_job requires the substantive mission and expected result")
job = await create_job(database, NodeContext.from_legacy(talk_id, "chatAgent", config), mission=mission,
lead_node_id=plan["lead_node_id"], delivery_node_ids=plan["talk_delivery_node_ids"], dispatch=True)
await dispatch_job(database, job.id)
return {"success": True, "operation": operation, "job_id": job.id, "state": job.state,
"acknowledgement": "I've given this to the team. I'll share their checked result here."}
scope = _scope(config)
if operation == "list_tasks":
if args.get("include_history"):
tasks = await service.list_durable_task_history(
workflow_id=scope["workflow_id"],
team_lead_node_id=scope["team_lead_node_id"],
status=args.get("status_filter"),
)
else:
tasks = await service.list_durable_tasks(**scope, status=args.get("status_filter"))
return {"success": True, "operation": operation, "tasks": tasks, "count": len(tasks)}
if operation == "get_task":
task_id = str(args.get("task_id") or "")
if not task_id:
raise ValueError("get_task requires task_id")
task = await service.get_durable_task(**scope, task_id=task_id)
return {"success": True, "operation": operation, "task": task}
if operation == "inspect_task_trace":
task_id = str(args.get("task_id") or "")
if not task_id:
raise ValueError("inspect_task_trace requires task_id")
from services.team_task_trace import get_team_task_trace_service
trace = await get_team_task_trace_service().get_trace(
**scope, task_id=task_id, attempt=args.get("attempt"),
cursor=args.get("cursor"), limit=int(args.get("limit") or 50),
detail=str(args.get("detail") or "summary"),
query=args.get("query"), search_mode=str(args.get("search_mode") or "literal"),
case_sensitive=bool(args.get("case_sensitive", False)),
context_lines=int(args.get("context_lines", 2)),
scan_limit=int(args.get("scan_limit", 250)), categories=args.get("categories"),
)
return {"success": True, "operation": operation, "trace": trace}
if operation == "assign_task":
from services.employees.team_runtime import validate_managed_assignment
validate_managed_assignment(args, config)
if not args.get("title") or not args.get("mission"):
raise ValueError("assign_task requires title and mission")
teammate = _resolve_teammate(config, args)
task = await service.assign_durable_task(
**scope, assignee_node_id=teammate["node_id"], title=args["title"],
mission=args["mission"], context=args.get("context"),
acceptance_criteria=args.get("acceptance_criteria"), depends_on=args.get("depends_on"),
trace_id=config.get("tool_call_id"),
)
delegation = None
if config.get("ai_service") and config.get("database"):
from services.handlers.tools import _execute_delegated_agent
child_config = {
**config,
"node_id": teammate["node_id"],
"node_type": teammate["node_type"],
"team_id": task["team_id"],
}
delegation = await _execute_delegated_agent(
{"task": args["mission"], "context": {**(args.get("context") or {}),
"acceptance_criteria": args.get("acceptance_criteria"), "depends_on": args.get("depends_on") or []}},
child_config,
precreated_task_id=task["id"],
)
# Temporal AgentWorkflow consumes this trusted scheduling envelope and
# starts the matching child through its existing bounded child-workflow
# machinery. Legacy execution may consume it through the shared
# delegation coordinator without creating a second TeamTask.
return {
"success": True, "operation": operation, "task": task,
"delegation": delegation,
"delegation_request": {
"team_task_id": task["id"], "assignee_node_id": teammate["node_id"],
"delegate_name": teammate["delegate_tool_name"], "task": args["mission"],
"context": args.get("context") or {},
"acceptance_criteria": args.get("acceptance_criteria"),
"depends_on": args.get("depends_on") or [],
},
}
if operation == "finish_team":
team = await service.finish_durable_team(**scope)
return {"success": True, "operation": operation, "team": team}
task_id = str(args.get("task_id") or "")
revision = args.get("expected_revision", args.get("revision"))
# Completion review commonly follows immediately after one child result.
# Resolve that unambiguous submitted task inside the trusted execution
# scope instead of leaving it permanently submitted because the model
# omitted identifiers. Never guess when multiple reviews are pending.
if not task_id and operation in {"accept_task", "mark_done"}:
submitted = await service.list_durable_tasks(**scope, status="submitted")
if len(submitted) == 1:
task_id = submitted[0]["id"]
revision = submitted[0]["revision"]
else:
raise ValueError(
"accept_task requires task_id when there is not exactly one submitted task; "
"call list_tasks or get_task first"
)
if not task_id:
raise ValueError(f"{operation} requires task_id")
current: Optional[Dict[str, Any]] = None
if revision is None:
current = await service.get_durable_task(**scope, task_id=task_id)
revision = current.get("revision")
if revision is None:
raise ValueError(f"{operation} requires expected_revision")
mapped = "accept" if operation in {"accept_task", "mark_done"} else operation.removesuffix("_task")
payload = {k: args[k] for k in ("title", "mission", "context", "acceptance_criteria", "reason") if k in args}
# Resolve the runner BEFORE mutating so a disconnected assignee fails
# the operation cleanly instead of flipping the row and then stalling.
delegate: Optional[Dict[str, Any]] = None
if operation == "reassign_task":
delegate = _resolve_teammate(config, args)
payload["assignee_node_id"] = delegate["node_id"]
elif operation == "retry_task":
if current is None:
current = await service.get_durable_task(**scope, task_id=task_id)
delegate = _resolve_teammate(
config, {"assignee_node_id": current.get("assigned_to")}
)
task = await service.mutate_durable_task(
**scope, task_id=task_id, revision=int(revision), operation=mapped, **payload,
)
result: Dict[str, Any] = {"success": True, "operation": operation, "task": task}
if delegate is not None:
# retry/reassign move the row to "queued", and nothing sweeps queued
# rows — the ONLY runner is this scheduling envelope, which the
# Temporal AgentWorkflow bridges to a DelegatedTaskWorkflow exactly
# like a fresh assign_task. Without it the mutation flipped the DB
# row and the work silently never re-ran.
result["delegation_request"] = {
"team_task_id": task["id"],
"assignee_node_id": delegate["node_id"],
"delegate_name": delegate["delegate_tool_name"],
"task": str(task.get("mission") or task.get("description") or ""),
"context": task.get("context") or {},
}
return result