agentdir-cli 0.7.5__py3-none-any.whl

agentdir/__init__.py

@@ -0,0 +1,3 @@
+"""AgentDir local agent work mailstore."""
+
+__version__ = "0.7.5"

agentdir/__main__.py

@@ -0,0 +1,6 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

agentdir/actors.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .envelope import build_envelope, envelope_bytes
+from .mailbox import atomic_deliver
+from .redaction import redact_text
+from .store import actor_mailbox
+
+
+def create_actor(root: str | Path, actor_id: str) -> tuple[Path, Path]:
+    inbox = actor_mailbox(root, actor_id, "inbox", create=True)
+    outbox = actor_mailbox(root, actor_id, "outbox", create=True)
+    return inbox, outbox
+
+
+def send_message(
+    *,
+    root: str | Path,
+    from_actor: str,
+    to_actor: str,
+    event_type: str,
+    body: str,
+    subject: str | None = None,
+    session_id: str | None = None,
+    task_id: str | None = None,
+    message_id: str | None = None,
+) -> tuple[Path, Path]:
+    create_actor(root, from_actor)
+    create_actor(root, to_actor)
+    redacted = redact_text(body)
+    extra_headers = {}
+    if redacted.replacements:
+        extra_headers["X-AgentDir-Redactions"] = str(redacted.replacements)
+        extra_headers["X-AgentDir-Redaction-Labels"] = ",".join(redacted.labels)
+    msg = build_envelope(
+        event_type=event_type,
+        body=redacted.text,
+        subject=subject,
+        from_actor=from_actor,
+        to_actor=to_actor,
+        session_id=session_id,
+        task_id=task_id,
+        extra_headers=extra_headers,
+        message_id=message_id,
+    )
+    data = envelope_bytes(msg)
+    inbox_path = atomic_deliver(actor_mailbox(root, to_actor, "inbox"), data)
+    outbox_path = atomic_deliver(actor_mailbox(root, from_actor, "outbox"), data)
+    return inbox_path, outbox_path

agentdir/artifacts.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import hashlib
+import mimetypes
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from .mailbox import fsync_directory
+from .store import require_root
+
+
+@dataclass(frozen=True)
+class Artifact:
+    sha256: str
+    path: Path
+    bytes: int
+    mime_type: str
+
+
+def artifact_path(root: str | Path, sha256: str) -> Path:
+    paths = require_root(root)
+    return paths.artifacts / "blobs" / "sha256" / sha256[:2] / sha256[2:4] / sha256
+
+
+def add_artifact(root: str | Path, source: str | Path) -> Artifact:
+    source_path = Path(source).expanduser().resolve()
+    digest = hashlib.sha256()
+    size = 0
+    with source_path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            size += len(chunk)
+            digest.update(chunk)
+    sha = digest.hexdigest()
+    target = artifact_path(root, sha)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if not target.exists():
+        temp = target.with_name(f".{target.name}.{os.getpid()}.tmp")
+        with source_path.open("rb") as src, temp.open("wb") as dst:
+            shutil.copyfileobj(src, dst)
+            dst.flush()
+            os.fsync(dst.fileno())
+        os.replace(temp, target)
+        fsync_directory(target.parent)
+    mime_type = mimetypes.guess_type(source_path.name)[0] or "application/octet-stream"
+    return Artifact(sha256=sha, path=target, bytes=size, mime_type=mime_type)
+
+
+def artifact_headers(artifact: Artifact) -> dict[str, str]:
+    return {
+        "X-AgentDir-Blob-SHA256": artifact.sha256,
+        "X-AgentDir-Blob-Bytes": str(artifact.bytes),
+        "X-AgentDir-Blob-Mime": artifact.mime_type,
+    }
+

agentdir/audit.py

@@ -0,0 +1,339 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from .context import audit_context_pack
+from .doctor import run_doctor
+from .git import git_status_short
+from .review import EVIDENCE_FAMILIES, evidence_rows, summarize_session
+from .sessions import read_current_session
+from .store import AgentDirError
+
+CHECK_PASS = "pass"
+CHECK_WARN = "warn"
+CHECK_FAIL = "fail"
+CHECK_NOT_APPLICABLE = "not_applicable"
+CHECK_STATUSES = (CHECK_PASS, CHECK_WARN, CHECK_FAIL, CHECK_NOT_APPLICABLE)
+
+CLAIM_SUPPORTED = "supported"
+CLAIM_UNSUPPORTED = "unsupported"
+CLAIM_CONTRADICTED = "contradicted"
+CLAIM_STATUSES = (CLAIM_SUPPORTED, CLAIM_UNSUPPORTED, CLAIM_CONTRADICTED)
+
+CLAIM_FAMILIES = tuple(family for family in EVIDENCE_FAMILIES if family != "diagnostic")
+
+CLAIM_KEYWORDS = {
+    "test": ("test", "tests", "pytest", "vitest", "jest", "mocha", "unittest"),
+    "lint": ("lint", "eslint", "ruff", "flake8"),
+    "typecheck": ("typecheck", "type check", "type-check", "tsc", "mypy", "pyright"),
+    "build": ("build",),
+    "doctor": ("doctor",),
+    "release": ("release", "deploy", "deployment", "publish"),
+}
+
+CLAIM_PATTERNS = {
+    "test": re.compile(r"\b(test|tests|pytest|vitest|jest)\b[^.\n]*(pass|passed|passing|green|succeed|succeeded)", re.I),
+    "lint": re.compile(r"\b(lint|eslint|ruff|flake8)\b[^.\n]*(pass|passed|passing|clean|succeed|succeeded)", re.I),
+    "typecheck": re.compile(
+        r"\b(typecheck|type check|type-check|tsc|mypy|pyright)\b[^.\n]*(pass|passed|passing|clean|succeed|succeeded)",
+        re.I,
+    ),
+    "build": re.compile(r"\b(build|built)\b[^.\n]*(pass|passed|passing|succeed|succeeded|successful|completed)", re.I),
+    "doctor": re.compile(r"\bdoctor\b[^.\n]*(pass|passed|passing|ok|healthy|clean|succeed|succeeded)", re.I),
+    "release": re.compile(
+        r"\b(release|deploy|deployment|publish)\b[^.\n]*(pass|passed|passing|succeed|succeeded|successful|completed)",
+        re.I,
+    ),
+}
+
+NEGATED_CLAIM_RE = re.compile(r"\b(not run|did not run|didn't run|was not run|wasn't run|without running)\b", re.I)
+_MISSING = object()
+
+
+def audit_session(
+    root: str | Path,
+    session_id: str | None = None,
+    *,
+    strict: bool = False,
+    finishing: bool = False,
+    run_health_check: bool = True,
+    rebuild: bool = True,
+    summary: dict[str, Any] | None = None,
+    evidence: list[dict[str, Any]] | None = None,
+    latest_pack: dict[str, Any] | None | object = _MISSING,
+    context_audit: dict[str, Any] | None | object = _MISSING,
+    doctor: dict[str, Any] | None | object = _MISSING,
+) -> dict[str, Any]:
+    if summary is None:
+        summary = summarize_session(root, session_id, rebuild=rebuild)
+        rebuild = False
+    resolved = summary["session_id"]
+    if evidence is None:
+        evidence = evidence_rows(root, resolved, rebuild=rebuild)
+        rebuild = False
+    event_counts = summary.get("event_counts") or {}
+    if latest_pack is _MISSING:
+        latest_pack = _latest_context_pack(root, resolved, rebuild=rebuild)
+        rebuild = False
+    if context_audit is _MISSING:
+        context_audit = _safe_context_audit(root, latest_pack, rebuild=rebuild)
+    if doctor is _MISSING:
+        doctor = run_doctor(root).as_dict() if run_health_check else None
+    current = read_current_session(root)
+    is_current = bool(current and current.session_id == resolved and current.status == "active")
+    failed_evidence = [row for row in evidence if row.get("event_type") == "tool.result" and row.get("tool_exit_code") not in (None, 0)]
+    dirty_status = git_status_short(root)
+    checks = [
+        _check(
+            "session_started",
+            CHECK_PASS if event_counts.get("session.started") or event_counts.get("work.started") else CHECK_FAIL,
+            "session has a start event" if event_counts.get("session.started") or event_counts.get("work.started") else "session has no start event",
+        ),
+        _check(
+            "session_finished",
+            CHECK_PASS if event_counts.get("session.ended") or event_counts.get("work.finished") or finishing else CHECK_WARN,
+            "session has a finish event" if event_counts.get("session.ended") or event_counts.get("work.finished") else (
+                "work finish is in progress" if finishing else "session is still active" if is_current else "session has no finish event"
+            ),
+        ),
+        _check(
+            "evidence_present",
+            CHECK_PASS if evidence else CHECK_WARN,
+            f"{len(evidence)} evidence record(s) captured" if evidence else "no evidence captured",
+        ),
+        _check(
+            "failed_tool_results",
+            CHECK_FAIL if failed_evidence else CHECK_PASS,
+            f"{len(failed_evidence)} failed tool result(s)" if failed_evidence else "no failed tool results",
+        ),
+        _check(
+            "context_pack_created",
+            CHECK_PASS if latest_pack else CHECK_WARN,
+            f"context pack {latest_pack['pack_id']} recorded" if latest_pack else "no context pack recorded",
+        ),
+        _context_check("context_sources_consumed", context_audit, "consumed_count", latest_pack),
+        _context_check("context_sources_cited", context_audit, "cited_count", latest_pack),
+        _doctor_check(doctor),
+        _check(
+            "git_dirty",
+            CHECK_WARN if dirty_status else CHECK_PASS,
+            "git worktree has changes" if dirty_status else "git worktree is clean",
+        ),
+    ]
+    return {
+        "session_id": resolved,
+        "ok": not any(check["status"] == CHECK_FAIL for check in checks),
+        "strict": strict,
+        "summary": summary,
+        "checks": checks,
+    }
+
+
+def audit_claims(
+    root: str | Path,
+    text: str,
+    session_id: str | None = None,
+    *,
+    strict: bool = False,
+    rebuild: bool = True,
+    summary: dict[str, Any] | None = None,
+    evidence: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    if summary is None:
+        summary = summarize_session(root, session_id, rebuild=rebuild)
+        rebuild = False
+    resolved = summary["session_id"]
+    if evidence is None:
+        evidence = evidence_rows(root, resolved, rebuild=rebuild)
+    tool_results = [row for row in evidence if row.get("event_type") == "tool.result"]
+    claims = []
+    for family in _detect_claim_families(text):
+        evidence = _latest_relevant_tool_result(tool_results, family)
+        if evidence is None:
+            status = CLAIM_UNSUPPORTED
+            message = f"no {family} evidence found"
+        elif evidence.get("tool_exit_code") == 0:
+            status = CLAIM_SUPPORTED
+            message = f"latest {family} evidence succeeded"
+        else:
+            status = CLAIM_CONTRADICTED
+            message = f"latest {family} evidence failed with exit {evidence.get('tool_exit_code')}"
+        claims.append(
+            {
+                "family": family,
+                "status": status,
+                "message": message,
+                "evidence": _evidence_ref(evidence),
+            }
+        )
+    return {
+        "session_id": resolved,
+        "ok": not any(claim["status"] in {CLAIM_UNSUPPORTED, CLAIM_CONTRADICTED} for claim in claims),
+        "strict": strict,
+        "claims": claims,
+    }
+
+
+def format_session_audit(audit: dict[str, Any]) -> str:
+    lines = [f"session={audit['session_id']}", f"ok={str(audit['ok']).lower()}"]
+    for check in audit["checks"]:
+        lines.append(f"{check['id']}={check['status']} {check['message']}")
+    return "\n".join(lines)
+
+
+def format_claims_audit(audit: dict[str, Any]) -> str:
+    lines = [f"session={audit['session_id']}", f"ok={str(audit['ok']).lower()}"]
+    if not audit["claims"]:
+        lines.append("claims=none")
+        return "\n".join(lines)
+    for claim in audit["claims"]:
+        evidence = claim.get("evidence") or {}
+        evidence_path = evidence.get("file_path") or ""
+        lines.append(f"{claim['family']}={claim['status']} {claim['message']} {evidence_path}".rstrip())
+    return "\n".join(lines)
+
+
+def session_audit_gaps(audit: dict[str, Any]) -> list[str]:
+    gaps: list[str] = []
+    for check in audit.get("checks") or []:
+        if check.get("id") == "git_dirty":
+            continue
+        if check.get("status") in {CHECK_WARN, CHECK_FAIL}:
+            gaps.append(f"{check['id']}: {check['message']}")
+    return gaps
+
+
+def claims_audit_gaps(audit: dict[str, Any] | None) -> list[str]:
+    if not audit:
+        return []
+    gaps: list[str] = []
+    for claim in audit.get("claims") or []:
+        if claim.get("status") in {CLAIM_UNSUPPORTED, CLAIM_CONTRADICTED}:
+            gaps.append(f"{claim['family']}: {claim['message']}")
+    return gaps
+
+
+def strict_session_exit_code(audit: dict[str, Any]) -> int:
+    return 1 if any(check["status"] == CHECK_FAIL for check in audit.get("checks") or []) else 0
+
+
+def strict_claims_exit_code(audit: dict[str, Any]) -> int:
+    return 1 if any(claim["status"] in {CLAIM_UNSUPPORTED, CLAIM_CONTRADICTED} for claim in audit.get("claims") or []) else 0
+
+
+def _check(
+    check_id: str,
+    status: str,
+    message: str,
+    *,
+    details: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    if status not in CHECK_STATUSES:
+        raise AgentDirError(f"Unknown audit check status: {status}")
+    payload = {"id": check_id, "status": status, "message": message}
+    if details:
+        payload["details"] = details
+    return payload
+
+
+def _context_check(
+    check_id: str,
+    context_audit: dict[str, Any] | None,
+    count_key: str,
+    latest_pack: dict[str, Any] | None,
+) -> dict[str, Any]:
+    if latest_pack is None:
+        return _check(check_id, CHECK_NOT_APPLICABLE, "no context pack recorded")
+    if context_audit is None:
+        return _check(check_id, CHECK_WARN, "context audit unavailable")
+    if context_audit.get("error"):
+        return _check(check_id, CHECK_WARN, f"context audit failed: {context_audit['error']}")
+    count = int(context_audit.get(count_key) or 0)
+    action = "consumed" if count_key == "consumed_count" else "cited"
+    return _check(
+        check_id,
+        CHECK_PASS if count else CHECK_WARN,
+        f"{count} context source(s) {action}" if count else f"no context sources {action}",
+    )
+
+
+def _doctor_check(doctor: dict[str, Any] | None) -> dict[str, Any]:
+    if doctor is None:
+        return _check("doctor_ok", CHECK_NOT_APPLICABLE, "doctor was not run")
+    return _check(
+        "doctor_ok",
+        CHECK_PASS if doctor.get("ok") else CHECK_FAIL,
+        "doctor reported ok" if doctor.get("ok") else "doctor reported errors",
+        details={"doctor": doctor},
+    )
+
+
+def _latest_context_pack(root: str | Path, session_id: str, *, rebuild: bool = True) -> dict[str, Any] | None:
+    from .control import latest_context_pack
+
+    return latest_context_pack(root, session_id, rebuild=rebuild)
+
+
+def _safe_context_audit(root: str | Path, latest_pack: dict[str, Any] | None | object, *, rebuild: bool = True) -> dict[str, Any] | None:
+    if latest_pack is _MISSING or latest_pack is None:
+        return None
+    pack_id = latest_pack["pack_id"]
+    try:
+        return audit_context_pack(root, pack_id, rebuild=rebuild)
+    except AgentDirError as exc:
+        return {"error": str(exc), "pack_id": pack_id}
+
+
+def _detect_claim_families(text: str) -> list[str]:
+    families: list[str] = []
+    for family in CLAIM_FAMILIES:
+        pattern = CLAIM_PATTERNS[family]
+        for match in pattern.finditer(text):
+            window = text[max(0, match.start() - 40): match.end() + 40]
+            if NEGATED_CLAIM_RE.search(window):
+                continue
+            families.append(family)
+            break
+    return families
+
+
+def _latest_relevant_tool_result(rows: list[dict[str, Any]], family: str) -> dict[str, Any] | None:
+    for row in reversed(rows):
+        if row.get("family") == family:
+            return row
+    keywords = CLAIM_KEYWORDS[family]
+    for row in reversed(rows):
+        haystack = _tool_result_search_text(row)
+        if any(keyword in haystack for keyword in keywords):
+            return row
+    return None
+
+
+def _tool_result_search_text(row: dict[str, Any]) -> str:
+    body_lines = []
+    for line in str(row.get("body_text") or "").splitlines():
+        if line.startswith(("cwd=", "duration_ms=", "redactions=", "stdout_truncated=", "stderr_truncated=")):
+            continue
+        body_lines.append(line)
+    return " ".join(
+        [
+            str(row.get("tool") or ""),
+            str(row.get("subject") or ""),
+            "\n".join(body_lines),
+        ]
+    ).lower()
+
+
+def _evidence_ref(row: dict[str, Any] | None) -> dict[str, Any] | None:
+    if row is None:
+        return None
+    return {
+        "event_type": row.get("event_type"),
+        "tool": row.get("tool"),
+        "tool_exit_code": row.get("tool_exit_code"),
+        "subject": row.get("subject"),
+        "file_path": row.get("file_path"),
+        "date_utc": row.get("date_utc"),
+    }

agentdir/capture.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import threading
+import time
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from .events import emit_event
+from .git import git_head, workspace_name
+from .redaction import redact_text
+from .sessions import ensure_session
+from .store import AgentDirError
+
+DEFAULT_MAX_CAPTURE_BYTES = 256 * 1024
+
+
+@dataclass
+class CapturedText:
+    text: str = ""
+    truncated: bool = False
+
+
+def _append_limited(capture: CapturedText, chunk: str, max_bytes: int) -> None:
+    if capture.truncated:
+        return
+    current = len(capture.text.encode("utf-8", errors="replace"))
+    remaining = max_bytes - current
+    encoded = chunk.encode("utf-8", errors="replace")
+    if len(encoded) <= remaining:
+        capture.text += chunk
+        return
+    capture.text += encoded[: max(0, remaining)].decode("utf-8", errors="replace")
+    capture.truncated = True
+
+
+def _tee_stream(stream, target, capture: CapturedText, max_bytes: int) -> None:
+    try:
+        for chunk in iter(lambda: stream.readline(), ""):
+            if chunk == "":
+                break
+            target.write(chunk)
+            target.flush()
+            _append_limited(capture, chunk, max_bytes)
+    finally:
+        stream.close()
+
+
+def run_tool(
+    root: str | Path,
+    *,
+    argv: list[str],
+    session_id: str | None = None,
+    tool_name: str | None = None,
+    cwd: str | Path | None = None,
+    max_capture_bytes: int = DEFAULT_MAX_CAPTURE_BYTES,
+    redact: bool = True,
+) -> int:
+    if not argv:
+        raise AgentDirError("argv is required")
+    if max_capture_bytes < 0:
+        raise AgentDirError("max_capture_bytes must be non-negative")
+
+    cwd_path = Path(cwd).expanduser().resolve() if cwd else Path.cwd()
+    session = ensure_session(root, session_id, title=f"AgentDir run: {argv[0]}", emit_started=session_id is None)
+    tool = tool_name or Path(argv[0]).name
+    start = datetime.now(UTC)
+    command_text = " ".join(argv)
+    head = git_head(cwd_path)
+    workspace = workspace_name(cwd_path)
+
+    emit_event(
+        root,
+        session_id=session.session_id,
+        event_type="tool.call",
+        subject=f"tool.call {tool}",
+        from_actor="agent",
+        body="\n".join(
+            [
+                f"tool={tool}",
+                f"argv={argv!r}",
+                f"cwd={cwd_path}",
+                f"started_at={start.isoformat()}",
+            ]
+        ),
+        workspace=workspace,
+        git_head=head,
+        tool=tool,
+    )
+
+    stdout_capture = CapturedText()
+    stderr_capture = CapturedText()
+    env = os.environ.copy()
+    env["AGENTDIR_SESSION"] = session.session_id
+    started = time.monotonic()
+    try:
+        process = subprocess.Popen(
+            argv,
+            cwd=cwd_path,
+            env=env,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            errors="replace",
+        )
+    except FileNotFoundError:
+        message = f"agentdir: command not found: {argv[0]}\n"
+        sys.stderr.write(message)
+        sys.stderr.flush()
+        emit_event(
+            root,
+            session_id=session.session_id,
+            event_type="tool.result",
+            subject=f"tool.result {tool} exit 127",
+            from_actor="agent",
+            body=f"command={command_text}\nexit_code=127\nstderr:\n{message}",
+            workspace=workspace,
+            git_head=head,
+            tool=tool,
+            tool_exit_code=127,
+        )
+        return 127
+
+    assert process.stdout is not None
+    assert process.stderr is not None
+    stdout_thread = threading.Thread(
+        target=_tee_stream,
+        args=(process.stdout, sys.stdout, stdout_capture, max_capture_bytes),
+        daemon=True,
+    )
+    stderr_thread = threading.Thread(
+        target=_tee_stream,
+        args=(process.stderr, sys.stderr, stderr_capture, max_capture_bytes),
+        daemon=True,
+    )
+    stdout_thread.start()
+    stderr_thread.start()
+    exit_code = process.wait()
+    stdout_thread.join()
+    stderr_thread.join()
+    duration_ms = int((time.monotonic() - started) * 1000)
+
+    stored_stdout = redact_text(stdout_capture.text) if redact else None
+    stored_stderr = redact_text(stderr_capture.text) if redact else None
+    stdout_text = stored_stdout.text if stored_stdout else stdout_capture.text
+    stderr_text = stored_stderr.text if stored_stderr else stderr_capture.text
+    redactions = (stored_stdout.replacements if stored_stdout else 0) + (
+        stored_stderr.replacements if stored_stderr else 0
+    )
+
+    body = "\n".join(
+        [
+            f"command={command_text}",
+            f"exit_code={exit_code}",
+            f"duration_ms={duration_ms}",
+            f"cwd={cwd_path}",
+            f"redactions={redactions}",
+            f"stdout_truncated={str(stdout_capture.truncated).lower()}",
+            f"stderr_truncated={str(stderr_capture.truncated).lower()}",
+            "",
+            "stdout:",
+            stdout_text,
+            "",
+            "stderr:",
+            stderr_text,
+        ]
+    )
+    emit_event(
+        root,
+        session_id=session.session_id,
+        event_type="tool.result",
+        subject=f"tool.result {tool} exit {exit_code}",
+        from_actor="agent",
+        body=body,
+        workspace=workspace,
+        git_head=head,
+        tool=tool,
+        tool_exit_code=exit_code,
+        extra_headers={
+            "X-AgentDir-Duration-Ms": str(duration_ms),
+            "X-AgentDir-Redactions": str(redactions),
+        },
+    )
+    return int(exit_code)