taskwarden 0.1.0__py3-none-any.whl

taskwarden/__init__.py

@@ -0,0 +1,9 @@
+"""taskwarden: a durable, owner-approved AI team for a business.
+
+Modules: loop (one task's run), gate (who may run what), tools (Tool, risk tiers, running a
+call), decisions (the owner's approve / edit / decline), sweeper (background runs), replies
+(a customer's reply wakes the task), folders (agents as AGENT.md + skills), models (table
+columns), host (what the app supplies). See README.md.
+"""
+
+__version__ = "0.1.0"

taskwarden/decisions.py

@@ -0,0 +1,168 @@
+"""The owner's decision on a parked task: approve, decline, revise (they wrote a change instead
+of approving), or answer (a question). Claimed first, then carried out.
+
+`claim` is quick and committed, so an app can answer the owner at once and `apply` in the
+background (approved actions, texts, emails, campaigns, can take a minute).
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from sqlalchemy import select, update
+
+from .loop import MAYBE_SENT, pending_calls, tool_msg
+
+# What a parked call reads when the owner wrote in the chat instead of approving it.
+REVISE_RESULT = ("Not done yet: the owner replied instead of approving: \"{change}\". If it "
+                 "changes this action, make the change and ask for approval again. If it is about "
+                 "something else, do that, and ask for this action again only if it still makes sense.")
+# A parked call whose tool no longer exists when the owner decides.
+GONE = "Not run: this action no longer exists. Say what you meant to do another way."
+# What the model reads before the result of a call the owner edited, so its report names
+# what really went out.
+EDITED = "The owner changed {fields} before approving, and it ran as changed. "
+APPROVAL_DECISIONS = ("approve", "decline", "revise")
+
+
+def edited(args: dict, edits: Optional[dict]) -> tuple[dict, list[str]]:
+    """The call's arguments with the owner's edits, and which ones changed. Only text the call
+    already had can be rewritten: no new argument, no change of type."""
+    changed = sorted(k for k, v in (edits or {}).items()
+                     if isinstance(v, str) and isinstance(args.get(k), str) and v != args[k])
+    return {**args, **{k: edits[k] for k in changed}}, changed
+
+
+def answered(state: list, results: list[dict]) -> list:
+    """The owner's decision, standing in for the placeholder each parked call left.
+
+    The loop parks a "Waiting for your approval." tool message per call id, so every call is
+    already answered in the saved state. A second message for the same tool_call_id would be a
+    duplicate answer, which providers reject, so replace in place and only append a result
+    whose placeholder is missing.
+    """
+    by_id = {r["tool_call_id"]: r for r in results}
+    out = []
+    for msg in state:
+        cid = msg.get("tool_call_id") if isinstance(msg, dict) else None
+        if cid is not None and cid in by_id:
+            out.append(by_id.pop(cid))  # the placeholder for this call is replaced, not joined
+        else:
+            out.append(msg)
+    return out + list(by_id.values())  # any answer whose placeholder was missing
+
+
+async def claim(host, db, organization_id: str, task_id: Any, decision: str):
+    """Check the decision fits the parked task and claim it ("running"), committed. The task,
+    or why not: "not_found" | "conflict" | "invalid"."""
+    Task = host.Task
+    task = (await db.execute(select(Task).where(
+        Task.id == task_id, Task.organization_id == organization_id
+    ))).scalar_one_or_none()
+    if task is None:
+        return "not_found"
+    if task.status != "waiting":
+        return "conflict"
+    pending = task.pending or {}
+    if pending.get("kind") == "ask_agent":
+        return "not_found"  # nothing for the owner to decide: a teammate is answering this one
+    if (pending.get("kind") == "approval") != (decision in APPROVAL_DECISIONS):
+        return "invalid"
+    claimed = (await db.execute(update(Task).where(
+        Task.id == task_id, Task.status == "waiting"
+    ).values(status="running").returning(Task.id))).scalar_one_or_none()
+    if claimed is None:
+        return "conflict"
+    task.status = "running"
+    await db.commit()
+    return task
+
+
+async def apply(host, db, organization_id: str, task: Any, decision: str, *,
+                note: Optional[str] = None, answer: Optional[str] = None, resume: bool = False,
+                declined_calls: Optional[list[str]] = None,
+                edited_args: Optional[dict[str, dict]] = None) -> None:
+    """Carry out a claimed decision: run what was approved (or record the decline, the change
+    asked for, or the answer), hand the results to the task and post the decision to its
+    thread. `task` is the claimed task, or its id from another session. `declined_calls`: on an
+    approve, the batch's calls (by tool_call_id) the owner left out; `edited_args`, the text the
+    owner rewrote before approving, by tool_call_id then argument (see `edited`). `resume`: the caller runs
+    the task now, so it stays "running" instead of going back to the queue."""
+    Task = host.Task
+    if not isinstance(task, Task):
+        task = (await db.execute(select(Task).where(
+            Task.id == task, Task.organization_id == organization_id
+        ))).scalar_one_or_none()
+        if task is None:  # deleted between the claim and now
+            return
+    pending = task.pending or {}
+    is_approval = pending.get("kind") == "approval"
+    calls = pending_calls(pending) if is_approval else []
+    skip = set(declined_calls or ())
+    runs = [decision == "approve" and c.get("tool_call_id", "") not in skip for c in calls]
+    # What runs is what the owner approved, their edits included.
+    changes = []
+    for i, (c, run) in enumerate(zip(calls, runs)):
+        args, changed = edited(c.get("args") or {}, (edited_args or {}).get(c.get("tool_call_id", "")))
+        calls[i] = {**c, "args": args} if run and changed else c
+        changes.append(changed if run else [])
+    results: list[dict] = []
+    if any(runs):
+        ctx, company = await host.context(db, organization_id)
+        region = host.region(company)
+        sent = set(task.contacted or [])
+    for call, run, changed in zip(calls, runs, changes):
+        tool = host.tools.get(call["tool"])
+        if tool is None:  # renamed or removed while it waited for the owner
+            results.append(tool_msg(call.get("tool_call_id", ""), GONE))
+            continue
+        if run:
+            key = host.sent_key(call["tool"], call.get("args") or {}, region)
+            if key is not None:
+                # Saved before it runs, as in the loop: a crash mid-send must not lead to a
+                # second send when the task is retried.
+                task.state = answered(task.state or [], [tool_msg(call.get("tool_call_id", ""), MAYBE_SENT)])
+                task.contacted = sorted(sent | {key})
+                await db.commit()
+            out, ok, _ = await host.execute(tool, ctx, call.get("args") or {})
+            host.audit(db, organization_id=organization_id, agent_id=task.agent_id,
+                       tool=call["tool"], risk=tool.risk,
+                       decision="approved" if ok else "error",
+                       rule="owner_edited" if changed else "owner_approved",
+                       task_id=task.id, actor="owner")
+            if changed:
+                out = EDITED.format(fields=", ".join(changed)) + out
+            if ok is not False:  # None: stopped at its timeout, it may have gone out
+                # What the owner approved is now sent: the resumed run must not repeat it.
+                if key is not None:
+                    sent.add(key)
+        else:
+            out = (REVISE_RESULT.format(change=answer or "") if decision == "revise"
+                   else "Owner declined." + (f" Note: {note}" if note else ""))
+            host.audit(db, organization_id=organization_id, agent_id=task.agent_id,
+                       tool=call["tool"], risk=tool.risk, decision="declined",
+                       rule="owner_revised" if decision == "revise" else "owner_declined",
+                       task_id=task.id, actor="owner")
+        results.append({"role": "tool", "tool_call_id": call.get("tool_call_id", ""), "content": out})
+    if any(runs):
+        task.contacted = sorted(sent)
+    if not is_approval:
+        results = [{"role": "tool", "tool_call_id": pending.get("tool_call_id", ""),
+                    "content": f"Owner answered: {answer or note or ''}"}]
+    echo, kind = answer or note or "", "text"
+    if is_approval and decision != "revise":
+        # What was decided, as data: the app words it for the owner, and the team's history
+        # reads it back as one line.
+        partial = any(runs) and not all(runs)
+        decided = [{"tool": c["tool"], "args": c.get("args") or {},
+                    **({"declined": True} if partial and not run else {})}
+                   for c, run in zip(calls, runs)]
+        echo, kind = json.dumps({"decision": "approved" if any(runs) else "declined",
+                                 "calls": decided, "note": note or None,
+                                 "names": await host.decision_names(db, organization_id, decided)}), "decision"
+
+    task.state = answered(task.state or [], results)
+    task.pending, task.status, task.attempts = None, "running" if resume else "queued", 0
+    host.post_message(db, organization_id=organization_id, thread=task.thread,
+                      sender="owner", body=echo, kind=kind, task_id=task.id)
+    await db.commit()

taskwarden/folders.py

@@ -0,0 +1,154 @@
+"""Agents as folders: `<agents>/<id>/AGENT.md` and `<agents>/<id>/skills/<name>/SKILL.md`.
+
+An agent is its core role (AGENT.md) plus one skill per job, each with its own words, tools and
+evals. The app turns a folder into its own agent definition; this module only reads and checks
+files. A bad folder fails when it is loaded, never at the first task that reads it. Whether the
+tool names exist is the app's check: only it knows its tools.
+
+`business_types` in AGENT.md is a list, null (every type), or the name of a group the app
+expands; `load_agent(folder, groups=...)` names the groups it accepts.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+_AGENT_KEYS = {"id", "name", "title", "aliases", "business_types", "tools", "skills", "agenda",
+               "skills_on_demand"}
+_SKILL_KEYS = {"name", "description", "tools", "requires", "evals"}
+_AGENDA_KEYS = {"cadence", "weekday", "goal", "skills"}
+
+USE_SKILL = "use_skill"
+SKILLS_HINT = ("Your skills: each is how you do one job. Before you do that job, load it with "
+               "use_skill; it gives you its instructions and its tools. Load the ones the task "
+               "needs, all in one response.")
+
+
+@dataclass(frozen=True)
+class Skill:
+    name: str
+    description: str
+    tools: tuple[str, ...]
+    text: str
+    evals: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class AgentFolder:
+    id: str
+    name: str
+    title: str
+    core: str
+    tools: tuple[str, ...]          # the core's own; see all_tools
+    skills: tuple[Skill, ...]
+    aliases: tuple[str, ...] = ()
+    # None = every type; a list; or a named group the roster expands ("field_work").
+    business_types: Optional[tuple[str, ...] | str] = None
+    agenda: Optional[dict] = None   # {cadence, weekday, goal, skills: preloaded}
+    # Step 2: the prompt lists the skills and use_skill loads one. Off: every skill is in
+    # the role (step 1). Switched on per agent, only when its evals hold.
+    on_demand: bool = False
+
+    @property
+    def role(self) -> str:
+        """Step 1: every skill is always loaded, the core first, then the skills in order."""
+        return " ".join([self.core, *(s.text for s in self.skills)])
+
+    @property
+    def all_tools(self) -> tuple[str, ...]:
+        return self.tools_for({s.name for s in self.skills})
+
+    def tools_for(self, loaded: set[str]) -> tuple[str, ...]:
+        """The core's tools, then each loaded skill's, in skill order, once each."""
+        seen: dict[str, None] = dict.fromkeys(self.tools)
+        for skill in self.skills:
+            if skill.name in loaded:
+                seen.update(dict.fromkeys(skill.tools))
+        return tuple(seen)
+
+    def prompt(self, loaded: set[str]) -> str:
+        """The role an on-demand agent starts with: its core, the skills already loaded, and
+        one line for each of the others."""
+        rest = [s for s in self.skills if s.name not in loaded]
+        parts = [self.core, *(s.text for s in self.skills if s.name in loaded)]
+        if rest:
+            parts.append(SKILLS_HINT + " " + " ".join(f"{s.name}: {s.description}"
+                                                         for s in rest))
+        return " ".join(parts)
+
+    def skill(self, name: str) -> Optional[Skill]:
+        return next((s for s in self.skills if s.name == name), None)
+
+    def use_skill_schema(self, loaded: set[str]) -> Optional[dict]:
+        names = [s.name for s in self.skills if s.name not in loaded]
+        if not (self.on_demand and names):
+            return None
+        return {"type": "function", "function": {
+            "name": USE_SKILL,
+            "description": "Load one of your skills: its instructions and its tools.",
+            "parameters": {"type": "object", "properties": {
+                "name": {"type": "string", "enum": names}}, "required": ["name"]}}}
+
+
+def _read(path: Path, keys: set[str]) -> tuple[dict, str]:
+    """(frontmatter, body as one line of text). The body is wrapped for reading; the words
+    are what counts, so line breaks become spaces."""
+    raw = path.read_text(encoding="utf-8")
+    if not raw.startswith("---\n"):
+        raise ValueError(f"{path}: starts with a --- frontmatter block")
+    head, _, body = raw[4:].partition("\n---\n")
+    meta = yaml.safe_load(head) or {}
+    if unknown := set(meta) - keys:
+        raise ValueError(f"{path}: unknown keys {sorted(unknown)}")
+    text = " ".join(body.split())
+    if not text:
+        raise ValueError(f"{path}: has no instructions")
+    return meta, text
+
+
+def _names(path: Path, meta: dict, key: str) -> tuple[str, ...]:
+    value = meta.get(key) or []
+    if not isinstance(value, list) or not all(isinstance(v, str) and v for v in value):
+        raise ValueError(f"{path}: {key} is a list of names")
+    return tuple(value)
+
+
+def load_skill(path: Path) -> Skill:
+    meta, text = _read(path, _SKILL_KEYS)
+    if meta.get("name") != path.parent.name:
+        raise ValueError(f"{path}: name must be {path.parent.name!r}")
+    if not (meta.get("description") or "").strip():
+        raise ValueError(f"{path}: needs a description")
+    return Skill(name=meta["name"], description=" ".join(meta["description"].split()),
+                 tools=_names(path, meta, "tools"), text=text, evals=_names(path, meta, "evals"))
+
+
+def load_agent(folder: Path, groups: tuple[str, ...] = ()) -> AgentFolder:
+    path = folder / "AGENT.md"
+    meta, core = _read(path, _AGENT_KEYS)
+    if meta.get("id") != folder.name:
+        raise ValueError(f"{path}: id must be {folder.name!r}")
+    for key in ("name", "title"):
+        if not (meta.get(key) or "").strip():
+            raise ValueError(f"{path}: needs a {key}")
+    skills = tuple(load_skill(folder / "skills" / name / "SKILL.md")
+                   for name in _names(path, meta, "skills"))
+    agenda = meta.get("agenda")
+    if agenda is not None and (not isinstance(agenda, dict) or set(agenda) - _AGENDA_KEYS
+                               or not agenda.get("goal") or not agenda.get("cadence")):
+        raise ValueError(f"{path}: agenda has cadence, goal and optionally weekday and skills")
+    if unknown := set((agenda or {}).get("skills") or []) - {s.name for s in skills}:
+        raise ValueError(f"{path}: agenda preloads unknown skills {sorted(unknown)}")
+    types = meta.get("business_types")
+    if isinstance(types, str) and types not in groups:
+        raise ValueError(f"{path}: business_types is a list, null or one of {groups}")
+    return AgentFolder(
+        id=meta["id"], name=meta["name"], title=meta["title"], core=core,
+        tools=_names(path, meta, "tools"), skills=skills,
+        aliases=_names(path, meta, "aliases"),
+        business_types=tuple(types) if isinstance(types, list) else types,
+        agenda={**agenda, "goal": " ".join(agenda["goal"].split())} if agenda else None,
+        on_demand=bool(meta.get("skills_on_demand")))

taskwarden/gate.py

@@ -0,0 +1,64 @@
+"""The action boundary: every tool call is decided before it runs.
+
+Order, first match wins: tool not granted -> deny; agent paused -> deny; an agent in practice
+("observe") -> reads run, everything else is only recorded; a self-started task
+reaching a customer or the money -> ask; remove/profile -> always ask; read/draft/routine ->
+allow; contact/spend/change -> the agent's setting ("ask" | "allow"); anything else -> deny
+(fail closed).
+
+A self-started task (one the app's own schedule began, not the owner) never sends, spends or
+commits the business without a click, however loose the agent's setting is: it reads and
+drafts freely, then parks, and the owner's approval runs the call it prepared. `outward` names
+the ROUTINE tools that still reach a customer (a text, a booking) for that rule.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from .tools import CHANGE, CONTACT, DRAFT, PROFILE, READ, REMOVE, ROUTINE, SPEND, Tool
+
+ALLOW, ASK, DENY = "allow", "ask", "deny"
+# The agent's practice setting, and the outcome of a call made in it: recorded, not run. A new
+# agent (or a new skill) can work real requests and show what it would have done.
+OBSERVE = "observe"
+SELF_STARTED_NEEDS_OWNER = "self_started_needs_owner"
+
+
+@dataclass(frozen=True)
+class Decision:
+    outcome: str
+    rule: str
+
+
+@dataclass(frozen=True)
+class AgentState:
+    """The owner's settings for one agent. An app adds its own fields by subclassing."""
+    setting: str = ASK
+    paused: bool = False
+    display_name: Optional[str] = None
+
+
+def decide(agent: Any, tool: Optional[Tool], state: AgentState, *,
+           self_started: bool = False, outward: frozenset = frozenset()) -> Decision:
+    """`agent.tools` is what the agent is granted."""
+    if tool is None or tool.name not in agent.tools:
+        return Decision(DENY, "tool_not_granted")
+    if state.paused:
+        return Decision(DENY, "agent_paused")
+    if state.setting == OBSERVE:
+        return Decision(ALLOW, "safe_action") if tool.risk == READ else Decision(OBSERVE, "practice")
+    if self_started and (tool.risk in (CONTACT, SPEND, CHANGE) or tool.name in outward):
+        return Decision(ASK, SELF_STARTED_NEEDS_OWNER)
+    if tool.risk == REMOVE:  # deletes can't be undone: always the owner's click
+        return Decision(ASK, "always_ask_remove")
+    if tool.risk == PROFILE:  # the business profile changes only with the owner's click
+        return Decision(ASK, "always_ask_profile")
+    if tool.risk in (READ, DRAFT, ROUTINE):
+        return Decision(ALLOW, "safe_action")
+    if tool.risk in (CONTACT, SPEND, CHANGE):
+        if state.setting == ASK:
+            return Decision(ASK, "owner_approval_required")
+        if state.setting == ALLOW:
+            return Decision(ALLOW, "owner_allowed")
+    return Decision(DENY, "fail_closed")

taskwarden/host.py

@@ -0,0 +1,252 @@
+"""What the app supplies to the harness. taskwarden never imports the app; the app hands it a Host.
+
+Each app writes its own (examples/shop.py is a complete one): its tables (the
+`Task` and `Message` models, see taskwarden.models for the columns), its agents and tools, the
+words its agents read, its model, and how its owner is told. Everything below is required
+unless it has a default in `BaseHost`: subclass it and write only what your app decides.
+"""
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from types import SimpleNamespace
+from typing import Any, Optional, Protocol
+
+from . import gate
+from . import tools as _tools
+from .gate import AgentState, Decision
+from .tools import Tool
+
+logger = logging.getLogger(__name__)
+
+
+class Host(Protocol):
+    # ── Tables and the roster ──
+    Task: Any                      # SQLAlchemy model with taskwarden.models.TaskColumns
+    chief: str                     # the agent the owner talks to when they name nobody
+    tools: dict[str, Tool]         # every tool, by name
+
+    def agent(self, agent_id: str) -> Any: ...  # .id .name .title .tools .folder
+    def agents_for(self, business_type: Optional[str]) -> list[Any]: ...
+    def tools_of(self, agent: Any, business_type: Optional[str]) -> tuple[str, ...]: ...
+    def for_business(self, agent: Any, business_type: Optional[str]) -> Any: ...
+
+    # ── Before a run ──
+    async def refuse_run(self, db: Any, task: Any, actor: str) -> bool:
+        """True when the business can't run the team now (no credits). Tell the owner if
+        `actor == "owner"`; the harness fails the task."""
+    async def context(self, db: Any, organization_id: str) -> tuple[Any, dict]:
+        """(the ctx every handler gets, with .db .organization_id .timezone; the business's
+        facts the host itself reads back: business_type, country)."""
+    async def agent_states(self, db: Any, organization_id: str) -> dict[str, AgentState]: ...
+    def default_state(self) -> AgentState: ...
+    async def llm(self, db: Any, organization_id: str) -> tuple[Any, str]:
+        """(an OpenAI-compatible async client, model name)."""
+    def extra_body(self, model: str) -> Optional[dict]: ...
+    def clean_text(self, text: Optional[str]) -> str: ...
+    def self_started(self, task: Any) -> bool:
+        """The app's schedule started this task: nothing leaves without the owner's click."""
+    def never_waits(self, task: Any) -> bool:
+        """This task may not ask anyone or park (a morning review): what needs the owner goes
+        in its report."""
+    def preloaded_skills(self, agent: Any, task: Any) -> set[str]: ...
+    async def system_prompt(self, db: Any, task: Any, agent: Any, name: str, teammates: list,
+                            now: datetime,
+                            channel: Optional[str], business_type: Optional[str],
+                            self_started: bool, loaded: set[str]) -> str: ...
+    def local_schemas(self, channel: Optional[str], task: Any) -> list[dict]:
+        """Tools the host answers inside the loop itself (a `show` that draws a table, say)."""
+    async def local_call(self, db: Any, organization_id: str, name: str, args: dict,
+                         reads: dict, shown: list) -> Optional[str]:
+        """The answer to a local tool, or None when `name` is not one."""
+    def region(self, company: dict) -> str: ...
+
+    # ── Each call ──
+    def decide(self, agent: Any, tool: Optional[Tool], state: AgentState, *,
+               self_started: bool) -> Decision: ...
+    async def precheck(self, tool: Tool, ctx: Any, args: dict) -> Optional[str]:
+        """The tool's own check before the owner is asked. Must not raise: a check that fails
+        to run returns None, and the owner is asked as before."""
+    def clean_args(self, args: dict) -> dict:
+        """The arguments a parked call keeps: without the ones the server owns."""
+    def use_skill(self, agent: Any, args: dict, loaded: set[str]) -> tuple[str, tuple[str, ...]]:
+        """Load a skill: taskwarden.loop.use_skill, unless the host records it too."""
+    async def execute(self, tool: Tool, ctx: Any, args: dict) -> tuple[str, Optional[bool], Any]:
+        """(text for the model, ok, the raw result of a read or None). ok None: unknown (a
+        call stopped at its timeout), counted as sent."""
+    def audit(self, db: Any, *, organization_id: str, agent_id: str, tool: str,
+              risk: Optional[str], decision: str, rule: str, task_id: Any, actor: str,
+              target: Optional[str] = None) -> None: ...
+    def reach_key(self, tool_name: str, args: dict, region: str) -> Optional[str]:
+        """`tool|recipient` when the call reaches one person: one message per person per turn."""
+    def sent_key(self, tool_name: str, args: dict, region: str) -> Optional[str]:
+        """`tool|recipient|body`: never the same message to the same person twice in a task."""
+    async def picture_url(self, image: Any) -> Optional[str]: ...
+    async def mark(self, organization_id: str, thread: str, agent_id: str, step: str) -> None:
+        """Live progress for the owner's screen; best effort."""
+
+    # ── Telling people ──
+    def post_message(self, db: Any, *, organization_id: str, thread: str, sender: str,
+                     body: str, kind: str = "text", task_id: Any = None) -> Any: ...
+    async def finish(self, db: Any, task: Any, body: str, shown: list, actor: str) -> None:
+        """Post the report (and anything shown), wake a teammate waiting on it
+        (taskwarden.loop.answer_ask), relay background work to the owner."""
+    async def decision_names(self, db: Any, organization_id: str, decided: list[dict]) -> dict:
+        """Names for the people the decided calls reach ({"+1555...": "Hannah Lee"}): the app
+        shows the decision with them."""
+    async def owner_fields(self, db: Any, task: Any) -> dict:
+        """Extra fields on a park that waits for the owner (a code they can reply with, say)."""
+    async def notify_parked(self, db: Any, task: Any, pending: dict, name: str, actor: str,
+                            channel: Optional[str], summary: str, body: str) -> None:
+        """Tell the owner something waits for them. May update task.pending."""
+
+    # Words the harness says to the model on the host's behalf.
+    NEVER_WAITS_REFUSED: str
+    NEVER_WAITS_NEEDS_OWNER: str
+    OUT_OF_STEPS: str
+
+
+class BaseHost:
+    """Defaults for every member of `Host` that has a sensible one. A subclass sets `Task`,
+    `Message`, `chief`, `agents` (by id) and `tools`, and writes `llm` and `system_prompt`;
+    everything else can stay as it is until the app needs more (examples/shop.py).
+
+    What the defaults leave out: no credit check, one time zone (UTC), no live progress, no
+    duplicate-send guard (write `sent_key` and `reach_key` once a tool reaches people), and
+    the owner is told only through the chat (write `notify_parked` for push, SMS or email)."""
+
+    Task: Any
+    Message: Any = None  # a model with taskwarden.models.MessageColumns; None posts nothing
+    chief: str
+    agents: dict[str, Any]
+    tools: dict[str, Tool]
+
+    NEVER_WAITS_REFUSED = "Refused: this task can't ask anyone. Put it in your report."
+    NEVER_WAITS_NEEDS_OWNER = ("Not done: this needs the owner, and this task can't wait for "
+                               "them. Put it in your report.")
+    OUT_OF_STEPS = "I ran out of steps before finishing. Ask me to carry on."
+
+    # ── Write these ──
+    async def llm(self, db: Any, organization_id: str) -> tuple[Any, str]:
+        raise NotImplementedError("return (an OpenAI-compatible async client, model name)")
+
+    async def system_prompt(self, db, task, agent, name, teammates, now, channel,
+                            business_type, self_started, loaded) -> str:
+        raise NotImplementedError("return the words the agent reads first")
+
+    # ── The roster ──
+    def agent(self, agent_id: str) -> Any:
+        return self.agents[agent_id]
+
+    def agents_for(self, business_type: Optional[str]) -> list[Any]:
+        return list(self.agents.values())
+
+    def tools_of(self, agent: Any, business_type: Optional[str]) -> tuple[str, ...]:
+        return tuple(agent.tools)
+
+    def for_business(self, agent: Any, business_type: Optional[str]) -> Any:
+        return agent
+
+    # ── Before a run ──
+    async def refuse_run(self, db, task, actor) -> bool:
+        return False
+
+    async def context(self, db, organization_id) -> tuple[Any, dict]:
+        return SimpleNamespace(db=db, organization_id=organization_id, timezone="UTC"), {}
+
+    async def agent_states(self, db, organization_id) -> dict[str, AgentState]:
+        return {}
+
+    def default_state(self) -> AgentState:
+        return AgentState()
+
+    def extra_body(self, model: str) -> Optional[dict]:
+        return None
+
+    def clean_text(self, text: Optional[str]) -> str:
+        return (text or "").strip()
+
+    def self_started(self, task) -> bool:
+        # A hand-off copies its parent's origin, so delegating is no way around the owner.
+        return task.origin != "owner"
+
+    def never_waits(self, task) -> bool:
+        return False
+
+    def preloaded_skills(self, agent, task) -> set[str]:
+        return set()
+
+    def local_schemas(self, channel, task) -> list[dict]:
+        return []
+
+    async def local_call(self, db, organization_id, name, args, reads, shown) -> Optional[str]:
+        return None
+
+    def region(self, company: dict) -> str:
+        return str(company.get("country") or "")
+
+    # ── Each call ──
+    def decide(self, agent, tool, state, *, self_started) -> Decision:
+        return gate.decide(agent, tool, state, self_started=self_started)
+
+    async def precheck(self, tool, ctx, args) -> Optional[str]:
+        if tool.check is None:
+            return None
+        try:
+            return await _tools.check(tool, ctx, args)
+        except Exception:  # a check that can't run asks the owner as before
+            logger.exception("taskwarden_precheck_failed tool=%s", tool.name)
+            return None
+
+    def clean_args(self, args: dict) -> dict:
+        return _tools.clean_args(args)
+
+    def use_skill(self, agent, args, loaded):
+        from .loop import use_skill  # the loop imports this module
+        return use_skill(agent, args, loaded)
+
+    async def execute(self, tool, ctx, args):
+        out, ok = await _tools.execute(tool, ctx, args)
+        return out, ok, None
+
+    def audit(self, db, **kw) -> None:
+        logger.info("taskwarden_audit %s", kw)
+
+    def reach_key(self, tool_name, args, region) -> Optional[str]:
+        return None
+
+    def sent_key(self, tool_name, args, region) -> Optional[str]:
+        return None
+
+    async def picture_url(self, image) -> Optional[str]:
+        return image if isinstance(image, str) else None
+
+    async def mark(self, organization_id, thread, agent_id, step) -> None:
+        return None
+
+    # ── Telling people ──
+    def post_message(self, db, *, organization_id, thread, sender, body, kind="text",
+                     task_id=None) -> Any:
+        if self.Message is None:
+            return None
+        msg = self.Message(organization_id=organization_id, thread=thread, sender=sender,
+                           body=body, kind=kind, task_id=task_id)
+        db.add(msg)
+        return msg
+
+    async def finish(self, db, task, body, shown, actor) -> None:
+        from .loop import answer_ask
+        self.post_message(db, organization_id=task.organization_id, thread=task.thread,
+                          sender=task.agent_id, body=body,
+                          kind="result" if task.parent_id else "text", task_id=task.id)
+        await answer_ask(self, db, task, body)  # a teammate waiting on this answer wakes
+
+    async def decision_names(self, db, organization_id, decided) -> dict:
+        return {}
+
+    async def owner_fields(self, db, task) -> dict:
+        return {}
+
+    async def notify_parked(self, db, task, pending, name, actor, channel, summary,
+                            body) -> None:
+        return None