@team-agent/installer 0.2.2 → 0.2.4

package/src/team_agent/provider_state/claude.py

@@ -0,0 +1,86 @@
+"""Claude transcript reader — the ONLY Claude-specific turn-state knowledge.
+
+Translates Claude transcript JSONL records into normalized lifecycle facts.
+Real markers (see turn-state-markers-evidence.md):
+  - assistant message.stop_reason == "tool_use"   -> open turn (working)
+  - assistant message.stop_reason == "end_turn"    -> turn complete (idle)
+  - user text == "[Request interrupted by user]"   -> interrupted
+  - user tool_result is_error == true              -> structured tool error
+  - system subtype == "api_error" and level=="error" -> provider api error
+Trailing metadata records (stop_hook_summary / turn_duration / last-prompt /
+ai-title / permission-mode / ...) are ignored for the turn verdict.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from team_agent.provider_state import common
+
+_INTERRUPT_TEXT = "[Request interrupted by user]"
+
+
+def extract_facts(records: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    facts: list[dict[str, Any]] = []
+    diagnostics: list[dict[str, Any]] = []
+    for record in records:
+        rtype = record.get("type")
+        message = record.get("message")
+        if rtype == "assistant" and isinstance(message, dict):
+            stop_reason = message.get("stop_reason")
+            turn_id = record.get("requestId") or record.get("uuid")
+            if stop_reason == "end_turn":
+                facts.append({"kind": common.TURN_COMPLETE, "turn_id": turn_id, "reason": "end_turn"})
+            elif stop_reason == "tool_use":
+                facts.append({"kind": common.TURN_OPEN, "turn_id": turn_id, "reason": "tool_use"})
+            elif stop_reason == "stop_sequence":
+                facts.append({"kind": common.TURN_COMPLETE, "turn_id": turn_id, "reason": "stop_sequence"})
+            # other/missing stop_reason on assistant is treated as an open turn fragment
+            elif stop_reason is None and isinstance(message.get("content"), list):
+                facts.append({"kind": common.TURN_OPEN, "turn_id": turn_id, "reason": "assistant_in_flight"})
+        elif rtype == "user" and isinstance(message, dict):
+            content = message.get("content")
+            if _content_has_interrupt(content):
+                facts.append({"kind": common.INTERRUPTED, "turn_id": record.get("uuid"), "reason": "user_interrupt"})
+            elif _content_has_tool_error(content):
+                facts.append({
+                    "kind": common.ERROR,
+                    # the turn being retried/affected, stable across records (C8 dedup)
+                    "turn_id": record.get("parentUuid") or record.get("uuid"),
+                    "reason": "tool_result_is_error",
+                    "signature": "tool_result_is_error",
+                    "raw": record,
+                })
+        elif rtype == "system" and record.get("subtype") == "api_error" and record.get("level") == "error":
+            facts.append({
+                "kind": common.ERROR,
+                # api_error retries within a session dedup on (signature, session) (C8)
+                "turn_id": record.get("sessionId") or record.get("parentUuid") or record.get("uuid"),
+                "reason": "api_error",
+                "signature": "api_error",
+                "raw": record,
+            })
+        # everything else (metadata, snapshots, titles) is ignored for the verdict
+    return facts, diagnostics
+
+
+def classify(session_log_text: str, *, process: Any = None) -> dict[str, Any]:
+    return common.classify_with_reader(extract_facts, session_log_text, process=process)
+
+
+def _content_has_interrupt(content: Any) -> bool:
+    if not isinstance(content, list):
+        return False
+    for item in content:
+        if isinstance(item, dict) and item.get("type") == "text" and item.get("text") == _INTERRUPT_TEXT:
+            return True
+    return False
+
+
+def _content_has_tool_error(content: Any) -> bool:
+    if not isinstance(content, list):
+        return False
+    for item in content:
+        if isinstance(item, dict) and item.get("type") == "tool_result" and item.get("is_error") is True:
+            return True
+    return False

package/src/team_agent/provider_state/codex.py

@@ -0,0 +1,84 @@
+"""Codex rollout reader — the ONLY Codex-specific turn-state knowledge.
+
+Translates Codex rollout JSONL (and app-server jsonrpc) records into normalized
+lifecycle facts. Real markers (see turn-state-markers-evidence.md):
+  - event_msg payload.type == "task_started"   -> open turn (working)
+  - event_msg payload.type == "task_complete"  -> turn complete (idle)
+  - event_msg payload.type == "turn_aborted" reason=="interrupted" -> interrupted
+App-server schema-derived markers:
+  - method "turn/completed" params.turn.status == "failed" -> failed/error
+  - method ".../requestApproval"                            -> approval block
+Telemetry (token_count, agent_message, patch_apply_end, ...) is not a close.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from team_agent.provider_state import common
+
+
+def extract_facts(records: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    facts: list[dict[str, Any]] = []
+    diagnostics: list[dict[str, Any]] = []
+    for record in records:
+        rtype = record.get("type")
+        payload = record.get("payload") if isinstance(record.get("payload"), dict) else None
+        if rtype == "event_msg" and payload is not None:
+            ptype = payload.get("type")
+            turn_id = payload.get("turn_id")
+            if ptype == "task_started":
+                facts.append({"kind": common.TURN_OPEN, "turn_id": turn_id, "reason": "task_started"})
+            elif ptype == "task_complete":
+                facts.append({"kind": common.TURN_COMPLETE, "turn_id": turn_id, "reason": "task_complete"})
+            elif ptype == "turn_aborted" and payload.get("reason") == "interrupted":
+                facts.append({"kind": common.INTERRUPTED, "turn_id": turn_id, "reason": "interrupted"})
+            elif ptype == "turn_aborted":
+                facts.append({"kind": common.INTERRUPTED, "turn_id": turn_id, "reason": str(payload.get("reason") or "aborted")})
+        elif _is_app_server(record):
+            fact = _app_server_fact(record)
+            if fact is not None:
+                facts.append(fact)
+        # response_item (assistant/user messages), token_count, etc. are not verdicts
+    return facts, diagnostics
+
+
+def classify(session_log_text: str, *, process: Any = None) -> dict[str, Any]:
+    return common.classify_with_reader(extract_facts, session_log_text, process=process)
+
+
+def _is_app_server(record: dict[str, Any]) -> bool:
+    return record.get("jsonrpc") == "2.0" and isinstance(record.get("method"), str)
+
+
+def _app_server_fact(record: dict[str, Any]) -> dict[str, Any] | None:
+    method = str(record.get("method") or "")
+    params = record.get("params") if isinstance(record.get("params"), dict) else {}
+    if method == "turn/completed":
+        turn = params.get("turn") if isinstance(params.get("turn"), dict) else {}
+        status = turn.get("status")
+        turn_id = turn.get("id")
+        if status == "failed":
+            return {
+                "kind": common.FAILED,
+                "turn_id": turn_id,
+                "reason": "turn_failed",
+                "signature": "turn_failed",
+                "raw": record,
+            }
+        if status == "completed":
+            return {"kind": common.TURN_COMPLETE, "turn_id": turn_id, "reason": "completed"}
+        if status == "interrupted":
+            return {"kind": common.INTERRUPTED, "turn_id": turn_id, "reason": "interrupted"}
+        if status == "inProgress":
+            return {"kind": common.TURN_OPEN, "turn_id": turn_id, "reason": "in_progress"}
+        return None
+    if method.endswith("requestApproval"):
+        return {
+            "kind": common.APPROVAL,
+            "turn_id": params.get("turnId") or params.get("turn_id"),
+            "reason": "approval_required",
+            "signature": "approval_required",
+            "raw": record,
+        }
+    return None

package/src/team_agent/provider_state/common.py

@@ -0,0 +1,207 @@
+"""Shared, provider-neutral plumbing for the turn-state readers.
+
+The per-provider readers (claude.py, codex.py) only translate their own record
+shapes into a normalized list of lifecycle facts; everything else — JSONL
+tail parsing, metadata filtering wiring, the verdict decision, and the
+process-identity liveness guard — lives here so it is written once.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable
+
+# Normalized lifecycle fact kinds emitted by every reader.
+TURN_OPEN = "turn_open"
+TURN_COMPLETE = "turn_complete"
+INTERRUPTED = "interrupted"
+FAILED = "failed"
+APPROVAL = "approval"
+ERROR = "error"  # non-closing structured error (e.g. transient api retry / tool is_error)
+
+_CLOSING = {TURN_COMPLETE, INTERRUPTED, FAILED}
+
+
+def parse_jsonl(text: str) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Parse JSONL text into (records, parse_diagnostics).
+
+    Lines that are blank are skipped. Lines that are not valid JSON objects are
+    collected as diagnostics rather than raising — the caller decides whether a
+    populated diagnostics list with zero usable records means ``unknown``.
+    """
+    records: list[dict[str, Any]] = []
+    diagnostics: list[dict[str, Any]] = []
+    for lineno, raw in enumerate(text.splitlines(), start=1):
+        line = raw.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except (ValueError, TypeError):
+            diagnostics.append({"kind": "json_decode_error", "line": lineno})
+            continue
+        if not isinstance(obj, dict):
+            diagnostics.append({"kind": "non_object_record", "line": lineno})
+            continue
+        records.append(obj)
+    return records, diagnostics
+
+
+def decide_state(
+    facts: list[dict[str, Any]],
+    *,
+    process: Any = None,
+    parse_diagnostics: list[dict[str, Any]] | None = None,
+    had_records: bool,
+    extra_diagnostics: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    """Turn a normalized fact stream into the public classify result.
+
+    Verdict = the LAST lifecycle fact, not the last physical record. An open
+    turn (a ``turn_open`` not yet closed) is a positive "still working" fact
+    that survives arbitrary file silence (Gap 32 C14); the only thing that can
+    demote it is a failed process-identity guard (Gap 32 C4).
+    """
+    diagnostics = list(parse_diagnostics or []) + list(extra_diagnostics or [])
+
+    lifecycle = [f for f in facts if f.get("kind") in (_CLOSING | {TURN_OPEN, APPROVAL})]
+    if not lifecycle:
+        # No turn-lifecycle fact at all. If the input was unreadable/empty or a
+        # changed format with no recognizable records, fail safe to unknown (C5).
+        reason = "no_turn_lifecycle_fact"
+        if not had_records:
+            reason = "unreadable_or_empty"
+        elif diagnostics:
+            reason = "unrecognized_format"
+        return _result("unknown", None, reason, "session_file", [], diagnostics)
+
+    last = lifecycle[-1]
+    kind = last.get("kind")
+    turn_id = last.get("turn_id")
+    reason = str(last.get("reason") or kind)
+
+    if kind == TURN_COMPLETE:
+        return _result("idle", turn_id, reason or "turn_complete", "session_file", [], diagnostics)
+    if kind == INTERRUPTED:
+        return _result("idle_interrupted", turn_id, reason or "interrupted", "session_file", ["interrupted"], diagnostics)
+    if kind == FAILED:
+        return _result("abnormal", turn_id, reason or "turn_failed", "session_file", ["turn_failed"], diagnostics)
+    if kind == APPROVAL:
+        return _result("blocked_on_human", turn_id, reason or "approval_required", "session_file", ["awaiting_approval"], diagnostics)
+
+    # kind == TURN_OPEN with no later close → open turn. To declare "working" we
+    # must POSITIVELY confirm the recorded process is still alive (C4 fail-safe);
+    # missing/partial identity cannot be optimistically read as working.
+    verdict, live_reason, live_diag = process_liveness(process)
+    if live_diag:
+        diagnostics = diagnostics + [live_diag]
+    if verdict == "alive":
+        return _result("working", turn_id, "open_turn", "session_file", [], diagnostics)
+    if verdict == "dead":
+        return _result("abnormal", turn_id, "crashed_mid_turn", "process_guard", ["crashed_mid_turn", live_reason], diagnostics)
+    # unverifiable: cannot confirm alive → fail safe to unknown, never working.
+    return _result("unknown", turn_id, "process_identity_unverified", "process_guard", ["process_identity_unverified", live_reason], diagnostics)
+
+
+_STRONG_IDENTITY_FIELDS = ("start_time", "cmdline", "create_time")
+
+
+def process_liveness(process: Any) -> tuple[str, str, dict[str, Any] | None]:
+    """Process-identity liveness guard (Gap 32 C4) — three-valued.
+
+    Returns (verdict, reason, diagnostic) where verdict is one of:
+      - ``"alive"``        — positively confirmed the same process is running
+      - ``"dead"``         — confirmed replaced/exited (identity mismatch or flag)
+      - ``"unverifiable"`` — identity missing/partial; CANNOT be read as working
+
+    Identity, not bare PID: aliveness must be affirmatively confirmed by a strong
+    identity field (start_time / cmdline / create_time) present and equal in BOTH
+    the recorded and the current snapshot. Missing/partial info is fail-safe
+    unverifiable, never optimistically "alive".
+
+    Accepted ``process`` shapes (any one):
+      - None / non-dict                      → unverifiable
+      - {"alive"|"running": bool}            → explicit
+      - {"identity_match": bool}             → explicit identity verdict
+      - {"expected"|"recorded": {...}, "current"|"observed": {...}}
+    """
+    if process is None or not isinstance(process, dict):
+        return "unverifiable", "process_identity_missing", {"kind": "process_identity_unverified"}
+    if process.get("alive") is False or process.get("running") is False:
+        return "dead", "process_not_running", {"kind": "process_dead", "detail": "not_running"}
+    if process.get("identity_match") is False:
+        return "dead", "process_identity_mismatch", {"kind": "process_identity_mismatch"}
+    if process.get("alive") is True or process.get("running") is True or process.get("identity_match") is True:
+        return "alive", "process_alive", None
+    recorded = process.get("recorded") if isinstance(process.get("recorded"), dict) else process.get("expected")
+    current = process.get("current") if isinstance(process.get("current"), dict) else process.get("observed")
+    if not (isinstance(recorded, dict) and isinstance(current, dict)):
+        return "unverifiable", "process_identity_partial", {"kind": "process_identity_unverified"}
+    if current.get("alive") is False or current.get("running") is False:
+        return "dead", "process_not_running", {"kind": "process_dead", "detail": "current_not_running"}
+    # Any shared strong identity field that DIFFERS = confirmed replacement.
+    for key in _STRONG_IDENTITY_FIELDS:
+        if key in recorded and key in current and recorded.get(key) != current.get(key):
+            return "dead", f"process_identity_mismatch:{key}", {
+                "kind": "process_identity_mismatch",
+                "field": key,
+                "recorded": recorded.get(key),
+                "current": current.get(key),
+            }
+    # Require at least one strong identity field present+equal in BOTH, with no
+    # recorded strong field missing from current (else we cannot confirm).
+    recorded_strong = [k for k in _STRONG_IDENTITY_FIELDS if k in recorded]
+    confirmed = [k for k in recorded_strong if k in current and recorded.get(k) == current.get(k)]
+    missing = [k for k in recorded_strong if k not in current]
+    if confirmed and not missing:
+        return "alive", "process_identity_match", None
+    return "unverifiable", "process_identity_partial", {
+        "kind": "process_identity_unverified",
+        "recorded_strong": recorded_strong,
+        "confirmed": confirmed,
+        "missing": missing,
+    }
+
+
+def process_is_live(process: Any) -> tuple[bool, str, dict[str, Any] | None]:
+    """Boolean wrapper used by conservative callers (e.g. whole-team-gone): a
+    process is treated as live unless it is CONFIRMED dead. Unverifiable counts
+    as live here so we never falsely declare the team gone."""
+    verdict, reason, diag = process_liveness(process)
+    return (verdict != "dead"), reason, diag
+
+
+def _result(
+    state: str,
+    turn_id: str | None,
+    reason: str,
+    source: str,
+    annotations: list[str],
+    diagnostics: list[dict[str, Any]],
+) -> dict[str, Any]:
+    return {
+        "state": state,
+        "turn_id": turn_id,
+        "reason": reason,
+        "source": source,
+        "annotations": list(annotations),
+        "diagnostics": list(diagnostics),
+    }
+
+
+def classify_with_reader(
+    extract_facts: Callable[[list[dict[str, Any]]], tuple[list[dict[str, Any]], list[dict[str, Any]]]],
+    session_log_text: str,
+    *,
+    process: Any = None,
+) -> dict[str, Any]:
+    """Run a provider reader's fact extractor through the shared pipeline."""
+    records, parse_diag = parse_jsonl(session_log_text or "")
+    facts, extra_diag = extract_facts(records)
+    return decide_state(
+        facts,
+        process=process,
+        parse_diagnostics=parse_diag,
+        had_records=bool(records),
+        extra_diagnostics=extra_diag,
+    )

package/src/team_agent/provider_state/registry.py

@@ -0,0 +1,118 @@
+"""Per-CLI idle/turn-state registry — PURE INFRA DATA (Gap 32 C7).
+
+This module is data only: session-file locations, turn-lifecycle marker
+descriptions, and per-CLI error white/black lists. It carries no predicate,
+abnormal, or wake logic. Adding a new provider is one entry here plus one
+reader module under ``provider_state/``; the neutral layers never change.
+
+The registry is shipped with the runtime as infra data — it is NOT
+user-mandatory configuration and is never loaded from a workspace.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Each entry is consumed by the matching provider reader. The neutral
+# idle_predicate / abnormal_track / wake modules never read provider names.
+_PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
+    "claude": {
+        "kind": "claude",
+        "reader_module": "team_agent.provider_state.claude",
+        "source": "infra",
+        "file_location": {
+            "root": "~/.claude/projects",
+            "layout": "<cwd-slug>/<session_id>.jsonl",
+            "format": "transcript-jsonl",
+        },
+        "event_types": {
+            "turn_open": "assistant message.stop_reason == tool_use",
+            "turn_complete": "assistant message.stop_reason == end_turn",
+            "interrupted": "user text == [Request interrupted by user]",
+            "tool_error": "user tool_result is_error == true",
+            "api_error": "system subtype == api_error and level == error",
+        },
+        "metadata_ignore": [
+            "stop_hook_summary",
+            "turn_duration",
+            "last-prompt",
+            "ai-title",
+            "permission-mode",
+            "file-history-snapshot",
+            "queue-operation",
+        ],
+        "error_whitelist": [],
+        "error_blacklist": [
+            "api_error",
+            "rate limit",
+            "overloaded",
+            "traceback",
+            "panic",
+        ],
+        "error_lists": {
+            "whitelist": [],
+            "blacklist": ["api_error", "rate limit", "overloaded", "traceback", "panic"],
+        },
+    },
+    "codex": {
+        "kind": "codex",
+        "reader_module": "team_agent.provider_state.codex",
+        "source": "infra",
+        "file_location": {
+            "root": "~/.codex/sessions",
+            "layout": "<YYYY>/<MM>/<DD>/rollout-<stamp>-<session_id>.jsonl",
+            "format": "rollout-jsonl",
+        },
+        "event_types": {
+            "turn_open": "event_msg payload.type == task_started",
+            "turn_complete": "event_msg payload.type == task_complete",
+            "interrupted": "event_msg payload.type == turn_aborted and reason == interrupted",
+            "failed": "app-server turn.status == failed",
+            "approval": "app-server method endswith requestApproval",
+        },
+        "metadata_ignore": [
+            "token_count",
+            "agent_message",
+            "context_compacted",
+            "mcp_tool_call_end",
+            "patch_apply_end",
+            "web_search_end",
+            "thread_goal_updated",
+        ],
+        "error_whitelist": [],
+        "error_blacklist": [
+            "failed",
+            "api error",
+            "rate limit",
+            "overloaded",
+            "traceback",
+            "panic",
+        ],
+        "error_lists": {
+            "whitelist": [],
+            "blacklist": ["failed", "api error", "rate limit", "overloaded", "traceback", "panic"],
+        },
+    },
+}
+
+
+def get_provider_registry(provider: str | None = None) -> Any:
+    """Return the infra registry.
+
+    With no argument, returns a copy of the whole per-CLI registry mapping.
+    With a provider name, returns that provider's entry (or ``None``).
+    """
+    if provider is None:
+        return {name: _copy_entry(entry) for name, entry in _PROVIDER_REGISTRY.items()}
+    entry = _PROVIDER_REGISTRY.get(provider)
+    return _copy_entry(entry) if entry is not None else None
+
+
+def supported_providers() -> list[str]:
+    return sorted(_PROVIDER_REGISTRY)
+
+
+def _copy_entry(entry: dict[str, Any]) -> dict[str, Any]:
+    import copy
+
+    return copy.deepcopy(entry)