@maudecode/talaria-web 1.14.0 → 1.15.0

package/sidecar/talaria_sidecar/methods/chat.py

@@ -257,13 +257,86 @@ def _clarify_timeout(params: dict) -> int:
         return 3600
 
 
+def _steer_slot_lock(agent):
+    """The Agent's own pending-steer lock (a plain ``Lock``), so a slot read or rewrite is atomic against its drains."""
+    lock = agent.__dict__.get("_pending_steer_lock") if hasattr(agent, "__dict__") else None
+    return contextlib.nullcontext() if lock is None else lock
+
+
+def _steer_slot(agent) -> str:
+    """The Agent's not-yet-applied steer text; call under ``_steer_slot_lock``."""
+    return str(getattr(agent, "_pending_steer", "") or "")
+
+
 def _agent_pending_steer_text(agent) -> str:
     """Predecessor ``_agent_pending_steer_text``: the Agent's not-yet-applied steer text."""
-    lock = agent.__dict__.get("_pending_steer_lock") if hasattr(agent, "__dict__") else None
-    if lock is None:
-        return str(getattr(agent, "_pending_steer", "") or "")
-    with lock:
-        return str(agent.__dict__.get("_pending_steer") or "")
+    with _steer_slot_lock(agent):
+        return _steer_slot(agent)
+
+
+def _slot_without(slot: str, pending: list[str], index: int) -> str | None:
+    """``slot`` without the steer ``pending[index]`` while the Agent still holds it, else None (it already took it).
+
+    The Agent keeps every not-yet-applied steer in one newline-joined slot, so the slot is the tail of ``pending``
+    (the server's steers, oldest first), possibly behind text another surface queued: the server's
+    ``pendingSteerSuffixStart`` rule. The longest tail that still holds the steer wins."""
+    for start in range(index + 1):
+        tail = "\n".join(pending[start:])
+        if slot == tail or slot.endswith("\n" + tail):
+            head = slot[: len(slot) - len(tail)].rstrip("\n")
+            return "\n".join(part for part in [head, *pending[start:index], *pending[index + 1:]] if part)
+    return None
+
+
+def withdraw_steer(agent, pending: list[str], index: int) -> bool:
+    """TAL-424: take a not-yet-applied steer back out of the Agent's slot, keeping the others in order. False when the
+    Agent already took it; the slot is then left as it was, so no text is ever lost."""
+    with _steer_slot_lock(agent):
+        rest = _slot_without(_steer_slot(agent), pending, index)
+        if rest is None:
+            return False
+        agent._pending_steer = rest or None
+        return True
+
+
+def steer_now(agent, pending: list[str], index: int) -> dict:
+    """TAL-424: deliver a pending steer now with the Agent's ``redirect``. During a model request that request restarts
+    with it (``delivery: redirect``); during tools it goes back on the slot and the tools yield (``delivery: steer``).
+    With no live request the steer stays pending: back in its place, or last when the slot changed meanwhile."""
+    text = pending[index]
+    with _steer_slot_lock(agent):
+        before = _steer_slot(agent)
+        rest = _slot_without(before, pending, index)
+        if rest is None:
+            return {"redirected": False, "withdrawn": False}
+        agent._pending_steer = rest or None
+    redirect = getattr(agent, "redirect", None)
+    try:
+        redirected = bool(redirect(text)) if callable(redirect) else False
+    except Exception as exc:  # noqa: BLE001
+        log.debug("redirect failed: %s", exc)
+        redirected = False
+    if not redirected:
+        with _steer_slot_lock(agent):
+            if _steer_slot(agent) == rest:
+                agent._pending_steer = before or None
+                return {"redirected": False, "withdrawn": True, "requeued": "kept"}
+        agent.steer(text)
+        return {"redirected": False, "withdrawn": True, "requeued": "last"}
+    with _steer_slot_lock(agent):
+        slot = _steer_slot(agent)
+    delivery = "steer" if slot == text or slot.endswith("\n" + text) else "redirect"
+    return {"redirected": True, "withdrawn": True, "delivery": delivery}
+
+
+def _steer_queue_params(params: dict) -> tuple[list[str], int]:
+    pending = params.get("pending")
+    index = params.get("index")
+    if not isinstance(pending, list) or not all(isinstance(t, str) and t.strip() for t in pending):
+        raise InvalidParams("pending must be a list of steer texts")
+    if not isinstance(index, int) or isinstance(index, bool) or not 0 <= index < len(pending):
+        raise InvalidParams("index must point into pending")
+    return [t.strip() for t in pending], index
 
 
 def _cancel_checkpoint(run: _Run) -> list | None:
@@ -725,6 +798,131 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
                 _RUNS_BY_SESSION.pop(session_id, None)
 
 
+def _checkpoint_required() -> bool:
+    """``compression.checkpoint_required`` needs the memory provider loaded to write the pre-compression checkpoint."""
+    try:
+        from hermes_cli.config import load_config
+
+        return ((load_config() or {}).get("compression") or {}).get("checkpoint_required") is True
+    except Exception:  # noqa: BLE001
+        return False
+
+
+#: Compressed results awaiting the server's write: ``commit_token -> (agent, profile home, expiry timer)``.
+_PENDING_COMPRESSIONS: dict[str, tuple[Any, Any, threading.Timer]] = {}
+_PENDING_COMPRESSIONS_LOCK = threading.Lock()
+#: A server that never answers (restart, crash) gets its compression discarded after this long.
+_PENDING_COMPRESSION_TTL = 600.0
+
+
+def _release_compression(agent, committed: bool) -> None:
+    """Emit (committed) or discard the Agent's deferred context-engine notification, then close the throwaway agent."""
+    from agent.conversation_compression import finalize_context_engine_compression_notification
+
+    try:
+        finalize_context_engine_compression_notification(agent, committed=committed)
+    finally:
+        with contextlib.suppress(Exception):
+            agent._end_session_on_close = False
+        close = getattr(agent, "close", None)
+        if callable(close):
+            try:
+                close()
+            except Exception:  # noqa: BLE001
+                log.debug("compression agent close failed", exc_info=True)
+
+
+def finalize_compression(token: str, committed: bool) -> bool:
+    """``chat.compress_finalize``: the server reports whether it installed the result; unknown tokens are a no-op."""
+    with _PENDING_COMPRESSIONS_LOCK:
+        entry = _PENDING_COMPRESSIONS.pop(token, None)
+    if entry is None:
+        return False
+    agent, home, expiry = entry
+    expiry.cancel()  # a no-op when the timer itself is finalizing
+    with scoped_home(home):
+        _release_compression(agent, committed=committed)
+    return True
+
+
+def compress(ctx: CallContext, params: dict) -> dict:
+    """Manual ``/compress`` of ``conversation_history`` through the Agent's shared core (``compress_now``) on a throwaway
+    agent, like the gateway's ``_run_manual_compression``. The server owns the transcript: it re-checks the session and
+    installs ``messages`` itself, so nothing here touches history or the cached turn agent. The agent has no session
+    store, so the Agent neither rotates nor writes state.db; its one deferred effect, the context-engine notification,
+    waits for ``chat.compress_finalize`` with the returned ``commit_token`` (two-phase, like the gateway's commit)."""
+    home = profile_home_param(params)
+    session_id = str(params.get("session_id") or "").strip()
+    if not session_id:
+        raise InvalidParams("session_id is required")
+    history = params.get("conversation_history")
+    if not isinstance(history, list):
+        raise InvalidParams("conversation_history must be a list")
+    model = str(params.get("model") or "").strip()
+    provider = str(params.get("model_provider") or "").strip() or None
+    focus_topic = str(params.get("focus_topic") or "").strip()[:500] or None
+    toolsets = params.get("enabled_toolsets")
+    runtime = _resolve_runtime(provider, model)
+    if not runtime.get("api_key"):
+        raise RpcError("No provider configured -- cannot compress.", condition="credential_missing")
+    from agent.conversation_compression_manual import CompressRequest, compress_now
+
+    AIAgent = _agent_class()
+    kwargs: dict = dict(
+        model=model or str(runtime.get("model") or ""),
+        provider=provider or runtime.get("provider"),
+        base_url=runtime.get("base_url"),
+        api_key=runtime.get("api_key"),
+        platform="webui",
+        quiet_mode=True,
+        enabled_toolsets=toolsets if isinstance(toolsets, list) else None,
+        session_id=session_id,
+    )
+    for name, value in (
+        ("api_mode", runtime.get("api_mode")),
+        ("acp_command", runtime.get("acp_command")),
+        ("acp_args", runtime.get("acp_args")),
+        ("credential_pool", runtime.get("credential_pool")),
+        ("gateway_session_key", session_id),
+        ("skip_memory", not _checkpoint_required()),
+    ):
+        if _supported(AIAgent, name) and value is not None:
+            kwargs[name] = value
+    agent = AIAgent(**kwargs)
+    held = False
+    try:
+        result = compress_now(agent, history, CompressRequest(focus_topic=focus_topic), task_id=session_id)
+        message = None
+        if result.status != "compressed":
+            from agent.conversation_compression_manual import render_compress_result
+
+            message = "\n".join(render_compress_result(result)) or None
+        payload = {
+            "status": result.status,
+            "messages": json.loads(json.dumps([m for m in result.after_messages if isinstance(m, dict)], default=str)),
+            "before_tokens": int(result.before_tokens or 0),
+            "after_tokens": int(result.after_tokens or 0),
+            "summary": json.loads(json.dumps(result.summary, default=str)) if isinstance(result.summary, dict) else None,
+            "message": message,
+            "agent_session_id": str(getattr(agent, "session_id", None) or session_id),
+            "commit_token": None,
+        }
+        if result.status == "compressed":
+            token = uuid.uuid4().hex
+            # A server that never answers (restart, failed RPC) gets the compression discarded on its own.
+            expiry = threading.Timer(_PENDING_COMPRESSION_TTL, finalize_compression, args=(token, False))
+            expiry.daemon = True
+            with _PENDING_COMPRESSIONS_LOCK:
+                _PENDING_COMPRESSIONS[token] = (agent, home, expiry)
+            expiry.start()
+            held = True
+            payload["commit_token"] = token
+        return payload
+    finally:
+        if not held:
+            _release_compression(agent, committed=False)
+
+
 def _run_for(params: dict) -> _Run | None:
     stream_id = str(params.get("stream_id") or "").strip()
     session_id = str(params.get("session_id") or "").strip()
@@ -748,6 +946,18 @@ def register(registry) -> None:
             with _turn_identity(session_id, workspace):
                 return start(ctx, params)
 
+    @registry.method("chat.compress")
+    def compress_(ctx: CallContext, params: dict) -> dict:
+        with scoped_home(profile_home_param(params)):
+            return compress(ctx, params)
+
+    @registry.method("chat.compress_finalize", requires_agent=False)
+    def compress_finalize_(ctx: CallContext, params: dict) -> dict:
+        token = str(params.get("commit_token") or "").strip()
+        if not token:
+            raise InvalidParams("commit_token is required")
+        return {"finalized": finalize_compression(token, params.get("committed") is True)}
+
     @registry.method("chat.interrupt", requires_agent=False)
     def interrupt_(ctx: CallContext, params: dict) -> dict:
         run = _run_for(params)
@@ -786,7 +996,24 @@ def register(registry) -> None:
         except Exception as exc:  # noqa: BLE001
             log.debug("steer failed: %s", exc)
             return {"accepted": False, "fallback": "steer_error"}
-        return {"accepted": accepted, "fallback": None if accepted else "not_running"}
+        # `can_redirect`: whether this Agent can deliver a pending steer now (TAL-424 "Send now").
+        return {"accepted": accepted, "fallback": None if accepted else "not_running", "can_redirect": callable(getattr(run.agent, "redirect", None))}
+
+    @registry.method("chat.steer_withdraw", requires_agent=False)
+    def steer_withdraw_(ctx: CallContext, params: dict) -> dict:
+        pending, index = _steer_queue_params(params)
+        run = _run_for(params)
+        if run is None or run.agent is None:
+            return {"withdrawn": False}
+        return {"withdrawn": withdraw_steer(run.agent, pending, index)}
+
+    @registry.method("chat.steer_now", requires_agent=False)
+    def steer_now_(ctx: CallContext, params: dict) -> dict:
+        pending, index = _steer_queue_params(params)
+        run = _run_for(params)
+        if run is None or run.agent is None:
+            return {"redirected": False, "withdrawn": False}
+        return steer_now(run.agent, pending, index)
 
     @registry.method("chat.evict_agent", requires_agent=False)
     def evict_(ctx: CallContext, params: dict) -> dict:

package/sidecar/talaria_sidecar/methods/cron.py

@@ -379,25 +379,33 @@ def register(registry) -> None:
             post["profile"] = str(body["profile"]).strip()
         if body.get("toast_notifications") is False:
             post["toast_notifications"] = False
-        snapshot_home = params.get("execution_home")
-        # The selected profile's provider/model snapshot is resolved before the job exists (predecessor
-        # ``_selected_profile_snapshot_updates`` ran before ``create_job``), so a failure leaves nothing behind.
-        if post.get("profile") and snapshot_home and not (body.get("model") and body.get("provider")) and not body.get("no_agent"):
+        if body.get("owner_profile"):
+            post["owner_profile"] = str(body["owner_profile"]).strip()
+        execution_home = params.get("execution_home")
+        if post.get("profile"):
+            if not execution_home:
+                raise InvalidParams("execution_home is required for a profile job")
+            home = Path(execution_home)
+        model, provider = (value.strip() or None if isinstance(value, str) else None for value in (body.get("model"), body.get("provider")))
+        # The scheduler ignores Talaria's profile field. Pin the execution profile's main model
+        # before creating it in that profile's own store. Scheduled workers bind credentials/config
+        # to the store home; owner_profile only preserves management from the creating Web profile.
+        if post.get("profile") and execution_home and not (model and provider) and not body.get("no_agent"):
             try:
-                from cron.jobs import _compute_provider_model_snapshots
-
-                with _SNAPSHOT_LOCK, scoped_home(Path(snapshot_home)):
-                    provider_snapshot, model_snapshot = _compute_provider_model_snapshots(provider=body.get("provider") or None, model=body.get("model") or None, base_url=None, no_agent=False)
-                if body.get("provider") is None:
-                    post["provider_snapshot"] = provider_snapshot
-                if body.get("model") is None:
-                    post["model_snapshot"] = model_snapshot
+                from cron.jobs import _main_model_pin
+
+                with _SNAPSHOT_LOCK, scoped_home(Path(execution_home)):
+                    profile_provider, profile_model = _main_model_pin()
+                if not profile_model:
+                    raise ValueError("Profile has no main model configured")
+                provider = provider or profile_provider
+                model = model or profile_model
             except Exception as exc:  # noqa: BLE001
-                raise RpcError(f"Cannot safely resolve cron snapshots for profile {post['profile']!r}", condition="cron_snapshot_failed") from exc
+                raise RpcError(f"Cannot safely resolve cron model for profile {post['profile']!r}", condition="cron_snapshot_failed") from exc
         with _store(home), scoped_home(home):
             try:
                 job = jobs.create_job(prompt=body.get("prompt") or "", schedule=body["schedule"], name=body.get("name") or None, deliver=body.get("deliver") or "local",
-                                      skills=body.get("skills") or [], model=body.get("model") or None, provider=body.get("provider") or None, **kwargs)
+                                      skills=body.get("skills") or [], model=model, provider=provider, **kwargs)
             except Exception as exc:  # noqa: BLE001
                 raise InvalidParams(str(exc)) from exc
             if post:

package/sidecar/talaria_sidecar/methods/process.py

@@ -4,8 +4,13 @@ routing; the sidecar drains and formats registry events."""
 
 from __future__ import annotations
 
+import json
 import logging
 import queue
+import sqlite3
+import time
+from contextlib import closing
+from pathlib import Path
 
 from ..errors import InvalidParams
 from ..home import profile_home_param, scoped_home
@@ -89,6 +94,62 @@ def mark_consumed(process_id: str) -> bool:
         return False
 
 
+def _delivery_api():
+    """The Agent's durable delivery ledger (``tools.async_delegation``), or None on an Agent without it."""
+    try:
+        from tools import async_delegation
+    except Exception:  # noqa: BLE001
+        return None
+    names = ("claim_event_delivery", "complete_event_delivery", "release_event_delivery")
+    return async_delegation if all(callable(getattr(async_delegation, n, None)) for n in names) else None
+
+
+def _ledger_event(evt: dict) -> dict:
+    return {k: v for k, v in evt.items() if k not in ("process_id", "consumed")}
+
+
+def claim_delivery(evt: dict, consumer: str) -> str | None:
+    """Claim a durable delegation completion before delivering it (TAL-459).
+
+    ``None``: another consumer holds it, or the ledger already delivered or dropped it, so do not deliver.
+    ``""``: nothing durable to acknowledge (interim notice, legacy event, or an Agent without the ledger)."""
+    api = _delivery_api()
+    if api is None:
+        return ""
+    claim_id = api.claim_event_delivery(_ledger_event(evt), consumer)
+    return None if claim_id is None else str(claim_id)
+
+
+def complete_delivery(evt: dict, claim_id: str) -> bool:
+    api = _delivery_api()
+    if api is None or not claim_id:
+        return False
+    api.complete_event_delivery(_ledger_event(evt), claim_id)
+    return True
+
+
+def release_delivery(evt: dict, claim_id: str) -> bool:
+    api = _delivery_api()
+    if api is None or not claim_id:
+        return False
+    api.release_event_delivery(_ledger_event(evt), claim_id)
+    return True
+
+
+def defer_delivery(evt: dict, claim_id: str) -> bool:
+    """Hand back a claim the target never admitted (its session was busy) without spending a delivery attempt;
+    the Agent drops a row for good after its attempt budget, so a busy session must not burn it."""
+    api = _delivery_api()
+    if api is None or not claim_id:
+        return False
+    defer = getattr(api, "defer_completion_delivery", None)
+    if not callable(defer) or evt.get("type") != "async_delegation" or not evt.get("delegation_id"):
+        api.release_event_delivery(_ledger_event(evt), claim_id)
+        return True
+    defer(str(evt["delegation_id"]), claim_id)
+    return True
+
+
 def format_notification(evt: dict) -> str:
     if evt.get("type") == "async_delegation":
         try:
@@ -122,6 +183,210 @@ def list_sessions() -> list[dict]:
     return out
 
 
+_LEDGER_COLUMNS = "delegation_id, origin_ui_session_id, state, dispatched_at, completed_at, updated_at, task_json, result_json, event_json IS NOT NULL"
+_LEDGER_LIMIT = 200
+
+
+def _json(text) -> dict:
+    try:
+        value = json.loads(text) if text else {}
+    except (TypeError, ValueError):
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+def _unit_goals(task: dict) -> list[str]:
+    goals = task.get("goals") if isinstance(task.get("goals"), list) else None
+    indexes = task.get("task_indexes") if isinstance(task.get("task_indexes"), list) else None
+    if goals and indexes:
+        return [str(goals[i]) for i in indexes if isinstance(i, int) and 0 <= i < len(goals)]
+    if goals:
+        return [str(g) for g in goals]
+    return [str(task.get("goal") or "")]
+
+
+def _child_statuses(result: dict) -> list[str]:
+    """Per-subagent outcome of a finished unit: a batch carries ``results``, a single task is its own result."""
+    if isinstance(result.get("results"), list):
+        return [str(r.get("status") or "") for r in result["results"] if isinstance(r, dict)]
+    return [str(result.get("status") or "")] if result else []
+
+
+def _ledger_rows(home: Path, session_ids: list[str]) -> list[dict]:
+    db_path = home / "state.db"
+    if not db_path.exists() or not session_ids:
+        return []
+    marks = ",".join("?" * len(session_ids))
+    with closing(sqlite3.connect(f"{db_path.resolve().as_uri()}?mode=ro", uri=True, timeout=5)) as conn:
+        try:
+            rows = conn.execute(f"SELECT {_LEDGER_COLUMNS} FROM async_delegations WHERE origin_ui_session_id IN ({marks}) ORDER BY dispatched_at DESC LIMIT ?", [*session_ids, _LEDGER_LIMIT]).fetchall()
+        except sqlite3.OperationalError:  # an Agent that never delegated has no ledger table yet
+            return []
+    out = []
+    for delegation_id, origin, state, dispatched_at, completed_at, updated_at, task_json, result_json, has_event in rows:
+        task, result = _json(task_json), _json(result_json)
+        goals = _unit_goals(task)
+        out.append({
+            "delegation_id": delegation_id, "origin_ui_session_id": origin, "state": state, "dispatched_at": dispatched_at,
+            "completed_at": completed_at, "updated_at": updated_at, "goals": goals,
+            "child_statuses": _child_statuses(result), "has_result": bool(has_event),
+        })
+    return out
+
+
+def _live_delegations() -> dict[str, dict]:
+    try:
+        from tools.async_delegation import list_async_delegations
+        items = list_async_delegations()
+    except Exception:  # noqa: BLE001 - an Agent without the live registry reports from the ledger alone
+        return {}
+    return {str(i.get("delegation_id")): {"status": str(i.get("status") or "")} for i in items if isinstance(i, dict) and i.get("delegation_id")}
+
+
+def _owned_processes(session_ids: set[str]) -> list[dict]:
+    """Notified or watched processes a WebUI session started (``session_key`` is the WebUI session id)."""
+    registry = _registry()
+    if registry is None:
+        return []
+    try:
+        with registry._lock:
+            sessions = [*registry._running.values(), *registry._finished.values()]
+    except Exception:  # noqa: BLE001
+        return []
+    out = []
+    for proc in sessions:
+        if str(getattr(proc, "session_key", "") or "") not in session_ids:
+            continue
+        watched = bool(getattr(proc, "watch_patterns", None))
+        if not (getattr(proc, "notify_on_complete", False) or watched):
+            continue
+        exited = bool(getattr(proc, "exited", False))
+        out.append({
+            "process_id": str(proc.id), "session_key": str(proc.session_key), "command": str(getattr(proc, "command", "") or "")[:200],
+            "started_at": float(getattr(proc, "started_at", 0) or 0) or None, "exited": exited,
+            "exited_at": float(getattr(proc, "exited_at", 0) or 0) or None, "exit_code": getattr(proc, "exit_code", None),
+            "completion_reason": str(getattr(proc, "completion_reason", "") or ""), "watched": watched,
+        })
+    return out
+
+
+_CHILD_WINDOW_S = 5
+
+
+def _live_children() -> list[dict]:
+    """Running subagents from the Agent's in-process registry: the only place a child's session id sits next to its
+    delegation id. An Agent without the registry reports none."""
+    try:
+        from tools.delegate_tool_registry import _active_subagents, _active_subagents_lock
+        with _active_subagents_lock:
+            records = list(_active_subagents.values())
+    except Exception:  # noqa: BLE001
+        return []
+    out = []
+    for r in records:
+        sid = getattr(r.get("agent"), "session_id", None)
+        if isinstance(sid, str) and sid:
+            out.append({"delegation_id": str(r.get("delegation_id") or ""), "goal": str(r.get("goal") or ""), "owner": str(r.get("owner_agent_session_id") or ""), "session_id": sid})
+    return out
+
+
+def _ledger_children(home: Path, owners: list[str]) -> list[dict]:
+    """Finished subagents' own sessions in state.db: ``source = subagent`` rows tagged ``_delegate_from`` with their
+    parent's session, each with its start time and first user message (the child's goal, sent verbatim)."""
+    db_path = home / "state.db"
+    if not db_path.exists() or not owners:
+        return []
+    marks = ",".join("?" * len(owners))
+    with closing(sqlite3.connect(f"{db_path.resolve().as_uri()}?mode=ro", uri=True, timeout=5)) as conn:
+        try:
+            # Only these chats' children: a long-lived profile keeps every subagent session it ever ran.
+            rows = conn.execute(
+                "SELECT s.id, s.model_config, s.started_at, (SELECT m.content FROM messages m WHERE m.session_id = s.id AND m.role = 'user' ORDER BY m.id LIMIT 1)"
+                f" FROM sessions s WHERE s.source = 'subagent' AND json_extract(s.model_config, '$._delegate_from') IN ({marks})", owners).fetchall()
+        except sqlite3.OperationalError:
+            return []
+    out = []
+    for sid, model_config, started_at, first in rows:
+        owner = _json(model_config).get("_delegate_from")
+        goal = _goal_text(first)
+        if owner in owners and goal:
+            out.append({"owner": owner, "session_id": sid, "started_at": started_at, "goal": goal})
+    return out
+
+
+_CONTENT_JSON_PREFIX = "\x00json:"
+_IMAGE_HINTS = "\n\n[Image attached"
+
+
+def _goal_text(content) -> str:
+    """The goal a child was sent, from its stored first message: a task with images is stored as multimodal parts
+    (native image input; the goal is the text part) or as the goal followed by image hints (text input)."""
+    if not isinstance(content, str):
+        return ""
+    if content.startswith(_CONTENT_JSON_PREFIX):
+        try:
+            parts = json.loads(content[len(_CONTENT_JSON_PREFIX):])
+        except ValueError:
+            return ""
+        texts = [p.get("text") for p in parts if isinstance(p, dict) and p.get("type") == "text"] if isinstance(parts, list) else []
+        return str(texts[0]) if texts and texts[0] else ""
+    return content.split(_IMAGE_HINTS, 1)[0]
+
+
+def unit_children(unit: dict, owner: str, live: list[dict], finished: list[dict], now: float) -> list[dict]:
+    """The subagent sessions one delegation unit ran, as ``{goal, session_id}`` per task, in task order. A live registry
+    record is exact (same owner, the unit's call id, the task's goal) and is used once. Without one, finished sessions
+    of that owner whose goal matches, started in the unit's window, count only when there are exactly as many as tasks
+    with that goal; anything else stays unlinked rather than guessed."""
+    unit_id, goals = unit["delegation_id"], [g for g in unit["goals"] if g]
+    pool = [r for r in live if r["owner"] == owner and r["delegation_id"] and (unit_id == r["delegation_id"] or unit_id.startswith(f"{r['delegation_id']}-"))]
+    linked: list[str | None] = []
+    used: set[str] = set()
+    for goal in goals:
+        record = next((r for r in pool if r["goal"] == goal and r["session_id"] not in used), None)
+        if record:
+            used.add(record["session_id"])
+        linked.append(record["session_id"] if record else None)
+    start = (unit.get("dispatched_at") or 0) - _CHILD_WINDOW_S
+    end = (unit.get("completed_at") or now) + _CHILD_WINDOW_S
+    for goal in {g for g, sid in zip(goals, linked) if sid is None}:
+        slots = [i for i, (g, sid) in enumerate(zip(goals, linked)) if g == goal and sid is None]
+        matches = sorted((c for c in finished if c["owner"] == owner and c["goal"] == goal and c["session_id"] not in used and start <= (c["started_at"] or 0) <= end), key=lambda c: c["started_at"] or 0)
+        if len(matches) == len(slots):
+            for i, c in zip(slots, matches):
+                linked[i] = c["session_id"]
+    return [{"goal": g, "session_id": sid} for g, sid in zip(goals, linked) if sid]
+
+
+def background_list(home: Path, session_ids: list[str]) -> dict:
+    """TAL-372: what the Agent knows about the background work of these WebUI sessions: delegations from the durable
+    ledger (with the live registry's status while they run) and notified processes from the process registry.
+    TAL-494: each delegation also names the subagent sessions it ran."""
+    live = _live_delegations()
+    delegations = _ledger_rows(home, session_ids)
+    live_children = _live_children()
+    finished = _ledger_children(home, session_ids) if delegations else []
+    now = time.time()
+    for row in delegations:
+        row["live_status"] = live.get(row["delegation_id"], {}).get("status")
+        row["children"] = unit_children(row, row["origin_ui_session_id"], live_children, finished, now)
+    return {"delegations": delegations, "processes": _owned_processes(set(session_ids))}
+
+
+def delegation_result(home: Path, session_id: str, delegation_id: str) -> str:
+    """The full result of a finished delegation unit, as the Agent words it for its own notification."""
+    db_path = home / "state.db"
+    if not db_path.exists():
+        return ""
+    with closing(sqlite3.connect(f"{db_path.resolve().as_uri()}?mode=ro", uri=True, timeout=5)) as conn:
+        try:
+            row = conn.execute("SELECT event_json FROM async_delegations WHERE delegation_id = ? AND origin_ui_session_id = ?", (delegation_id, session_id)).fetchone()
+        except sqlite3.OperationalError:
+            return ""
+    event = _json(row[0]) if row else {}
+    return format_notification(event) if event else ""
+
+
 def register(registry_) -> None:
     @registry_.method("process.drain")
     def drain_(ctx: CallContext, params: dict) -> dict:
@@ -142,6 +407,39 @@ def register(registry_) -> None:
             raise InvalidParams("process_id is required")
         return {"ok": mark_consumed(process_id)}
 
+    def _delivery_params(params: dict) -> dict:
+        evt = params.get("event")
+        if not isinstance(evt, dict):
+            raise InvalidParams("event must be an object")
+        return evt
+
+    @registry_.method("process.claim_delivery")
+    def claim_(ctx: CallContext, params: dict) -> dict:
+        evt = _delivery_params(params)
+        consumer = str(params.get("consumer") or "").strip()
+        if not consumer:
+            raise InvalidParams("consumer is required")
+        with scoped_home(profile_home_param(params)):
+            return {"claim_id": claim_delivery(evt, consumer)}
+
+    @registry_.method("process.complete_delivery")
+    def complete_(ctx: CallContext, params: dict) -> dict:
+        evt = _delivery_params(params)
+        with scoped_home(profile_home_param(params)):
+            return {"ok": complete_delivery(evt, str(params.get("claim_id") or ""))}
+
+    @registry_.method("process.release_delivery")
+    def release_(ctx: CallContext, params: dict) -> dict:
+        evt = _delivery_params(params)
+        with scoped_home(profile_home_param(params)):
+            return {"ok": release_delivery(evt, str(params.get("claim_id") or ""))}
+
+    @registry_.method("process.defer_delivery")
+    def defer_(ctx: CallContext, params: dict) -> dict:
+        evt = _delivery_params(params)
+        with scoped_home(profile_home_param(params)):
+            return {"ok": defer_delivery(evt, str(params.get("claim_id") or ""))}
+
     @registry_.method("process.format_notification")
     def format_(ctx: CallContext, params: dict) -> dict:
         evt = params.get("event")
@@ -149,6 +447,26 @@ def register(registry_) -> None:
             raise InvalidParams("event must be an object")
         return {"text": format_notification(evt)}
 
+    def _session_ids(params: dict) -> list[str]:
+        ids = params.get("session_ids")
+        if not isinstance(ids, list) or not all(isinstance(i, str) and i for i in ids):
+            raise InvalidParams("session_ids must be a list of session ids")
+        return ids
+
+    @registry_.method("process.background_list")
+    def background_list_(ctx: CallContext, params: dict) -> dict:
+        ids = _session_ids(params)
+        with scoped_home(profile_home_param(params)) as home:
+            return background_list(home, ids)
+
+    @registry_.method("process.delegation_result")
+    def delegation_result_(ctx: CallContext, params: dict) -> dict:
+        sid, did = str(params.get("session_id") or ""), str(params.get("delegation_id") or "")
+        if not sid or not did:
+            raise InvalidParams("session_id and delegation_id are required")
+        with scoped_home(profile_home_param(params)) as home:
+            return {"text": delegation_result(home, sid, did)}
+
     @registry_.method("process.list")
     def list_(ctx: CallContext, params: dict) -> dict:
         with scoped_home(profile_home_param(params)):