ag2-sparrow 0.1.0__tar.gz

ag2_sparrow-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: ag2-sparrow
+Version: 0.1.0
+Summary: Transport client that connects a local agent to AG2 Space: long-polls the task gateway for your agent's tasks and posts results back.
+Author: AG2 Space
+License: MIT
+Project-URL: Homepage, https://ag2.space
+Project-URL: Source, https://github.com/sonichi/sutando
+Keywords: ag2,agent,relay,gateway,matrix
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# ag2-sparrow
+
+*The AG2 Space task relay client.*
+
+Transport client that connects a **local agent** to **AG2 Space**.
+
+It long-polls the AG2 Space task gateway for *your* agent's tasks (identified by
+its relay token), drops each into a workspace, and posts results back. It carries
+no agent logic — pair it with a worker (e.g. [`agent-connect`](https://github.com/ag2-space/agent-connect))
+that turns each task into an agent run.
+
+## Install
+
+```sh
+pipx install ag2-sparrow        # or: pip install ag2-sparrow
+```
+
+## Run
+
+```sh
+REMOTE_TASK_TOKEN=<your relay token from the AG2 Space Agent Portal> \
+REMOTE_TASK_URL=https://chat.ag2.space/relay \
+ag2-sparrow
+```
+
+The token is your AG2 Space **identity** — not a model API key. Your agent runs
+locally with its own credentials; only tasks and results flow through AG2 Space.
+
+## Single source of truth
+
+These modules are the canonical AG2 Space relay client, kept in lockstep with
+[`sonichi/sutando`](https://github.com/sonichi/sutando) `src/`. They are copied
+verbatim (never forked) via `tools/sync_from_src.py`; a CI drift-check fails if
+the package diverges from the source. Zero third-party runtime dependencies.
+
+## License
+
+MIT

ag2_sparrow-0.1.0/README.md

@@ -0,0 +1,38 @@
+# ag2-sparrow
+
+*The AG2 Space task relay client.*
+
+Transport client that connects a **local agent** to **AG2 Space**.
+
+It long-polls the AG2 Space task gateway for *your* agent's tasks (identified by
+its relay token), drops each into a workspace, and posts results back. It carries
+no agent logic — pair it with a worker (e.g. [`agent-connect`](https://github.com/ag2-space/agent-connect))
+that turns each task into an agent run.
+
+## Install
+
+```sh
+pipx install ag2-sparrow        # or: pip install ag2-sparrow
+```
+
+## Run
+
+```sh
+REMOTE_TASK_TOKEN=<your relay token from the AG2 Space Agent Portal> \
+REMOTE_TASK_URL=https://chat.ag2.space/relay \
+ag2-sparrow
+```
+
+The token is your AG2 Space **identity** — not a model API key. Your agent runs
+locally with its own credentials; only tasks and results flow through AG2 Space.
+
+## Single source of truth
+
+These modules are the canonical AG2 Space relay client, kept in lockstep with
+[`sonichi/sutando`](https://github.com/sonichi/sutando) `src/`. They are copied
+verbatim (never forked) via `tools/sync_from_src.py`; a CI drift-check fails if
+the package diverges from the source. Zero third-party runtime dependencies.
+
+## License
+
+MIT

ag2_sparrow-0.1.0/ag2_sparrow/__init__.py

@@ -0,0 +1,12 @@
+"""ag2-sparrow — connect a local agent to AG2 Space (the AG2 task relay client).
+
+Transport only: long-polls the AG2 Space task gateway for THIS agent's tasks
+(identified by its relay token), drops each into a workspace, and posts results
+back. No agent logic — a worker (e.g. ag2-space/agent-connect) turns each task
+into an agent run.
+
+The modules here are the canonical AG2 Space relay client, kept in lockstep with
+sonichi/sutando `src/` via tools/sync_from_src.py (a drift-check test fails CI if
+they diverge — single source of truth, no hand-maintained fork).
+"""
+__version__ = "0.1.0"

ag2_sparrow-0.1.0/ag2_sparrow/__main__.py

@@ -0,0 +1,4 @@
+from .remote_gateway_bridge import main
+
+if __name__ == "__main__":
+    main()

ag2_sparrow-0.1.0/ag2_sparrow/local_task_protocol.py

@@ -0,0 +1,495 @@
+"""
+Local Task Protocol — read-side reference implementation.
+
+Interaction-planes refactor, step 3 (read side). The durable local execution
+boundary: this module names the schema of `tasks/*.txt` files and provides the
+canonical pure functions for reading them. It consolidates parsing that today
+is hand-rolled per consumer (task_priority.py, task-bridge's `_isVoiceTask`,
+each bridge's header scan) so new code imports ONE definition. Writers are
+deliberately untouched in this phase — the write-side switch happens per
+bridge, later, with byte-identical golden tests.
+
+The result-body half of the protocol already lives in `src/result_markers.py`
+(#873) and stays there; this module is the TASK-file half plus shared schema
+constants.
+
+R1 invariant (design doc §6): everything here is stdlib-only, no network, no
+daemon, no lock service — the last-resort producers (health-check --emit-task,
+Sutando.app context-drop) must keep working under total daemon death, and the
+future write side of this module inherits that constraint.
+
+## The two header shapes (and why there are two parsers)
+
+Producers serialize headers in two shapes with three distinct trust
+mechanisms — established by surveying 3.4k archived task files plus every
+live writer (2026-07-06):
+
+**task-last** (task-bridge.ts chat/voice/context-drop, agent-api `/task`):
+every header precedes the `task:` line; the body after it is untrusted
+multi-line content. Ordering IS the trust mechanism — consumers stop
+header-scanning at the first `task:` line, or a body containing
+`\naccess_tier: owner` forges headers (the PR #982 injection, re-flagged in
+#1035). Use `parse_task_headers()`.
+
+**task-mid** (all Python bridges: discord/slack/telegram/gateway, plus
+health-check and github-webhook): `task:` lands mid-file and real headers
+(source, channel_id, …) follow it. Safe only because the writer neutralizes
+the body by one of two mechanisms: newline-stripping every value
+(`_one_line` in the gateway, the sanitizer in github-webhook) or defanging
+header-like body lines with a ZWSP prefix (`task_body_guard.
+confine_user_content` in discord/telegram). Use
+`parse_task_headers_trusted()` — full scan, LAST occurrence wins, which the
+gateway's tier defense depends on (its locally-decided `access_tier` is
+written last to beat anything the remote side claimed).
+
+Pick the parser by writer, never by sniffing content. The safe default for
+a file of unknown provenance is `parse_task_headers()` — it under-reads
+task-mid files rather than over-trusting task-last ones. That under-read is
+real: `parse_priority_from_text` (stop-at-`task:`) has never seen a
+bridge-written `priority:` field. The write-side phase converges writers on
+task-last; until then both parsers exist and are named for their trust model.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable
+
+# ── Schema constants ─────────────────────────────────────────────────────────
+
+# Interaction-plane vocabulary (step 1, PR #1953). Producers stamp exactly one
+# of these next to `source:`; the remote-gateway bridge whitelists inbound
+# values against this set (unknown → "message").
+INTERACTION_TYPES = frozenset({
+    "message", "realtime_audio", "realtime_video",
+    "tool_initiated", "system_event", "self_reflective",
+})
+
+# Content-modality vocabulary (interaction-model 4D, step 1.5). The modalities
+# a task's payload spans — orthogonal to interaction_type (which names the
+# *mode*, not the media). A text-only DM is {"text"}; a photo with a caption is
+# {"text", "image"}; a voice note is {"audio"}. Producers stamp a comma-joined
+# subset next to `interaction_type`; readers whitelist against this set
+# (unknown token dropped), the same discipline as the interaction_type gateway
+# whitelist.
+CONTENT_MODALITIES = frozenset({"text", "image", "audio", "video", "file"})
+
+# Media-form vocabulary — the load-bearing routing axis of the 4D model:
+# `attachment` = a discrete, already-bounded object delivered alongside a
+# message (a photo, a PDF, a voice note) → lands in the task file as an
+# AttachmentRef the Core fetches + analyzes. `live_stream` = a continuous
+# real-time media plane (a call's audio, a screen share) → does NOT belong in
+# a task file; it is owned by the LiveAgentRuntime. A missing header defaults
+# to `attachment`: messaging is the default plane, and `live_stream` is the
+# explicit opt-out that routes a payload away from the task-file path.
+MEDIA_FORMS = frozenset({"attachment", "live_stream"})
+
+# Task priority enum (src/task_priority.py is the behavior owner; these are
+# the schema names). Consumer semantics: highest first, mtime FIFO tiebreak.
+PRIORITIES = ("urgent", "normal", "low")
+
+# Access tiers (CLAUDE.md access-control sections). `owner` is full
+# processing; team/other are sandboxed. A missing header reads as owner for
+# legacy local files — that default belongs to consumers, not this module.
+ACCESS_TIERS = ("owner", "team", "other")
+
+# The header vocabulary: every key observed in the real archive corpus
+# (3,401 files, 2026-07-06) plus the live writers' full sets. This list is
+# ENFORCED in two places that must stay in lockstep (Codex P2 on PR #1954):
+# - the parsers below promote ONLY these keys to headers (an unknown
+#   `key: value` line stays in the body — so junk like transcript dialogue
+#   `Caller: hi` never becomes metadata), and
+# - task_body_guard.confine_user_content defangs exactly these keys in
+#   untrusted bodies (it imports this list), so no key a parser would trust
+#   can survive undefanged in user-supplied content.
+# Adding a producer header = add it here; the guard follows automatically.
+KNOWN_HEADER_KEYS = (
+    "id", "timestamp", "task", "source", "access_tier", "user_id",
+    "channel_id", "priority", "interaction_type", "source_message_id",
+    "channel_name", "guild_name", "attempts", "sender_name", "room_name",
+    "parent_message_id", "reminder", "author_name", "author_id", "chat_id",
+    "thread_ts", "reply_to_event", "reply_to_me", "callSid", "caller",
+    "from", "call_sid", "hint", "instructions", "transcript",
+    # interaction-model 4D, step 1.5 — structured media metadata. Listing them
+    # here promotes them to headers AND (via the guard's shared import) defangs
+    # them in untrusted bodies, so a forged `attachments:` body line can never
+    # smuggle a fetch locator past the parser.
+    "content_modalities", "media_form", "attachments",
+    # Platform-signed metadata pointer (one-line JSON object): a signed
+    # reference to the delivering platform's canonical agent operating card,
+    # verifiable offline-of-the-task against the platform's well-known key
+    # (skills/agent-room-ops/verify_platform_card.py). Header status means a
+    # trusted bridge wrote it; the guard defangs a forged `platform_card:`
+    # body line the same as `attachments:`.
+    "platform_card",
+)
+_KNOWN_KEY_SET = frozenset(KNOWN_HEADER_KEYS)
+
+# Task-id shape: `task-<slug>` where slug is dash-separated [a-z0-9] segments
+# (task-1783..., task-chat-1783..., task-phone-..., task-summary-...,
+# task-gh-..., task-health-...). Mirrors the gateway bridge's `_valid_tid`
+# defense: ids become filenames, so the charset is the path-traversal guard.
+TASK_ID_RE = re.compile(r"^task-[A-Za-z0-9][A-Za-z0-9-]{0,120}$")
+
+
+def valid_task_id(tid: str) -> bool:
+    """True iff `tid` is a well-formed task id, safe to embed in a filename.
+
+    Rejects path separators, dots, whitespace, and empty/oversized ids — the
+    id is used as `tasks/<tid>.txt` and `results/<tid>.txt`, so this is the
+    single traversal gate for readers that accept ids from message content
+    (e.g. `[deduped: <tid>]` holders).
+    """
+    return bool(TASK_ID_RE.match(tid or ""))
+
+
+# ── Header parsing ───────────────────────────────────────────────────────────
+
+_HEADER_LINE_RE = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*):[ \t]?(.*)$")
+
+
+@dataclass
+class TaskHeaders:
+    """Parsed view of a task file. `headers` preserves the parser's trust
+    rule (see module docstring).
+
+    `body` semantics differ BY PARSER — this is deliberate and load-bearing:
+    - `parse_task_headers` (task-last): the full work item — the `task:`
+      line's content plus every line after it, verbatim.
+    - `parse_task_headers_trusted` / `_lenient` (task-mid): the `task:`
+      line's content plus every subsequent NON-vocabulary line. Vocabulary
+      header lines (KNOWN_HEADER_KEYS) after `task:` are promoted to
+      `headers` and excluded from body; everything else — health-check
+      failure bullets, phone transcript dialogue, unknown `key:`-shaped
+      lines — stays in body. Every post-`task:` line lands in exactly one
+      of headers/body (no silent loss; Codex P2s on PR #1954). For the
+      byte-verbatim work item including trailing headers, use `task_body()`.
+    """
+    headers: dict = field(default_factory=dict)
+    body: str = ""
+
+    def get(self, key: str, default: str | None = None) -> str | None:
+        return self.headers.get(key, default)
+
+
+def task_body(text: str) -> str:
+    """The complete work item of a task file, shape-independent: everything
+    from the first `task:` line onward, verbatim, with only the `task:`
+    prefix stripped from that first line. Never drops a line — for task-mid
+    files this includes trailing headers, which is the honest trade: a reader
+    that wants clean headers uses the parsers; a reader that wants the full
+    work item (health bullets, phone transcript, meeting instructions) uses
+    this and must tolerate header lines inside it."""
+    lines = text.split("\n")
+    for i, line in enumerate(lines):
+        if line.startswith("task:"):
+            return "\n".join([line[len("task:"):].lstrip()] + lines[i + 1:])
+    return ""
+
+
+def parse_task_headers(text: str) -> TaskHeaders:
+    """Parse a **task-last** file: collect `key: value` lines strictly BEFORE
+    the first `task:` line; everything from `task:` onward is untrusted body.
+
+    This is the safe default parser — the delimiter rule that keeps a
+    user-supplied body from forging headers (PR #982 / #1035). First
+    occurrence of a key wins (a duplicate later is more likely forged than
+    corrective). The body includes the `task:` line's own content.
+    """
+    headers: dict = {}
+    body_lines: list[str] = []
+    in_body = False
+    for line in text.split("\n"):
+        if in_body:
+            body_lines.append(line)
+            continue
+        if line.startswith("task:"):
+            in_body = True
+            body_lines.append(line[len("task:"):].lstrip())
+            continue
+        m = _HEADER_LINE_RE.match(line)
+        if m and m.group(1) in _KNOWN_KEY_SET:
+            headers.setdefault(m.group(1), m.group(2))
+        # Unknown-key and non-matching lines before task: are tolerated and
+        # skipped — real archive files contain blank lines and free-text
+        # hint blocks; only vocabulary keys become metadata.
+    return TaskHeaders(headers=headers, body="\n".join(body_lines))
+
+
+def parse_task_headers_lenient(text: str) -> TaskHeaders:
+    """Parse across ALL lines, FIRST occurrence of each key wins.
+
+    The shape-union reader: producers' field order has changed across eras
+    (May-2026 voice tasks were task-mid; today's are task-last), so consumers
+    that must classify files of any age — e.g. discord-bridge's DM-fallback
+    `source:` probe — need a scan that finds headers wherever that era's
+    writer put them. First-wins resists trailing-body forgery when the real
+    header exists; it does NOT protect a file that legitimately lacks the
+    probed key (a body line can then supply it). That spoofability predates
+    this module — hardening it means changing verdicts for historical shapes
+    and is deliberately out of scope for the read-side refactor.
+    """
+    return _parse_task_mid(text, last_wins=False)
+
+
+def parse_task_headers_trusted(text: str) -> TaskHeaders:
+    """Parse a **task-mid** file from a trusted writer (remote-gateway-bridge):
+    scan ALL lines for `key: value`, LAST occurrence wins.
+
+    Only valid when the writer is known to newline-strip every value — that
+    property is what makes the full scan injection-free, and last-wins is
+    load-bearing: the gateway writes its locally-decided `access_tier` last
+    precisely so it beats anything the remote side claimed earlier in the
+    file. Applying this parser to a task-last file would let the body forge
+    headers; pick the parser by writer, not by content sniffing.
+    """
+    return _parse_task_mid(text, last_wins=True)
+
+
+def _parse_task_mid(text: str, last_wins: bool) -> TaskHeaders:
+    """Shared task-mid scan. Headers = vocabulary keys only
+    (KNOWN_HEADER_KEYS); body = the `task:` line's content plus every
+    subsequent NON-vocabulary line — so continuation content (health-check
+    failure bullets, phone transcript dialogue, skill-hint blocks) is
+    preserved losslessly in body while trailing real headers are excluded.
+    Every input line after `task:` lands in exactly one of headers/body
+    (fidelity is asserted over the full archive corpus in the golden test).
+    An unknown `key: value` shape (`Caller: hi`) is body, never metadata."""
+    headers: dict = {}
+    body_lines: list[str] = []
+    in_body = False
+    for line in text.split("\n"):
+        if not in_body and line.startswith("task:"):
+            in_body = True
+            body_lines.append(line[len("task:"):].lstrip())
+            continue
+        m = _HEADER_LINE_RE.match(line)
+        if m and m.group(1) in _KNOWN_KEY_SET:
+            if last_wins:
+                headers[m.group(1)] = m.group(2)
+            else:
+                headers.setdefault(m.group(1), m.group(2))
+        elif in_body:
+            body_lines.append(line)
+    # Trailing blank lines are file-termination artifacts, not content —
+    # interior blank lines are preserved.
+    while body_lines and body_lines[-1] == "":
+        body_lines.pop()
+    return TaskHeaders(headers=headers, body="\n".join(body_lines))
+
+
+# ── Media attachments (interaction-model 4D, step 1.5) ───────────────────────
+
+
+@dataclass
+class AttachmentRef:
+    """One discrete media object carried by a task, source-independent.
+
+    The unified descriptor every bridge normalizes its native attachment into
+    (Discord CDN url, Slack file, Telegram file_id, Matrix mxc://, or an
+    already-downloaded local path) so the Core sees ONE shape regardless of
+    surface. `locator` is the source-specific pointer to the bytes; the
+    safe-fetch policy (bridge/relay side, a later slice) resolves a remote
+    locator to a local path and may rewrite `locator` in place once fetched.
+
+    Deliberately metadata-only: no bytes, no file handles (R1 stdlib-only, and
+    a task file must stay a small text record). `size`/`sha256` let a consumer
+    enforce a limit and dedupe *before* fetching. Every field but `locator` is
+    optional — a ref with nothing to point at is meaningless, so an element
+    lacking a locator is dropped on both encode and decode.
+    """
+    locator: str
+    id: str = ""
+    mime: str = ""
+    filename: str = ""
+    size: int = 0
+    sha256: str = ""
+    expiry: str = ""  # ISO-8601 UTC; "" = no expiry / already-local
+
+    def as_dict(self) -> dict:
+        """Compact dict for JSON serialization — omits empty/zero fields so the
+        header line stays small and round-trips back to an equal ref."""
+        d: dict = {"locator": self.locator}
+        for k in ("id", "mime", "filename", "sha256", "expiry"):
+            v = getattr(self, k)
+            if v:
+                d[k] = v
+        if self.size:
+            d["size"] = self.size
+        return d
+
+
+def parse_content_modalities(headers: dict) -> frozenset:
+    """The whitelisted set of content modalities from a parsed header dict.
+
+    Reads the comma-joined `content_modalities` value, lower-cases + trims each
+    token, and drops anything outside CONTENT_MODALITIES — an unknown token is
+    noise, never a new modality (same rule as the interaction_type whitelist).
+    Missing/empty → empty set; a text-only task need not stamp `{"text"}`."""
+    raw = (headers or {}).get("content_modalities") or ""
+    return frozenset(
+        t for t in (tok.strip().lower() for tok in raw.split(",")) if t in CONTENT_MODALITIES
+    )
+
+
+def parse_media_form(headers: dict) -> str:
+    """The task's media form: `attachment` (default) or `live_stream`.
+
+    Whitelists the `media_form` value; anything unknown or missing collapses to
+    `attachment`, the safe default that routes the payload through the normal
+    task-file path rather than mis-claiming a LiveAgentRuntime stream."""
+    v = ((headers or {}).get("media_form") or "").strip().lower()
+    return v if v in MEDIA_FORMS else "attachment"
+
+
+def parse_attachments(headers: dict) -> list["AttachmentRef"]:
+    """Decode the `attachments:` header — a one-line JSON array of objects —
+    into AttachmentRefs.
+
+    Tolerant by contract: a malformed value, a non-list payload, a non-object
+    element, or an element with no `locator` is skipped, never raised. A bad
+    attachments header must not block reading the rest of the task (the same
+    never-block principle as the audit sink). Missing header → []."""
+    raw = (headers or {}).get("attachments")
+    if not raw:
+        return []
+    try:
+        arr = json.loads(raw)
+    except (ValueError, TypeError):
+        return []
+    if not isinstance(arr, list):
+        return []
+    refs: list[AttachmentRef] = []
+    for el in arr:
+        if not isinstance(el, dict):
+            continue
+        locator = el.get("locator")
+        if not locator or not isinstance(locator, str):
+            continue
+        size = el.get("size", 0)
+        if isinstance(size, bool):
+            size = 0  # a JSON bool is not a byte count (int(True) == 1 would lie)
+        elif not isinstance(size, int):
+            try:
+                size = int(size)
+            except (ValueError, TypeError):
+                size = 0
+        if size < 0:
+            size = 0  # a negative byte count is nonsense and would slip past a
+            #            `ref.size and ref.size > max_bytes` cap check — normalize
+            #            it to 0 (unknown) so limit enforcement stays sound.
+        refs.append(AttachmentRef(
+            locator=locator,
+            id=str(el.get("id", "")),
+            mime=str(el.get("mime", "")),
+            filename=str(el.get("filename", "")),
+            size=size,
+            sha256=str(el.get("sha256", "")),
+            expiry=str(el.get("expiry", "")),
+        ))
+    return refs
+
+
+def format_attachments(refs: Iterable["AttachmentRef"]) -> str:
+    """Encode AttachmentRefs into the one-line JSON value of an `attachments:`
+    header — the write-side inverse of parse_attachments.
+
+    Guaranteed single-line (json escapes any embedded newline in a field), so
+    it is safe for both task-last single-line values and the task-mid
+    newline-stripping writers. Refs without a locator are dropped (they'd be
+    unparseable on read, so encoding them would not round-trip)."""
+    payload = [r.as_dict() for r in refs if r.locator]
+    return json.dumps(payload, separators=(",", ":"), ensure_ascii=False)
+
+
+def modality_for_mime(mime: str) -> str:
+    """Map an attachment MIME type to a content modality (CONTENT_MODALITIES):
+    image/audio/video by top-level type, everything else (pdf, zip, docx,
+    unknown) → `file`. The shared home for the mapping each bridge needs when it
+    stamps `content_modalities` — promoted here once a third bridge required it
+    (discord/telegram carried private copies first)."""
+    m = (mime or "").lower()
+    if m.startswith("image/"):
+        return "image"
+    if m.startswith("audio/"):
+        return "audio"
+    if m.startswith("video/"):
+        return "video"
+    return "file"
+
+
+def media_attachment_headers(attachment_refs: Iterable["AttachmentRef"], has_text: bool) -> str:
+    """Build the `content_modalities`/`media_form`/`attachments` header block a
+    bridge stamps on a task file when a message carried attachments (step 1.5).
+    Returns "" when there are no refs — so a text-only task's headers are
+    unchanged.
+
+    `content_modalities` = `text` (iff `has_text`) plus one modality per ref
+    mime; `media_form` = `attachment` (these are discrete objects — a live
+    stream is never emitted through the messaging task path); `attachments` =
+    the one-line JSON from `format_attachments`. The block is newline-terminated
+    so it composes directly into a writer's header f-string. Pure — a bridge can
+    unit-test its write path without a live message object."""
+    refs = [r for r in attachment_refs if r.locator]
+    if not refs:
+        return ""
+    mods = set()
+    if has_text:
+        mods.add("text")
+    for r in refs:
+        mods.add(modality_for_mime(r.mime))
+    return (
+        f"content_modalities: {','.join(sorted(mods))}\n"
+        f"media_form: attachment\n"
+        f"attachments: {format_attachments(refs)}\n"
+    )
+
+
+# ── Archive rules ────────────────────────────────────────────────────────────
+
+_MONTH_DIR_RE = re.compile(r"^\d{4}-\d{2}$")
+
+
+def archive_month_dir(base: Path, iso_timestamp: str) -> Path:
+    """Month-partitioned archive dir for a given ISO timestamp: the layout
+    task-bridge.ts introduced in PR #591 (`archive/YYYY-MM/`). The month
+    comes from the supplied timestamp, not the wall clock, so writers and
+    tests are deterministic around month boundaries."""
+    return base / "archive" / iso_timestamp[:7]
+
+
+def find_archived_task(tasks_dir: Path, task_id: str) -> Path | None:
+    """Locate a task file across the live dir, the legacy flat archive, and
+    the month-partitioned archive — the same candidate set task-bridge's
+    `_isVoiceTask` walks. Returns the first existing path or None. Rejects
+    malformed ids rather than globbing with them (traversal gate)."""
+    if not valid_task_id(task_id):
+        return None
+    fname = f"{task_id}.txt"
+    candidates = [tasks_dir / fname, tasks_dir / "processed" / fname,
+                  tasks_dir / "archive" / fname]
+    archive_root = tasks_dir / "archive"
+    if archive_root.is_dir():
+        for entry in sorted(archive_root.iterdir()):
+            if entry.is_dir() and _MONTH_DIR_RE.match(entry.name):
+                candidates.append(entry / fname)
+    for p in candidates:
+        if p.exists():
+            return p
+    return None
+
+
+def iter_archived_tasks(tasks_dir: Path) -> Iterable[Path]:
+    """Yield every archived task file (flat legacy + month-partitioned),
+    for corpus sweeps and golden tests."""
+    archive_root = tasks_dir / "archive"
+    if not archive_root.is_dir():
+        return
+    for p in sorted(archive_root.glob("*.txt")):
+        yield p
+    for entry in sorted(archive_root.iterdir()):
+        if entry.is_dir() and _MONTH_DIR_RE.match(entry.name):
+            yield from sorted(entry.glob("*.txt"))