agentdir-cli 0.7.5__py3-none-any.whl

agentdir/hooks.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import json
+import stat
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from .events import emit_event
+from .git import git_branch, git_head, git_output, git_status_short
+from .sessions import end_session, read_current_session, start_session
+from .store import AgentDirError, init_root
+
+DEFAULT_HOOKS = ("pre-commit", "post-commit", "pre-push", "post-checkout", "post-merge")
+MANAGED_MARKER = "# AgentDir managed hook"
+
+
+@dataclass(frozen=True)
+class HookInfo:
+    hook: str
+    path: str
+    installed: bool
+    managed: bool
+    original: str | None = None
+
+
+def git_hooks_dir(cwd: str | Path | None = None) -> Path:
+    git_dir = git_output(["rev-parse", "--git-dir"], cwd)
+    if not git_dir:
+        raise AgentDirError("AgentDir hooks require a git repository")
+    path = Path(git_dir)
+    if not path.is_absolute():
+        root = git_output(["rev-parse", "--show-toplevel"], cwd)
+        base = Path(root) if root else Path(cwd or Path.cwd())
+        path = base / path
+    hooks = path.resolve() / "hooks"
+    hooks.mkdir(parents=True, exist_ok=True)
+    return hooks
+
+
+def hook_status(cwd: str | Path | None = None, hooks: list[str] | None = None) -> list[HookInfo]:
+    hooks_dir = git_hooks_dir(cwd)
+    names = hooks or list(DEFAULT_HOOKS)
+    statuses: list[HookInfo] = []
+    for name in names:
+        path = hooks_dir / name
+        original = hooks_dir / f"{name}.agentdir-original"
+        managed = path.is_file() and MANAGED_MARKER in path.read_text(encoding="utf-8", errors="ignore")
+        statuses.append(
+            HookInfo(
+                hook=name,
+                path=str(path),
+                installed=path.exists(),
+                managed=managed,
+                original=str(original) if original.exists() else None,
+            )
+        )
+    return statuses
+
+
+def install_hooks(
+    root: str | Path,
+    *,
+    cwd: str | Path | None = None,
+    hooks: list[str] | None = None,
+    force: bool = False,
+) -> list[HookInfo]:
+    init_root(root)
+    hooks_dir = git_hooks_dir(cwd)
+    installed: list[HookInfo] = []
+    for name in hooks or list(DEFAULT_HOOKS):
+        target = hooks_dir / name
+        original = hooks_dir / f"{name}.agentdir-original"
+        if target.exists():
+            managed = target.is_file() and MANAGED_MARKER in target.read_text(encoding="utf-8", errors="ignore")
+            if not managed:
+                if original.exists() and not force:
+                    raise AgentDirError(f"Refusing to overwrite existing hook and backup: {target}")
+                if original.exists() and force:
+                    original.unlink()
+                target.rename(original)
+        target.write_text(_hook_script(name, original), encoding="utf-8")
+        target.chmod(target.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+        installed.append(
+            HookInfo(
+                hook=name,
+                path=str(target),
+                installed=True,
+                managed=True,
+                original=str(original) if original.exists() else None,
+            )
+        )
+    return installed
+
+
+def uninstall_hooks(
+    *,
+    cwd: str | Path | None = None,
+    hooks: list[str] | None = None,
+) -> list[HookInfo]:
+    hooks_dir = git_hooks_dir(cwd)
+    removed: list[HookInfo] = []
+    for name in hooks or list(DEFAULT_HOOKS):
+        target = hooks_dir / name
+        original = hooks_dir / f"{name}.agentdir-original"
+        managed = target.is_file() and MANAGED_MARKER in target.read_text(encoding="utf-8", errors="ignore")
+        if managed:
+            target.unlink()
+            if original.exists():
+                original.rename(target)
+        removed.append(
+            HookInfo(
+                hook=name,
+                path=str(target),
+                installed=target.exists(),
+                managed=target.is_file() and MANAGED_MARKER in target.read_text(encoding="utf-8", errors="ignore"),
+                original=str(original) if original.exists() else None,
+            )
+        )
+    return removed
+
+
+def record_hook_event(
+    root: str | Path,
+    *,
+    hook: str,
+    original_exit_code: int,
+    stdin_file: str | Path | None = None,
+    hook_args: list[str] | None = None,
+    cwd: str | Path | None = None,
+) -> None:
+    session = read_current_session(root)
+    created_hook_session = session is None or session.status != "active"
+    if created_hook_session:
+        session = start_session(
+            root,
+            title=f"Git hook {hook}",
+            actor="git",
+            note="AgentDir background git hook session.",
+            cwd=cwd,
+        )
+    stdin_text = ""
+    if stdin_file:
+        path = Path(stdin_file)
+        if path.is_file():
+            stdin_text = path.read_text(encoding="utf-8", errors="replace")[:32_000]
+    body = "\n".join(
+        [
+            f"hook={hook}",
+            f"original_exit_code={original_exit_code}",
+            f"args={json.dumps(hook_args or [])}",
+            f"branch={git_branch(cwd) or ''}",
+            f"git_head={git_head(cwd) or ''}",
+            f"recorded_at={datetime.now(UTC).isoformat()}",
+            "",
+            "git_status_short:",
+            git_status_short(cwd),
+            "",
+            "stdin:",
+            stdin_text,
+        ]
+    )
+    emit_event(
+        root,
+        session_id=session.session_id,
+        event_type=f"git.hook.{hook}",
+        subject=f"git hook {hook} exit {original_exit_code}",
+        from_actor="git",
+        body=body,
+        git_head=git_head(cwd),
+        tool="git",
+        tool_exit_code=original_exit_code,
+    )
+    if created_hook_session:
+        end_session(
+            root,
+            status="completed",
+            summary=f"Recorded git hook {hook} exit {original_exit_code}.",
+            actor="git",
+        )
+
+
+def _hook_script(name: str, original: Path) -> str:
+    return f"""#!/bin/sh
+{MANAGED_MARKER}: {name}
+hook_name="{name}"
+stdin_file="$(mktemp "${{TMPDIR:-/tmp}}/agentdir-hook.XXXXXX")" || stdin_file=""
+if [ -n "$stdin_file" ]; then
+  cat > "$stdin_file"
+fi
+
+original="{original}"
+original_status=0
+if [ -x "$original" ]; then
+  if [ -n "$stdin_file" ]; then
+    "$original" "$@" < "$stdin_file"
+  else
+    "$original" "$@"
+  fi
+  original_status=$?
+fi
+
+if command -v agentdir >/dev/null 2>&1; then
+  if [ -n "$stdin_file" ]; then
+    agentdir hooks record --hook "$hook_name" --original-exit-code "$original_status" --stdin-file "$stdin_file" -- "$@" >/dev/null 2>&1 || true
+  else
+    agentdir hooks record --hook "$hook_name" --original-exit-code "$original_status" -- "$@" >/dev/null 2>&1 || true
+  fi
+fi
+
+if [ -n "$stdin_file" ]; then
+  rm -f "$stdin_file"
+fi
+exit "$original_status"
+"""

agentdir/index.py

@@ -0,0 +1,362 @@
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import time
+from collections import defaultdict
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from pathlib import Path
+
+try:
+    import fcntl
+except ImportError:  # pragma: no cover - AgentDir targets Unix-like developer machines.
+    fcntl = None
+
+from .envelope import parse_envelope, validate_required
+from .mailbox import iter_records
+from .memory import index_memory_document, index_session_summaries, memory_schema_sql
+from .store import AgentDirError, discover_mailboxes, paths_for, require_root
+
+SCHEMA = """
+pragma foreign_keys = on;
+create table if not exists metadata (key text primary key, value text not null);
+create table if not exists messages (
+  id integer primary key,
+  message_id text,
+  mailbox_kind text not null,
+  mailbox_path text not null,
+  file_path text not null unique,
+  state text not null,
+  event_type text,
+  subject text,
+  from_actor text,
+  to_actor text,
+  session_id text,
+  task_id text,
+  parent_message_id text,
+  date_header text,
+  date_utc text,
+  created_ns integer,
+  git_head text,
+  workspace text,
+  tool text,
+  tool_exit_code integer,
+  body_sha256 text,
+  body_text text,
+  indexed_at text not null,
+  malformed integer not null default 0,
+  errors text not null default '[]'
+);
+create index if not exists messages_message_id_idx on messages(message_id);
+create index if not exists messages_session_idx on messages(session_id);
+create index if not exists messages_event_type_idx on messages(event_type);
+create index if not exists messages_task_idx on messages(task_id);
+create table if not exists headers (
+  message_rowid integer not null references messages(id) on delete cascade,
+  name text not null,
+  value text not null
+);
+create table if not exists artifacts (
+  sha256 text primary key,
+  path text not null,
+  bytes integer,
+  mime_type text,
+  created_at text not null
+);
+create table if not exists message_artifacts (
+  message_rowid integer not null references messages(id) on delete cascade,
+  sha256 text not null
+);
+"""
+
+
+@dataclass
+class IndexResult:
+    indexed: int = 0
+    malformed: int = 0
+    duplicates: dict[str, list[str]] = field(default_factory=dict)
+
+
+def now_iso() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def initialize_schema(conn: sqlite3.Connection) -> None:
+    conn.executescript(SCHEMA)
+    conn.executescript(memory_schema_sql())
+    conn.execute("insert or replace into metadata(key, value) values('schema_version', '3')")
+    conn.execute("insert or replace into metadata(key, value) values('vector_memory', 'yes')")
+    conn.execute("insert or replace into metadata(key, value) values('hybrid_passages', 'yes')")
+    conn.execute("insert or replace into metadata(key, value) values('memory_backend', 'local-hybrid')")
+    conn.execute("insert or replace into metadata(key, value) values('semantic_embeddings', 'optional')")
+    try:
+        conn.execute(
+            "create virtual table if not exists message_fts using fts5(message_id, subject, body_text)"
+        )
+        conn.execute("insert or replace into metadata(key, value) values('fts5', 'yes')")
+    except sqlite3.DatabaseError:
+        conn.execute("insert or replace into metadata(key, value) values('fts5', 'no')")
+
+
+def connect_index(root: str | Path) -> sqlite3.Connection:
+    paths = require_root(root)
+    conn = sqlite3.connect(paths.index_path)
+    conn.row_factory = sqlite3.Row
+    conn.execute("pragma foreign_keys = on")
+    return conn
+
+
+@contextmanager
+def index_rebuild_lock(indexes: Path):
+    indexes.mkdir(parents=True, exist_ok=True)
+    lock_path = indexes / ".agentdir-index.lock"
+    with lock_path.open("a+", encoding="utf-8") as lock:
+        if fcntl is not None:
+            fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            if fcntl is not None:
+                fcntl.flock(lock.fileno(), fcntl.LOCK_UN)
+
+
+def rebuild_index(root: str | Path) -> IndexResult:
+    paths = require_root(root)
+    with index_rebuild_lock(paths.indexes):
+        temp_path = paths.index_path.with_name(
+            f"{paths.index_path.name}.{os.getpid()}.{time.time_ns()}.tmp"
+        )
+        conn = sqlite3.connect(temp_path)
+        conn.row_factory = sqlite3.Row
+        replaced = False
+        try:
+            conn.execute("pragma foreign_keys = on")
+            initialize_schema(conn)
+            result = _index_into(conn, root)
+            conn.commit()
+            _carry_forward_semantic_embeddings(conn, paths.index_path)
+            conn.close()
+            os.replace(temp_path, paths.index_path)
+            replaced = True
+            return result
+        finally:
+            if not replaced:
+                conn.close()
+            if not replaced and temp_path.exists():
+                temp_path.unlink()
+
+
+def update_index(root: str | Path) -> IndexResult:
+    return rebuild_index(root)
+
+
+def _carry_forward_semantic_embeddings(conn: sqlite3.Connection, previous_index: Path) -> None:
+    # Rebuilds start from an empty temp database, which would discard the
+    # semantic embedding cache and force a full re-embed on the next semantic
+    # query. Embeddings are content-addressed by (source_id, model,
+    # text_sha256), so rows whose document text is unchanged stay valid; the
+    # join drops rows for documents that no longer exist.
+    if not previous_index.exists():
+        return
+    try:
+        conn.execute("attach database ? as previous", (str(previous_index),))
+    except sqlite3.DatabaseError:
+        return
+    try:
+        conn.execute(
+            """
+            insert or replace into semantic_embeddings(
+              source_id, model, text_sha256, dimensions, vector_json, indexed_at
+            )
+            select prev.source_id, prev.model, prev.text_sha256,
+                   prev.dimensions, prev.vector_json, prev.indexed_at
+            from previous.semantic_embeddings prev
+            join memory_documents md
+              on md.source_id = prev.source_id and md.text_sha256 = prev.text_sha256
+            """
+        )
+        conn.commit()
+    except sqlite3.DatabaseError:
+        conn.rollback()
+    finally:
+        conn.execute("detach database previous")
+
+
+def _index_into(conn: sqlite3.Connection, root: str | Path) -> IndexResult:
+    conn.execute("delete from memory_terms")
+    conn.execute("delete from memory_passages")
+    conn.execute("delete from memory_documents")
+    conn.execute("delete from message_artifacts")
+    conn.execute("delete from headers")
+    conn.execute("delete from messages")
+    try:
+        conn.execute("delete from message_fts")
+    except sqlite3.DatabaseError:
+        pass
+
+    paths = paths_for(root)
+    result = IndexResult()
+    seen: dict[str, list[str]] = defaultdict(list)
+    for kind, mailbox in discover_mailboxes(root):
+        for record in iter_records(mailbox):
+            rowid, message_id, malformed = _insert_record(
+                conn=conn,
+                root=paths.root,
+                kind=kind,
+                mailbox=record.mailbox,
+                state=record.state,
+                path=record.path,
+            )
+            result.indexed += 1
+            if malformed:
+                result.malformed += 1
+            if message_id:
+                seen[message_id].append(str(record.path.relative_to(paths.root)))
+
+    index_session_summaries(conn)
+    result.duplicates = {mid: files for mid, files in seen.items() if len(files) > 1}
+    return result
+
+
+def _insert_record(
+    *,
+    conn: sqlite3.Connection,
+    root: Path,
+    kind: str,
+    mailbox: Path,
+    state: str,
+    path: Path,
+) -> tuple[int, str | None, bool]:
+    relative_mailbox = str(mailbox.relative_to(root))
+    relative_file = str(path.relative_to(root))
+    errors: list[str] = []
+    try:
+        parsed = parse_envelope(path)
+        errors.extend(validate_required(parsed))
+        msg = parsed.message
+        body_text = parsed.body_text
+        body_sha = parsed.body_sha256
+    except Exception as exc:
+        msg = None
+        body_text = ""
+        body_sha = None
+        errors.append(f"parse error: {exc}")
+
+    get = msg.get if msg is not None else lambda _name, _default=None: None
+    malformed = bool(errors)
+    message_id = get("Message-ID")
+    event_type = get("X-AgentDir-Event-Type")
+    subject = get("Subject")
+    from_actor = get("From")
+    to_actor = get("To")
+    session_id = get("X-AgentDir-Session")
+    task_id = get("X-AgentDir-Task")
+    date_header = get("Date")
+    date_utc = _date_to_utc_iso(date_header)
+    git_head = get("X-AgentDir-Git-Head")
+    workspace = get("X-AgentDir-Workspace")
+    tool = get("X-AgentDir-Tool")
+    tool_exit_code = _int_or_none(get("X-AgentDir-Tool-Exit-Code"))
+    indexed_at = now_iso()
+    cursor = conn.execute(
+        """
+        insert into messages(
+          message_id, mailbox_kind, mailbox_path, file_path, state, event_type,
+          subject, from_actor, to_actor, session_id, task_id, parent_message_id,
+          date_header, date_utc, created_ns, git_head, workspace, tool,
+          tool_exit_code, body_sha256, body_text, indexed_at,
+          malformed, errors
+        ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            message_id,
+            kind,
+            relative_mailbox,
+            relative_file,
+            state,
+            event_type,
+            subject,
+            from_actor,
+            to_actor,
+            session_id,
+            task_id,
+            get("In-Reply-To"),
+            date_header,
+            date_utc,
+            _int_or_none(get("X-AgentDir-Created-Ns")),
+            git_head,
+            workspace,
+            tool,
+            tool_exit_code,
+            body_sha,
+            body_text,
+            indexed_at,
+            1 if malformed else 0,
+            json.dumps(errors),
+        ),
+    )
+    rowid = int(cursor.lastrowid)
+    if msg is not None:
+        for name, value in msg.items():
+            conn.execute(
+                "insert into headers(message_rowid, name, value) values (?, ?, ?)",
+                (rowid, name, value),
+            )
+        for sha in msg.get_all("X-AgentDir-Blob-SHA256", []):
+            conn.execute(
+                "insert into message_artifacts(message_rowid, sha256) values (?, ?)",
+                (rowid, sha),
+            )
+    try:
+        conn.execute(
+            "insert into message_fts(rowid, message_id, subject, body_text) values (?, ?, ?, ?)",
+            (rowid, message_id, subject, body_text),
+        )
+    except sqlite3.DatabaseError:
+        pass
+    index_memory_document(
+        conn,
+        message_rowid=rowid,
+        message_id=message_id,
+        session_id=session_id,
+        event_type=event_type,
+        subject=subject,
+        from_actor=from_actor,
+        to_actor=to_actor,
+        task_id=task_id,
+        tool=tool,
+        tool_exit_code=tool_exit_code,
+        workspace=workspace,
+        git_head=git_head,
+        date_header=date_header,
+        date_utc=date_utc,
+        file_path=relative_file,
+        body_text=body_text,
+        indexed_at=indexed_at,
+    )
+    return rowid, message_id, malformed
+
+
+def _int_or_none(value: str | None) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def _date_to_utc_iso(value: str | None) -> str | None:
+    if value is None:
+        return None
+    try:
+        parsed = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=UTC)
+    return parsed.astimezone(UTC).isoformat()

agentdir/mailbox.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import os
+import secrets
+import socket
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+from .store import AgentDirError, ensure_mailbox
+
+_SEQUENCE = 0
+
+
+@dataclass(frozen=True)
+class MaildirRecord:
+    mailbox: Path
+    state: str
+    path: Path
+
+
+def _safe_hostname() -> str:
+    hostname = socket.gethostname() or "localhost"
+    return hostname.replace("/", "\\057").replace(":", "\\072").lstrip(".") or "localhost"
+
+
+def unique_basename() -> str:
+    global _SEQUENCE
+    _SEQUENCE += 1
+    basename = f"{time.time_ns()}.P{os.getpid()}Q{_SEQUENCE}R{secrets.token_hex(8)}.{_safe_hostname()}"
+    if "/" in basename or ":" in basename or basename.startswith("."):
+        raise AgentDirError("Generated unsafe Maildir basename")
+    return basename
+
+
+def fsync_directory(path: Path) -> None:
+    if not hasattr(os, "O_DIRECTORY"):
+        return
+    try:
+        fd = os.open(path, os.O_RDONLY | os.O_DIRECTORY)
+    except OSError:
+        return
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def atomic_deliver(mailbox: Path, data: bytes, basename: str | None = None) -> Path:
+    ensure_mailbox(mailbox)
+    for _ in range(20):
+        name = basename or unique_basename()
+        tmp_path = mailbox / "tmp" / name
+        new_path = mailbox / "new" / name
+        try:
+            fd = os.open(tmp_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        except FileExistsError:
+            basename = None
+            continue
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp_path, new_path)
+        fsync_directory(mailbox / "tmp")
+        fsync_directory(mailbox / "new")
+        return new_path
+    raise AgentDirError("Unable to create a unique Maildir filename")
+
+
+def iter_records(mailbox: Path, states: Iterable[str] = ("new", "cur")) -> list[MaildirRecord]:
+    records: list[MaildirRecord] = []
+    for state in states:
+        if state not in {"new", "cur"}:
+            continue
+        directory = mailbox / state
+        if not directory.is_dir():
+            continue
+        for path in sorted(directory.iterdir()):
+            if path.is_file() and not path.name.startswith("."):
+                records.append(MaildirRecord(mailbox=mailbox, state=state, path=path))
+    return records
+