AbstractRuntime 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

abstractruntime/rendering/agent_trace_report.py

@@ -0,0 +1,256 @@
+"""Agent scratchpad → Markdown report renderer.
+
+Goal:
+- Clear, complete, and token-efficient review artifact for agent runs.
+- No truncation of tool call arguments or tool execution results.
+
+Input shape:
+The "scratchpad" passed around by hosts is expected to include runtime-owned node traces,
+typically at `scratchpad["node_traces"]`, which is sourced from:
+`RunState.vars["_runtime"]["node_traces"]` (ADR-0010).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+from .json_stringify import JsonStringifyMode, stringify_json
+
+
+@dataclass(frozen=True)
+class AgentTraceMarkdownReportConfig:
+    """Rendering configuration.
+
+    Keep defaults conservative to avoid bloating outputs.
+    """
+
+    include_timestamps: bool = False
+    json_mode: JsonStringifyMode = JsonStringifyMode.BEAUTIFY
+
+
+def _as_dict(value: Any) -> Optional[Dict[str, Any]]:
+    return value if isinstance(value, dict) else None
+
+
+def _collect_trace_steps(node_traces: Dict[str, Any]) -> List[Tuple[str, str, Dict[str, Any]]]:
+    """Flatten node_traces into a chronologically sortable list of (ts, node_id, entry)."""
+    out: list[tuple[str, str, Dict[str, Any]]] = []
+    for node_id, trace in node_traces.items():
+        t = _as_dict(trace)
+        if not t:
+            continue
+        steps = t.get("steps")
+        if not isinstance(steps, list):
+            continue
+        for entry in steps:
+            e = _as_dict(entry)
+            if not e:
+                continue
+            ts = e.get("ts")
+            ts_s = ts if isinstance(ts, str) else ""
+            out.append((ts_s, node_id, e))
+    # ISO timestamps are lexicographically sortable.
+    out.sort(key=lambda x: x[0])
+    return out
+
+
+def _code_block(value: Any, *, language: str) -> str:
+    """Render a value inside a fenced code block (no truncation)."""
+    if language == "json":
+        text = stringify_json(value, mode=JsonStringifyMode.BEAUTIFY, sort_keys=False, parse_strings=False)
+    else:
+        text = "" if value is None else str(value)
+    return f"```{language}\n{text}\n```"
+
+
+def _render_tool_call(call: Dict[str, Any], result: Optional[Dict[str, Any]], *, cfg: AgentTraceMarkdownReportConfig) -> str:
+    name = call.get("name")
+    call_id = call.get("call_id") or call.get("id") or ""
+    args = call.get("arguments", {})
+
+    title = f"#### Tool: `{name}`"
+    if isinstance(call_id, str) and call_id:
+        title += f" (call_id={call_id})"
+
+    lines: list[str] = [title, "", "**Arguments**", _code_block(args, language="json")]
+
+    if result is None:
+        lines.extend(["", "**Result**", "_missing tool result in trace entry_"])
+        return "\n".join(lines)
+
+    success = result.get("success") if isinstance(result.get("success"), bool) else None
+    error = result.get("error")
+    output = result.get("output")
+
+    lines.append("")
+    lines.append("**Result**")
+    if success is not None:
+        lines.append(f"- **success**: {str(success).lower()}")
+    if error is not None:
+        lines.append(f"- **error**: {error}")
+
+    # Output can be string or JSON.
+    if isinstance(output, (dict, list, bool, int, float)) or output is None:
+        lines.append(_code_block(output, language="json"))
+    else:
+        lines.append(_code_block(output, language="text"))
+
+    return "\n".join(lines)
+
+
+def _index_tool_results_by_call_id(tool_results: Any) -> Dict[str, Dict[str, Any]]:
+    """Build a call_id → result mapping from a TOOL_CALLS effect outcome."""
+    if not isinstance(tool_results, dict):
+        return {}
+    results = tool_results.get("results")
+    if not isinstance(results, list):
+        return {}
+    out: dict[str, Dict[str, Any]] = {}
+    for r in results:
+        rr = _as_dict(r)
+        if not rr:
+            continue
+        call_id = rr.get("call_id")
+        if isinstance(call_id, str) and call_id:
+            out[call_id] = rr
+    return out
+
+
+def render_agent_trace_markdown(scratchpad: Any, *, config: Optional[AgentTraceMarkdownReportConfig] = None) -> str:
+    """Render an agent scratchpad (runtime-owned node traces) into Markdown."""
+    cfg = config or AgentTraceMarkdownReportConfig()
+
+    sp = _as_dict(scratchpad)
+    if sp is None:
+        return "# Agent Trace Report\n\n_No scratchpad provided._\n"
+
+    node_traces = sp.get("node_traces")
+    if not isinstance(node_traces, dict):
+        # Allow passing node_traces directly.
+        if isinstance(scratchpad, dict) and "steps" in scratchpad and "node_id" in scratchpad:
+            node_traces = {str(scratchpad.get("node_id")): scratchpad}
+        else:
+            return "# Agent Trace Report\n\n_No node_traces found in scratchpad._\n"
+
+    header: list[str] = ["# Agent Trace Report"]
+
+    sub_run_id = sp.get("sub_run_id")
+    workflow_id = sp.get("workflow_id")
+    if isinstance(sub_run_id, str) and sub_run_id:
+        header.append(f"- **sub_run_id**: `{sub_run_id}`")
+    if isinstance(workflow_id, str) and workflow_id:
+        header.append(f"- **workflow_id**: `{workflow_id}`")
+
+    header.append("")
+
+    steps = _collect_trace_steps(node_traces)
+    if not steps:
+        return "\n".join(header + ["_No trace steps found._", ""])
+
+    lines: list[str] = header + ["## Timeline", ""]
+
+    for idx, (ts, node_id, entry) in enumerate(steps, start=1):
+        status = entry.get("status")
+        status_s = status if isinstance(status, str) else ""
+        effect = _as_dict(entry.get("effect")) or {}
+        effect_type = effect.get("type")
+        effect_type_s = effect_type if isinstance(effect_type, str) else ""
+
+        lines.append(f"### {idx}. `{node_id}` — `{effect_type_s}` ({status_s})")
+        if cfg.include_timestamps and ts:
+            lines.append(f"- **ts**: `{ts}`")
+        duration_ms = entry.get("duration_ms")
+        if isinstance(duration_ms, (int, float)) and duration_ms >= 0:
+            lines.append(f"- **duration_ms**: {float(duration_ms):.3f}")
+
+        if status_s == "failed":
+            err = entry.get("error")
+            if err is not None:
+                lines.append("")
+                lines.append("**Error**")
+                lines.append(_code_block(err, language="text"))
+            lines.append("")
+            continue
+
+        result = _as_dict(entry.get("result"))
+
+        if effect_type_s == "llm_call":
+            # Keep it token-efficient: only show what the LLM produced + whether it asked for tools.
+            content = result.get("content") if result else None
+            tool_calls = result.get("tool_calls") if result else None
+            model = result.get("model") if result else None
+            finish_reason = result.get("finish_reason") if result else None
+
+            if isinstance(model, str) and model:
+                lines.append(f"- **model**: `{model}`")
+            if isinstance(finish_reason, str) and finish_reason:
+                lines.append(f"- **finish_reason**: `{finish_reason}`")
+
+            if isinstance(tool_calls, list) and tool_calls:
+                lines.append("- **tool_calls_requested**:")
+                for c in tool_calls:
+                    cc = _as_dict(c)
+                    if not cc:
+                        continue
+                    nm = cc.get("name")
+                    cid = cc.get("call_id") or ""
+                    if isinstance(nm, str) and nm:
+                        suffix = f" (call_id={cid})" if isinstance(cid, str) and cid else ""
+                        lines.append(f"  - `{nm}`{suffix}")
+            else:
+                lines.append("- **tool_calls_requested**: none")
+
+            if isinstance(content, str) and content.strip():
+                lines.append("")
+                lines.append("**Assistant content**")
+                lines.append(_code_block(content, language="markdown"))
+            lines.append("")
+            continue
+
+        if effect_type_s == "tool_calls":
+            payload = _as_dict(effect.get("payload")) or {}
+            calls = payload.get("tool_calls")
+            calls_list: list[Any]
+            if isinstance(calls, list):
+                calls_list = calls
+            elif calls is None:
+                calls_list = []
+            else:
+                calls_list = [calls]
+
+            results_by_id = _index_tool_results_by_call_id(result)
+            if not calls_list:
+                lines.append("- **tool_calls**: none")
+                lines.append("")
+                continue
+
+            lines.append("")
+            for call_any in calls_list:
+                call = _as_dict(call_any)
+                if not call:
+                    continue
+                call_id = call.get("call_id")
+                call_id_s = call_id if isinstance(call_id, str) else ""
+                r = results_by_id.get(call_id_s) if call_id_s else None
+                lines.append(_render_tool_call(call, r, cfg=cfg))
+                lines.append("")
+            continue
+
+        # Fallback: show a compact JSON of the result (still no truncation).
+        if result is not None:
+            lines.append("")
+            lines.append("**Result (raw)**")
+            lines.append(_code_block(result, language="json"))
+            lines.append("")
+
+    # Validate that report is JSON-safe when embedded (defensive, should always be true).
+    try:
+        json.dumps({"report": "\n".join(lines)})
+    except Exception:
+        pass
+
+    return "\n".join(lines).rstrip() + "\n"
+
+

abstractruntime/rendering/json_stringify.py

@@ -0,0 +1,136 @@
+"""JSON stringify utilities.
+
+Why this exists in AbstractRuntime:
+- Many hosts need consistent "JSON → string" semantics (UI preview, reports, prompts).
+- Keeping the core logic in runtime avoids host-specific divergence (layering, ADR-0001).
+
+This intentionally stays dependency-light (stdlib only).
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+from enum import Enum
+from typing import Any, Optional
+
+
+class JsonStringifyMode(str, Enum):
+    """Formatting mode for JSON stringification."""
+
+    NONE = "none"  # default json.dumps formatting (single line, spaces after separators)
+    BEAUTIFY = "beautify"  # multi-line, indented
+    MINIFIED = "minified"  # condensed separators (no spaces)
+
+
+def _strip_code_fence(text: str) -> str:
+    s = text.strip()
+    if not s.startswith("```"):
+        return s
+    # Opening fence line can be ```json / ```js etc; drop it.
+    nl = s.find("\n")
+    if nl == -1:
+        return s.strip("`").strip()
+    body = s[nl + 1 :]
+    end = body.rfind("```")
+    if end != -1:
+        body = body[:end]
+    return body.strip()
+
+
+def _jsonify(value: Any) -> Any:
+    """Convert a value into JSON-serializable types (best-effort)."""
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+    if isinstance(value, dict):
+        return {str(k): _jsonify(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_jsonify(v) for v in value]
+    if isinstance(value, tuple):
+        return [_jsonify(v) for v in value]
+    return str(value)
+
+
+def _parse_jsonish_maybe(text: str) -> Optional[Any]:
+    """Best-effort parse of JSON-ish strings.
+
+    Accepts:
+    - strict JSON
+    - JSON embedded in a larger string (extract first object/array substring)
+    - Python-literal dict/list (common LLM output), via ast.literal_eval
+    """
+    s = _strip_code_fence(text)
+    if not s:
+        return None
+    s = s.strip()
+    if not s:
+        return None
+
+    try:
+        return json.loads(s)
+    except Exception:
+        pass
+
+    # Best-effort: parse the first JSON object/array substring.
+    decoder = json.JSONDecoder()
+    starts: list[int] = []
+    for i, ch in enumerate(s):
+        if ch in "{[":
+            starts.append(i)
+        if len(starts) >= 64:
+            break
+    for i in starts:
+        try:
+            parsed, _end = decoder.raw_decode(s[i:])
+            return parsed
+        except Exception:
+            continue
+
+    # Last resort: tolerate Python-literal dict/list output.
+    try:
+        return ast.literal_eval(s)
+    except Exception:
+        return None
+
+
+def stringify_json(
+    value: Any,
+    *,
+    mode: str | JsonStringifyMode = JsonStringifyMode.BEAUTIFY,
+    beautify_indent: int = 2,
+    sort_keys: bool = False,
+    parse_strings: bool = True,
+) -> str:
+    """Render a JSON-like value into a string.
+
+    Args:
+        value: Any JSON-like value (dict/list/scalar). If `parse_strings=True`, a string
+            that contains JSON (or JSON-ish text) is parsed and then rendered.
+        mode: none | beautify | minified.
+        beautify_indent: Indentation width for beautify mode.
+        sort_keys: When true, sort object keys for deterministic output.
+        parse_strings: When true, attempt to parse JSON-ish strings before rendering.
+    """
+    mode_value = mode.value if isinstance(mode, JsonStringifyMode) else str(mode or "").strip().lower()
+    if mode_value not in {m.value for m in JsonStringifyMode}:
+        mode_value = JsonStringifyMode.BEAUTIFY.value
+
+    if parse_strings and isinstance(value, str) and value.strip():
+        parsed = _parse_jsonish_maybe(value)
+        if parsed is not None:
+            value = parsed
+
+    safe = _jsonify(value)
+
+    if mode_value == JsonStringifyMode.MINIFIED.value:
+        return json.dumps(safe, ensure_ascii=False, sort_keys=sort_keys, separators=(",", ":"))
+
+    if mode_value == JsonStringifyMode.NONE.value:
+        return json.dumps(safe, ensure_ascii=False, sort_keys=sort_keys)
+
+    indent = beautify_indent if isinstance(beautify_indent, int) else 2
+    if indent < 0:
+        indent = 2
+    return json.dumps(safe, ensure_ascii=False, sort_keys=sort_keys, indent=indent)
+
+

abstractruntime/scheduler/scheduler.py

@@ -19,6 +19,7 @@ from typing import Any, Callable, Dict, List, Optional
 
 from ..core.models import RunState, RunStatus, WaitReason, WaitState
 from ..core.runtime import Runtime
+from ..core.event_keys import build_event_wait_key
 from ..storage.base import QueryableRunStore
 from .registry import WorkflowRegistry
 
@@ -30,6 +31,18 @@ def utc_now_iso() -> str:
     return datetime.now(timezone.utc).isoformat()
 
 
+def _is_paused(vars: Any) -> bool:
+    if not isinstance(vars, dict):
+        return False
+    runtime_ns = vars.get("_runtime")
+    if not isinstance(runtime_ns, dict):
+        return False
+    control = runtime_ns.get("control")
+    if not isinstance(control, dict):
+        return False
+    return bool(control.get("paused") is True)
+
+
 @dataclass
 class SchedulerStats:
     """Statistics about scheduler operation."""
@@ -218,6 +231,76 @@ class Scheduler:
             payload=payload,
         )
 
+    def emit_event(
+        self,
+        *,
+        name: str,
+        payload: Dict[str, Any],
+        scope: str = "session",
+        session_id: Optional[str] = None,
+        workflow_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        max_steps: int = 100,
+        limit: int = 10_000,
+    ) -> List[RunState]:
+        """Emit an event and resume all matching WAIT_EVENT runs.
+
+        This is the host-facing API for external signals (Temporal-style).
+
+        Default scope is "session" (workflow instance). For session scope, you must
+        provide `session_id` (typically the root run_id for that instance).
+        """
+        name2 = str(name or "").strip()
+        if not name2:
+            raise ValueError("emit_event requires a non-empty name")
+
+        scope2 = str(scope or "session").strip().lower() or "session"
+
+        wait_key = build_event_wait_key(
+            scope=scope2,
+            name=name2,
+            session_id=session_id,
+            workflow_id=workflow_id,
+            run_id=run_id,
+        )
+
+        # Find runs waiting for this event key.
+        waiting_runs = self._run_store.list_runs(
+            status=RunStatus.WAITING,
+            wait_reason=WaitReason.EVENT,
+            limit=limit,
+        )
+
+        resumed: List[RunState] = []
+        envelope: Dict[str, Any] = {
+            "event_id": None,
+            "name": name2,
+            "scope": scope2,
+            "session_id": session_id,
+            "payload": dict(payload) if isinstance(payload, dict) else {"value": payload},
+            "emitted_at": utc_now_iso(),
+            "emitter": {"source": "external"},
+        }
+
+        for r in waiting_runs:
+            if _is_paused(getattr(r, "vars", None)):
+                continue
+            if r.waiting is None:
+                continue
+            if r.waiting.wait_key != wait_key:
+                continue
+            wf = self._registry.get_or_raise(r.workflow_id)
+            new_state = self._runtime.resume(
+                workflow=wf,
+                run_id=r.run_id,
+                wait_key=wait_key,
+                payload=envelope,
+                max_steps=max_steps,
+            )
+            resumed.append(new_state)
+
+        return resumed
+
     def find_waiting_runs(
         self,
         *,
@@ -289,11 +372,17 @@ class Scheduler:
 
         resumed_count = 0
         for run in due_runs:
+            if _is_paused(getattr(run, "vars", None)):
+                continue
+            # Record resumption immediately to avoid a race where the run completes
+            # (via runtime.tick) before the main thread observes updated stats.
+            self._stats.runs_resumed += 1
+            resumed_count += 1
             try:
                 self._resume_wait_until(run)
-                resumed_count += 1
-                self._stats.runs_resumed += 1
             except Exception as e:
+                self._stats.runs_resumed -= 1
+                resumed_count -= 1
                 logger.error("Failed to resume run %s: %s", run.run_id, e)
                 self._stats.runs_failed += 1
                 self._record_error(f"Run {run.run_id}: {e}")
@@ -368,6 +457,8 @@ class Scheduler:
         )
 
         for run in waiting_runs:
+            if _is_paused(getattr(run, "vars", None)):
+                continue
             if run.waiting is None:
                 continue
             if run.waiting.reason != WaitReason.SUBWORKFLOW:

abstractruntime/storage/__init__.py

@@ -4,6 +4,7 @@ from .base import RunStore, LedgerStore, QueryableRunStore
 from .in_memory import InMemoryRunStore, InMemoryLedgerStore
 from .json_files import JsonFileRunStore, JsonlLedgerStore
 from .ledger_chain import HashChainedLedgerStore, verify_ledger_chain
+from .observable import ObservableLedgerStore, ObservableLedgerStoreProtocol
 from .snapshots import Snapshot, SnapshotStore, InMemorySnapshotStore, JsonSnapshotStore
 
 __all__ = [
@@ -16,10 +17,11 @@ __all__ = [
     "JsonlLedgerStore",
     "HashChainedLedgerStore",
     "verify_ledger_chain",
+    "ObservableLedgerStore",
+    "ObservableLedgerStoreProtocol",
     "Snapshot",
     "SnapshotStore",
     "InMemorySnapshotStore",
     "JsonSnapshotStore",
 ]
 
-

abstractruntime/storage/artifacts.py

@@ -86,9 +86,24 @@ class Artifact:
         return json.loads(self.content.decode("utf-8"))
 
 
-def compute_artifact_id(content: bytes) -> str:
-    """Compute content-addressed artifact ID using SHA-256."""
-    return hashlib.sha256(content).hexdigest()[:32]
+def compute_artifact_id(content: bytes, *, run_id: Optional[str] = None) -> str:
+    """Compute a deterministic artifact id.
+
+    By default, artifacts are content-addressed (SHA-256, truncated) so the same bytes
+    produce the same id.
+
+    If `run_id` is provided, the id is *namespaced to that run* to avoid cross-run
+    collisions when using a shared `FileArtifactStore(base_dir)` and to preserve
+    correct `list_by_run(...)` / purge-by-run semantics.
+    """
+    h = hashlib.sha256()
+    if run_id is not None:
+        rid = str(run_id).strip()
+        if rid:
+            h.update(rid.encode("utf-8"))
+            h.update(b"\0")
+    h.update(content)
+    return h.hexdigest()[:32]
 
 
 def validate_artifact_id(artifact_id: str) -> None:
@@ -318,7 +333,7 @@ class InMemoryArtifactStore(ArtifactStore):
         artifact_id: Optional[str] = None,
     ) -> ArtifactMetadata:
         if artifact_id is None:
-            artifact_id = compute_artifact_id(content)
+            artifact_id = compute_artifact_id(content, run_id=run_id)
 
         metadata = ArtifactMetadata(
             artifact_id=artifact_id,
@@ -397,7 +412,7 @@ class FileArtifactStore(ArtifactStore):
         artifact_id: Optional[str] = None,
     ) -> ArtifactMetadata:
         if artifact_id is None:
-            artifact_id = compute_artifact_id(content)
+            artifact_id = compute_artifact_id(content, run_id=run_id)
 
         metadata = ArtifactMetadata(
             artifact_id=artifact_id,

abstractruntime/storage/json_files.py

@@ -10,6 +10,7 @@ This is meant as a straightforward MVP backend.
 from __future__ import annotations
 
 import json
+import uuid
 from dataclasses import asdict
 from pathlib import Path
 from typing import Any, Dict, List, Optional
@@ -36,8 +37,20 @@ class JsonFileRunStore(RunStore):
 
     def save(self, run: RunState) -> None:
         p = self._path(run.run_id)
-        with p.open("w", encoding="utf-8") as f:
-            json.dump(asdict(run), f, ensure_ascii=False, indent=2)
+        # Atomic write to prevent corrupted/partial JSON when multiple threads/processes
+        # (e.g. WS tick loop + UI pause/cancel) write the same run file concurrently.
+        tmp = p.with_name(f"{p.name}.{uuid.uuid4().hex}.tmp")
+        try:
+            with tmp.open("w", encoding="utf-8") as f:
+                json.dump(asdict(run), f, ensure_ascii=False, indent=2)
+            tmp.replace(p)
+        finally:
+            # Best-effort cleanup if replace() failed.
+            try:
+                if tmp.exists():
+                    tmp.unlink()
+            except Exception:
+                pass
 
     def load(self, run_id: str) -> Optional[RunState]:
         p = self._path(run_id)