pcli-agent 0.1.0__py3-none-any.whl

pcli/session/models.py

@@ -0,0 +1,168 @@
+"""Persisted session data model."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from pcli.llm.models import ChatMessage, Role, ToolCall, Usage
+from pcli.session.audit import AuditEntry
+from pcli.util.ids import new_id
+
+CURRENT_SCHEMA_VERSION = 1
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+class Message(BaseModel):
+    id: str = Field(default_factory=lambda: new_id("msg_"))
+    role: Role
+    content: str | None = None
+    tool_calls: list[ToolCall] | None = None
+    tool_call_id: str | None = None
+    name: str | None = None
+    created_at: datetime = Field(default_factory=_utcnow)
+    pruned_artifact_id: str | None = None
+    """Set when this tool-role message's content has been replaced with a
+    compact placeholder by agent/context_pruning.py's prune_old_tool_results
+    — the original full content was archived first (retrievable via
+    fetch_artifact), and this field is the idempotency guard preventing a
+    message from being re-archived/re-pruned on a later call."""
+
+    def to_chat_message(self) -> ChatMessage:
+        return ChatMessage(
+            role=self.role,
+            content=self.content,
+            tool_calls=self.tool_calls,
+            tool_call_id=self.tool_call_id,
+            name=self.name,
+        )
+
+    @classmethod
+    def from_chat_message(cls, message: ChatMessage) -> Message:
+        return cls(
+            role=message.role,
+            content=message.content,
+            tool_calls=message.tool_calls,
+            tool_call_id=message.tool_call_id,
+            name=message.name,
+        )
+
+
+class ToolInvocation(BaseModel):
+    id: str = Field(default_factory=lambda: new_id("inv_"))
+    tool_name: str
+    arguments: dict[str, Any] = Field(default_factory=dict)
+    result_summary: str = ""
+    full_result_ref: str | None = None
+    """Blob filename (relative to the session's blobs/ dir) holding the full,
+    untruncated result, when it was too large to inline in result_summary."""
+    status: Literal["ok", "error", "denied"] = "ok"
+    backend: str | None = None
+    duration_ms: float | None = None
+    permission_decision: str | None = None
+    created_at: datetime = Field(default_factory=_utcnow)
+
+
+class TurnCost(BaseModel):
+    turn_index: int
+    model: str
+    usage: Usage
+    cost_usd: float
+    estimated: bool = False
+    created_at: datetime = Field(default_factory=_utcnow)
+    source: Literal["main", "subagent", "compaction", "memory"] = "main"
+    """Which conversation this usage actually came from. cost/context.py's
+    current_context_usage/looks_like_context_ceiling need this to find the
+    last *main*-conversation entry specifically — a subagent's,
+    compaction's, or memory extraction's own usage is real spend (still
+    counted in SessionCost.total_tokens/session_total_usd) but reflects a
+    completely different, unrelated conversation's size, not how full the
+    main conversation's context window actually is. Defaults to "main" so a
+    session persisted before this field existed still validates and behaves
+    exactly as it did before (every entry was implicitly a main-turn entry
+    back then)."""
+
+
+class SessionCost(BaseModel):
+    turns: list[TurnCost] = Field(default_factory=list)
+    session_total_usd: float = 0.0
+    total_tokens: int = 0
+
+
+class PermissionGrant(BaseModel):
+    tool_name: str
+    argument_pattern: str | None = None
+    scope: Literal["session", "always"] = "session"
+    decision: Literal["allow", "deny"] = "allow"
+    created_at: datetime = Field(default_factory=_utcnow)
+
+
+class TodoItem(BaseModel):
+    content: str
+    status: Literal["pending", "in_progress", "completed"] = "pending"
+
+
+class Decision(BaseModel):
+    """One entry in the session's decision log (see tools/builtin/decision_tool.py).
+    Append-only audit trail — unlike TodoItem, an entry is never mutated once
+    recorded; a change of mind is a new entry, not an edit of the old one."""
+
+    decision: str
+    rationale: str
+    created_at: datetime = Field(default_factory=_utcnow)
+
+
+class Session(BaseModel):
+    id: str = Field(default_factory=lambda: new_id("sess_"))
+    schema_version: int = CURRENT_SCHEMA_VERSION
+    created_at: datetime = Field(default_factory=_utcnow)
+    updated_at: datetime = Field(default_factory=_utcnow)
+    title: str | None = None
+    model: str = ""
+    gateway_base_url: str = ""
+    messages: list[Message] = Field(default_factory=list)
+    tool_invocations: list[ToolInvocation] = Field(default_factory=list)
+    cost: SessionCost = Field(default_factory=SessionCost)
+    permission_grants: list[PermissionGrant] = Field(default_factory=list)
+    todos: list[TodoItem] = Field(default_factory=list)
+    decisions: list[Decision] = Field(default_factory=list)
+    audit_log: list[AuditEntry] = Field(default_factory=list)
+    """Tamper-evident, hash-chained record of permission decisions and
+    tool calls - see session/audit.py. Empty unless Settings.
+    audit_mode_enabled was on when this session ran; append-only, same as
+    decisions/tool_invocations."""
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    working_dir: str | None = None
+    """Where this session was created (Path.cwd() at the time) - resuming it
+    from a different directory means every relative path in its tool-call
+    history refers to a different set of files, so callers check this
+    against the current cwd before resuming (see session/directory_check.py)
+    and warn rather than silently proceeding. None for a session persisted
+    before this field existed, or one that was never tied to a real cwd
+    (e.g. some test fixtures) - never treated as a mismatch."""
+
+    def touch(self) -> None:
+        self.updated_at = _utcnow()
+
+    def derive_title(self) -> str:
+        if self.title:
+            return self.title
+        for message in self.messages:
+            if message.role == "user" and message.content:
+                text = message.content.strip().splitlines()[0]
+                return text[:60] + ("..." if len(text) > 60 else "")
+        return "New session"
+
+
+class SessionIndexEntry(BaseModel):
+    id: str
+    title: str
+    updated_at: datetime
+    model: str
+    message_count: int
+    total_cost_usd: float

pcli/session/store.py

@@ -0,0 +1,127 @@
+"""On-disk CRUD for sessions, plus a fast index for listing without loading
+every session file in full."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterable
+from pathlib import Path
+
+from pcli.config.paths import sessions_dir
+from pcli.session.models import Session, SessionIndexEntry
+
+
+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)
+
+
+class SessionNotFoundError(Exception):
+    pass
+
+
+class SessionStore:
+    def __init__(self, base_dir: Path | None = None) -> None:
+        self._base_dir = base_dir or sessions_dir()
+        self._index_path = self._base_dir / "index.json"
+
+    def session_dir(self, session_id: str) -> Path:
+        return self._base_dir / session_id
+
+    def blobs_dir(self, session_id: str) -> Path:
+        return self.session_dir(session_id) / "blobs"
+
+    def _session_file(self, session_id: str) -> Path:
+        return self.session_dir(session_id) / "session.json"
+
+    def new_session(
+        self, *, model: str = "", gateway_base_url: str = "", working_dir: str | None = None
+    ) -> Session:
+        session = Session(model=model, gateway_base_url=gateway_base_url, working_dir=working_dir)
+        self.save(session)
+        return session
+
+    def save(self, session: Session) -> None:
+        session.touch()
+        _atomic_write(
+            self._session_file(session.id), session.model_dump_json(indent=2)
+        )
+        self._upsert_index(session)
+
+    def load(self, session_id: str) -> Session:
+        path = self._session_file(session_id)
+        if not path.exists():
+            raise SessionNotFoundError(session_id)
+        return Session.model_validate_json(path.read_text(encoding="utf-8"))
+
+    def delete(self, session_id: str) -> None:
+        import shutil
+
+        session_dir = self.session_dir(session_id)
+        if session_dir.exists():
+            shutil.rmtree(session_dir)
+        index = self._read_index()
+        index.pop(session_id, None)
+        self._write_index(index)
+
+    def list_index(self) -> list[SessionIndexEntry]:
+        index = self._read_index()
+        entries = [SessionIndexEntry.model_validate(v) for v in index.values()]
+        return sorted(entries, key=lambda e: e.updated_at, reverse=True)
+
+    def prune_empty_sessions(self, *, exclude_session_ids: Iterable[str] = ()) -> int:
+        """Deletes every persisted session with zero messages. new_session()
+        saves eagerly the moment a fresh session is created (before the
+        leading system prompt is even appended in ChatScreen.__init__), so
+        closing pcli without ever sending a message leaves a useless,
+        never-touched entry cluttering /sessions — this is the only way a
+        session ends up with message_count == 0, since messages are only
+        ever appended, never removed (even a turn that fails outright still
+        persists the system prompt + the user's message first). Returns how
+        many were pruned."""
+        exclude = set(exclude_session_ids)
+        pruned = 0
+        for entry in self.list_index():
+            if entry.message_count == 0 and entry.id not in exclude:
+                self.delete(entry.id)
+                pruned += 1
+        return pruned
+
+    def write_blob(self, session_id: str, invocation_id: str, content: str) -> str:
+        blob_name = f"{invocation_id}.txt"
+        self.write_blob_named(session_id, blob_name, content)
+        return blob_name
+
+    def write_blob_named(self, session_id: str, blob_name: str, content: str) -> None:
+        """Writes a blob under an exact filename (no '.txt' appended) — used
+        by the importer to restore blobs under their original blob_name."""
+        blob_path = self.blobs_dir(session_id) / blob_name
+        _atomic_write(blob_path, content)
+
+    def read_blob(self, session_id: str, blob_name: str) -> str:
+        blob_path = self.blobs_dir(session_id) / blob_name
+        return blob_path.read_text(encoding="utf-8")
+
+    def _read_index(self) -> dict[str, dict]:
+        if not self._index_path.exists():
+            return {}
+        return json.loads(self._index_path.read_text(encoding="utf-8"))
+
+    def _write_index(self, index: dict[str, dict]) -> None:
+        _atomic_write(self._index_path, json.dumps(index, indent=2, default=str))
+
+    def _upsert_index(self, session: Session) -> None:
+        index = self._read_index()
+        entry = SessionIndexEntry(
+            id=session.id,
+            title=session.derive_title(),
+            updated_at=session.updated_at,
+            model=session.model,
+            message_count=len(session.messages),
+            total_cost_usd=session.cost.session_total_usd,
+        )
+        index[session.id] = json.loads(entry.model_dump_json())
+        self._write_index(index)

pcli/telegram/bot.py

@@ -0,0 +1,266 @@
+"""run_telegram_daemon: the actual python-telegram-bot wiring behind `pcli
+telegram` (cli.py) - builds an Application, registers handlers that
+forward to TelegramDaemon's public methods (daemon.py, where the real
+business logic and its test coverage live), and runs until stopped.
+
+python-telegram-bot (the optional "telegram" extra - see pyproject.toml)
+is imported lazily inside this function, not at module level, so pcli
+imports and runs fine with the extra not installed - same discipline as
+browser/session.py's Playwright import and telegram/sender.py's own.
+
+This module is deliberately thin glue around TelegramDaemon, in the same
+spirit browser/session.py's _ensure_page is thin glue around Playwright's
+own launch call - the business logic it wires up (message queueing,
+authorization, permission correlation) is what's heavily unit tested
+(test_telegram_daemon.py, test_telegram_permissions.py); this function's
+own handler-registration/lifecycle wiring gets lighter, fake-PTB coverage
+(test_telegram_bot.py) rather than an exhaustive one, since faithfully
+reproducing PTB's full Application/Updater lifecycle in a fake would cost
+far more than it would ever catch.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+
+from pcli.agent.runtime import build_agent_runtime, build_permission_manager
+from pcli.config.settings import Settings
+from pcli.session.store import SessionStore
+from pcli.telegram.daemon import TelegramDaemon
+from pcli.telegram.sender import BotSender
+
+logger = logging.getLogger(__name__)
+
+
+async def notify_telegram(settings: Settings, text: str) -> None:
+    """A one-off message to the configured chat, independent of the full
+    daemon above - what `pcli run --notify-telegram` uses to report a
+    scheduled run's result without needing a whole Application/polling
+    loop just to send one outgoing message. Callers check
+    settings.is_telegram_configured() themselves first (see cli.py) - this
+    assumes both fields are already set."""
+    from telegram import Bot  # type: ignore[import-not-found]
+
+    async with Bot(settings.telegram_bot_token) as bot:
+        await BotSender(bot).send_message(settings.telegram_chat_id, text)
+
+
+async def run_telegram_daemon(
+    settings: Settings,
+    cwd: Path,
+    *,
+    on_ready: Callable[[str], None] = lambda _session_id: None,
+    stop_event: asyncio.Event | None = None,
+) -> None:
+    """Runs until `stop_event` is set (or the process receives Ctrl+C,
+    propagating as KeyboardInterrupt/CancelledError through the wait
+    below) - a fresh, internal Event by default, so a plain `await
+    run_telegram_daemon(settings, cwd)` in cli.py blocks forever, exactly
+    what a long-running daemon should do. Tests pass an already-set Event
+    to make this return promptly instead.
+
+    `on_ready(session_id)` fires once polling has actually started -
+    cli.py uses it to print a confirmation with something to reference
+    (`pcli --resume <session_id>` after the daemon stops)."""
+    from telegram import Update  # type: ignore[import-not-found]
+    from telegram.ext import (  # type: ignore[import-not-found]
+        ApplicationBuilder,
+        CallbackQueryHandler,
+        CommandHandler,
+        ContextTypes,
+        MessageHandler,
+        filters,
+    )
+
+    runtime = await build_agent_runtime(settings, cwd, browser_headless=True)
+    store = SessionStore()
+    permission_manager = build_permission_manager(settings)
+
+    application = ApplicationBuilder().token(settings.telegram_bot_token).build()
+    sender = BotSender(application.bot)
+    daemon = TelegramDaemon(
+        settings=settings,
+        runtime=runtime,
+        permission_manager=permission_manager,
+        store=store,
+        cwd=cwd,
+        sender=sender,
+    )
+
+    async def on_text(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        chat = update.effective_chat
+        message = update.effective_message
+        if chat is not None and message is not None and message.text:
+            await daemon.handle_text(chat.id, message.text)
+
+    async def on_new_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        if update.effective_chat is not None:
+            await daemon.handle_new_command(update.effective_chat.id)
+
+    async def on_rename_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        chat = update.effective_chat
+        if chat is None:
+            return
+        arg = " ".join(context.args) if context.args else None
+        await daemon.handle_rename_command(chat.id, arg)
+
+    async def on_allowed_roots_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        chat = update.effective_chat
+        if chat is None:
+            return
+        rest = " ".join(context.args) if context.args else ""
+        await daemon.handle_allowed_roots_command(chat.id, rest)
+
+    async def on_memory_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        chat = update.effective_chat
+        if chat is None:
+            return
+        rest = " ".join(context.args) if context.args else ""
+        await daemon.handle_memory_command(chat.id, rest)
+
+    async def on_help_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        if update.effective_chat is not None:
+            await daemon.handle_help_command(update.effective_chat.id)
+
+    async def on_toolbox_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        chat = update.effective_chat
+        if chat is None:
+            return
+        rest = " ".join(context.args) if context.args else ""
+        await daemon.handle_toolbox_command(chat.id, rest)
+
+    async def on_compact_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        if update.effective_chat is not None:
+            await daemon.handle_compact_command(update.effective_chat.id)
+
+    async def on_models_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        chat = update.effective_chat
+        if chat is None:
+            return
+        arg = " ".join(context.args) if context.args else None
+        await daemon.handle_models_command(chat.id, arg)
+
+    async def on_sessions_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        chat = update.effective_chat
+        if chat is None:
+            return
+        rest = " ".join(context.args) if context.args else ""
+        await daemon.handle_sessions_command(chat.id, rest)
+
+    async def on_export_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        chat = update.effective_chat
+        if chat is None:
+            return
+        arg = " ".join(context.args) if context.args else None
+        await daemon.handle_export_command(chat.id, arg)
+
+    async def on_plan_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        if update.effective_chat is not None:
+            await daemon.handle_plan_command(update.effective_chat.id)
+
+    async def on_build_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        if update.effective_chat is not None:
+            await daemon.handle_build_command(update.effective_chat.id)
+
+    async def on_unsupported_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        chat = update.effective_chat
+        message = update.effective_message
+        if chat is None or message is None or not message.text:
+            return
+        command = message.text.split()[0] if message.text.split() else message.text
+        await daemon.handle_unsupported_command(chat.id, command)
+
+    # Telegram bot commands can only contain [A-Za-z0-9_] - no hyphens - so
+    # every hyphenated TUI command name below is spelled with underscores
+    # here instead (e.g. /context-limit -> /context_limit). A single
+    # CommandHandler registered against all these names, routed by this one
+    # dict, instead of ten near-identical PTB handler registrations.
+    scalar_setting_commands: dict[str, Callable[[int, str | None], Awaitable[None]]] = {
+        "timeout": daemon.handle_timeout_command,
+        "temperature": daemon.handle_temperature_command,
+        "budget": daemon.handle_budget_command,
+        "context_limit": daemon.handle_context_limit_command,
+        "max_tool_iterations": daemon.handle_max_tool_iterations_command,
+        "artifact_threshold": daemon.handle_artifact_threshold_command,
+        "max_tool_calls_per_turn": daemon.handle_max_tool_calls_per_turn_command,
+        "max_tool_calls_per_minute": daemon.handle_max_tool_calls_per_minute_command,
+        "prune_tool_results": daemon.handle_prune_tool_results_command,
+        "max_response_tokens": daemon.handle_max_response_tokens_command,
+    }
+
+    async def on_scalar_setting_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        chat = update.effective_chat
+        message = update.effective_message
+        if chat is None or message is None or not message.text:
+            return
+        tokens = message.text.split()
+        if not tokens:
+            return
+        command = tokens[0][1:].partition("@")[0]  # drop leading "/" and any "@botname" suffix
+        handler = scalar_setting_commands.get(command)
+        if handler is None:
+            return
+        arg = " ".join(context.args) if context.args else None
+        await handler(chat.id, arg)
+
+    async def on_callback_query(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        query = update.callback_query
+        if query is None:
+            return
+        await query.answer()
+        if query.data:
+            await daemon.handle_callback(query.data)
+        try:
+            # Best-effort - clears the buttons so a decision can't be
+            # pressed twice. Not fatal if the message is too old/already
+            # edited for Telegram to allow this.
+            await query.edit_message_reply_markup(reply_markup=None)
+        except Exception:
+            logger.debug("Could not clear the inline keyboard after a decision", exc_info=True)
+
+    application.add_handler(CommandHandler("new", on_new_command))
+    application.add_handler(CommandHandler("rename", on_rename_command))
+    application.add_handler(CommandHandler("allowed_roots", on_allowed_roots_command))
+    application.add_handler(CommandHandler("memory", on_memory_command))
+    application.add_handler(CommandHandler("help", on_help_command))
+    application.add_handler(CommandHandler("toolbox", on_toolbox_command))
+    application.add_handler(CommandHandler("compact", on_compact_command))
+    application.add_handler(CommandHandler("models", on_models_command))
+    application.add_handler(CommandHandler("sessions", on_sessions_command))
+    application.add_handler(CommandHandler("export", on_export_command))
+    application.add_handler(CommandHandler("plan", on_plan_command))
+    application.add_handler(CommandHandler("build", on_build_command))
+    application.add_handler(
+        CommandHandler(list(scalar_setting_commands), on_scalar_setting_command)
+    )
+    # Must come before the plain-text handler below and after the specific
+    # command handlers above: filters.COMMAND matches any /word-shaped
+    # message, not just registered ones, so without this anything not
+    # explicitly registered matched no handler at all and was silently
+    # dropped by PTB itself - never even reaching TelegramDaemon. See
+    # handle_unsupported_command's own docstring.
+    application.add_handler(MessageHandler(filters.COMMAND, on_unsupported_command))
+    application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, on_text))
+    application.add_handler(CallbackQueryHandler(on_callback_query))
+
+    worker = asyncio.create_task(daemon.run_forever())
+    try:
+        async with application:
+            await application.start()
+            await application.updater.start_polling()
+            on_ready(daemon.session_id)
+            wait_for = stop_event if stop_event is not None else asyncio.Event()
+            try:
+                await wait_for.wait()
+            except (KeyboardInterrupt, asyncio.CancelledError):
+                pass
+            finally:
+                await application.updater.stop()
+                await application.stop()
+    finally:
+        worker.cancel()
+        await runtime.client.aclose()
+        await runtime.browser_session.close()