visru 0.0.1__py3-none-any.whl

visru/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

visru/agent/__init__.py

@@ -0,0 +1 @@
+"""The harness: the loop, the context it keeps, and the record it leaves."""

visru/agent/context.py

@@ -0,0 +1,276 @@
+"""What the model is holding: the live-image budget, elision, and compaction.
+
+Images dominate context cost. One 2000x1333 render is about 3,400 visual tokens,
+so twenty of them cost more than the rest of a long session put together. A loop
+that simply appends every image it takes dies around step thirty, and it dies by
+silently truncating rather than by raising.
+
+So this keeps a fixed number of images live and swaps older ones for a text stub
+naming the artifact that made them (README.md:91). The stub is only honest
+because `view("a_0042")` brings the image back — see `tools.resolve_ref`.
+
+Messages are provider-neutral. Blocks are plain dicts with a `type`, and a
+backend maps them to whatever its API wants; nothing here imports a vendor SDK.
+"""
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Iterator
+
+from PIL import Image
+
+from visru.config import Config
+from visru.geometry import visual_tokens
+from visru.tools import ToolResult
+
+# Rough, and deliberately so: a real tokeniser call per step would cost a network
+# round trip to learn something the budget only needs to the nearest few percent.
+CHARS_PER_TOKEN = 4
+STUB_CHARS = 140
+REACTION_CHARS = 300  # README.md:415 — what the model said after seeing the image
+
+
+def _clip(text: str, limit: int) -> str:
+    return text if len(text) <= limit else text[:limit].rstrip() + "…"
+
+
+@dataclass
+class ToolCall:
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+
+@dataclass
+class ToolOutput:
+    """One tool result, and whether its images are still live."""
+
+    call_id: str
+    name: str
+    text: str
+    images: list[Image.Image] = field(default_factory=list)
+    artifacts: list[str] = field(default_factory=list)
+    elided: bool = False
+    is_error: bool = False
+    reaction: str = ""  # what the model said after seeing this, set by add_turn
+
+    @property
+    def live_images(self) -> int:
+        return 0 if self.elided else len(self.images)
+
+    def stub(self) -> str:
+        """The note that replaces the pixels.
+
+        Two halves, per README.md:415. The tool's own first line names the asset,
+        the box and the scale — enough to decide whether the image is worth asking
+        back. What the model said next is usually its reading of that image, and
+        losing that is how a session forgets a fact it already established and
+        pays to look a second time.
+        """
+        head = self.text.splitlines()[0] if self.text else ""
+        for artifact_id in self.artifacts:  # not repeated inside its own stub
+            head = head.replace(f"artifact={artifact_id}", "").strip()
+        head = _clip(head, STUB_CHARS)
+
+        named = ", ".join(self.artifacts) or self.name
+        said = _clip(" ".join(self.reaction.split()), REACTION_CHARS)
+        return f"[{named} elided: {head}" + (f"; model noted: {said}" if said else "") + "]"
+
+    def elide(self) -> int:
+        """Drop the pixels, keep the record. Returns how many images went."""
+        freed = self.live_images
+        self.elided = True
+        return freed
+
+
+@dataclass
+class Step:
+    """One model turn and the tool results it asked for.
+
+    Compaction works in whole steps because the providers require every tool call
+    to be answered; folding away half a step would leave an unanswered call and
+    the request would be rejected.
+    """
+
+    text: str
+    calls: list[ToolCall] = field(default_factory=list)
+    outputs: list[ToolOutput] = field(default_factory=list)
+    followup: str = ""  # a word from the harness when the step called no tools
+    # Whatever the backend needs handed back verbatim next turn — on Anthropic,
+    # the assistant content blocks, because thinking blocks must be replayed
+    # unchanged on the same model and cannot be rebuilt from text.
+    raw: Any = None
+
+
+class Context:
+    def __init__(self, task: str, cfg: Config, system: str = ""):
+        self.task = task
+        self.cfg = cfg
+        self.system = system
+        self.steps: list[Step] = []
+        self.summary: str = ""
+        self.elisions = 0
+        self.compactions = 0
+
+    # --- building ---------------------------------------------------------
+    def add_turn(self, text: str, calls: list[ToolCall] | None = None,
+                 raw: Any = None) -> Step:
+        # What the model says now is its reading of whatever it was just shown, so
+        # it belongs to those results: it is the half of an elision note that
+        # carries meaning rather than coordinates.
+        if text and self.steps:
+            for out in self.steps[-1].outputs:
+                if not out.reaction:
+                    out.reaction = text
+        step = Step(text=text, calls=list(calls or []), raw=raw)
+        self.steps.append(step)
+        return step
+
+    def add_output(self, call: ToolCall, result: ToolResult,
+                   is_error: bool = False) -> ToolOutput:
+        if not self.steps:
+            raise ValueError("a tool result needs a model turn to answer")
+        out = ToolOutput(call_id=call.id, name=call.name, text=result.text,
+                         images=list(result.images), artifacts=list(result.artifacts),
+                         is_error=is_error)
+        self.steps[-1].outputs.append(out)
+        self.enforce()
+        return out
+
+    def add_user(self, text: str) -> None:
+        """A word from the harness rather than from a tool.
+
+        Only legal after a turn that called nothing: a step with tool results
+        already owes the model a user message, and two in a row is a bad request.
+        """
+        if not self.steps:
+            raise ValueError("nothing to reply to yet")
+        if self.steps[-1].outputs:
+            raise ValueError("that step already answers with tool results")
+        self.steps[-1].followup = text
+
+    def add_error(self, call: ToolCall, message: str) -> ToolOutput:
+        """A failed call still has to answer its tool_use, or the next request 400s."""
+        return self.add_output(call, ToolResult(text=f"error: {message}"), is_error=True)
+
+    # --- budget -----------------------------------------------------------
+    @property
+    def live_images(self) -> int:
+        return sum(o.live_images for step in self.steps for o in step.outputs)
+
+    def _outputs(self) -> Iterator[ToolOutput]:
+        for step in self.steps:
+            yield from step.outputs
+
+    def estimate_tokens(self) -> int:
+        patch = self.cfg.model.patch
+        chars = len(self.system) + len(self.task) + len(self.summary)
+        tokens = 0
+        for step in self.steps:
+            chars += len(step.text)
+            for call in step.calls:
+                chars += len(call.name) + len(json.dumps(call.arguments, default=str))
+            for out in step.outputs:
+                chars += len(out.stub()) if out.elided else len(out.text)
+                if not out.elided:
+                    tokens += sum(visual_tokens(im.width, im.height, patch)
+                                  for im in out.images)
+        return tokens + chars // CHARS_PER_TOKEN
+
+    # --- keeping it inside the limits -------------------------------------
+    def enforce(self) -> None:
+        self._elide()
+        self._compact()
+
+    def _elide(self) -> None:
+        """Swap the oldest images for stubs once the budget is exceeded.
+
+        A batch at a time, not one per step: rewriting history invalidates the
+        cached prefix, so doing it every time an image arrives would pay the
+        cache miss on every single turn (config.py:34).
+        """
+        limit = self.cfg.context.max_live_images
+        if self.live_images <= limit:
+            return
+        freed = 0
+        for out in self._outputs():  # oldest first
+            if freed >= self.cfg.context.elide_batch:
+                break
+            if out.live_images:
+                freed += out.elide()
+                self.elisions += 1
+
+    def _compact(self) -> None:
+        """Fold the oldest steps into one note when the whole thing grows too big.
+
+        Artifact IDs survive verbatim. A compacted summary that dropped them would
+        strand the evidence: the model would cite an ID the ledger can still see
+        but the model can no longer name, and the claim would be refused for a
+        reason invisible to it.
+        """
+        if self.estimate_tokens() <= self.cfg.context.compact_at_tokens:
+            return
+        if len(self.steps) < 4:  # nothing to fold that is not still in play
+            return
+
+        keep = max(2, len(self.steps) // 2)
+        folded, self.steps = self.steps[:-keep], self.steps[-keep:]
+
+        lines, seen = [], []
+        for step in folded:
+            head = step.text.strip().splitlines()[0] if step.text.strip() else ""
+            if head:
+                lines.append(f"- {head[:STUB_CHARS]}")
+            for out in step.outputs:
+                for artifact_id in out.artifacts:
+                    if artifact_id not in seen:
+                        seen.append(artifact_id)
+
+        self.summary = (
+            f"{self.summary}\n" if self.summary else "") + (
+            f"[{len(folded)} earlier steps compacted]\n" + "\n".join(lines) +
+            (f"\nArtifacts from those steps, still viewable by ID: {', '.join(seen)}"
+             if seen else ""))
+        self.compactions += 1
+
+    # --- rendering --------------------------------------------------------
+    def render(self) -> list[dict[str, Any]]:
+        """Provider-neutral messages. Blocks carry PIL images; backends encode them."""
+        opening = self.task if not self.summary else f"{self.task}\n\n{self.summary}"
+        messages: list[dict[str, Any]] = [
+            {"role": "user", "content": [{"type": "text", "text": opening}]}]
+
+        for step in self.steps:
+            assistant: list[dict[str, Any]] = []
+            if step.text:
+                assistant.append({"type": "text", "text": step.text})
+            for call in step.calls:
+                assistant.append({"type": "tool_use", "id": call.id,
+                                  "name": call.name, "input": call.arguments})
+            if assistant:
+                # `raw`, when a backend stored one, is that backend's own version of
+                # this turn. It may replay it instead of the neutral blocks; every
+                # other backend ignores the key.
+                messages.append({"role": "assistant", "content": assistant,
+                                 "raw": step.raw})
+
+            if step.outputs:
+                results = [{"type": "tool_result", "tool_use_id": out.call_id,
+                            "content": self._result_blocks(out),
+                            "is_error": out.is_error}
+                           for out in step.outputs]
+                messages.append({"role": "user", "content": results})
+            elif step.followup:
+                messages.append({"role": "user",
+                                 "content": [{"type": "text", "text": step.followup}]})
+        return messages
+
+    @staticmethod
+    def _result_blocks(out: ToolOutput) -> list[dict[str, Any]]:
+        """Images first, then text — the order the MCP server already established."""
+        if out.elided:
+            return [{"type": "text", "text": out.stub()}]
+        blocks: list[dict[str, Any]] = [{"type": "image", "image": im}
+                                        for im in out.images]
+        blocks.append({"type": "text", "text": out.text})
+        return blocks

visru/agent/loop.py

@@ -0,0 +1,184 @@
+"""The agent loop: ask the model, run what it asks for, write it all down.
+
+Deliberately thin. Everything hard lives elsewhere — the image budget in
+`context.py`, the record in `trajectory.py`, what the evidence warrants in
+`evidence/ledger.py` — and this file is what makes them take turns.
+
+The loop ends one of three ways: the model submits a report the ledger accepts,
+the model stops asking for tools, or it runs out of steps. All three are results;
+only the first is an answer.
+"""
+
+import json
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from visru.agent.context import Context, ToolCall
+from visru.agent.trajectory import Trajectory
+from visru.backends import Backend, Response
+from visru.tools import ToolContext, ToolResult, registry
+from visru.tools.registry import USER_ERRORS
+
+PROMPT_PATH = Path(__file__).parent / "prompts" / "system.md"
+
+# Said when the model stops calling tools without reporting. Without this a loop
+# just spins: the model says "I think it is a stop sign", nobody asks for
+# evidence, and 200 steps later there is still no report.
+NUDGE = ("Finish by calling submit_report with a claim for each thing you are "
+         "asserting, each with the artifact IDs that show it.")
+
+# Said instead when the turn died at max_tokens. A truncated turn carries no call,
+# so the nudge above would answer a question the model never finished asking, and
+# the next turn spends another full output budget on more of the same.
+TRUNCATED = ("Your last turn was cut off at the output limit before it called "
+            "anything. Call one tool now, with no preamble.")
+
+# The same call, with the same arguments, this many times in a run: the model is
+# not reading the answers. Counted over the whole run rather than consecutively,
+# because a stuck model cycles rather than repeats — view, ocr, view, ocr, each
+# pair identical to the last — and any "same as the previous turn" test sees two
+# alternating signatures and never fires. Re-viewing an elided artifact is normal,
+# so the limit leaves room for a few honest repeats.
+REPEAT_LIMIT = 4
+
+# Turns that died at max_tokens without calling anything, over the whole run — not
+# in a row. An open model that starts repeating itself alternates: one degenerate
+# turn, one small real call, one degenerate turn. Every consecutive counter resets
+# on the call in between, so this one deliberately never resets.
+TRUNCATION_LIMIT = 3
+
+
+def system_prompt() -> str:
+    return PROMPT_PATH.read_text()
+
+
+@dataclass
+class Session:
+    """How a run ended, and where to read what happened."""
+
+    session: str
+    steps: int
+    reason: str  # reported | stopped | stuck | exhausted
+    report: str = ""
+    trajectory: Path | None = None
+    elisions: int = 0
+    compactions: int = 0
+    peak_live_images: int = 0
+    usage: dict[str, int] = field(default_factory=dict)
+
+    @property
+    def reported(self) -> bool:
+        return self.reason == "reported"
+
+    def summary(self) -> str:
+        return (f"{self.session}: {self.reason} after {self.steps} steps "
+                f"({self.elisions} images elided, {self.compactions} compactions, "
+                f"peak {self.peak_live_images} live)")
+
+
+def _accrue(total: dict[str, int], usage: dict[str, int]) -> None:
+    for key, value in usage.items():
+        total[key] = total.get(key, 0) + value
+
+
+def _child_runner(backend: Backend):
+    """A subagent session on this model, offered every tool but the harness-only ones."""
+    tools = [name for name in registry.TOOLS if name not in registry.HARNESS_ONLY]
+
+    def run_child(task: str, child: ToolContext, max_steps: int) -> "Session":
+        return run(task, child, backend, max_steps=max_steps, tools=tools)
+    return run_child
+
+
+def run(task: str, ctx: ToolContext, backend: Backend, max_steps: int = 200,
+        system: str | None = None, tools: list[str] | None = None) -> Session:
+    """Drive one session to an answer, a stop, or the step limit.
+
+    `tools` limits which tools the model is offered and may call; None means all.
+    """
+    system = system_prompt() if system is None else system
+    context = Context(task=task, cfg=ctx.cfg, system=system)
+    ctx.run_child, ctx.child_usage = _child_runner(backend), {}  # for `delegate`
+    log = Trajectory(ctx.root, ctx.session)
+    schemas = registry.schemas(tools)
+    log.session_header(ctx.cfg, task, system, [s["name"] for s in schemas])
+
+    usage: dict[str, int] = {}
+    peak, step, nudged = 0, -1, False
+    seen: Counter[tuple] = Counter()
+    truncations = 0
+    reason, report = "exhausted", ""
+
+    for step in range(max_steps):
+        response: Response = backend.complete(system, context.render(), schemas)
+        _accrue(usage, response.usage)
+        log.model_turn(step, response.text, response.usage)
+        context.add_turn(response.text, response.calls, raw=response.raw)
+
+        if not response.calls:
+            if response.stop_reason == "length":
+                truncations += 1
+                if truncations >= TRUNCATION_LIMIT:
+                    reason = "stuck"
+                    break
+                context.add_user(TRUNCATED)
+                continue
+            # Ask once for a report. If it still calls nothing, it has finished
+            # thinking, and spending the rest of the budget to prove that is waste.
+            if nudged:
+                reason = "stopped"
+                break
+            nudged = True
+            context.add_user(NUDGE)
+            continue
+        nudged = False
+
+        sig = tuple((c.name, json.dumps(c.arguments, sort_keys=True))
+                   for c in response.calls)
+        seen[sig] += 1
+        if seen[sig] >= REPEAT_LIMIT:
+            reason = "stuck"
+            break
+
+        accepted, peak = _run_calls(ctx, response.calls, tools, context, log, step, peak)
+        if accepted is not None:
+            reason, report = "reported", accepted
+            break
+
+    _accrue(usage, ctx.child_usage)  # subagents ran on this session's behalf
+    return Session(session=ctx.session, steps=step + 1, reason=reason, report=report,
+                   trajectory=log.path, elisions=context.elisions,
+                   compactions=context.compactions,
+                   peak_live_images=max(peak, context.live_images), usage=usage)
+
+
+def _run_calls(ctx: ToolContext, calls: list[ToolCall], tools: list[str] | None,
+               context: Context, log: Trajectory, step: int,
+               peak: int) -> tuple[str | None, int]:
+    """Run one turn's calls in order. Returns (accepted report text or None, peak)."""
+    for call in calls:
+        result, error = _execute(ctx, call, tools)
+        context.add_output(call, result)
+        log.tool_call(step, call.name, call.arguments, result.text,
+                      result.artifacts, shown=bool(result.images), error=error)
+        peak = max(peak, context.live_images)
+        if call.name == "submit_report" and error is None:
+            return result.text, peak
+    return None, peak
+
+
+def _execute(ctx: ToolContext, call: ToolCall,
+             allowed: list[str] | None = None) -> tuple[ToolResult, str | None]:
+    """Run one call. Bad input comes back as a message, not an exception.
+
+    A raised error would end the session; the model can usually fix a bad box or a
+    misspelled asset ID on its next turn, and it only can if it is told what was
+    wrong. This mirrors what the MCP server does with ToolError.
+    """
+    try:
+        return registry.execute(ctx, call.name, call.arguments, allowed), None
+    except USER_ERRORS as exc:
+        message = exc.args[0] if exc.args else str(exc)
+        return ToolResult(text=f"error: {message}"), str(message)

visru/agent/prompts/system.md

@@ -0,0 +1,89 @@
+You are a visual investigator. You answer questions about images and video by
+looking at them with tools, not by guessing from a thumbnail.
+
+The images you are shown are renders of much larger assets. Every coordinate you
+send or receive is in **source-asset pixels** — the original file's resolution —
+never the pixels of the render in front of you.
+
+# How to work
+
+1. **Start coarse.** Call `list_assets` to see what exists. For a video, call
+   `sample_frames` before anything else. Find the thing first, then look closely.
+
+2. **Zoom before claiming.** A render below `inspected_scale` is not evidence.
+   Every tool result tells you its scale and says plainly whether it is at or
+   below that line; if it says BELOW, call `view` on a tighter box before you
+   assert anything about small text or small objects. Reading a whole 4K frame
+   at once produces confident nonsense.
+
+3. **Refer to things by mark ID.** `detect`, `ocr` and `segment` return numbered
+   marks. Say "mark 3", and pass marks to `segment` or `overlay` with
+   `from_artifact`. Do not retype pixel coordinates you were just given.
+
+4. **Check counts, text and locations a second way, with `cross_check`.** A
+   reading from one method is a guess that sounds like a fact. Get a second
+   method's output — a `detect` count against your own reading of a zoomed
+   `view`, an `ocr` line against what you can see — then call `cross_check` with
+   both artifact IDs and your reading. It compares them and returns a check
+   artifact. Two methods only count as independent if they do not share a model:
+   a `segment` mask prompted from a `detect` box inherits that detection's
+   errors, and `cross_check` will refuse the pair.
+
+5. **Know what you have not looked at.** Call `coverage` before you report. It
+   lists what you viewed at or above `inspected_scale` and what you never
+   opened; say so in your report rather than implying you looked everywhere.
+
+6. **Look at your overlays.** `overlay` draws a claim back onto the pixels. If the
+   shape does not sit on the thing it names, the claim is wrong — say so and fix
+   it rather than reporting it.
+
+# Video
+
+Frames are addressed as `vid_<id>#<frame_index>`; times are in seconds.
+
+- **Find when first.** `search` with a short description ranks frames sampled
+  about once a second and merges neighbouring hits into time windows. A window
+  says where to look, not what happened.
+- **Then look.** `sample_frames` with `t0`/`t1` around a candidate window, then
+  `view` a frame ref before claiming any detail. Narrow the window with a
+  second, tighter `sample_frames` rather than guessing between two cells.
+- **Follow an object** with `track` from one frame: it reports when the object
+  is present and when it drops out. Check the frames either side of a change
+  with `view` — a mask that drifts is a lost track, not an event.
+- **Long videos:** `delegate` gives each time window to a subagent and returns
+  their claims and artifact IDs. View the key frames yourself before reporting.
+- **Answer times as a window**, `start..end` in seconds, e.g. `12.4..15.0`. A
+  `cross_check` of kind `temporal` compares your reading of frames against a
+  `search` window or a `track`.
+
+# Artifacts
+
+Every tool that shows you pixels returns an artifact ID like `a_0042`. Two uses:
+
+- **Cite it.** Evidence in your report is a list of artifact IDs.
+- **Ask for it back.** Older images are replaced in your context by a note like
+  `[a_0042 elided: source=im_9b9 box=[1100, 280, 1460, 580] scale=2.000; model
+  noted: the sign reads TRADER JOE'S]`. The pixels are gone, the artifact is not.
+  Call `view("a_0042")` to see it again exactly as it was. You do not need to
+  re-derive the box.
+
+# Finishing
+
+End by calling `submit_report` with one claim per thing you are asserting.
+
+A claim carries a status, and the ledger checks that your evidence warrants it.
+It will reject a status stronger than what you have shown, and it lists every
+problem at once rather than one per attempt:
+
+- No evidence? The claim must be `hypothesis`.
+- Evidence but no passing independent check? `supported`.
+- Evidence plus a `cross_check` artifact that agreed, cited in the claim's
+  `checks` as `"a_0009"`? `verified`. A check you describe yourself does not
+  count, however you word it.
+- A `cross_check` that disagreed? `contested`.
+- A DISAGREE is a reportable result, not to retry
+
+Claim what you actually established. A `hypothesis` stated honestly is worth more
+than a `verified` that gets refused, and far more than a confident wrong answer.
+If you could not determine something, say so and report it as unresolved rather
+than filling the gap.

visru/agent/subagents.py

@@ -0,0 +1,116 @@
+"""Subagents: one agent per time window of a video, run one after another.
+
+A long video does not fit in one context at useful resolution: an hour at one
+contact sheet a minute is sixty sheets, and the image budget holds sixteen. So
+the parent splits the video into windows and hands each to a child session with
+its own context, trajectory and ledger. The parent gets back text — each child's
+claims and the artifact IDs behind them — never the child's images, so its own
+context stays small, and it can `view` any of those artifacts itself.
+
+A child is an ordinary `loop.run` on a session named `<parent>_w<k>`. That name
+is how coverage credits the parent with what its children looked at.
+
+ponytail: sequential. Children in threads would need a lock around artifact IDs
+and one model instance per thread; add when wall-clock on long videos hurts.
+"""
+
+import json
+
+from visru.evidence.ledger import LEDGER_DIR
+from visru.tools import ToolContext, ToolResult, resolve_ref
+from visru.workspace.registry import parse_ref
+
+MAX_WINDOWS = 8
+
+CHILD_TASK = """You are one of several investigators, each given one time window of the \
+same video.
+
+Video: {asset} ({name}), {duration:.1f} s long.
+Your window: {t0:.2f}..{t1:.2f} s. Look only there; others cover the rest.
+
+Question: {question}
+
+Investigate with your tools — sample_frames with t0/t1 inside your window is the \
+place to start — then call submit_report. If what the question asks about happens \
+in your window, give a claim whose text states its time window as "start..end" in \
+seconds. If it does not, give a claim saying so, citing the frames you looked at. \
+Every claim needs the artifact IDs that show it."""
+
+
+def _windows(duration: float, windows: list[list[float]] | None, n: int
+             ) -> list[tuple[float, float]]:
+    if windows is None:
+        if not 1 <= n <= MAX_WINDOWS:
+            raise ValueError(f"n must be 1..{MAX_WINDOWS}, got {n}")
+        return [(duration * i / n, duration * (i + 1) / n) for i in range(n)]
+    if not windows or len(windows) > MAX_WINDOWS:
+        raise ValueError(f"give 1..{MAX_WINDOWS} windows as [[t0, t1], ...] in seconds")
+    out = []
+    for w in windows:
+        if len(w) != 2:
+            raise ValueError(f"each window is [t0, t1] in seconds, got {w}")
+        t0, t1 = max(0.0, float(w[0])), min(duration, float(w[1]))
+        if t1 <= t0:
+            raise ValueError(f"window {w} is empty inside the video's 0..{duration:.2f}s")
+        out.append((t0, t1))
+    return out
+
+
+def _claims(ctx: ToolContext, session: str) -> list[dict]:
+    path = ctx.root / LEDGER_DIR / f"{session}.json"
+    return json.loads(path.read_text())["claims"] if path.is_file() else []
+
+
+def _claim_lines(head: str, claims: list[dict], cited: list[str]) -> str:
+    """One window's report as text; the artifact IDs it cites are added to `cited`."""
+    lines = [head]
+    for c in claims:
+        refs = list(c.get("evidence", [])) + [
+            k["check"] for k in c.get("checks", []) if isinstance(k, dict)
+            and k.get("check")]
+        cited.extend(refs)
+        lines.append(f"  {c['claim_id']} [{c['status']}] {c['text']}"
+                     + (f"  evidence: {', '.join(refs)}" if refs else ""))
+    if not claims:
+        lines.append("  no report: treat this window as not inspected")
+    return "\n".join(lines)
+
+
+def delegate(ctx: ToolContext, ref: str, question: str,
+             windows: list[list[float]] | None = None, n: int = 4,
+             max_steps: int = 15) -> ToolResult:
+    """Run one subagent per time window and collect what each reported."""
+    if ctx.run_child is None:
+        raise ValueError("delegate runs subagents, which needs the visru agent loop; "
+                         "under another harness, use its own subagents")
+    if not str(question).strip():
+        raise ValueError("delegate needs the question each subagent should answer")
+    asset_id, _ = parse_ref(resolve_ref(ctx, ref)[0])
+    asset = ctx.registry.get(asset_id)
+    if asset.kind != "video":
+        raise ValueError(f"{asset_id} is an image; delegate splits a video by time")
+    duration = asset.duration or 0.0
+    spans = _windows(duration, windows, n)
+
+    blocks, cited = [], []
+    for t0, t1 in spans:
+        ctx.children += 1
+        child = ToolContext(ctx.root, ctx.cfg, session=f"{ctx.session}_w{ctx.children}")
+        task = CHILD_TASK.format(asset=asset_id, name=asset.name, duration=duration,
+                                 t0=t0, t1=t1, question=question)
+        result = ctx.run_child(task, child, max_steps)  # no delegate inside: no recursion
+        for key, value in result.usage.items():
+            ctx.child_usage[key] = ctx.child_usage.get(key, 0) + value
+
+        claims = _claims(ctx, child.session) if result.reported else []
+        head = (f"[{t0:.2f}..{t1:.2f}s] {child.session}: {result.reason} after "
+                f"{result.steps} steps")
+        blocks.append(_claim_lines(head, claims, cited))
+
+    text = (f"delegated {len(spans)} windows of {asset_id} ({duration:.1f}s) to subagents:\n"
+            + "\n".join(blocks)
+            + "\nTheir artifacts are yours to view or cite by ID, and a check they ran "
+            "can go in your own claim's checks. Their conclusions are not yours until you "
+            "have looked: view the key frames before reporting.")
+    return ToolResult(text=text, artifacts=list(dict.fromkeys(cited)))
+