glaip-sdk 0.0.20__py3-none-any.whl → 0.7.7__py3-none-any.whl

glaip_sdk/cli/slash/tui/toast.py

@@ -0,0 +1,123 @@
+"""Toast notification helpers for Textual TUIs.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from enum import Enum
+
+
+class ToastVariant(str, Enum):
+    """Toast message variant."""
+
+    INFO = "info"
+    SUCCESS = "success"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+DEFAULT_TOAST_DURATIONS_SECONDS: dict[ToastVariant, float] = {
+    ToastVariant.SUCCESS: 2.0,
+    ToastVariant.INFO: 3.0,
+    ToastVariant.WARNING: 3.0,
+    ToastVariant.ERROR: 5.0,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ToastState:
+    """Immutable toast payload."""
+
+    message: str
+    variant: ToastVariant
+    duration_seconds: float
+
+
+class ToastBus:
+    """Single-toast state holder with auto-dismiss."""
+
+    def __init__(self) -> None:
+        """Initialize the bus."""
+        self._state: ToastState | None = None
+        self._dismiss_task: asyncio.Task[None] | None = None
+
+    @property
+    def state(self) -> ToastState | None:
+        """Return the current toast state."""
+        return self._state
+
+    def show(
+        self,
+        message: str,
+        variant: ToastVariant | str = ToastVariant.INFO,
+        *,
+        duration_seconds: float | None = None,
+    ) -> None:
+        """Set toast state and schedule auto-dismiss."""
+        resolved_variant = self._coerce_variant(variant)
+        resolved_duration = (
+            DEFAULT_TOAST_DURATIONS_SECONDS[resolved_variant] if duration_seconds is None else float(duration_seconds)
+        )
+
+        self._state = ToastState(
+            message=message,
+            variant=resolved_variant,
+            duration_seconds=resolved_duration,
+        )
+
+        self._cancel_dismiss_task()
+
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            raise RuntimeError(
+                "Cannot schedule toast auto-dismiss: no running event loop. "
+                "ToastBus.show() must be called from within an async context."
+            ) from None
+
+        self._dismiss_task = loop.create_task(self._auto_dismiss(resolved_duration))
+
+    def clear(self) -> None:
+        """Clear the current toast."""
+        self._cancel_dismiss_task()
+        self._state = None
+
+    def copy_success(self, label: str | None = None) -> None:
+        """Show clipboard success toast."""
+        message = "Copied to clipboard" if not label else f"Copied {label} to clipboard"
+        self.show(message=message, variant=ToastVariant.SUCCESS)
+
+    def copy_failed(self) -> None:
+        """Show clipboard failure toast."""
+        self.show(
+            message="Clipboard unavailable. Text printed below",
+            variant=ToastVariant.WARNING,
+        )
+
+    def _coerce_variant(self, variant: ToastVariant | str) -> ToastVariant:
+        if isinstance(variant, ToastVariant):
+            return variant
+        try:
+            return ToastVariant(variant)
+        except ValueError:
+            return ToastVariant.INFO
+
+    def _cancel_dismiss_task(self) -> None:
+        if self._dismiss_task is None:
+            return
+        if not self._dismiss_task.done():
+            self._dismiss_task.cancel()
+        self._dismiss_task = None
+
+    async def _auto_dismiss(self, duration_seconds: float) -> None:
+        try:
+            await asyncio.sleep(duration_seconds)
+        except asyncio.CancelledError:
+            return
+
+        self._state = None
+        self._dismiss_task = None

glaip_sdk/cli/transcript/__init__.py

@@ -4,68 +4,28 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
-from glaip_sdk.cli.transcript.cache import (
-    TranscriptCacheStats,
-    TranscriptPayload,
-    TranscriptStoreResult,
-    ensure_cache_dir,
-    get_transcript_cache_stats,
-    latest_manifest_entry,
-    manifest_path,
-    resolve_manifest_entry,
-    store_transcript,
-    suggest_filename,
-)
 from glaip_sdk.cli.transcript.cache import (
     export_transcript as export_cached_transcript,
 )
-from glaip_sdk.cli.transcript.capture import (
-    StoredTranscriptContext,
-    coerce_events,
-    coerce_result_text,
-    compute_finished_at,
-    extract_server_run_id,
-    register_last_transcript,
-    store_transcript_for_session,
+from glaip_sdk.cli.transcript.cache import (
+    get_transcript_cache_stats,
+    suggest_filename,
 )
+from glaip_sdk.cli.transcript.capture import store_transcript_for_session
 from glaip_sdk.cli.transcript.export import (
     normalise_export_destination,
     resolve_manifest_for_export,
 )
-from glaip_sdk.cli.transcript.launcher import (
-    maybe_launch_post_run_viewer,
-    should_launch_post_run_viewer,
-)
-from glaip_sdk.cli.transcript.viewer import (
-    PostRunViewer,
-    ViewerContext,
-    run_viewer_session,
-)
+from glaip_sdk.cli.transcript.history import load_history_snapshot
+from glaip_sdk.cli.transcript.launcher import maybe_launch_post_run_viewer
 
 __all__ = [
-    "TranscriptCacheStats",
-    "TranscriptPayload",
-    "TranscriptStoreResult",
-    "ensure_cache_dir",
-    "get_transcript_cache_stats",
-    "manifest_path",
-    "store_transcript",
-    "suggest_filename",
-    "latest_manifest_entry",
-    "resolve_manifest_entry",
     "export_cached_transcript",
-    "StoredTranscriptContext",
-    "coerce_events",
-    "coerce_result_text",
-    "compute_finished_at",
-    "extract_server_run_id",
-    "register_last_transcript",
-    "store_transcript_for_session",
-    "resolve_manifest_for_export",
-    "normalise_export_destination",
+    "get_transcript_cache_stats",
+    "load_history_snapshot",
     "maybe_launch_post_run_viewer",
-    "should_launch_post_run_viewer",
-    "ViewerContext",
-    "PostRunViewer",
-    "run_viewer_session",
+    "normalise_export_destination",
+    "resolve_manifest_for_export",
+    "store_transcript_for_session",
+    "suggest_filename",
 ]

glaip_sdk/cli/transcript/cache.py

@@ -8,13 +8,17 @@ from __future__ import annotations
 
 import json
 import os
-import uuid
-from collections.abc import Iterable
+import secrets
+from collections.abc import Iterable, Iterator
 from dataclasses import dataclass
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any
 
+from glaip_sdk.utils.datetime_helpers import (
+    coerce_datetime as _coerce_datetime,
+)
+
 DEFAULT_CACHE_ROOT = Path(
     os.getenv(
         "AIP_TRANSCRIPT_CACHE_DIR",
@@ -22,6 +26,11 @@ DEFAULT_CACHE_ROOT = Path(
     )
 )
 MANIFEST_FILENAME = "manifest.jsonl"
+JSONL_SUFFIX = ".jsonl"
+UTC_OFFSET_SUFFIX = "+00:00"
+
+_RUN_ID_PREFIX = "run_"
+_RUN_ID_ALPHABET = "23456789abcdefghjkmnpqrstuvwxyz"
 
 
 @dataclass(slots=True)
@@ -61,6 +70,124 @@ class TranscriptCacheStats:
     total_bytes: int
 
 
+def generate_run_id(length: int = 6) -> str:
+    """Return a short, human-friendly run identifier."""
+    length = max(4, min(int(length or 0), 16)) or 6
+    return _RUN_ID_PREFIX + "".join(secrets.choice(_RUN_ID_ALPHABET) for _ in range(length))
+
+
+def _timestamp_to_iso(value: Any) -> str | None:
+    """Convert supported timestamp-like values to an ISO8601 string with UTC designator."""
+    dt = _coerce_datetime(value)
+    if dt is None:
+        return None
+    if dt.year < 2000:
+        return None
+    return dt.isoformat().replace(UTC_OFFSET_SUFFIX, "Z")
+
+
+def _compute_duration_seconds(start: Any, end: Any) -> int | None:
+    """Compute whole-second duration between two timestamp-like values."""
+    start_dt = _coerce_datetime(start)
+    end_dt = _coerce_datetime(end)
+    if start_dt is None or end_dt is None:
+        return None
+    delta = (end_dt - start_dt).total_seconds()
+    if delta < 0:
+        return None
+    return int(round(delta))
+
+
+def _iter_candidate_paths(entry: dict[str, Any], directory: Path) -> Iterator[Path]:
+    """Yield plausible transcript paths for a manifest entry, deduplicated."""
+    seen: set[str] = set()
+
+    def _offer(path: Path) -> Iterator[Path]:
+        key = str(path)
+        if key not in seen:
+            seen.add(key)
+            yield path
+
+    for candidate in _filename_candidate_paths(entry, directory):
+        yield from _offer(candidate)
+    for candidate in _cache_path_candidate_paths(entry):
+        yield from _offer(candidate)
+    for candidate in _run_id_candidate_paths(entry, directory):
+        yield from _offer(candidate)
+
+
+def _filename_candidate_paths(entry: dict[str, Any], directory: Path) -> tuple[Path, ...]:
+    """Return possible transcript paths derived from the manifest filename."""
+    filename = entry.get("filename")
+    if not filename:
+        return ()
+    candidate = Path(str(filename))
+    if not candidate.is_absolute():
+        candidate = directory / candidate
+    return (candidate,)
+
+
+def _cache_path_candidate_paths(entry: dict[str, Any]) -> tuple[Path, ...]:
+    """Return legacy cache_path-derived transcript candidates."""
+    cache_path = entry.get("cache_path")
+    if not cache_path:
+        return ()
+    return (Path(str(cache_path)).expanduser(),)
+
+
+def _run_id_candidate_paths(entry: dict[str, Any], directory: Path) -> tuple[Path, ...]:
+    """Return candidate transcript paths derived from the run id."""
+    run_id = entry.get("run_id")
+    if not run_id:
+        return ()
+    paths: list[Path] = []
+    for variant in _run_id_variants(str(run_id)):
+        name = variant if variant.endswith(JSONL_SUFFIX) else f"{variant}{JSONL_SUFFIX}"
+        paths.append(directory / name)
+    return tuple(paths)
+
+
+def _run_id_variants(run_id: str) -> set[str]:
+    """Return plausible filename stems derived from a run id."""
+    variants = {run_id}
+    if run_id.startswith(_RUN_ID_PREFIX):
+        suffix = run_id[len(_RUN_ID_PREFIX) :]
+        if suffix:
+            variants.update({suffix, f"run-{suffix}"})
+        variants.add(f"run-{run_id}")
+    else:
+        variants.update({f"run-{run_id}", _RUN_ID_PREFIX + run_id})
+    return variants
+
+
+def transcript_path_candidates(entry: dict[str, Any], cache_dir: Path | None = None) -> list[Path]:
+    """Return possible transcript file locations for a manifest entry."""
+    directory = ensure_cache_dir(cache_dir)
+    return list(_iter_candidate_paths(entry, directory))
+
+
+def resolve_transcript_path(entry: dict[str, Any], cache_dir: Path | None = None) -> Path:
+    """Resolve the cached transcript path for a manifest entry or raise informative errors."""
+    candidates = transcript_path_candidates(entry, cache_dir)
+    if not candidates:
+        raise FileNotFoundError("Cached transcript path missing from manifest.")
+
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+
+    raise FileNotFoundError(f"Cached transcript file not found: {candidates[0]}")
+
+
+def _manifest_sort_key(entry: dict[str, Any]) -> datetime:
+    """Return a datetime for ordering manifest rows, defaulting to the distant past."""
+    for key in ("started_at", "created_at"):
+        dt = _coerce_datetime(entry.get(key))
+        if dt is not None:
+            return dt
+    return datetime.min.replace(tzinfo=timezone.utc)
+
+
 def ensure_cache_dir(cache_dir: Path | None = None) -> Path:
     """Ensure the cache directory exists and return it."""
     directory = cache_dir or DEFAULT_CACHE_ROOT
@@ -88,15 +215,17 @@ def manifest_path(cache_dir: Path | None = None) -> Path:
 
 
 def _parse_iso(ts: str | None) -> datetime | None:
+    """Parse metadata timestamps that may use the legacy Z suffix."""
     if not ts:
         return None
     try:
-        return datetime.fromisoformat(ts.replace("Z", "+00:00"))
+        return datetime.fromisoformat(ts.replace("Z", UTC_OFFSET_SUFFIX))
     except Exception:
         return None
 
 
 def _load_manifest_entries(cache_dir: Path | None = None) -> list[dict[str, Any]]:
+    """Read manifest entries from disk, returning an empty list when missing."""
     path = manifest_path(cache_dir)
     entries: list[dict[str, Any]] = []
     if not path.exists():
@@ -124,14 +253,25 @@ def _json_default(value: Any) -> Any:
     return repr(value)
 
 
-def _write_manifest(
-    entries: Iterable[dict[str, Any]], cache_dir: Path | None = None
-) -> None:
+def _write_manifest(entries: Iterable[dict[str, Any]], cache_dir: Path | None = None) -> None:
+    """Atomically write manifest entries back to disk."""
     path = manifest_path(cache_dir)
-    with path.open("w", encoding="utf-8") as fh:
+    tmp_path = path.with_name(f"{path.name}.tmp")
+    with tmp_path.open("w", encoding="utf-8") as fh:
         for entry in entries:
             fh.write(json.dumps(entry, ensure_ascii=False, default=_json_default))
             fh.write("\n")
+    tmp_path.replace(path)
+
+
+def load_manifest_entries(cache_dir: Path | None = None) -> list[dict[str, Any]]:
+    """Public wrapper around manifest loading for downstream tooling."""
+    return _load_manifest_entries(cache_dir)
+
+
+def write_manifest(entries: Iterable[dict[str, Any]], cache_dir: Path | None = None) -> None:
+    """Persist manifest entries atomically."""
+    _write_manifest(entries, cache_dir)
 
 
 def store_transcript(
@@ -141,10 +281,38 @@ def store_transcript(
 ) -> TranscriptStoreResult:
     """Persist a transcript to disk and update the manifest."""
     directory = ensure_cache_dir(cache_dir)
-    filename = f"run-{payload.run_id}.jsonl"
+    filename = _normalise_run_filename(payload.run_id)
     transcript_path = directory / filename
 
-    meta_line = {
+    meta_line = _build_meta_line(payload)
+    transcript_path = _write_transcript_file(transcript_path, filename, meta_line, payload.events)
+    size_bytes = _safe_file_size(transcript_path)
+    manifest_entry = _build_manifest_entry(payload, transcript_path.name, size_bytes)
+    if transcript_path.parent != directory:
+        manifest_entry["cache_path"] = str(transcript_path)
+
+    existing_entries = _load_manifest_entries(directory)
+    existing_entries.append(manifest_entry)
+    _write_manifest(existing_entries, directory)
+
+    return TranscriptStoreResult(
+        path=transcript_path,
+        manifest_entry=manifest_entry,
+        pruned_entries=[],
+    )
+
+
+def _normalise_run_filename(run_id: str) -> str:
+    """Ensure cached run filenames always end with .jsonl."""
+    run_basename = run_id.rstrip()
+    if run_basename.endswith(JSONL_SUFFIX):
+        run_basename = run_basename[: -len(JSONL_SUFFIX)]
+    return f"{run_basename}{JSONL_SUFFIX}"
+
+
+def _build_meta_line(payload: TranscriptPayload) -> dict[str, Any]:
+    """Return the metadata header stored at the top of transcript files."""
+    return {
         "type": "meta",
         "run_id": payload.run_id,
         "agent_id": payload.agent_id,
@@ -160,11 +328,20 @@ def store_transcript(
         "source": payload.source,
     }
 
-    def _write_transcript(path: Path) -> None:
-        with path.open("w", encoding="utf-8") as fh:
+
+def _write_transcript_file(
+    path: Path,
+    filename: str,
+    meta_line: dict[str, Any],
+    events: list[dict[str, Any]],
+) -> Path:
+    """Persist the transcript JSONL file, falling back to cwd when necessary."""
+
+    def _write(target: Path) -> None:
+        with target.open("w", encoding="utf-8") as fh:
             fh.write(json.dumps(meta_line, ensure_ascii=False, default=_json_default))
             fh.write("\n")
-            for event in payload.events:
+            for event in events:
                 fh.write(
                     json.dumps(
                         {"type": "event", "event": event},
@@ -175,34 +352,62 @@ def store_transcript(
                 fh.write("\n")
 
     try:
-        _write_transcript(transcript_path)
+        _write(path)
+        return path
     except PermissionError:
-        directory = _fallback_cache_dir()
-        transcript_path = directory / filename
-        _write_transcript(transcript_path)
+        fallback_dir = _fallback_cache_dir()
+        fallback_path = fallback_dir / filename
+        _write(fallback_path)
+        return fallback_path
+
+
+def _safe_file_size(path: Path) -> int:
+    """Return the file size, tolerating missing paths."""
+    try:
+        return path.stat().st_size
+    except FileNotFoundError:
+        return 0
+
 
-    size_bytes = transcript_path.stat().st_size
-    manifest_entry = {
+def _build_manifest_entry(payload: TranscriptPayload, filename: str, size_bytes: int) -> dict[str, Any]:
+    """Generate the manifest row corresponding to a stored transcript."""
+    entry: dict[str, Any] = {
         "run_id": payload.run_id,
         "agent_id": payload.agent_id,
         "agent_name": payload.agent_name,
-        "created_at": payload.created_at.isoformat(),
-        "cache_path": str(transcript_path),
+        "started_at": _timestamp_to_iso(payload.started_at) or payload.created_at.isoformat(),
+        "finished_at": _timestamp_to_iso(payload.finished_at),
+        "duration_seconds": _compute_duration_seconds(payload.started_at, payload.finished_at),
         "size_bytes": size_bytes,
+        "filename": filename,
         "retained": True,
-        "source": payload.source,
-        "server_run_id": payload.server_run_id,
+        "model": payload.model,
     }
 
-    existing_entries = _load_manifest_entries(directory)
-    existing_entries.append(manifest_entry)
-    _write_manifest(existing_entries, directory)
+    api_url = payload.meta.get("api_url")
+    if api_url:
+        entry["api_url"] = api_url
 
-    return TranscriptStoreResult(
-        path=transcript_path,
-        manifest_entry=manifest_entry,
-        pruned_entries=[],
-    )
+    if entry["duration_seconds"] is None:
+        entry["duration_seconds"] = _coerce_duration_hint(payload.meta.get("final_duration_seconds"))
+
+    if entry.get("finished_at") is None and entry.get("started_at") and entry.get("duration_seconds") is not None:
+        start_dt = _coerce_datetime(entry["started_at"])
+        if start_dt is not None:
+            finished_dt = start_dt + timedelta(seconds=int(entry["duration_seconds"]))
+            entry["finished_at"] = finished_dt.isoformat().replace(UTC_OFFSET_SUFFIX, "Z")
+
+    return entry
+
+
+def _coerce_duration_hint(value: Any) -> int | None:
+    """Convert loose duration hints to whole seconds."""
+    try:
+        if value is None:
+            return None
+        return int(round(float(value)))
+    except Exception:
+        return None
 
 
 def latest_manifest_entry(cache_dir: Path | None = None) -> dict[str, Any] | None:
@@ -210,11 +415,7 @@ def latest_manifest_entry(cache_dir: Path | None = None) -> dict[str, Any] | Non
     entries = _load_manifest_entries(cache_dir)
     if not entries:
         return None
-    return max(
-        entries,
-        key=lambda e: _parse_iso(e.get("created_at"))
-        or datetime.min.replace(tzinfo=timezone.utc),
-    )
+    return max(entries, key=_manifest_sort_key)
 
 
 def resolve_manifest_entry(
@@ -237,21 +438,14 @@ def export_transcript(
 ) -> Path:
     """Copy a cached transcript to the requested destination path."""
     directory = ensure_cache_dir(cache_dir)
-    entry = (
-        resolve_manifest_entry(run_id, directory)
-        if run_id
-        else latest_manifest_entry(directory)
-    )
+    entry = resolve_manifest_entry(run_id, directory) if run_id else latest_manifest_entry(directory)
     if entry is None:
         raise FileNotFoundError("No cached transcripts available for export.")
 
-    cache_path = entry.get("cache_path")
-    if not cache_path:
-        raise FileNotFoundError("Cached transcript path missing from manifest.")
-
-    cache_file = Path(cache_path)
-    if not cache_file.exists():
-        raise FileNotFoundError(f"Cached transcript file not found: {cache_file}")
+    try:
+        cache_file = resolve_transcript_path(entry, directory)
+    except FileNotFoundError as exc:
+        raise FileNotFoundError(str(exc)) from exc
 
     destination.parent.mkdir(parents=True, exist_ok=True)
 
@@ -259,9 +453,7 @@ def export_transcript(
         lines = cache_file.read_text(encoding="utf-8").splitlines()
         records = [json.loads(line) for line in lines if line.strip()]
     except json.JSONDecodeError as exc:
-        raise FileNotFoundError(
-            f"Cached transcript file is corrupted: {cache_file}"
-        ) from exc
+        raise FileNotFoundError(f"Cached transcript file is corrupted: {cache_file}") from exc
 
     with destination.open("w", encoding="utf-8") as fh:
         for idx, record in enumerate(records):
@@ -275,14 +467,20 @@ def export_transcript(
 
 def suggest_filename(entry: dict[str, Any] | None = None) -> str:
     """Return a friendly filename suggestion for exporting a transcript."""
-    run_id = entry.get("run_id") if entry else uuid.uuid4().hex
-    created_at = (
-        entry.get("created_at") if entry else datetime.now(timezone.utc).isoformat()
-    )
-    timestamp = (
-        created_at.replace(":", "").replace("-", "").replace("T", "_").split("+")[0]
-    )
-    return f"aip-run-{timestamp}-{run_id}.jsonl"
+    run_id = entry.get("run_id") if entry else None
+    if not run_id:
+        run_id = generate_run_id()
+
+    timestamp_source = None
+    if entry:
+        timestamp_source = entry.get("started_at") or entry.get("created_at")
+
+    if not timestamp_source:
+        timestamp_source = datetime.now(timezone.utc).isoformat()
+
+    timestamp = str(timestamp_source).replace(":", "").replace("-", "").replace("T", "_").split("+")[0]
+    safe_run_id = str(run_id).replace("/", "-").replace(" ", "-")
+    return f"aip-run-{timestamp}-{safe_run_id}{JSONL_SUFFIX}"
 
 
 def build_payload(
@@ -313,7 +511,7 @@ def build_payload(
         created_at=datetime.now(timezone.utc),
         source=source,
         meta=meta,
-        run_id=uuid.uuid4().hex,
+        run_id=generate_run_id(),
     )