taskops-cli 0.2.0__py3-none-any.whl

taskops/contracts/gitstate.py

@@ -0,0 +1,45 @@
+"""Where a task's code actually IS — on a branch, and whether anybody else can see it.
+
+The gap this closes: a task marked `done` whose commits never left the machine is invisible to every
+teammate, and the board said "done" anyway. Commits proved that work happened; this proves it is
+REACHABLE. Those are different claims and only one of them was being made.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+__all__ = ["BranchState"]
+
+
+class BranchState(TypedDict):
+    """One branch's relationship to its remote."""
+
+    branch: str
+    upstream: str
+    """`origin/tk/tk-4f2a9c/…`, or "" when the branch has never been pushed at all.
+
+    Empty is the common case for a task branch and the one that matters most: it means the work
+    exists on exactly one laptop.
+    """
+
+    ahead: int
+    """Commits here the remote does not have. Nonzero = unpushed work."""
+
+    behind: int
+    """Commits the remote has and this branch does not — somebody else moved it."""
+
+    pushed: bool
+    """`ahead == 0` AND there is an upstream. The one boolean a card needs.
+
+    Derived rather than left to each reader, because "pushed" from two integers and a string is a
+    calculation three renderers would each get subtly wrong.
+    """
+
+    exists: bool
+    """False when the branch is not in this repository at all.
+
+    Not the same as unpushed: an agent on another machine holds a lease naming a branch this clone
+    has never heard of, and a board that reported that as "0 commits, unpushed" would be describing
+    a branch it cannot see as though it had looked.
+    """

taskops/contracts/index.py

@@ -0,0 +1,37 @@
+"""The INDEX of what has been written up — one row per file in `.taskops/reports/`.
+
+Deliberately not `ReportFile`: that carries the whole markdown, and a listing of thirty days
+that shipped thirty dossiers would be a megabyte of text nobody on the screen is reading. This
+is the row you click, and the body arrives on `GET /api/report` when you do.
+
+`label` is the file's STEM and is treated as an opaque string everywhere. Today it is a date;
+a report over a range is named for the range (`2026-07-22..2026-07-28`, `all`), and anything
+that parsed the label as a day would break on the first one of those.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+__all__ = ["ReportEntry"]
+
+
+class ReportEntry(TypedDict):
+    label: str
+    """The file's stem — a date, or a range. Opaque: what you pass back to read or narrate it."""
+
+    path: str
+    exists: bool
+    """False for the one row that is not a file: today, when nobody has written it up yet. It
+    is listed anyway, because 'generate today's report' is the reason this screen exists."""
+
+    stale: bool
+    missing_events: int
+    """How many of the day's events landed after the report was generated. Always 0 for a label
+    that is not a single day — a range has no window this can be counted against."""
+
+    has_narration: bool
+    """Whether the prose section has been written. The dossier's facts are free to regenerate;
+    the narration is the part a model was paid for and a human may have edited."""
+
+    bytes: int

taskops/contracts/lease.py

@@ -0,0 +1,43 @@
+"""The lease — a claim that expires, which is what makes a crash survivable.
+
+A boolean `assigned_to` column cannot express "this agent said it was working on
+it and then its process was killed", so a board built on one accumulates tasks
+nobody is doing and nobody can take. A lease has a deadline: every taskops call
+the holder makes pushes it out, and silence hands the task back.
+
+Not a filesystem lock, for the same reason: a lock file outlives the process that
+took it, and cleaning one up correctly is exactly the problem a TTL already
+solved.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+__all__ = ["Lease"]
+
+
+class Lease(TypedDict):
+    """Who is on a task, until when, and where they are doing it."""
+
+    task: str
+    actor: str
+
+    session: str
+    """The Claude Code session id, when the claim came from an agent.
+
+    The join key to everything outside taskops: the transcript at
+    `~/.claude/projects/<slug>/<session>.jsonl`, and the hook invocations that
+    report activity. Without it, a live board can show that a task is claimed but
+    not what its agent is doing right now.
+    """
+
+    branch: str
+    """`tk/<id>/<slug>`, once the agent creates it. Empty until then — a claim
+    happens before the branch, and the guard that binds commits to tasks needs to
+    tell "no branch yet" apart from "on the wrong branch"."""
+
+    acquired: float
+    expires: float
+    """When silence gives the task back. Compared against `_clock.now()`, so it
+    is wall-clock and survives a restart on either side."""

taskops/contracts/log.py

@@ -0,0 +1,59 @@
+"""An agent's conversation, as the card shows it.
+
+Claude Code writes every session to a JSONL transcript. taskops does NOT copy those into its own event
+log, and that is deliberate: one session here was 198 KB for 39 entries, `events.jsonl` is committed to
+git, and the whole value of that file is that a human can read its diff. So the card stores a POINTER
+and the transcript is read on demand.
+
+The honest consequence, worth stating where the type is defined: a transcript is LOCAL. A teammate who
+pulls the log gets the card, the commits and the conversation summary, but not the transcript — that
+file only exists on the machine the agent ran on.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+__all__ = ["LogEntry", "SessionLog", "EntryKind"]
+
+EntryKind = Literal["prompt", "thinking", "text", "tool", "result", "other"]
+"""What one entry IS, flattened from the transcript's shape.
+
+The raw format nests differently per role — an assistant message holds a list of content blocks, each
+with its own type — and a reader wants one flat stream. `other` is the escape hatch: the format is not
+documented as stable, so an entry this version does not recognise is shown rather than dropped.
+"""
+
+
+class LogEntry(TypedDict):
+    """One turn, one thought, or one tool call."""
+
+    kind: EntryKind
+    text: str
+    """The readable content. For a tool call, a one-line summary rather than the arguments — a
+    dashboard showing forty lines of JSON per Edit is a dashboard nobody scrolls."""
+
+    tool: str
+    """The tool name for `kind == "tool"`, else "". Kept separate from `text` so a viewer can badge
+    it without parsing prose back apart."""
+
+    ts: float
+    session: str
+
+
+class SessionLog(TypedDict):
+    """Everything one card's agents said, in order."""
+
+    task: str
+    sessions: list[str]
+    """The session ids found for this card. More than one is normal: a card can be released and
+    picked up again, and each attempt is its own session."""
+
+    entries: list[LogEntry]
+    source: str
+    """Where the transcripts were read from, so a viewer showing nothing can say WHY — a missing
+    directory and an empty conversation look identical otherwise."""
+
+    truncated: bool
+    """True when entries were dropped to stay under a limit. Reported rather than silent: a viewer
+    that quietly showed the first hundred turns of a long session would be lying about the ending."""

taskops/contracts/remote.py

@@ -0,0 +1,48 @@
+"""The ONE server this project syncs against, and this machine's place in its log.
+
+One remote per project, deliberately. Two would be federation — the same event arriving
+under two cursors, a report whose "who saw more" question has three answers — and none of
+that is designed. `remote add` refuses the second one by name rather than silently keeping
+a list nobody reads.
+
+This is the only contract that carries a SECRET. It is written to `.taskops/remote.json`
+with mode 0600, that path is inside the block `taskops init` gitignores, and no renderer
+ever prints `token` — a token in a commit is the exact disaster the file mode exists to
+prevent, and it survives every rotation of the branch it landed on.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+__all__ = ["Remote"]
+
+
+class Remote(TypedDict):
+    url: str
+    """The server's base, with no trailing slash — `https://taskops.example.com`."""
+
+    token: str
+    """The bearer sent on every request. Never printed, never rendered, never committed."""
+
+    pushed: int
+    """The last LOCAL `seq` this machine has sent UP. Its own number, never the server's.
+
+    The first version drained the `exported` flag instead — shared with the git-log export —
+    and on any project that had ever run `taskops sync`, everything was already marked and
+    `push` sent nothing, silently, forever. Found live on the first real project connected:
+    a 370-event board pushed as `0 event(s) out`. Two sinks need two cursors.
+    """
+
+    cursor: int
+    """The last `seq` this machine imported FROM THAT SERVER.
+
+    A SERVER-side number, and it is only ever compared against server-side numbers: every
+    sqlite numbers its own rows, so measuring this against a local `seq` would be a
+    coincidence pretending to be an ordering.
+
+    If the server forgets it — a store recreated from scratch — the next `GET /api/sync`
+    answers from 0 and the client re-imports everything. That is a no-op, not a repair
+    job: ids are content hashes, so `relay` accepts each event exactly once no matter how
+    many times it is offered.
+    """

taskops/contracts/results.py

@@ -0,0 +1,84 @@
+"""What the use cases hand back — the shapes the renderers turn into text.
+
+Separate from the entities because they answer a QUESTION rather than describing
+a thing: a `Claim` is not stored anywhere, it is the assembled answer to "what
+should I work on", including the parts the agent would otherwise have to ask three
+more times for.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+from .dep import Dep
+from .event import Inbox
+from .lease import Lease
+from .task import Task, TaskView
+
+__all__ = ["PlanResult", "Claim", "NextResult", "UpdateResult", "EditResult"]
+
+
+class PlanResult(TypedDict):
+    """What a decomposition created. Returned in creation order, which is the
+    order the caller listed them — so an agent can map its own plan onto ids."""
+
+    created: list[Task]
+    deps: list[Dep]
+    unblocked: list[str]
+    """Ids that came out of `plan` already pickable. Usually the leaves; if this
+    is empty the caller built a graph where nothing can start, which is a planning
+    bug worth seeing immediately rather than discovering at the first `next`."""
+
+
+class Claim(TypedDict):
+    """A task, claimed, with everything needed to start on it."""
+
+    view: TaskView
+    lease: Lease
+    branch: str
+    """The branch to create: `tk/<id>/<slug>`. Handed over rather than left to the
+    agent to compose, because the commit guard matches on this exact shape."""
+
+    inbox: Inbox
+    """Delivered with the claim. An agent that just picked up work is the most
+    likely to have been messaged about it, and this is a read it was making
+    anyway — so the inbox rides along instead of costing another call."""
+
+
+class NextResult(TypedDict):
+    """The answer to "what should I do", including "nothing, and here is why"."""
+
+    claim: Claim | None
+    reason: str
+    """Empty when a claim was made. Otherwise the actual obstacle — everything is
+    blocked, everything is claimed by someone else, or the project is finished.
+    An agent told "nothing ready" with no reason asks a human; told which, it can
+    often unblock itself."""
+
+    ready: int
+    working: int
+    blocked: int
+
+
+class UpdateResult(TypedDict):
+    """The effect of one update: the new state, and what it set free."""
+
+    task: Task
+    unblocked: list[Task]
+    """Tasks that became pickable because this one closed. The auto-unblock, made
+    visible: an agent finishing a task learns what it just handed to the fleet."""
+
+    notified: list[str]
+    """Actors whose inbox this reached — the mentions, resolved."""
+
+
+class EditResult(TypedDict):
+    """The card after a rewrite, and which fields actually moved.
+
+    `changed` rather than a bare task: an edit that asked for a new title and got none —
+    because the value was already there — is worth saying out loud, since the alternative
+    is a caller believing it landed something the log has no event for.
+    """
+
+    task: Task
+    changed: list[str]

taskops/contracts/task.py

@@ -0,0 +1,94 @@
+"""The task, and the whole of what an agent needs to read to work on one.
+
+`Task` is the row. `TaskView` is the answer to "what am I doing and what does it
+touch" — assembled once so an agent does not have to make five calls to find out
+that something else is already editing the file it was about to rewrite.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+from .._types import Status
+from .commit import CommitRef
+from .event import Event
+from .lease import Lease
+
+__all__ = ["Task", "TaskView"]
+
+
+class Task(TypedDict):
+    """One unit of work. Flat on purpose: this IS the row and the wire format."""
+
+    id: str
+    title: str
+
+    spec: str
+    """The brief, complete enough that an agent reads it and needs nothing else.
+
+    The single most important field in the system and the one most often written
+    badly. A title is a label; a spec says what done looks like, what must not
+    change, and where to look — because the reader is a fresh context that was
+    not in the room when the work was decided.
+    """
+
+    status: Status
+    priority: int
+    """0 urgent … 3 someday. Lower sorts first, which is why it is not a Literal:
+    a project that wants five bands should not need an engine change."""
+
+    parent: str | None
+    """An epic's id. The TREE is here; the DAG is `deps` — they answer different
+    questions ("what is this part of" vs "what must happen first")."""
+
+    labels: list[str]
+    files: list[str]
+    """The edit surface, as the planner understands it. A hint, never a lock: the
+    scheduler uses it to avoid handing two agents the same file, and being wrong
+    costs a merge conflict rather than a wrong answer."""
+
+    created_by: str
+
+    assignee: str
+    """Who this card is FOR, or "" for the open pool.
+
+    Set by a planner that knows who should do the work, and by `dispatch` before it launches a
+    worker. It is not a claim: an assigned card still has to be claimed, so the lease stays the only
+    thing that says somebody is actually on it. What assignment changes is the SCHEDULER — an
+    assigned card is invisible to every other agent, which is what makes "this one is yours" mean
+    something instead of being a label anybody can ignore.
+    """
+
+    created: float
+    updated: float
+
+
+class TaskView(TypedDict):
+    """Everything about one task, in one read."""
+
+    task: Task
+    lease: Lease | None
+    blocked_by: list[Task]
+    """Open dependencies. Empty is the whole reason a task is pickable."""
+
+    blocks: list[Task]
+    """What is waiting on this one — the argument for finishing it today."""
+
+    children: list[Task]
+    neighbours: list[Task]
+    """Tasks whose `files` intersect this one's. The collision warning: an agent
+    that reads this knows who to message before it starts, not after the merge."""
+
+    thread: list[Event]
+    """Comments and directed messages, oldest first. The conversation about this
+    task, from every actor that has ever touched it."""
+
+    commits: list[CommitRef]
+    """The commits bound to this task, oldest first — with their subjects and the files they touched.
+
+    `list[str]` at first, which threw away the subject and the file list the event already carried: a
+    finished card rendered as a column of hashes, and the only substance on the page was whatever the
+    agent happened to put in a comment.
+    """
+
+    history: list[Event]

taskops/contracts/tools.py

@@ -0,0 +1,110 @@
+"""What a tool call carries IN — the inputs, as types.
+
+The MCP `inputSchema` is generated from these (`transports/mcp/schema.py`), so a parameter is
+declared once and cannot exist on the wire without existing in the dispatch, or the reverse — which
+is how a tool ends up advertising a flag nobody reads.
+
+The description TEXT lives in `_fields`. It is the contract, not decoration — the only thing a
+calling agent reads before choosing arguments — but it is prose, and keeping it out of here means a
+change to a tool's SHAPE is reviewable on its own.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal, TypedDict
+
+from . import _fields as f
+
+__all__ = ["PlanParams", "NextParams", "UpdateParams", "AskParams", "ReportParams",
+           "DispatchParams", "RecoverParams"]
+
+
+class _Target(TypedDict):
+    """Which repository. Every tool needs it; none of them guesses it."""
+
+    repo_path: f.Repo
+
+
+class _PlanRequired(_Target):
+    tasks: Annotated[list[dict[str, Any]], f.TASKS]
+
+
+class PlanParams(_PlanRequired, total=False):
+    actor: f.Actor
+
+
+class NextParams(_Target, total=False):
+    actor: f.Actor
+    session: f.Session
+    labels: Annotated[str, f.LABELS]
+    task: Annotated[str, f.CLAIM_ONE]
+
+
+class _UpdateRequired(_Target):
+    task: f.TaskId
+
+
+class UpdateParams(_UpdateRequired, total=False):
+    status: Annotated[Literal["in_progress", "blocked", "review", "done", "released",
+                              "cancelled"], f.STATUS]
+    comment: Annotated[str, f.COMMENT]
+    mentions: Annotated[str, f.MENTIONS]
+    blocked_on: Annotated[str, f.BLOCKED_ON]
+    no_code: Annotated[bool, f.NO_CODE]
+
+
+class AskParams(_Target, total=False):
+    task: Annotated[str, f.ASK_TASK]
+    query: Annotated[str, f.ASK_QUERY]
+
+
+class DispatchParams(_Target, total=False):
+    """Prepare worker agents for cards. The caller spawns them as its own sub-agents.
+
+    There is deliberately NO `spawn` field here, and its absence is the design rather than an
+    omission. The use case can start detached processes and `taskops dispatch --spawn` does, because
+    that is a human at a terminal asking for it — but a model calling a tool must not be able to make
+    this package launch another Claude Code. An agent inside a session already HAS a way to run work
+    in parallel: its own sub-agent tool, on the subscription that is already paid for. Spawning from
+    here opens a new billed session per worker, which is how a real fleet drained an API balance
+    mid-run and left six cards claimed by processes that no longer existed.
+
+    A capability the engine has and a transport withholds is a normal thing for this codebase — the
+    surfaces are thin, not identical.
+    """
+
+    tasks: Annotated[str, f.DISPATCH_TASKS]
+    count: Annotated[int, f.DISPATCH_COUNT]
+    prefix: Annotated[str, f.PREFIX]
+    model: Annotated[str, f.MODEL]
+    dry_run: Annotated[bool, f.DRY_RUN]
+    actor: f.Actor
+
+
+class RecoverParams(_Target, total=False):
+    """Hand back the cards of workers that died. The other half of dispatching a fleet."""
+
+    force: Annotated[bool, f.RECOVER_FORCE]
+    grace: Annotated[int, f.RECOVER_GRACE]
+    actor: f.Actor
+
+
+class ReportParams(_Target, total=False):
+    """The four views a model may ask for, and no more.
+
+    `fleet` and `burndown` were advertised here and are not any more. One answered a question
+    agents stopped having — "who is free" means nothing when a worker is created on demand,
+    and the studio dropped the panel for the same reason — while the other was never
+    implemented and replied with a sentence saying so. A tool that lists a kind an agent
+    cannot use spends the description budget teaching it to pick wrong. `fleet` survives as a
+    use case: the HTTP api still serves it, because a human looking at a board does want to
+    know which claim has gone quiet.
+    """
+
+    kind: Annotated[Literal["board", "standup", "day", "range"], f.REPORT_KIND]
+    actor: Annotated[str, f.REPORT_ACTOR]
+    since: Annotated[str, f.SINCE]
+    date: Annotated[str, f.DATE]
+    last: Annotated[str, f.LAST]
+    from_date: Annotated[str, f.FROM_DATE]
+    to: Annotated[str, f.TO_DATE]

taskops/contracts/wire.py

@@ -0,0 +1,60 @@
+"""A message that travels on the SOCKET and is never stored.
+
+The counterpart of `Event`, defined by what it is NOT: an event is the durable
+record — hashed, written to sqlite, exported to `events.jsonl` and committed —
+and a wire message is a frame the studio pushes to whoever happens to be looking.
+Nothing persists it, nothing replays it, and a browser that reconnects has simply
+missed it.
+
+That distinction is load-bearing, not stylistic. The first thing this carries is
+the narration of a report, arriving a few characters at a time; a thousand prose
+fragments in `events.jsonl` would destroy the one property that file has, which is
+that a human can read its diff. The FILE on disk is the durable copy of a
+narration — this is only the window onto it being written.
+
+`kind` is open for the same reason `Event.kind` is: a reader that does not know a
+kind ignores the frame, and a newer taskops may send kinds this one never heard of.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+__all__ = ["WireMessage"]
+
+
+class WireMessage(TypedDict):
+    """One ephemeral frame: what happened, to which report, and the text of it."""
+
+    kind: str
+    """Namespaced by subject — `narration.delta`, `narration.pass`, `narration.done`,
+    `narration.failed`. A consumer switches on it and drops what it does not know."""
+
+    label: str
+    """Which report this is about (`2026-07-28`, `2026-07-22..2026-07-28`, `all`).
+
+    Never absent: two narrations can be in flight at once, and a delta that cannot
+    say which document it belongs to would be appended to whichever panel is open.
+    """
+
+    text: str
+    """The payload, shaped by `kind` — a fragment of prose for a delta, `2/4` for a
+    pass, the failure verbatim for a failure, empty for a completion."""
+
+    root: str
+    """WHICH project emitted it: the absolute path of the store, as `str(store.root)`.
+
+    A path and not a "project name" on purpose. The emitter is a narration running deep
+    inside a use case; it does not know — and must not have to know — under which URL
+    prefix some server happened to mount it, or whether it is mounted at all. The root is
+    the one identifier both ends already share, and the consumer (`usecases.feed.follow`)
+    resolves its own from the very same function.
+
+    Never absent. The channel is process-global, so a server holding many boards open
+    broadcasts every frame to all of them; a message that cannot say where it came from
+    would be prose from one project appearing on another project's screen. That is why a
+    message WITHOUT this field is dropped rather than delivered — see `follow`.
+
+    It never reaches the browser: `transports.http.live` strips it before framing, because
+    it is a path on the server's filesystem and no client has any business reading it.
+    """

taskops/engine/__init__.py

@@ -0,0 +1,34 @@
+"""Layer 3 — the decisions. Sync, and it never talks to a caller.
+
+Split from `usecases` by WHO it is for: these functions decide things (may this move
+happen, which task is next, is that agent alive), and a use case orchestrates them
+into an answer a transport can render. That is why nothing here formats text and
+nothing here reads an argument a model wrote.
+
+`machine` is the only module allowed to decide a status move — `tests/architecture`
+enforces it — because a transition table plus one convenient status check elsewhere
+is two state machines, and the convenient one always forgets the guard.
+"""
+
+from __future__ import annotations
+
+from . import replay
+from .activity import fleet, standup
+from .bus import BUS, EventBus
+from .day import date_of, day_report, first_date, label_of, period_report, shift
+from .gitstate import branch_state, branch_states
+from .history import activity
+from .identity import parse, resolve
+from .log import build, record, relay
+from .machine import Facts, allowed_from, check_move
+from .narrate import OnPass, OnText, narrate
+from .project import board, counts
+from .reports import NO_STAMP, missing_events, stamp, stamped_seq
+from .scheduler import branch_for, claim, open_children, ready_tasks, sweep_dead, unblock
+from .wire import WIRE, Broadcast, is_wire
+from .worker import Launched, launch
+
+__all__ = ["Facts", "check_move", "allowed_from", "resolve", "parse", "record",
+           "build", "relay", "BUS", "EventBus", "unblock", "ready_tasks", "claim",
+           "branch_for", "sweep_dead", "open_children", "board", "standup", "fleet", "activity", "day_report", "period_report", "first_date", "label_of", "shift", "date_of",
+           "counts", "replay", "narrate", "OnPass", "OnText", "stamp", "stamped_seq", "NO_STAMP", "missing_events", "branch_state", "branch_states", "launch", "Launched", "WIRE", "Broadcast", "is_wire"]

taskops/engine/_blocks.py

@@ -0,0 +1,48 @@
+"""Reading the CONTENT of a transcript entry: a tool call's arguments, a tool result's payload.
+
+Split from `_entries` by depth rather than by topic. That module walks the entry's shape and decides
+what each line IS; this one reaches inside a block and decides what to SHOW of it — which is where the
+judgement about brevity lives, and the part that gets tuned after looking at a real dashboard.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+__all__ = ["summarise", "result_text"]
+
+_IDENTIFYING = ("file_path", "command", "path", "pattern", "query", "task", "prompt")
+"""Argument names that say WHICH thing a tool acted on, in the order they are worth showing.
+
+`file_path` first because Read/Write/Edit are most of any transcript, then `command` for Bash. A call
+whose arguments contain none of these falls back to naming its keys, which at least says what shape it
+had.
+"""
+
+
+def summarise(tool: str, arguments: object) -> str:
+    """A tool call in ONE line: the argument that identifies it, never the whole payload.
+
+    A dashboard showing the full `input` of every Edit is a dashboard nobody scrolls — the diff is
+    already in git, and what a reader wants here is which file was touched.
+    """
+    if not isinstance(arguments, dict):
+        return tool
+    args = cast("dict[str, Any]", arguments)
+    for key in ("file_path", "command", "path", "pattern", "query", "task", "prompt"):
+        found = args.get(key)
+        if isinstance(found, str) and found.strip():
+            return f"{found.strip()[:200]}"
+    return ", ".join(sorted(args)[:4])
+
+
+def result_text(content: object) -> str:
+    """A tool result, which arrives as a string or as a list of blocks."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        blocks = cast("list[object]", content)
+        parts = [str(cast("dict[str, Any]", block).get("text", ""))
+                 for block in blocks if isinstance(block, dict)]
+        return "\n".join(part for part in parts if part)
+    return ""