ccx-native 0.0.1 → 0.1.0

package/ccx/claude/external.py

@@ -0,0 +1,253 @@
+"""Read-only exact native Claude session evidence for controlled CCX import.
+
+A native SID is not a CCX worker target. Only the exact canonical original
+session ID may be inspected for one owner-proven import. No external session
+discovery, cache materialization, daemon control, reply or native-bg adoption.
+"""
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+
+from ccx.system import oslayer
+from ccx.constants import CLAUDE_HOME
+from ccx.store.paths import transcript_path_for
+from ccx.claude.transcript import pending_ask_user_question
+
+
+WAIT_NONE = "none"
+
+
+WAIT_QUESTION = "question"
+
+
+WAIT_PERMISSION = "permission"
+
+
+WAIT_SHELL = "shell"
+
+
+WAIT_UNKNOWN = "unknown"
+
+
+_BACKGROUND_KINDS = {"daemon", "daemon-worker", "bg", "background"}
+
+
+def short_from_id(identifier: str) -> str:
+    return identifier.split("-", 1)[0][:8]
+
+
+def _job_state(short: str) -> dict | None:
+    try:
+        return json.loads((CLAUDE_HOME / "jobs" / short / "state.json").read_text())
+    except (OSError, ValueError):
+        return None
+
+
+def _session_files(identifier: str) -> list[dict]:
+    root = CLAUDE_HOME / "sessions"
+    if not root.exists():
+        return []
+    out = []
+    for p in root.glob("*.json"):
+        try:
+            meta = json.loads(p.read_text())
+        except (OSError, ValueError):
+            continue
+        sid = meta.get("sessionId")
+        if sid == identifier:
+            out.append(meta)
+    return out
+
+
+def exact_import_candidate(session_id: str) -> dict:
+    """Read ONLY an exact native Claude SID's provider-owned import facts."""
+    import stat
+    from uuid import UUID
+    from ccx.errors import InvalidRequest, SessionNotFound, SessionUnavailable
+
+    try:
+        if str(UUID(session_id)) != session_id:
+            raise ValueError("noncanonical")
+    except (ValueError, TypeError, AttributeError) as exc:
+        raise InvalidRequest("import needs the exact canonical native Claude sessionId") from exc
+    # Never resolve prefixes/names or materialize a cached external CCX record.
+    found = sorted((CLAUDE_HOME / "projects").glob(f"*/{session_id}.jsonl"))
+    if not found:
+        raise SessionNotFound("native Claude session transcript not found: " + session_id)
+    if len(found) != 1:
+        raise SessionUnavailable("ambiguous exact native Claude transcript locations: "
+                                 + session_id)
+    path = found[0]
+    try:
+        st = path.lstat()
+        if not stat.S_ISREG(st.st_mode) or st.st_size <= 0:
+            raise SessionUnavailable("native Claude transcript is missing or empty")
+    except OSError as exc:
+        raise SessionUnavailable("native Claude transcript is unavailable") from exc
+
+    meta = _session_files(session_id)
+    live = []
+    # PID-keyed metadata survives process exit/reuse. Establish presence from
+    # the kernel, not argv: unreadable argv must never turn a live original
+    # into an apparently stopped import candidate.
+    for entry in meta:
+        pid = entry.get("pid")
+        if type(pid) is not int or pid <= 0:
+            continue  # no process to claim from this metadata row
+        observed = oslayer.process_info(pid)
+        if observed.presence == "dead":
+            continue  # stopped originals keep their existing import policy
+        start = entry.get("procStart")
+        if (observed.presence != "alive"
+                or not oslayer.provider_start_matches(
+                    start, observed.start_token, entry.get("pidDomain"))):
+            raise SessionUnavailable(
+                "live native Claude original PID/procStart identity unproven"
+            )
+        live.append(entry)
+    if len(live) > 1:
+        raise SessionUnavailable("more than one live native Claude process names session")
+    info = (live[0] if live else meta[0] if meta else {})
+    if len(meta) > 1 and not live and any(
+            (m.get("cwd"), m.get("kind")) !=
+            (info.get("cwd"), info.get("kind")) for m in meta):
+        raise SessionUnavailable("contradictory exact native Claude session metadata")
+    original_cwd = _cwd_from_transcript(path)
+    claimed_cwd = info.get("cwd")
+    if original_cwd and claimed_cwd and os.path.realpath(original_cwd) != os.path.realpath(claimed_cwd):
+        raise SessionUnavailable("native Claude transcript and session metadata cwd disagree")
+    cwd = claimed_cwd or original_cwd
+    if not isinstance(cwd, str) or not cwd or not os.path.isdir(cwd):
+        raise SessionUnavailable("native Claude source cwd is unavailable")
+    cwd = os.path.realpath(cwd)
+    if path != transcript_path_for(cwd, session_id):
+        raise SessionUnavailable("exact native Claude transcript does not match canonical cwd/project")
+    short = short_from_id(session_id)
+    job = _job_state(short)
+    if isinstance(job, dict) and job.get("sessionId") is None:
+        raise SessionUnavailable("native-bg job short collision has no exact session identity")
+    background = (isinstance(job, dict) and job.get("sessionId") == session_id
+                  or info.get("kind") in _BACKGROUND_KINDS)
+    return {
+        "sessionId": session_id,
+        "short": short,
+        "cwd": cwd,
+        "transcript": str(path),
+        "name": info.get("name"),
+        "live": bool(live),
+        "status": info.get("status") if live else None,
+        "waitKind": _wait_kind(bool(live), info.get("status"), info.get("waitingFor")),
+        "backgroundAgent": background,
+    }
+
+
+def _cwd_from_transcript(path: pathlib.Path) -> str | None:
+    try:
+        with path.open() as f:
+            for line in f:
+                try:
+                    evt = json.loads(line)
+                except ValueError:
+                    continue
+                cwd = evt.get("cwd")
+                if cwd:
+                    return cwd
+    except OSError:
+        return None
+    return None
+
+
+def _wait_kind(live: bool, status: str | None, waiting_for: str | None) -> str:
+    if not live:
+        return WAIT_NONE
+    if waiting_for == "permission prompt":
+        return WAIT_PERMISSION
+    if waiting_for == "dialog open":
+        return WAIT_QUESTION
+    if status == "shell" or waiting_for == "sandbox request":
+        return WAIT_SHELL
+    if waiting_for in ("worker request", "input needed"):
+        return WAIT_UNKNOWN
+    return WAIT_NONE
+
+
+def import_eligibility(rec: dict) -> tuple[bool, str, str]:
+    """Can this exact native Claude session be imported under CCX management?
+
+    Product rule: a regular external Claude session may be imported when it is
+    **idle** — including a *live* idle one — or when it is stopped/not-live with
+    a transcript at rest. Everything non-idle refuses: busy, any wait
+    (permission/question/shell/unknown), native-bg, missing transcript, missing cwd.
+
+    Note: importing a live-idle session is an *active resume*, not a passive
+    attach — the original terminal must not be used afterward (the caller warns
+    about this). ccx deliberately does not require closing the old terminal."""
+    short = rec.get("short") or short_from_id(rec.get("sessionId") or "?")
+    status = rec.get("status")
+    live = bool(rec.get("live"))
+    wait_kind = rec.get("waitKind") or WAIT_NONE
+    cwd = rec.get("cwd") or ""
+
+    if rec.get("backgroundAgent"):
+        return False, "native-bg", (
+            f"session {short} is a native Claude background agent; native-bg "
+            "import is not supported. Inspect or manage that job through "
+            "Claude's own interface; CCX cannot control or import it"
+        )
+    # Live, non-idle states first — the common, most-actionable "wait and retry"
+    # refusals. Only an *idle* live session (and a stopped one) is importable.
+    if live:
+        if wait_kind == WAIT_PERMISSION:
+            return False, "permission", (
+                f"session {short} is waiting on a permission prompt owned by the "
+                "Claude TUI; approve/reject it there, wait for the session to go "
+                "idle, then import"
+            )
+        if wait_kind == WAIT_QUESTION:
+            return False, "question", (
+                f"session {short} is waiting on a question/dialog; answer it in the "
+                "Claude TUI, wait for the session to go idle, then import"
+            )
+        if wait_kind == WAIT_SHELL:
+            return False, "shell", (
+                f"session {short} is in a shell command; let it return to the prompt, "
+                "then import"
+            )
+        if wait_kind != WAIT_NONE:  # unknown / worker-request / input-needed
+            return False, "unknown", (
+                f"session {short} is in an unknown wait state ({wait_kind}); resolve it "
+                "in the Claude TUI and import once it is idle"
+            )
+        if status == "busy":
+            return False, "busy", (
+                f"session {short} is busy (a turn is running); wait for the current "
+                "turn to finish, then import"
+            )
+        if status != "idle":
+            return False, "not-idle", (
+                f"session {short} is live with status={status or 'unknown'}; import only "
+                "when it is idle and not waiting"
+            )
+    # A stopped/non-live session can still have an unanswered AskUserQuestion as
+    # the last tool use in the transcript. Resuming that under ccx would re-enter
+    # the question during the import auto-continue turn, before an operator has a
+    # clean `ccx answer` opportunity, so refuse it just like a live question wait.
+    transcript = rec.get("transcript")
+    if transcript and os.path.exists(transcript):
+        pend = pending_ask_user_question(transcript)
+        if pend and pend.get("questions"):
+            return False, "question", (
+                f"session {short} has an unanswered question/dialog in its transcript; "
+                "answer or abandon it in Claude, wait for the session to go idle, then import"
+            )
+    # Preconditions for a clean resume-under-ccx (checked after the live-state
+    # gate so a busy session reports 'busy', not an incidental cwd/transcript edge).
+    if not transcript or not os.path.isfile(transcript):
+        return False, "no-transcript", (
+            f"session {short} has no transcript yet; start a turn in Claude before importing"
+        )
+    if not (cwd and os.path.isdir(cwd)):
+        return False, "no-cwd", f"session {short} cwd does not exist: {cwd or '(unset)'}"
+    return True, "ok", f"session {short} is importable"

package/ccx/claude/host/events.py

@@ -0,0 +1,297 @@
+from __future__ import annotations
+import json
+import os
+import pathlib
+import stat
+import time
+from ccx.ops.semantics import KIND_ELICITATION
+from ccx.constants import (
+    CCX_EVENTS_KEEP,
+    CCX_EVENTS_MAX,
+    EVENT_PREVIEW_LIMIT,
+    EVENT_SCHEMA_VERSION,
+)
+
+
+def _permission_preview(req: dict | None) -> dict | None:
+    """Build the persisted/broadcast preview of a pending permission request.
+
+    Large arbitrary tool inputs (e.g. a big Write) are truncated to a short
+    preview so the on-disk record and broadcast stay small. AskUserQuestion is the
+    exception: its `input.questions` is the structure `ccx answer` must read to map
+    options/text to the right question and validate labels. Truncating it away
+    would leave the answer path with zero questions and produce misleading errors
+    for long question sets, so AUQ input is always kept whole."""
+    if not req:
+        return None
+    if req.get("kind") == KIND_ELICITATION:
+        return _elicitation_preview(req)
+    tool_name = req.get("tool_name")
+    tool_input = req.get("tool_input")
+    try:
+        rendered = json.dumps(tool_input, ensure_ascii=False)
+    except TypeError:
+        rendered = json.dumps(str(tool_input))
+    if tool_name == "AskUserQuestion":
+        safe_input = tool_input
+    elif len(rendered) > 2000:
+        safe_input = {"preview": rendered[:2000] + "…", "truncated": True}
+    else:
+        safe_input = tool_input
+    return {
+        "type": "permission",
+        "id": req.get("id"),
+        "tool": tool_name,
+        "input": safe_input,
+        "requested_at": int(req.get("requested_at", time.time()) * 1000),
+        "message": req.get("message"),
+    }
+
+
+def _elicitation_preview(req: dict) -> dict:
+    """Persisted/broadcast preview of a pending MCP elicitation.
+
+    The schema is kept whole (it is what a responder must satisfy) but the free
+    text is bounded. ``id`` is ``None`` for a dialog CCX only observed from a
+    notification: it has no brokered hook request, so it cannot be answered."""
+    message = req.get("message")
+    if isinstance(message, str) and len(message) > 4000:
+        message = message[:4000] + "…"
+    return {
+        "type": KIND_ELICITATION,
+        "id": req.get("id"),
+        "tool": None,
+        "server": req.get("server"),
+        "mode": req.get("mode") or "form",
+        "message": message,
+        "url": req.get("url"),
+        "elicitation_id": req.get("elicitation_id"),
+        "schema": req.get("schema"),
+        "requested_at": int(req.get("requested_at", time.time()) * 1000),
+    }
+
+
+def _elicitation_request(data: dict, request_id: str | None) -> dict:
+    """Host-side pending gate for one Elicitation hook payload."""
+    schema = data.get("requested_schema")
+    return {
+        "kind": KIND_ELICITATION,
+        "id": request_id,
+        "server": data.get("mcp_server_name"),
+        "mode": data.get("mode") or "form",
+        "message": data.get("message"),
+        "url": data.get("url"),
+        "elicitation_id": data.get("elicitation_id"),
+        "schema": schema if isinstance(schema, dict) else None,
+        "requested_at": time.time(),
+        "raw": data,
+    }
+
+
+def _stamp_event(evt: dict, *, short: str, seq: int, epoch: str, ts: float,
+                 v: int = EVENT_SCHEMA_VERSION) -> dict:
+    """Return a copy of `evt` with the standard envelope fields stamped on.
+
+    The envelope (v/type/short/seq/epoch/ts) is authoritative: `seq` is a
+    per-host monotonic counter, `epoch` identifies this host life (it changes on
+    every respawn, so a subscriber can tell that `seq` numbering restarted), and
+    `ts` is the broadcast wall-clock. `type` is supplied by the caller and left
+    untouched; any other event-specific fields pass through unchanged."""
+    out = dict(evt)
+    out["v"] = v
+    out["short"] = short
+    out["seq"] = seq
+    out["epoch"] = epoch
+    out["ts"] = ts
+    return out
+
+
+def _event_preview(value, limit: int = EVENT_PREVIEW_LIMIT) -> str:
+    """Bounded JSON-ish preview of an arbitrary tool input/result for an event.
+
+    Always returns a short string so the broadcast and sidecar line stay small.
+    Falls back to `str()` for anything not JSON-serializable; never raises."""
+    if value is None:
+        return ""
+    try:
+        rendered = json.dumps(value, ensure_ascii=False, default=str)
+    except (TypeError, ValueError):
+        rendered = str(value)
+    if len(rendered) > limit:
+        return rendered[:limit] + "…"
+    return rendered
+
+
+def _bounded_text(value, limit: int = EVENT_PREVIEW_LIMIT) -> str | None:
+    """Bounded plain-text preview (no JSON quoting) for message-like fields.
+
+    Returns None for an absent value so callers can omit/null the field rather
+    than emit a misleading empty string."""
+    if value is None:
+        return None
+    s = value if isinstance(value, str) else str(value)
+    if len(s) > limit:
+        return s[:limit] + "…"
+    return s
+
+
+def _hook_tool_use_id(data: dict):
+    """Best-effort extraction of the tool_use id across hook payload spellings."""
+    return (data.get("tool_use_id") or data.get("toolUseID")
+            or data.get("toolUseId"))
+
+
+def _externally_completed_question(req: dict | None, data: dict) -> bool:
+    """Exact original input/name match for a native tool outcome (incl. failure).
+
+    Hook result content can contain user answers; *only* the tool_input at
+    invocation time is the correlation key. Tool-use IDs may be absent or
+    inconsistent between PermissionRequest and PostToolUse, and may not make
+    different original inputs equivalent.
+    """
+    return bool(
+        isinstance(req, dict) and req.get("kind") != KIND_ELICITATION
+        and isinstance(req.get("tool_name"), str)
+        and isinstance(req.get("tool_input"), dict)
+        and isinstance(data, dict)
+        and req["tool_name"] == data.get("tool_name")
+        and isinstance(data.get("tool_input"), dict)
+        and req["tool_input"] == data["tool_input"]
+    )
+
+
+def _oldest_native_gate(published: dict | None, queued: list[dict], data: dict):
+    """Oldest arrival wins when two native calls have identical full input."""
+    for req in ([published] if published is not None else []) + list(queued):
+        if _externally_completed_question(req, data):
+            return req
+    return None
+
+
+def _hook_tool_result(data: dict):
+    """The tool's result blob, accepting either `tool_response` (newer hook
+    payloads) or `tool_output` (older spelling) as the key."""
+    resp = data.get("tool_response")
+    if resp is None:
+        resp = data.get("tool_output")
+    return resp
+
+
+def _tool_started_event(data: dict, turn: int) -> dict:
+    return {
+        "type": "tool_started",
+        "tool_use_id": _hook_tool_use_id(data),
+        "tool": data.get("tool_name"),
+        "input_preview": _event_preview(data.get("tool_input")),
+        "turn": turn,
+    }
+
+
+def _tool_ok(data: dict) -> bool:
+    """Best-effort success flag for a finished tool. Defaults True; flips to
+    False only when the hook's result blob carries an explicit error marker."""
+    resp = _hook_tool_result(data)
+    if isinstance(resp, dict):
+        if resp.get("is_error") or resp.get("isError"):
+            return False
+        if resp.get("error"):
+            return False
+    return True
+
+
+def _tool_finished_event(data: dict, turn: int, duration_ms: int | None) -> dict:
+    return {
+        "type": "tool_finished",
+        "tool_use_id": _hook_tool_use_id(data),
+        "tool": data.get("tool_name"),
+        "duration_ms": duration_ms,
+        "ok": _tool_ok(data),
+        "result_preview": _event_preview(_hook_tool_result(data)),
+        "turn": turn,
+    }
+
+
+def _subagent_finished_event(data: dict, turn: int) -> dict:
+    agent_id = (data.get("agent_id") or data.get("subagent_id")
+                or data.get("agentId") or data.get("subagentId"))
+    agent_type = (data.get("agent_type") or data.get("subagent_type")
+                  or data.get("agentType") or data.get("subagentType"))
+    last_message = (data.get("last_message") or data.get("lastMessage")
+                    or data.get("result"))
+    return {
+        "type": "subagent_finished",
+        "agent_id": agent_id,
+        "agent_type": agent_type,
+        # None (not "") when absent, so consumers don't see a misleading empty
+        # message for a subagent whose last text the hook didn't carry.
+        "last_message": _bounded_text(last_message),
+        "turn": turn,
+    }
+
+
+def _count_lines(path) -> int:
+    """Fast newline count for the sidecar (binary, chunked, no parsing). Used to
+    seed the in-memory line counter at host start. Returns 0 if absent/unreadable."""
+    path = pathlib.Path(path)
+    n = 0
+    try:
+        with path.open("rb") as f:
+            while True:
+                chunk = f.read(1 << 20)
+                if not chunk:
+                    break
+                n += chunk.count(b"\n")
+    except OSError:
+        return 0
+    return n
+
+
+def _rotate_events_file(path, *, max_lines: int = CCX_EVENTS_MAX,
+                        keep_lines: int = CCX_EVENTS_KEEP) -> bool:
+    """Bounded rotation: if `path` holds more than `max_lines` lines, rewrite it
+    keeping only the last `keep_lines`. Returns True if a rotation happened.
+
+    Atomic via a temp file + os.replace, so a concurrent reader always sees a
+    complete file. The caller must reopen its append handle afterward — the old
+    handle still points at the now-unlinked inode."""
+    path = pathlib.Path(path)
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            lines = f.readlines()
+    except (OSError, ValueError):
+        return False
+    if len(lines) <= max_lines:
+        return False
+    tail = lines[-keep_lines:]
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    # Private like the original journal: readers refuse group/other bits, and
+    # a plain open() would inherit the host's umask (0664 under umask 002).
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC | os.O_NOFOLLOW | os.O_CLOEXEC,
+                 0o600)
+    os.fchmod(fd, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        f.writelines(tail)
+    os.replace(tmp, path)
+    return True
+
+
+def _open_event_journal(store, short: str):
+    """Append handle on the worker's private event journal, or None.
+
+    Created 0600; an existing journal we own with loose group/other bits (from
+    an older rotation) is tightened rather than abandoned. Anything else —
+    not a regular file, another owner, a symlink — is refused.
+    """
+    with store.lease():
+        with store._gen("workers", "claude", short) as fd:
+            event_fd = os.open(
+                "events.ndjson", os.O_WRONLY | os.O_CREAT | os.O_APPEND |
+                os.O_NOFOLLOW | os.O_CLOEXEC, 0o600, dir_fd=fd,
+            )
+            stat_event = os.fstat(event_fd)
+            if not stat.S_ISREG(stat_event.st_mode) or stat_event.st_uid != os.getuid():
+                os.close(event_fd)
+                raise PermissionError("worker event journal is untrusted")
+            if stat_event.st_mode & 0o077:
+                os.fchmod(event_fd, 0o600)
+    return os.fdopen(event_fd, "ab", buffering=0)