pcli-agent 0.1.0__py3-none-any.whl

pcli/scheduler/runner.py

@@ -0,0 +1,84 @@
+"""Executes one task end-to-end against the headless runtime - the shared
+implementation behind both `pcli run` (cli.py) and a scheduled job firing
+(scheduler/daemon.py). Factored out so the two entry points can't drift:
+both build the same AgentRuntime, load/create the session the same way, run
+the same run_headless_task, and send the same optional Telegram
+notification.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pcli.agent.headless import (
+    HeadlessTurnResult,
+    ProgressCallback,
+    new_headless_session,
+    run_headless_task,
+)
+from pcli.agent.runtime import build_agent_runtime, build_permission_manager
+from pcli.config.settings import Settings
+from pcli.session.store import SessionNotFoundError, SessionStore
+from pcli.telegram.bot import notify_telegram
+
+
+class ScheduledSessionNotFoundError(Exception):
+    """Raised when a job's session_id no longer resolves to a real session
+    (e.g. it was deleted via `pcli sessions`) - the caller decides whether
+    that's fatal for this run or should fall back to a fresh session."""
+
+
+async def run_task_once(
+    task: str,
+    *,
+    settings: Settings,
+    store: SessionStore,
+    cwd: Path,
+    session_id: str | None = None,
+    quiet: bool = True,
+    headed: bool = False,
+    notify_telegram_flag: bool = False,
+    on_progress: ProgressCallback = lambda _line: None,
+) -> HeadlessTurnResult:
+    """Builds a fresh AgentRuntime, loads/creates the session, runs the
+    task, optionally notifies Telegram, and cleanly closes the runtime -
+    the same sequence `pcli run` has always done, now also used by a fired
+    scheduled job. Raises ScheduledSessionNotFoundError if session_id is
+    given but doesn't resolve (the runtime is still cleaned up first)."""
+    if session_id:
+        try:
+            session = store.load(session_id)
+        except SessionNotFoundError:
+            raise ScheduledSessionNotFoundError(session_id) from None
+    else:
+        session = new_headless_session(store, settings, cwd)
+
+    runtime = await build_agent_runtime(settings, cwd, browser_headless=not headed)
+    try:
+        result = await run_headless_task(
+            task,
+            session=session,
+            runtime=runtime,
+            settings=settings,
+            permission_manager=build_permission_manager(settings),
+            cwd=cwd,
+            store=store,
+            on_progress=on_progress,
+        )
+    finally:
+        await runtime.client.aclose()
+        await runtime.browser_session.close()
+
+    if notify_telegram_flag:
+        if not settings.is_telegram_configured():
+            on_progress(
+                "notify_telegram was requested but telegram_bot_token/telegram_chat_id aren't "
+                "configured - skipping the notification."
+            )
+        else:
+            try:
+                await notify_telegram(settings, result.final_text)
+            except Exception as exc:  # noqa: BLE001 - a failed notification shouldn't fail the run
+                on_progress(f"Failed to send the Telegram notification: {exc}")
+
+    return result

pcli/scheduler/store.py

@@ -0,0 +1,75 @@
+"""On-disk persistence for `pcli schedule`'s job list (scheduler/models.py) -
+mirrors memory/store.py's shape (a single JSON file under data_dir(),
+atomic-written, loaded fresh on every call rather than cached) so `pcli
+schedule add` from one process and `pcli schedule run`'s daemon loop in
+another always see each other's latest writes without needing to share
+in-memory state or restart anything."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from pcli.config.paths import schedule_file
+from pcli.scheduler.models import ScheduleJob, ScheduleStore
+
+
+def _atomic_write(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_suffix(path.suffix + ".tmp")
+    tmp_path.write_text(content, encoding="utf-8")
+    os.replace(tmp_path, path)
+
+
+def read_schedule() -> ScheduleStore:
+    path = schedule_file()
+    if not path.exists():
+        return ScheduleStore()
+    return ScheduleStore.model_validate_json(path.read_text(encoding="utf-8"))
+
+
+def write_schedule(store: ScheduleStore) -> None:
+    _atomic_write(schedule_file(), store.model_dump_json(indent=2))
+
+
+def add_job(job: ScheduleJob) -> ScheduleJob:
+    store = read_schedule()
+    store.jobs.append(job)
+    write_schedule(store)
+    return job
+
+
+def remove_job(job_id: str) -> bool:
+    """Returns whether anything was removed."""
+    store = read_schedule()
+    before = len(store.jobs)
+    store.jobs = [j for j in store.jobs if j.id != job_id]
+    if len(store.jobs) == before:
+        return False
+    write_schedule(store)
+    return True
+
+
+def get_job(job_id: str) -> ScheduleJob | None:
+    return next((j for j in read_schedule().jobs if j.id == job_id), None)
+
+
+def set_job_enabled(job_id: str, enabled: bool) -> bool:
+    """Returns whether a matching job was found and updated."""
+    store = read_schedule()
+    for job in store.jobs:
+        if job.id == job_id:
+            job.enabled = enabled
+            write_schedule(store)
+            return True
+    return False
+
+
+def update_job(job: ScheduleJob) -> None:
+    """Replaces the stored job with the same id as `job` - used to persist
+    daemon-side bookkeeping (next_run_at/last_run_at/last_status/last_error)
+    after a run, without the caller needing to hand-roll the read/mutate/
+    write cycle itself."""
+    store = read_schedule()
+    store.jobs = [job if j.id == job.id else j for j in store.jobs]
+    write_schedule(store)

pcli/scheduler/triggers.py

@@ -0,0 +1,84 @@
+"""Signature computation for the two event-based ScheduleJob trigger kinds
+(scheduler/models.py's "file_change"/"git_commit") - both are polled by
+scheduler/daemon.py exactly like a cron job's next_run_at, just comparing a
+cheap signature instead of a timestamp. No new dependency: file signatures
+are plain os.stat() calls (no file contents read, binary-safe), and git
+commit lookups just shell out to `git rev-parse` - there's nothing here a
+file-watching library or GitPython would meaningfully simplify for a single
+poll-driven check."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import subprocess
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_MISSING_PATH_SENTINEL = "missing"
+
+
+def compute_path_signature(path: Path) -> str:
+    """A sha256 hex digest over the sorted (relative_path, mtime_ns, size)
+    of every file under `path` (or just `path` itself if it's a file) -
+    changes whenever a watched file is added, removed, or modified,
+    without reading any file's actual contents. Any path component named
+    ".git" is skipped, so watching a repo's working tree doesn't fire on
+    the repo's own internal bookkeeping. A path that doesn't exist yet (or
+    no longer exists) gets a constant sentinel signature, so "still
+    missing" is never treated as a change - only the path reappearing is."""
+    if not path.exists():
+        return _MISSING_PATH_SENTINEL
+
+    if path.is_file():
+        files = [path]
+    else:
+        files = sorted(p for p in path.rglob("*") if p.is_file() and ".git" not in p.parts)
+
+    entries = []
+    for file_path in files:
+        try:
+            stat = file_path.stat()
+        except OSError:
+            # Deleted between the rglob listing and this stat() call -
+            # treat as simply absent from this signature, not an error.
+            continue
+        try:
+            relative = file_path.relative_to(path)
+        except ValueError:
+            relative = file_path
+        entries.append(f"{relative.as_posix()}:{stat.st_mtime_ns}:{stat.st_size}")
+
+    digest = hashlib.sha256("\n".join(sorted(entries)).encode("utf-8"))
+    return digest.hexdigest()
+
+
+def get_git_head_sha(repo_path: Path, branch: str | None) -> str | None:
+    """Runs `git rev-parse {branch or 'HEAD'}` in repo_path. Returns None
+    (logged as a warning, not raised) if git isn't installed, repo_path
+    isn't a git repo, or branch doesn't exist - the daemon just skips that
+    job for this poll rather than marking it an error, since this is
+    typically a transient/config issue that resolves itself (e.g. the repo
+    hasn't been cloned yet) rather than a real job failure."""
+    ref = branch or "HEAD"
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", ref],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        logger.warning("Couldn't run git in %s: %s", repo_path, exc)
+        return None
+
+    if result.returncode != 0:
+        logger.warning(
+            "git rev-parse %s failed in %s: %s", ref, repo_path, result.stderr.strip()
+        )
+        return None
+
+    return result.stdout.strip()

pcli/session/audit.py

@@ -0,0 +1,122 @@
+"""Tamper-evident audit log: a hash-chained record of permission decisions
+and tool calls, kept alongside - not instead of - Session.tool_invocations/
+permission_grants. Opt-in (Settings.audit_mode_enabled), for regulated-
+industry use where a user needs to prove, after the fact, what an
+unattended agent actually did and that the record wasn't edited later.
+
+The chain primitive is deliberately simple: each entry's hash covers its
+own content plus the previous entry's hash, same as a git commit or a
+certificate-transparency log. No new dependency (stdlib hashlib/json
+only), no signing/external timestamping service - that would be real
+complexity for marginal benefit over what a plain SHA-256 chain already
+gives: editing, reordering, or deleting an old entry breaks the chain from
+that point forward, and the break can't be silently repaired without
+re-deriving every hash after it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import BaseModel, Field
+
+from pcli.util.ids import new_id
+
+if TYPE_CHECKING:
+    from pcli.session.models import Session
+
+_GENESIS_HASH = "0" * 64
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+class AuditEntry(BaseModel):
+    id: str = Field(default_factory=lambda: new_id("audit_"))
+    created_at: datetime = Field(default_factory=_utcnow)
+    kind: Literal["tool_call", "permission_decision"]
+    summary: str
+    """Human-readable one-liner, e.g. 'read_file allowed' or 'run_shell
+    denied: command matched denylist entry'."""
+    detail: dict[str, Any] = Field(default_factory=dict)
+    """kind-specific structured payload - see append_audit_entry's callers
+    (agent/runtime.py's record_tool_invocation, permissions/manager.py's
+    check_with_reason) for the exact fields each kind carries."""
+    prev_hash: str
+    """The previous entry's entry_hash, or _GENESIS_HASH for the first
+    entry in a session's chain."""
+    entry_hash: str
+    """sha256 over a canonical (sort_keys=True) JSON serialization of
+    every field above except this one - see _compute_hash."""
+
+
+@dataclass
+class AuditVerification:
+    valid: bool
+    entry_count: int
+    broken_at_index: int | None = None
+    reason: str | None = None
+
+
+def _hashable_payload(entry: AuditEntry) -> dict[str, Any]:
+    return {
+        "id": entry.id,
+        "created_at": entry.created_at.isoformat(),
+        "kind": entry.kind,
+        "summary": entry.summary,
+        "detail": entry.detail,
+        "prev_hash": entry.prev_hash,
+    }
+
+
+def _compute_hash(payload: dict[str, Any]) -> str:
+    canonical = json.dumps(payload, sort_keys=True, default=str)
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def append_audit_entry(
+    session: Session, *, kind: Literal["tool_call", "permission_decision"], summary: str, detail: dict[str, Any]
+) -> AuditEntry:
+    """Appends one entry to session.audit_log, chained onto whatever's
+    already there. Callers gate this behind Settings.audit_mode_enabled
+    themselves (agent/runtime.py's record_tool_invocation, permissions/
+    manager.py's PermissionManager) - this function always appends
+    unconditionally when called, same as Session.decisions/
+    tool_invocations never gate themselves either."""
+    prev_hash = session.audit_log[-1].entry_hash if session.audit_log else _GENESIS_HASH
+    entry = AuditEntry(kind=kind, summary=summary, detail=detail, prev_hash=prev_hash, entry_hash="")
+    entry.entry_hash = _compute_hash(_hashable_payload(entry))
+    session.audit_log.append(entry)
+    return entry
+
+
+def verify_audit_chain(session: Session) -> AuditVerification:
+    """Recomputes every entry's hash from its recorded fields and checks
+    prev_hash linkage - an empty log is valid (nothing to verify, not an
+    error: audit_mode_enabled may simply have been off for this session)."""
+    expected_prev = _GENESIS_HASH
+    for index, entry in enumerate(session.audit_log):
+        if entry.prev_hash != expected_prev:
+            return AuditVerification(
+                valid=False,
+                entry_count=len(session.audit_log),
+                broken_at_index=index,
+                reason="prev_hash does not match the preceding entry's hash - an entry was "
+                "likely reordered or deleted",
+            )
+        recomputed = _compute_hash(_hashable_payload(entry))
+        if recomputed != entry.entry_hash:
+            return AuditVerification(
+                valid=False,
+                entry_count=len(session.audit_log),
+                broken_at_index=index,
+                reason="entry_hash does not match the recomputed hash - this entry's content "
+                "was modified after it was recorded",
+            )
+        expected_prev = entry.entry_hash
+    return AuditVerification(valid=True, entry_count=len(session.audit_log))

pcli/session/directory_check.py

@@ -0,0 +1,28 @@
+"""Warns (never blocks) when a session is resumed from a different directory
+than where it was created - every relative path in its tool-call history
+resolves against that original directory, so a mismatch is worth surfacing
+before continuing, not silently ignoring. Deliberately its own tiny module
+(not a method on Session) so both the TUI's session picker and the CLI's
+--resume flag can share the exact same check without depending on Textual
+or Typer."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pcli.session.models import Session
+
+
+def directory_mismatch(session: Session, cwd: Path) -> str | None:
+    """None if there's nothing to warn about (no recorded working_dir, or it
+    matches cwd); otherwise a human-readable warning message."""
+    if not session.working_dir:
+        return None
+    stored = Path(session.working_dir)
+    if stored.expanduser().resolve() == cwd.expanduser().resolve():
+        return None
+    return (
+        f"This session was last run in {session.working_dir}, but you're currently in "
+        f"{cwd}. Relative paths in its history (and any new tool calls) will resolve "
+        "against the current directory, not the original one."
+    )

pcli/session/export.py

@@ -0,0 +1,57 @@
+"""Exports a session to a portable, self-contained .pcli-session.json[.gz] file.
+
+The gateway API key is never part of the Session model in the first place, so
+there is nothing to redact there. `permission_grants` travels with the export
+for fidelity, but importer.py drops it by default (see importer.py docstring)
+so an imported session can't silently grant shell access on the new machine.
+"""
+
+from __future__ import annotations
+
+import gzip
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pcli import __version__
+from pcli.session.models import Session
+from pcli.session.store import SessionStore
+
+FORMAT_NAME = "pcli-session"
+FORMAT_VERSION = 1
+
+
+def export_session(
+    session: Session,
+    out_path: Path,
+    *,
+    store: SessionStore | None = None,
+    use_gzip: bool | None = None,
+) -> Path:
+    store = store or SessionStore()
+    if use_gzip is None:
+        use_gzip = out_path.suffix == ".gz"
+
+    blobs: dict[str, str] = {}
+    for invocation in session.tool_invocations:
+        if invocation.full_result_ref:
+            blobs[invocation.full_result_ref] = store.read_blob(
+                session.id, invocation.full_result_ref
+            )
+
+    envelope = {
+        "format": FORMAT_NAME,
+        "format_version": FORMAT_VERSION,
+        "exported_at": datetime.now(UTC).isoformat(),
+        "pcli_version": __version__,
+        "session": json.loads(session.model_dump_json()),
+        "blobs": blobs,
+    }
+
+    body = json.dumps(envelope, indent=2).encode("utf-8")
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    if use_gzip:
+        out_path.write_bytes(gzip.compress(body))
+    else:
+        out_path.write_bytes(body)
+    return out_path

pcli/session/importer.py

@@ -0,0 +1,92 @@
+"""Imports a session exported by session/export.py.
+
+Three deliberate safety choices:
+- `permission_grants` is dropped unless `restore_grants=True` is passed
+  explicitly, so an imported session can't silently carry "always allow
+  shell" grants onto a new machine.
+- The session always gets a *new* id on import (the original id is kept in
+  metadata for traceability) so importing never collides with / overwrites
+  an existing local session.
+- `working_dir` is always cleared: it names a directory on whatever machine
+  originally created the session, essentially never the importing one, so
+  keeping it would just make every resume trip the directory-mismatch
+  warning (session/directory_check.py) for no reason - export/import is a
+  deliberate move to a new place, not an accidental one.
+"""
+
+from __future__ import annotations
+
+import gzip
+import json
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from pcli.session.export import FORMAT_NAME, FORMAT_VERSION
+from pcli.session.models import Session
+from pcli.session.store import SessionStore
+
+
+class SessionImportError(Exception):
+    pass
+
+
+# Each entry migrates a raw session dict from its key version to key+1.
+# e.g. {1: _migrate_v1_to_v2} once format_version 2 exists.
+_MIGRATIONS: dict[int, Callable[[dict[str, Any]], dict[str, Any]]] = {}
+
+
+def _read_envelope(path: Path) -> dict[str, Any]:
+    raw = path.read_bytes()
+    if raw[:2] == b"\x1f\x8b":  # gzip magic bytes
+        raw = gzip.decompress(raw)
+    return json.loads(raw.decode("utf-8"))
+
+
+def import_session(
+    path: Path,
+    *,
+    store: SessionStore | None = None,
+    restore_grants: bool = False,
+) -> Session:
+    store = store or SessionStore()
+    envelope = _read_envelope(path)
+
+    if envelope.get("format") != FORMAT_NAME:
+        raise SessionImportError(f"Not a pcli session export: {path}")
+
+    version = envelope.get("format_version")
+    if not isinstance(version, int):
+        raise SessionImportError(f"Missing/invalid format_version in {path}")
+    if version > FORMAT_VERSION:
+        raise SessionImportError(
+            f"{path} was exported by a newer pcli (format_version={version}); "
+            f"this pcli supports up to {FORMAT_VERSION}. Upgrade pcli to import it."
+        )
+
+    session_data = envelope["session"]
+    while version < FORMAT_VERSION:
+        migrate = _MIGRATIONS.get(version)
+        if migrate is None:
+            raise SessionImportError(f"No migration registered from format_version {version}")
+        session_data = migrate(session_data)
+        version += 1
+
+    original_id = session_data.pop("id", None)
+    if not restore_grants:
+        session_data["permission_grants"] = []
+    session_data["working_dir"] = None
+
+    session = Session.model_validate(session_data)
+    session.metadata["imported_from_id"] = original_id
+    session.metadata["imported_from_file"] = str(path)
+
+    blobs: dict[str, str] = envelope.get("blobs", {})
+    for invocation in session.tool_invocations:
+        if invocation.full_result_ref and invocation.full_result_ref in blobs:
+            store.write_blob_named(
+                session.id, invocation.full_result_ref, blobs[invocation.full_result_ref]
+            )
+
+    store.save(session)
+    return session