agent-learning-kit 0.1.0__py3-none-any.whl

fi/alk/live/_transcript.py

@@ -0,0 +1,240 @@
+"""JSONL transcript recorder + reader for live lanes (ARCH Decision 3).
+
+Imports: stdlib only. The file IS the ledger: one JSON object per line,
+``{"t": <monotonic-relative s>, "channel": ..., "type": ..., "payload": ...}``
+with ``channel`` in {"user", "agent", "tool", "lane"}. Redaction runs at
+write time — declared ``required_env`` VALUES never hit disk. The recorder
+owns the size cap (``AGENT_LEARNING_LIVE_TRANSCRIPT_MAX_BYTES``, default
+64 MiB/scenario): over-cap behavior is retain head+tail, never silently drop.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from collections import deque
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+TRANSCRIPT_MAX_BYTES_ENV = "AGENT_LEARNING_LIVE_TRANSCRIPT_MAX_BYTES"
+DEFAULT_TRANSCRIPT_MAX_BYTES = 64 * 1024 * 1024
+TRANSCRIPT_CHANNELS = ("user", "agent", "tool", "lane")
+
+# Bytes reserved out of the tail budget for the truncation marker line.
+_TRUNCATION_MARKER_RESERVE = 512
+
+
+def redact_env_values(text: str, required_env: Sequence[str]) -> str:
+    """Replace any occurrence of a declared env var's VALUE with
+    '[redacted:<NAME>]'. Extends the existing redacted-auth evidence pattern
+    (trinity evaluation-hook gates carry auth.redacted evidence) to lane
+    transcripts."""
+
+    for name in required_env:
+        value = os.environ.get(name)
+        if value:
+            text = text.replace(value, f"[redacted:{name}]")
+    return text
+
+
+def transcript_max_bytes() -> int:
+    """Resolve the per-scenario transcript size cap (3A owns this env var)."""
+
+    raw = os.environ.get(TRANSCRIPT_MAX_BYTES_ENV)
+    if raw:
+        try:
+            value = int(raw)
+            if value > 0:
+                return value
+        except ValueError:
+            pass
+    return DEFAULT_TRANSCRIPT_MAX_BYTES
+
+
+class TranscriptRecorder:
+    """Append-only JSONL replay transcript (R§3.1, DFAH lineage).
+
+    One line per event. The dual-channel requirement for voice lanes is just
+    two channels of this stream. Capture-to-fixture re-reads the file
+    verbatim, so the recorder never writes secrets: every serialized event is
+    passed through :func:`redact_env_values` before write.
+    """
+
+    def __init__(
+        self,
+        path: str | Path,
+        *,
+        required_env: Sequence[str],
+        max_bytes: int | None = None,
+    ) -> None:
+        self.path = Path(path)
+        self.required_env = tuple(required_env)
+        self._max_bytes = int(max_bytes) if max_bytes else transcript_max_bytes()
+        self._head_budget = max(self._max_bytes // 2, 1)
+        self._tail_budget = max(
+            self._max_bytes - self._head_budget - _TRUNCATION_MARKER_RESERVE, 1
+        )
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._fh = open(self.path, "a", encoding="utf-8")
+        self._t0 = time.monotonic()
+        self._bytes_written = 0
+        self._original_bytes = 0
+        self._original_sha = hashlib.sha256()
+        self._event_count = 0
+        self._channels: set[str] = set()
+        self._buffering_tail = False
+        self._tail: deque[tuple[int, str]] = deque()
+        self._tail_bytes = 0
+        self._dropped_events = 0
+        self._closed = False
+        self._summary: dict[str, Any] | None = None
+        # In-memory (already redacted) copies for attribution/stats. Control
+        # events are small; bulk audio lives in side files, never in events.
+        self.events: list[dict[str, Any]] = []
+
+    # -- write path ---------------------------------------------------------
+
+    def record(
+        self, channel: str, type: str, payload: Mapping[str, Any]
+    ) -> None:
+        if self._closed:
+            raise RuntimeError(f"transcript {self.path} is closed")
+        event = {
+            "t": round(time.monotonic() - self._t0, 6),
+            "channel": str(channel),
+            "type": str(type),
+            "payload": payload if isinstance(payload, dict) else dict(payload),
+        }
+        line = json.dumps(event, ensure_ascii=False, default=str)
+        line = redact_env_values(line, self.required_env)
+        try:
+            stored = json.loads(line)
+        except ValueError:
+            stored = {
+                "t": event["t"],
+                "channel": event["channel"],
+                "type": event["type"],
+                "payload": {"unserializable": True},
+            }
+        self.events.append(stored)
+        data = line + "\n"
+        nbytes = len(data.encode("utf-8"))
+        self._event_count += 1
+        self._channels.add(event["channel"])
+        self._original_bytes += nbytes
+        self._original_sha.update(data.encode("utf-8"))
+        if not self._buffering_tail:
+            if self._bytes_written + nbytes <= self._head_budget:
+                self._fh.write(data)
+                self._bytes_written += nbytes
+                return
+            self._buffering_tail = True
+        self._tail.append((nbytes, data))
+        self._tail_bytes += nbytes
+        while self._tail and self._tail_bytes > self._tail_budget:
+            dropped_bytes, _ = self._tail.popleft()
+            self._tail_bytes -= dropped_bytes
+            self._dropped_events += 1
+
+    # -- close + summary ----------------------------------------------------
+
+    def close(self) -> dict[str, Any]:
+        """Flush the tail, close the file, and return the artifact summary:
+        ``{path, event_count, channels, duration_s, bytes, sha256, complete}``
+        plus a ``truncated`` stanza when the cap dropped events."""
+
+        if self._closed:
+            assert self._summary is not None
+            return self._summary
+        truncated = self._dropped_events > 0
+        if self._buffering_tail:
+            if truncated:
+                marker = json.dumps(
+                    {
+                        "t": round(time.monotonic() - self._t0, 6),
+                        "channel": "lane",
+                        "type": "transcript_truncated",
+                        "payload": {
+                            "retained": "head_and_tail",
+                            "dropped_events": self._dropped_events,
+                        },
+                    },
+                    ensure_ascii=False,
+                )
+                self._fh.write(marker + "\n")
+                self._bytes_written += len((marker + "\n").encode("utf-8"))
+            for nbytes, data in self._tail:
+                self._fh.write(data)
+                self._bytes_written += nbytes
+            self._tail.clear()
+            self._tail_bytes = 0
+        self._fh.close()
+        self._closed = True
+        file_sha = hashlib.sha256()
+        try:
+            with open(self.path, "rb") as handle:
+                for chunk in iter(lambda: handle.read(1 << 20), b""):
+                    file_sha.update(chunk)
+            bytes_on_disk = self.path.stat().st_size
+        except OSError:
+            bytes_on_disk = self._bytes_written
+        summary: dict[str, Any] = {
+            "path": str(self.path),
+            "event_count": self._event_count,
+            "channels": sorted(self._channels),
+            "duration_s": round(time.monotonic() - self._t0, 6),
+            "bytes": bytes_on_disk,
+            "sha256": file_sha.hexdigest(),
+            "complete": not truncated,
+        }
+        if truncated:
+            summary["truncated"] = {
+                "original_bytes": self._original_bytes,
+                "original_sha256": self._original_sha.hexdigest(),
+                "retained": "head_and_tail",
+                "dropped_events": self._dropped_events,
+            }
+        self._summary = summary
+        return summary
+
+
+def read_transcript(path: str | Path) -> list[dict[str, Any]]:
+    """Read a JSONL transcript back into its event list (the replay source).
+
+    Unparseable lines are surfaced as ``transcript_unreadable_line`` lane
+    events rather than silently skipped — attribution treats an unreadable
+    transcript as lane_infra evidence.
+    """
+
+    events: list[dict[str, Any]] = []
+    with open(path, "r", encoding="utf-8") as handle:
+        for line_number, line in enumerate(handle, start=1):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                event = json.loads(line)
+            except ValueError:
+                events.append(
+                    {
+                        "t": None,
+                        "channel": "lane",
+                        "type": "transcript_unreadable_line",
+                        "payload": {"line_number": line_number},
+                    }
+                )
+                continue
+            if isinstance(event, dict):
+                events.append(event)
+            else:
+                events.append(
+                    {
+                        "t": None,
+                        "channel": "lane",
+                        "type": "transcript_unreadable_line",
+                        "payload": {"line_number": line_number},
+                    }
+                )
+    return events

fi/alk/live/_workers/__init__.py

@@ -0,0 +1,9 @@
+"""Subprocess ENTRY MODULES for live lanes (P3-D1).
+
+These files are only ever executed as subprocesses
+(``sys.executable path/to/worker.py``) by ``_runner.spawn_lane_subprocess``
+with the lane extra installed; the release process never imports them. They
+are the ONLY sanctioned home for framework imports under the
+live_lane_boundary gate (workers here keep even those lazy, inside function
+bodies, so the files also import clean without any extra).
+"""

fi/alk/live/_workers/a2a_worker.py

@@ -0,0 +1,316 @@
+"""A2A lane worker (3E) — untrusted subprocess entry (P3-D1).
+
+Doubles as the loopback A2A peer entry (peer mode). In client mode it walks
+the protocol stages against a peer — card discovery → task lifecycle →
+artifact exchange (R§1 #18) — spawning its own peer-mode sibling on
+127.0.0.1 when no remote peer URL is given (the shipped loopback default
+tier). In peer mode it serves a deterministic echo agent over the REAL A2A
+HTTP protocol.
+
+IPC with the harness (client mode): see livekit_worker.py — same
+one-boot-line / JSONL contract. The peer subprocess receives its own boot
+line (``{"type": "boot", "mode": "peer", "port": N}``) from the client.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import os
+import socket
+import subprocess
+import sys
+import time
+import traceback
+import uuid
+from typing import Any
+
+
+def _emit(channel: str, type_: str, payload: dict[str, Any]) -> None:
+    print(
+        json.dumps(
+            {"channel": channel, "type": type_, "payload": payload},
+            ensure_ascii=False,
+            default=str,
+        ),
+        flush=True,
+    )
+
+
+def _read_boot() -> dict[str, Any]:
+    line = sys.stdin.readline()
+    if not line.strip():
+        raise RuntimeError("missing boot message on stdin")
+    boot = json.loads(line)
+    if not isinstance(boot, dict) or boot.get("type") != "boot":
+        raise RuntimeError("first stdin line must be a boot message")
+    return boot
+
+
+def _capability_hash(framework: str, version: str) -> str:
+    return hashlib.sha256(f"{framework}:{version}".encode("utf-8")).hexdigest()
+
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return int(sock.getsockname()[1])
+
+
+# --- peer mode ----------------------------------------------------------------
+
+
+def _run_peer(boot: dict[str, Any]) -> None:
+    import uvicorn
+    from a2a.server.agent_execution import AgentExecutor
+    from a2a.server.apps import A2AStarletteApplication
+    from a2a.server.request_handlers import DefaultRequestHandler
+    from a2a.server.tasks import InMemoryTaskStore
+    from a2a.types import AgentCapabilities, AgentCard, AgentSkill
+    from a2a.utils import new_agent_text_message
+
+    port = int(boot.get("port") or 0) or _free_port()
+
+    class _EchoExecutor(AgentExecutor):
+        """Deterministic loopback peer behavior: echo the user text."""
+
+        async def execute(self, context: Any, event_queue: Any) -> None:
+            text = ""
+            try:
+                text = context.get_user_input()
+            except Exception:
+                pass
+            await event_queue.enqueue_event(
+                new_agent_text_message(f"echo: {text}")
+            )
+
+        async def cancel(self, context: Any, event_queue: Any) -> None:
+            return None
+
+    skill = AgentSkill(
+        id="echo",
+        name="Echo",
+        description="Echoes the inbound message text (deterministic).",
+        tags=["echo", "loopback"],
+    )
+    card = AgentCard(
+        name="agent-learning-loopback-peer",
+        description="Credential-free loopback A2A peer shipped with the kit.",
+        url=f"http://127.0.0.1:{port}/",
+        version="1.0.0",
+        default_input_modes=["text"],
+        default_output_modes=["text"],
+        capabilities=AgentCapabilities(streaming=False),
+        skills=[skill],
+    )
+    handler = DefaultRequestHandler(
+        agent_executor=_EchoExecutor(), task_store=InMemoryTaskStore()
+    )
+    application = A2AStarletteApplication(agent_card=card, http_handler=handler)
+    uvicorn.run(
+        application.build(), host="127.0.0.1", port=port, log_level="error"
+    )
+
+
+# --- client mode ----------------------------------------------------------------
+
+
+def _extract_texts(value: Any, into: list[str]) -> None:
+    """Best-effort recursive text extraction across a2a-sdk event shapes."""
+
+    if value is None:
+        return
+    if isinstance(value, str):
+        if value.strip():
+            into.append(value)
+        return
+    if isinstance(value, (list, tuple)):
+        for item in value:
+            _extract_texts(item, into)
+        return
+    for attribute in ("text", "parts", "artifacts", "history", "root", "message", "status"):
+        if hasattr(value, attribute):
+            _extract_texts(getattr(value, attribute), into)
+
+
+async def _run_client(boot: dict[str, Any]) -> None:
+    import importlib.metadata
+
+    import httpx
+
+    import a2a as a2a_pkg
+    from a2a.client import A2ACardResolver
+
+    version = importlib.metadata.version("a2a-sdk")
+    _emit(
+        "lane",
+        "framework_ready",
+        {
+            "framework": "a2a-sdk",
+            "framework_version": version,
+            "capability_hash": _capability_hash("a2a-sdk", version),
+            "package_paths": [os.path.dirname(a2a_pkg.__file__)],
+        },
+    )
+    config = boot.get("config") or {}
+    stages = [str(stage) for stage in (config.get("stages") or [])]
+    message_text = str(config.get("message") or "ping from the harness")
+    peer_url = config.get("peer_url")
+    peer_process: subprocess.Popen[str] | None = None
+    checks: dict[str, bool] = {}
+    try:
+        if not peer_url:
+            port = _free_port()
+            peer_process = subprocess.Popen(
+                [sys.executable, os.path.abspath(__file__)],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                text=True,
+                env=dict(os.environ),
+            )
+            assert peer_process.stdin is not None
+            peer_process.stdin.write(
+                json.dumps({"type": "boot", "mode": "peer", "port": port}) + "\n"
+            )
+            peer_process.stdin.flush()
+            peer_url = f"http://127.0.0.1:{port}"
+
+        base_url = str(peer_url).rstrip("/")
+        async with httpx.AsyncClient(timeout=30.0) as http_client:
+            # Wait for the peer to come up (loopback boot is fast but async).
+            card_paths = (
+                "/.well-known/agent-card.json",
+                "/.well-known/agent.json",
+            )
+            deadline = time.monotonic() + 30.0
+            reachable = False
+            while time.monotonic() < deadline and not reachable:
+                for path in card_paths:
+                    try:
+                        response = await http_client.get(base_url + path)
+                        if response.status_code == 200:
+                            reachable = True
+                            break
+                    except httpx.HTTPError:
+                        pass
+                if not reachable:
+                    await asyncio.sleep(0.2)
+            if not reachable:
+                raise RuntimeError(f"A2A peer at {base_url} never became reachable")
+
+            # --- stage: card discovery -----------------------------------
+            resolver = A2ACardResolver(http_client, base_url)
+            card = await resolver.get_agent_card()
+            card_ok = bool(getattr(card, "name", None))
+            _emit(
+                "agent",
+                "protocol_stage",
+                {"stage": "card_discovery", "ok": card_ok, "peer": getattr(card, "name", None)},
+            )
+            if "card_discovery" in stages:
+                checks["card_discovery"] = card_ok
+
+            # --- stage: task lifecycle + artifact exchange ----------------
+            texts: list[str] = []
+            lifecycle_ok = False
+            try:
+                from a2a.client import ClientConfig, ClientFactory
+                from a2a.types import Message, Part, Role, TextPart
+
+                factory = ClientFactory(ClientConfig(httpx_client=http_client))
+                client = factory.create(card)
+                try:
+                    outbound = Message(
+                        role=Role.user,
+                        parts=[Part(root=TextPart(text=message_text))],
+                        message_id=uuid.uuid4().hex,
+                    )
+                except TypeError:
+                    outbound = Message(
+                        role=Role.user,
+                        parts=[Part(root=TextPart(text=message_text))],
+                        messageId=uuid.uuid4().hex,
+                    )
+                _emit("user", "message", {"text": message_text})
+                async for event in client.send_message(outbound):
+                    lifecycle_ok = True
+                    _extract_texts(event, texts)
+            except ImportError:
+                # Older SDK line: single-shot A2AClient JSON-RPC surface.
+                from a2a.client import A2AClient
+                from a2a.types import (
+                    Message,
+                    MessageSendParams,
+                    Part,
+                    Role,
+                    SendMessageRequest,
+                    TextPart,
+                )
+
+                client = A2AClient(httpx_client=http_client, agent_card=card)
+                request = SendMessageRequest(
+                    id=uuid.uuid4().hex,
+                    params=MessageSendParams(
+                        message=Message(
+                            role=Role.user,
+                            parts=[Part(root=TextPart(text=message_text))],
+                            messageId=uuid.uuid4().hex,
+                        )
+                    ),
+                )
+                _emit("user", "message", {"text": message_text})
+                response = await client.send_message(request)
+                lifecycle_ok = response is not None
+                _extract_texts(response, texts)
+
+            reply = next((text for text in texts if "echo" in text.lower()), "")
+            artifact_ok = bool(reply) or any(text.strip() for text in texts)
+            _emit(
+                "agent",
+                "protocol_stage",
+                {"stage": "task_lifecycle", "ok": lifecycle_ok},
+            )
+            _emit(
+                "agent",
+                "protocol_stage",
+                {
+                    "stage": "artifact_exchange",
+                    "ok": artifact_ok,
+                    "text": (reply or " ".join(texts))[:500],
+                },
+            )
+            if "task_lifecycle" in stages:
+                checks["task_lifecycle"] = lifecycle_ok
+            if "artifact_exchange" in stages:
+                checks["artifact_exchange"] = artifact_ok
+
+        passed = bool(checks) and all(checks.values())
+        _emit("lane", "verification", {"passed": passed, "checks": checks})
+    finally:
+        if peer_process is not None:
+            peer_process.terminate()
+            try:
+                peer_process.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                peer_process.kill()
+
+
+def main() -> int:
+    boot = _read_boot()
+    mode = str(boot.get("mode") or "client")
+    try:
+        if mode == "peer":
+            _run_peer(boot)
+        else:
+            asyncio.run(_run_client(boot))
+    except Exception:
+        _emit("lane", "worker_error", {"traceback": traceback.format_exc()})
+        traceback.print_exc(file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())