agentic-cli 0.5.1__tar.gz → 0.5.3__tar.gz

{agentic_cli-0.5.1 → agentic_cli-0.5.3}/CHANGELOG.md

@@ -5,6 +5,51 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.5.3] - 2026-06-14
+
+### Added
+- **Session fact extraction now runs on exit** (`auto_extract_session_facts`): `BaseWorkflowManager.on_session_end()` is invoked from the CLI shutdown path (`BaseCLIApp._extract_session_facts_on_exit`), extracting key facts/preferences from the conversation into memory. Previously the hook had no call site. `on_session_end()` now also sources the session messages itself (from the live backend session) when called with no arguments; it remains a safe no-op without a memory store, and never blocks shutdown.
+
+### Removed
+- **Tool Reflection Store removed** (`save_reflection` tool, `ReflectionStore`, `REFLECTION_STORE`, and the `enable_tool_reflections` setting). Introduced in v0.5.0 as a "cross-session learning primitive," it shipped only as a standalone store + tool — the planned injection and session-end wiring were never completed, so it was inert from v0.5.0 through v0.5.2 (the v0.5.0 changelog's "wired via session-end hook" was inaccurate). The design also conflated mechanical failure-capture with LLM heuristic synthesis in a single opportunistic tool the model had to remember to call. Removed rather than finished; tool-failure heuristics, if wanted later, are better served by automatic capture + session-end synthesis (mirroring `auto_extract_session_facts`) or by tagged entries in the existing memory store.
+
+### Security
+- **`grep` ripgrep argument injection fixed** (`tools/grep_tool.py`): the LLM-supplied `pattern` was passed to ripgrep as a bare positional, so a value like `--pre=<cmd>` was parsed as a flag and could run an arbitrary program per searched file — remote code execution holding only `filesystem.read`. The pattern is now passed via `-e` and option parsing is terminated with `--` before the path, so neither can be interpreted as a flag.
+- **`execute_python` library escape closed** (`tools/executor.py`): the AST/name allow-list cannot neutralize `numpy`/`pandas`/`scipy`/`sklearn`/`matplotlib`, which re-expose file, network, and pickle I/O through public APIs (e.g. `numpy.DataSource().open()`, `pandas.read_pickle(url)`) — an escape from the in-process restrictions (arbitrary file read, pickle-based code execution) when no OS sandbox is active. These `SANDBOXED_MODULES` are now importable **only when `os_sandbox_enabled=True`**; without it, only the pure-computation `CORE_MODULES` are available. The class docstring now states that the AST validation is defense-in-depth, not a security boundary.
+- **arXiv PDF download SSRF fixed** (`tools/arxiv_source.py`): `download_pdf` issued a raw `httpx.get(follow_redirects=True)` with no URL validation or size cap on a `pdf_url` taken from a remote Atom feed — bypassing the hardened `ContentFetcher`. It now routes through `get_or_create_fetcher().fetch()`, inheriting SSRF validation (private-IP/redirect blocking), DNS-rebinding checks, and the byte cap. The arXiv API endpoints were also switched from plaintext HTTP to HTTPS to remove the on-path feed-rewrite vector.
+
+### Changed
+- **`execute_python` no longer exposes `numpy`/`pandas` (etc.) by default.** Enabling them requires `os_sandbox_enabled=True` (with `sandbox-exec` on macOS or `bwrap` on Linux). This is a deliberate, user-visible reduction of the default capability surface.
+
+### Fixed
+- **ADK session resume was a silent no-op** (`workflow/adk/manager.py`): `_inject_session_messages` appended events to the copy returned by `create_session`, so the stored session stayed empty and "Session resumed" restored nothing on the ADK backend. Now uses `append_event` with real `google.adk.events.Event` objects so events land in the stored session.
+- **Corrupt sessions index no longer hides every session** (`persistence/session.py`): a corrupt or non-dict `_sessions_index.json` read as empty, so the next save reset it to a single entry and all other sessions vanished from `list_sessions()`. The index now rebuilds from the session files on any parse/shape error (and a non-dict payload no longer raises `AttributeError`).
+- **`MemoryStore` is now thread-safe** (`tools/memory_tools.py`): added a lock around `store`/`update`/`delete`/`search` and the full-file `_save` (note `search` is a writer — it bumps access counters). Prevents "dictionary changed size during iteration" and lost writes when LangGraph's `ToolNode` runs tools concurrently in executor threads.
+- **Atomic writes are now durable** (`file_utils.py::_atomic_write`): fsync before the rename (so a crash can't persist the rename ahead of the data and destroy the previously-good file), a unique temp filename (two concurrent writers no longer truncate a shared `.tmp`), and explicit UTF-8 (no locale-dependent `UnicodeEncodeError`). Applies to all persistence consumers (settings, sessions, memory).
+- **LangGraph graph construction was completely broken** (`workflow/langgraph/graph_builder.py`): `build()` called the local `_get_tools(config)` helper in the agent-node loop before it was defined further down the function, so Python treated `_get_tools` as an unbound local and every graph build raised `UnboundLocalError`. The helper (and `_overrides`) are now defined before first use. This went unnoticed because the dev env had no `langgraph` installed, so the build tests were skipped.
+- **LangGraph sqlite/postgres checkpointers were nonfunctional** (`workflow/langgraph/persistence/checkpointers.py`): `create_checkpointer` returned `SqliteSaver/PostgresSaver.from_conn_string(...)` directly, but in current `langgraph-checkpoint-*` that is a context manager (not a saver), and the sync savers can't serve the async `astream_events` path. `create_checkpointer` is now async and uses the async savers (`AsyncSqliteSaver`/`AsyncPostgresSaver`): it enters the connection context, calls `setup()`, and returns `(saver, context_manager)`; `LangGraphWorkflowManager` closes the context manager in `cleanup()`. The `langgraph` extra now also pulls `langgraph-checkpoint-sqlite`/`-postgres`.
+- **LangGraph node `retry` deprecation** (`workflow/langgraph/graph_builder.py`): `graph.add_node(..., retry=...)` updated to `retry_policy=...` (`retry` is deprecated since LangGraph 0.5, removed in 2.0).
+- Test suite is collectable in the default dev env again: `pytest.importorskip` guards added to `test_context_window.py`, `test_langgraph_state_tools.py`, and `test_backend_isolation.py`, which imported `langgraph`/`langchain_core`/`google.genai` unconditionally. The hybrid-search test now guards on `bm25s`, and `conftest.py` sets `KMP_DUPLICATE_LIB_OK=TRUE` so the real-FAISS and torch-backed tests (the `kb` extra) don't abort the interpreter on the duplicate OpenMP runtime.
+- **FAISS index could be left corrupt by a crash** (`knowledge_base/vector_store.py`): `save()` wrote the index in place via `faiss.write_index(self._index, path)`, so a crash mid-write left a truncated `index.faiss` — and `faiss.read_index` raises on a torn file, bricking the whole knowledge base until it was deleted by hand. The index is now written to a temp file in the same directory and `os.replace`d into position (atomic), with the temp cleaned up on failure; the misleading "mappings first is crash-safe" comment was corrected to describe what is actually guaranteed.
+- **Settings UI could persist invalid values** (`config.py::update_setting`): the non-special path used `object.__setattr__`, bypassing Pydantic entirely, so a wrong-typed or out-of-range value from the settings dialog was written straight to the instance and saved to `settings.json`, poisoning later runs. It now goes through `__pydantic_validator__.validate_assignment`, which type- and constraint-checks the value (and rejects unknown keys) before it lands — raising `ValidationError` (a `ValueError`, already handled by `apply_settings`).
+- **Ctrl+C now actually cancels an in-flight workflow** (`cli/message_processor.py`): the status bar advertised "Ctrl+C: cancel", but the binding only finished the thinking boxes — the workflow kept streaming and burning tokens. The event stream is now consumed in a cancellable task that a watcher aborts when the boxes are finished out from under it (the HITL dialog window is exempted), so Ctrl+C stops the run and prints "Cancelled."
+- **Quickstart tools were silently denied** (`README.md`): the README's `greet` example passed an unregistered raw callable and called registration "optional", but the permission engine (on by default) fails closed and denies any tool without a capability declaration on both backends. The quickstart now registers `greet` (`capabilities=EXEMPT`) and the docs state that registration is required for a tool to run.
+- **Gemini 2.5 thinking config caused HTTP 400 on every call** (`workflow/adk/manager.py`): `_get_planner` always built `ThinkingConfig(thinking_level=...)`, but `thinking_level` is a Gemini-3-only field — Gemini 2.5 models (including the default `gemini-2.5-flash`) reject it with `400 "Thinking level is not supported for this model"`. With the default `thinking_effort=medium`, every Gemini call failed (the ADK demo was unusable out of the box). The manager now uses the numeric `thinking_budget` for Gemini 2.5 models and reserves `thinking_level` for Gemini 3. Surfaced by the new live scenario tests.
+
+## [0.5.2] - 2026-05-01
+
+### Security
+- **`kb_ingest` split into `kb_ingest_text` / `kb_ingest_file` / `kb_ingest_url`**: the previous unified tool declared only `kb.write` (auto-allowed by the builtin `kb.*` rule) while internally reading arbitrary local paths and fetching arbitrary URLs. The split lets the permission engine gate `filesystem.read` and `http.read` at the right entry point, and the URL path now flows through the hardened `ContentFetcher` (URLValidator + manual redirect revalidation + DNS-rebinding mitigation).
+- **Concept-page slug traversal blocked** (`ConceptStore`): explicit slugs are validated against a strict `[a-z0-9-]+` allowlist, and `_concept_path` asserts the resolved path stays under `base_dir`. A slug like `../../etc/passwd` is now rejected before any filesystem write.
+- **Webfetch redirect handling rewritten**: `ContentFetcher.fetch` no longer follows redirects via httpx. Each `Location` is revalidated through `URLValidator` *before* the next GET, cross-host redirects are reported without contacting the new origin, same-host redirects re-check `robots.txt`, and the redirect chain is capped at 5.
+- **`os_sandbox_enabled=True` now fails closed**: when shell or Python execution is requested with sandboxing on, both executors refuse to run if the resolved sandbox is `NoOpSandbox` or wrap fails — instead of silently dropping back to plain subprocess/ulimit.
+
+### Changed
+- **`kb_ingest` tool removed** in favor of the three split entry points; `KB_WRITER_TOOLS` and `make_kb_tools` updated. Internal helper renamed: `_ingest_document_with_kb` → `_ingest_text_with_kb` / `_ingest_file_with_kb` / `_ingest_url_with_kb`.
+- **research_demo agent guide** updated to direct ingestion at `ingest_arxiv_paper` for arXiv papers and at the typed `kb_ingest_*` tools for everything else.
+
 ## [0.5.1] - 2026-04-18
 
 ### Added

agentic_cli-0.5.3/CLAUDE.md

@@ -0,0 +1,183 @@
+# Agentic CLI - Shared Framework for Agentic Applications
+
+## Project Overview
+
+Agentic CLI is a shared library providing the core infrastructure for building domain-specific CLI applications powered by LLM agents.
+
+## Tech Stack
+
+- **Language**: Python 3.12+
+- **CLI UI**: `thinking-prompt` - enhanced CLI with thinking boxes and markdown
+- **Workflow**: Google ADK + LangGraph - dual orchestration backends (selectable via settings)
+- **Config**: `pydantic-settings` - type-safe configuration
+- **Logging**: `structlog` - structured logging
+
+## Project Structure
+
+```
+agentic-cli/
+├── src/agentic_cli/
+│   ├── __init__.py           # Package exports, lazy imports
+│   ├── config.py             # BaseSettings (pydantic-settings)
+│   ├── settings_mixins.py    # Composable settings field groups
+│   ├── settings_persistence.py # save_settings() (excludes SECRET_FIELDS)
+│   ├── constants.py          # Shared constants, truncate()
+│   ├── file_utils.py         # atomic_write_json / atomic_write_text
+│   ├── logging.py
+│   ├── cli/
+│   │   ├── app.py            # BaseCLIApp
+│   │   ├── commands.py       # Command, CommandRegistry
+│   │   ├── builtin_commands.py
+│   │   ├── workflow_controller.py  # WorkflowController (lazy/background init, orchestrator swap)
+│   │   ├── message_processor.py    # WorkflowEvent → ThinkingPromptSession rendering
+│   │   ├── settings_command.py     # /settings command
+│   │   ├── settings_introspection.py # Pydantic field → UI item introspection
+│   │   └── usage_tracker.py        # Token usage / status bar
+│   ├── workflow/
+│   │   ├── base_manager.py   # BaseWorkflowManager (abstract; service detection, tool assembly)
+│   │   ├── factory.py        # create_workflow_manager_from_settings (ADK vs LangGraph routing)
+│   │   ├── service_registry.py # get_service/require_service + ContextVar registry
+│   │   ├── events.py         # WorkflowEvent, EventType
+│   │   ├── config.py         # AgentConfig
+│   │   ├── models.py
+│   │   ├── settings.py       # Workflow/tool settings schema
+│   │   ├── retry.py          # Rate-limit retry helpers
+│   │   ├── tool_summaries.py
+│   │   ├── permissions/      # Framework-independent capability engine
+│   │   │   ├── engine.py     # PermissionEngine (deny-wins, default-ASK)
+│   │   │   ├── capabilities.py # Capability, EXEMPT
+│   │   │   ├── matchers.py   # PathMatcher, URLMatcher, ShellMatcher, StringGlobMatcher
+│   │   │   └── rules.py, store.py, prompt.py
+│   │   ├── adk/              # ADK orchestrator
+│   │   │   ├── manager.py    # GoogleADKWorkflowManager
+│   │   │   ├── event_processor.py  # ADKEventProcessor
+│   │   │   ├── permission_plugin.py # PermissionPlugin (gates tool calls)
+│   │   │   ├── task_progress_plugin.py # Emits TASK_PROGRESS events
+│   │   │   └── plugins.py    # LLM traffic logging (raw_llm_logging)
+│   │   └── langgraph/        # LangGraph orchestrator
+│   │       ├── manager.py    # LangGraphWorkflowManager
+│   │       ├── graph_builder.py # LangGraphBuilder (graph + LLM factory)
+│   │       ├── state.py
+│   │       ├── permission_wrap.py # wrap_tool_for_permission
+│   │       └── persistence/  # Checkpointers, stores
+│   ├── tools/
+│   │   ├── registry.py       # ToolRegistry, @register_tool, ToolCategory
+│   │   ├── factories.py      # Service-bound tool builders (per-manager flavors)
+│   │   ├── executor.py       # SafePythonExecutor (CORE_MODULES; SANDBOXED_MODULES gated on OS sandbox)
+│   │   ├── execution_tools.py # execute_python
+│   │   ├── knowledge_tools.py # kb_search, kb_ingest_{text,file,url}, kb_list, kb_read, kb_write_concept, kb_search_concepts
+│   │   ├── arxiv_tools.py    # search_arxiv, fetch_arxiv_paper, ingest_arxiv_paper
+│   │   ├── arxiv_source.py   # ArxivSearchSource (feed fetch, download_pdf)
+│   │   ├── pdf_utils.py      # extract_pdf_text
+│   │   ├── interaction_tools.py # ask_clarification
+│   │   ├── file_read.py      # read_file, diff_compare
+│   │   ├── file_write.py     # write_file, edit_file
+│   │   ├── glob_tool.py      # glob
+│   │   ├── grep_tool.py      # grep
+│   │   ├── search.py         # web_search (Tavily/Brave backends)
+│   │   ├── webfetch_tool.py  # web_fetch + get_or_create_fetcher (orchestrator)
+│   │   ├── memory_tools.py   # save_memory, search_memory, update_memory, delete_memory + MemoryStore
+│   │   ├── _core/           # Backend-neutral tool logic
+│   │   │   ├── planning.py  # save_plan/get_plan core (+ checkbox parsing)
+│   │   │   └── tasks.py     # save_tasks/get_tasks core (+ progress parsing)
+│   │   ├── adk/state_tools.py       # ADK-native plan/task tools (ToolContext.state)
+│   │   ├── langgraph/state_tools.py # LangGraph-native plan/task tools (Command/InjectedState)
+│   │   ├── sandbox/         # Stateful code-execution sandbox (sandbox_execute)
+│   │   ├── shell/           # 8-layer shell security (+ os_sandbox/)
+│   │   └── webfetch/        # Fetcher, converter, validator, robots, summarizer
+│   ├── knowledge_base/
+│   │   ├── models.py         # Document, SearchResult
+│   │   ├── embeddings.py     # EmbeddingService
+│   │   ├── vector_store.py   # VectorStore (FAISS)
+│   │   ├── bm25_index.py     # BM25 index (+ _bm25_backends.py: bm25s / rank_bm25)
+│   │   ├── concepts.py       # ConceptStore (concept pages)
+│   │   ├── sidecar.py        # Markdown sidecar rendering
+│   │   ├── sources.py
+│   │   ├── _mocks.py         # MockEmbeddingService, MockVectorStore (+ _mock_bm25.py)
+│   │   └── manager.py        # KnowledgeBaseManager
+│   └── persistence/
+│       └── session.py        # SessionPersistence
+├── tests/
+│   ├── conftest.py           # MockContext, shared fixtures
+│   ├── test_*.py             # Unit tests
+│   ├── tools/                # Tool-specific tests
+│   ├── workflow/             # Backend-isolation / workflow tests
+│   └── integration/          # ADK & LangGraph pipeline tests
+└── examples/                 # Demo scripts
+```
+
+## Running Commands
+
+**IMPORTANT**: Always use `conda run -n agenticcli` prefix for running commands:
+
+```bash
+# Create the environment (first time only)
+conda env create -f environment.yml
+
+# Install package
+conda run -n agenticcli pip install -e .
+
+# Run tests
+conda run -n agenticcli python -m pytest tests/ -v
+
+# Run Python
+conda run -n agenticcli python -c "from agentic_cli import BaseCLIApp; print(BaseCLIApp)"
+```
+
+## Branching Strategy
+
+- **main**: Stable branch, matches latest release. Only updated via merges from `develop` when releasing.
+- **develop**: Integration branch for ongoing work. Small fixes can be committed directly here.
+- **feature/\***: Feature branches for larger changes. Branch from `develop`, merge back to `develop`.
+- **fix/\***: Fix branches for fixing issues. Branch from `develop`, merge back to `develop`.
+- **refactor/\***: For larger refactoring changes. Branch from `develop`, merge back to `develop`.
+
+Workflow:
+1. For small fixes: commit directly to `develop`
+2. For features: create `feature/<name>` (or `fix/<name>` or `refactor/<name>`) from `develop`, work there, merge back to `develop`
+3. When ready to release: merge `develop` → `main` and tag the release
+
+### What NOT to commit
+- `docs/` is gitignored on purpose (see `.gitignore`). It is a scratchpad for review notes, plans, and internal analysis. **Never `git add docs/…` or suggest committing anything under `docs/`.** If a document belongs in the repo, it lives elsewhere (README, CHANGELOG, top-level `*.md`).
+
+## Development Principles
+
+### Code Style
+- Follow PEP 8 style guidelines
+- Use type hints throughout
+- Prefer descriptive variable names
+
+### Key Design Decisions
+- **Abstract base classes**: BaseCLIApp and BaseWorkflowManager for domain extension
+- **Dual orchestrator**: ADK and LangGraph backends, selectable via settings
+- **Lazy initialization**: Defer heavy imports until needed
+- **Event-based streaming**: Real-time updates via AsyncGenerator
+- **UI-agnostic workflow**: WorkflowEvent objects can be consumed by any UI
+
+### Key Design Patterns
+- **Tool error handling**: All tools return `{"success": bool, ...}` dicts. Never raise `ToolError`.
+- **Tool registration**: Use `@register_tool(category=..., capabilities=..., description=...)` decorator. `capabilities=` is required — pass `EXEMPT` for tools that need no permission check or a list of `Capability(name, target_arg=...)` tuples the engine matches against rules. Tools are auto-discovered via the global `ToolRegistry`.
+- **Permissions**: `workflow/permissions/` holds a framework-independent engine that evaluates declared capabilities against rules from four sources (builtin, user `~/.{app_name}/settings.json`, project `./.{app_name}/settings.json`, in-memory session). ADK + LangGraph gate tool calls via `workflow/adk/permission_plugin.py::PermissionPlugin` and `workflow/langgraph/permission_wrap.py::wrap_tool_for_permission`.
+- **Service registry**: Tools access services and shared state via `get_service(key)` from `workflow.service_registry`. A single ContextVar holds a `dict[str, Any]` set by the workflow manager during processing. Complex services (KBManager, SandboxManager, MemoryStore) are lazily created; simple state (plan string, task list) lives directly in the registry dict.
+- **Manager detection**: `BaseWorkflowManager._detect_required_managers()` scans each agent's tool names against the `_TOOL_SERVICE_MAP` (name → service key, in `base_manager.py`); `_ensure_managers_initialized()` then lazily instantiates only the services actually needed (KBManager, SandboxManager, MemoryStore, …). Adding a new service-backed tool means adding its name → service entry to `_TOOL_SERVICE_MAP`. (There is no `@requires` decorator.)
+- **Atomic writes**: Use `atomic_write_json`/`atomic_write_text` from `file_utils.py` for file persistence.
+
+### Console Output
+All console output must go through `ThinkingPromptSession` methods. Never use `rich.Console` or `print()` directly.
+
+Available session methods:
+- `session.add_response(text, markdown=True)` - Display text/markdown response
+- `session.add_rich(renderable)` - Display Rich renderables (Panel, Table, etc.)
+- `session.add_message(role, content)` - Add message to history
+- `session.add_error(content)` - Display error message
+- `session.add_warning(content)` - Display warning message
+- `session.add_success(content)` - Display success message
+- `session.clear()` - Clear the terminal screen
+
+## Testing
+
+- **Framework**: pytest with `asyncio_mode = "auto"`
+- **MockContext**: From `tests/conftest.py` — provides isolated settings and temp dirs for all tests
+- **MockVectorStore** and **MockEmbeddingService**: In `knowledge_base/_mocks.py` for testing without ML dependencies
+- **FAISS tests**: Guard with `pytest.importorskip("faiss")` since FAISS is not installed in dev env
+- **Integration tests**: `tests/integration/` covers ADK and LangGraph pipeline tests

{agentic_cli-0.5.1 → agentic_cli-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-cli
-Version: 0.5.1
+Version: 0.5.3
 Summary: A framework for building domain-specific agentic CLI applications
 Project-URL: Homepage, https://github.com/shoom1/agentic-cli
 Project-URL: Repository, https://github.com/shoom1/agentic-cli
@@ -43,6 +43,8 @@ Requires-Dist: langchain-core>=0.3.0; extra == 'langgraph'
 Requires-Dist: langchain-google-genai>=2.0.0; extra == 'langgraph'
 Requires-Dist: langchain-openai>=0.2.0; extra == 'langgraph'
 Requires-Dist: langchain>=0.3.0; extra == 'langgraph'
+Requires-Dist: langgraph-checkpoint-postgres>=2.0; extra == 'langgraph'
+Requires-Dist: langgraph-checkpoint-sqlite>=2.0; extra == 'langgraph'
 Requires-Dist: langgraph>=0.2.0; extra == 'langgraph'
 Description-Content-Type: text/markdown
 
@@ -141,8 +143,12 @@ import asyncio
 from agentic_cli import BaseCLIApp, BaseSettings
 from agentic_cli.cli import AppInfo
 from agentic_cli.workflow import AgentConfig
+from agentic_cli.tools import register_tool, ToolCategory
+from agentic_cli.workflow.permissions import EXEMPT
 
-# Define your tools
+# Define your tools. Tools are permission-gated, so register each one with
+# the capabilities it needs (EXEMPT = a pure function that touches nothing).
+@register_tool(category=ToolCategory.OTHER, capabilities=EXEMPT)
 def greet(name: str) -> dict:
     """Greet a person by name."""
     return {"success": True, "greeting": f"Hello, {name}!"}
@@ -390,14 +396,14 @@ def search_database(query: str, limit: int = 10) -> dict:
     return {"success": True, "results": results, "count": len(results)}
 ```
 
-Registering via `@register_tool` is optional — you can pass raw callables into `AgentConfig.tools`. Registering gives the tool metadata for the registry, capability-aware permission gating, and tool-summary formatting.
+**Registration is required for a tool to run.** The permission engine is on by default, and any tool without a capability declaration is denied at call time (fail-closed) on both the ADK and LangGraph backends. You can still pass raw callables into `AgentConfig.tools`, but unless they are registered with `@register_tool` they will be blocked — register every tool with `capabilities=` (or `EXEMPT` for pure, side-effect-free functions). Registration also gives the tool registry metadata and tool-summary formatting.
 
 ### Capabilities
 
 Tool access is gated by the **permission engine** (see the HITL section below). Each registered tool declares what it touches via `capabilities=`:
 
 - **`Capability("namespace.action", target_arg="...")`** — e.g. `Capability("filesystem.write", target_arg="path")`, `Capability("http.read", target_arg="url")`, `Capability("shell.exec", target_arg="command")`. The engine resolves `target_arg` against the actual tool-call arguments and matches against rules.
-- **`EXEMPT`** — opts the tool out of the engine entirely. Reserved for backend-internal tools (e.g. ADK `transfer_to_agent`, backend state tools).
+- **`EXEMPT`** — opts the tool out of the engine entirely. Use for tools that need no permission check: pure functions with no side effects, and backend-internal tools (e.g. ADK `transfer_to_agent`, backend state tools).
 
 ### Built-in Tools
 
@@ -460,7 +466,7 @@ results = search_arxiv("transformer attention", max_results=10, categories=["cs.
 paper = fetch_arxiv_paper("1706.03762")  # "Attention Is All You Need"
 ```
 
-The `ArxivSearchSource` (in `knowledge_base/sources.py`) is cached via the service registry and reused across tools, including `kb_ingest` for arXiv URLs.
+The `ArxivSearchSource` (in `knowledge_base/sources.py`) is cached via the service registry and reused across tools. To pull a paper into the KB, use `ingest_arxiv_paper(arxiv_id)` — it composes the arxiv source with `kb_manager`.
 
 #### File Operations
 
@@ -513,7 +519,8 @@ Renamed tools and a new concept-pages subsystem:
 
 ```python
 from agentic_cli.tools import (
-    kb_search, kb_ingest, kb_read, kb_list,
+    kb_search, kb_ingest_text, kb_ingest_file, kb_ingest_url,
+    kb_read, kb_list,
     kb_write_concept, kb_search_concepts,
     KB_READER_TOOLS, KB_WRITER_TOOLS,
 )
@@ -522,12 +529,16 @@ from agentic_cli.tools import (
 | Tool | Purpose |
 |------|---------|
 | `kb_search` | Hybrid BM25 + vector search with RRF fusion, filters by source/date |
-| `kb_ingest` | Ingest content or URL (arXiv URLs auto-fetch metadata + PDF) |
+| `kb_ingest_text` | Ingest in-memory text content (no FS or network access) |
+| `kb_ingest_file` | Ingest a local file; declares `filesystem.read(path)` for the permission engine |
+| `kb_ingest_url` | Ingest content from an http(s) URL; routed through the hardened `ContentFetcher` and declares `http.read(url)` |
 | `kb_read` | Return the per-document markdown sidecar (lazy-generated on first read) |
 | `kb_list` | List documents, optionally filtered |
 | `kb_write_concept` | Agent-authored concept/summary page (slugged, merged on overwrite) |
 | `kb_search_concepts` | Search concept pages (title-weighted, case-insensitive) |
 
+The single `kb_ingest` tool was split in 0.5.2 so each entry point declares the right capability — text-only stays under `kb.write`, while file and URL ingestion correctly trip `filesystem.read` / `http.read` checks. For arXiv papers, prefer `ingest_arxiv_paper(arxiv_id)`.
+
 Bundle convenience:
 
 ```python
@@ -784,7 +795,8 @@ agentic-cli/
 │   │   ├── arxiv_source.py       # ArxivSearchSource (service-registered)
 │   │   ├── execution_tools.py    # execute_python
 │   │   ├── interaction_tools.py  # ask_clarification
-│   │   ├── knowledge_tools.py    # kb_search / kb_ingest / kb_read / kb_list /
+│   │   ├── knowledge_tools.py    # kb_search / kb_ingest_text / kb_ingest_file /
+│   │   │                         #   kb_ingest_url / kb_read / kb_list /
 │   │   │                         #   kb_write_concept / kb_search_concepts
 │   │   ├── file_read.py          # read_file, diff_compare
 │   │   ├── file_write.py         # write_file, edit_file (atomic)

{agentic_cli-0.5.1 → agentic_cli-0.5.3}/README.md

@@ -93,8 +93,12 @@ import asyncio
 from agentic_cli import BaseCLIApp, BaseSettings
 from agentic_cli.cli import AppInfo
 from agentic_cli.workflow import AgentConfig
+from agentic_cli.tools import register_tool, ToolCategory
+from agentic_cli.workflow.permissions import EXEMPT
 
-# Define your tools
+# Define your tools. Tools are permission-gated, so register each one with
+# the capabilities it needs (EXEMPT = a pure function that touches nothing).
+@register_tool(category=ToolCategory.OTHER, capabilities=EXEMPT)
 def greet(name: str) -> dict:
     """Greet a person by name."""
     return {"success": True, "greeting": f"Hello, {name}!"}
@@ -342,14 +346,14 @@ def search_database(query: str, limit: int = 10) -> dict:
     return {"success": True, "results": results, "count": len(results)}
 ```
 
-Registering via `@register_tool` is optional — you can pass raw callables into `AgentConfig.tools`. Registering gives the tool metadata for the registry, capability-aware permission gating, and tool-summary formatting.
+**Registration is required for a tool to run.** The permission engine is on by default, and any tool without a capability declaration is denied at call time (fail-closed) on both the ADK and LangGraph backends. You can still pass raw callables into `AgentConfig.tools`, but unless they are registered with `@register_tool` they will be blocked — register every tool with `capabilities=` (or `EXEMPT` for pure, side-effect-free functions). Registration also gives the tool registry metadata and tool-summary formatting.
 
 ### Capabilities
 
 Tool access is gated by the **permission engine** (see the HITL section below). Each registered tool declares what it touches via `capabilities=`:
 
 - **`Capability("namespace.action", target_arg="...")`** — e.g. `Capability("filesystem.write", target_arg="path")`, `Capability("http.read", target_arg="url")`, `Capability("shell.exec", target_arg="command")`. The engine resolves `target_arg` against the actual tool-call arguments and matches against rules.
-- **`EXEMPT`** — opts the tool out of the engine entirely. Reserved for backend-internal tools (e.g. ADK `transfer_to_agent`, backend state tools).
+- **`EXEMPT`** — opts the tool out of the engine entirely. Use for tools that need no permission check: pure functions with no side effects, and backend-internal tools (e.g. ADK `transfer_to_agent`, backend state tools).
 
 ### Built-in Tools
 
@@ -412,7 +416,7 @@ results = search_arxiv("transformer attention", max_results=10, categories=["cs.
 paper = fetch_arxiv_paper("1706.03762")  # "Attention Is All You Need"
 ```
 
-The `ArxivSearchSource` (in `knowledge_base/sources.py`) is cached via the service registry and reused across tools, including `kb_ingest` for arXiv URLs.
+The `ArxivSearchSource` (in `knowledge_base/sources.py`) is cached via the service registry and reused across tools. To pull a paper into the KB, use `ingest_arxiv_paper(arxiv_id)` — it composes the arxiv source with `kb_manager`.
 
 #### File Operations
 
@@ -465,7 +469,8 @@ Renamed tools and a new concept-pages subsystem:
 
 ```python
 from agentic_cli.tools import (
-    kb_search, kb_ingest, kb_read, kb_list,
+    kb_search, kb_ingest_text, kb_ingest_file, kb_ingest_url,
+    kb_read, kb_list,
     kb_write_concept, kb_search_concepts,
     KB_READER_TOOLS, KB_WRITER_TOOLS,
 )
@@ -474,12 +479,16 @@ from agentic_cli.tools import (
 | Tool | Purpose |
 |------|---------|
 | `kb_search` | Hybrid BM25 + vector search with RRF fusion, filters by source/date |
-| `kb_ingest` | Ingest content or URL (arXiv URLs auto-fetch metadata + PDF) |
+| `kb_ingest_text` | Ingest in-memory text content (no FS or network access) |
+| `kb_ingest_file` | Ingest a local file; declares `filesystem.read(path)` for the permission engine |
+| `kb_ingest_url` | Ingest content from an http(s) URL; routed through the hardened `ContentFetcher` and declares `http.read(url)` |
 | `kb_read` | Return the per-document markdown sidecar (lazy-generated on first read) |
 | `kb_list` | List documents, optionally filtered |
 | `kb_write_concept` | Agent-authored concept/summary page (slugged, merged on overwrite) |
 | `kb_search_concepts` | Search concept pages (title-weighted, case-insensitive) |
 
+The single `kb_ingest` tool was split in 0.5.2 so each entry point declares the right capability — text-only stays under `kb.write`, while file and URL ingestion correctly trip `filesystem.read` / `http.read` checks. For arXiv papers, prefer `ingest_arxiv_paper(arxiv_id)`.
+
 Bundle convenience:
 
 ```python
@@ -736,7 +745,8 @@ agentic-cli/
 │   │   ├── arxiv_source.py       # ArxivSearchSource (service-registered)
 │   │   ├── execution_tools.py    # execute_python
 │   │   ├── interaction_tools.py  # ask_clarification
-│   │   ├── knowledge_tools.py    # kb_search / kb_ingest / kb_read / kb_list /
+│   │   ├── knowledge_tools.py    # kb_search / kb_ingest_text / kb_ingest_file /
+│   │   │                         #   kb_ingest_url / kb_read / kb_list /
 │   │   │                         #   kb_write_concept / kb_search_concepts
 │   │   ├── file_read.py          # read_file, diff_compare
 │   │   ├── file_write.py         # write_file, edit_file (atomic)

{agentic_cli-0.5.1 → agentic_cli-0.5.3}/examples/research_demo/agents.py

@@ -50,7 +50,7 @@ When asked to research papers on a topic:
 1. Check if a relevant concept page already exists with `kb_search_concepts(topic)`. If one is relevant, read it first — it already synthesizes prior work and lists the source `doc_ids` you can follow.
 2. Search arXiv for relevant papers. If a search returns `success: false`, report the error instead of retrying with simpler queries.
 3. Fetch metadata for papers of interest.
-4. Ingest papers into the knowledge base by passing an arXiv PDF URL to `kb_ingest` — this auto-fetches metadata, downloads the PDF, extracts text, embeds chunks, and generates the sidecar in one call. The response includes the LLM-generated `summary` and the `document_id`.
+4. Ingest papers into the knowledge base. For arXiv papers, call `ingest_arxiv_paper(arxiv_id)` — it handles metadata, PDF download, and rate limiting. For other web sources use `kb_ingest_url(url)`; for a local PDF use `kb_ingest_file(path)`; for raw text you already hold use `kb_ingest_text(content)`. Each returns a `document_id` and the LLM-generated `summary`.
 5. Read each paper's sidecar with `kb_read(doc_id)` to plan the per-paper analysis.
 6. Pull full text with `kb_read(doc_id, full=True)` for any sections where the sidecar is insufficient (specific numbers, quotes, methodology details).
 7. Save detailed per-paper analyses via `write_file`.

{agentic_cli-0.5.1 → agentic_cli-0.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentic-cli"
-version = "0.5.1"
+version = "0.5.3"
 description = "A framework for building domain-specific agentic CLI applications"
 readme = "README.md"
 license = "MIT"
@@ -56,6 +56,10 @@ langgraph = [
     "langchain-openai>=0.2.0",
     "langchain-anthropic>=0.2.0",
     "langchain-google-genai>=2.0.0",
+    # Persistent checkpointer backends (sqlite/postgres store_type). The async
+    # savers are required because the manager streams via astream_events.
+    "langgraph-checkpoint-sqlite>=2.0",
+    "langgraph-checkpoint-postgres>=2.0",
 ]
 
 [project.scripts]

{agentic_cli-0.5.1 → agentic_cli-0.5.3}/src/agentic_cli/__init__.py

@@ -92,4 +92,4 @@ __all__ = [
     "CLISettingsMixin",
 ]
 
-__version__ = "0.5.1"
+__version__ = "0.5.3"

{agentic_cli-0.5.1 → agentic_cli-0.5.3}/src/agentic_cli/cli/app.py

@@ -456,6 +456,29 @@ class BaseCLIApp:
         else:
             logger.error("session_save_on_exit_failed", error=result.get("error"))
 
+    async def _extract_session_facts_on_exit(self) -> None:
+        """Extract key facts from the session into memory on exit (if enabled).
+
+        Gated by the ``auto_extract_session_facts`` setting; a no-op when the
+        workflow isn't ready or has no memory store. Never raises — fact
+        extraction must not block a clean shutdown.
+        """
+        if not getattr(self._settings, "auto_extract_session_facts", False):
+            return
+
+        if not self._workflow_controller.is_ready:
+            return
+
+        workflow = self._workflow_controller.workflow
+        try:
+            facts = await workflow.on_session_end()
+        except Exception:
+            logger.debug("session_fact_extraction_on_exit_failed", exc_info=True)
+            return
+
+        if facts:
+            logger.info("session_facts_extracted", count=len(facts))
+
     async def run(self) -> None:
         """Run the main application loop."""
         logger.info("repl_starting")
@@ -474,6 +497,9 @@ class BaseCLIApp:
             # Run the session - user sees prompt immediately!
             await self.session.run_async()
 
+        # Extract session facts into memory on exit (if enabled)
+        await self._extract_session_facts_on_exit()
+
         # Save persistent session on exit
         if self._session_id:
             await self._save_session_on_exit()

{agentic_cli-0.5.1 → agentic_cli-0.5.3}/src/agentic_cli/cli/message_processor.py

@@ -7,6 +7,7 @@ This module provides:
 from __future__ import annotations
 
 import asyncio
+from contextlib import suppress
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, ClassVar
 
@@ -74,6 +75,10 @@ class _EventProcessingState:
     workflow_controller: "WorkflowController | None" = field(default=None, repr=False)
     status_line: str = "Processing..."
     thinking_started: bool = False
+    # True while a HITL dialog is on screen: during that window there are no
+    # active thinking boxes, so the Ctrl+C watcher must not mistake the absence
+    # of boxes for a cancel request.
+    in_hitl: bool = False
     thinking_content: list[str] = field(default_factory=list)
     response_content: list[str] = field(default_factory=list)
     # Prevents double-counting when LangGraph emits both CONTEXT_TRIMMED and LLM_USAGE
@@ -189,16 +194,21 @@ class MessageProcessor:
         # deadlocking the workflow runner.
         async def _handle_input(request: "UserInputRequest") -> str:
             nonlocal events_ctx
-            if state.thinking_started and events_ctx is not None:
-                events_ctx.finish(add_to_history=False)
-                state.thinking_started = False
-
-            response = await self._prompt_user_input(request, ui)
-
-            events_ctx = ui.start_thinking(
-                state.get_status, content_format="ansi"
-            )
-            state.thinking_started = True
+            # Mark the HITL window before tearing down the events box so the
+            # cancel watcher doesn't read "no active boxes" as a Ctrl+C.
+            state.in_hitl = True
+            try:
+                if state.thinking_started and events_ctx is not None:
+                    events_ctx.finish(add_to_history=False)
+                    state.thinking_started = False
+
+                response = await self._prompt_user_input(request, ui)
+            finally:
+                events_ctx = ui.start_thinking(
+                    state.get_status, content_format="ansi"
+                )
+                state.thinking_started = True
+                state.in_hitl = False
             return response
 
         workflow.set_input_callback(_handle_input)
@@ -210,13 +220,33 @@ class MessageProcessor:
                     )
                     state.thinking_started = True
 
-                    async for event in workflow.process(
-                        message=message,
-                        user_id=settings.default_user,
-                    ):
-                        handler = dispatch.get(event.type)
-                        if handler is not None:
-                            await handler(self, event, state, ui, settings, workflow)
+                    # Consume the event stream in a cancellable task so Ctrl+C
+                    # can abort an in-flight run. thinking_prompt's Ctrl+C
+                    # binding finishes all thinking boxes (so ui.is_thinking
+                    # flips False) but never cancels our coroutine, so we watch
+                    # for that and cancel the task ourselves.
+                    async def _consume() -> None:
+                        async for event in workflow.process(
+                            message=message,
+                            user_id=settings.default_user,
+                        ):
+                            handler = dispatch.get(event.type)
+                            if handler is not None:
+                                await handler(
+                                    self, event, state, ui, settings, workflow
+                                )
+
+                    proc_task = asyncio.create_task(_consume())
+                    if await self._watch_for_cancel(proc_task, ui, state):
+                        # Ctrl+C already finished every active box; just drop
+                        # our now-dead references so the next turn starts clean.
+                        state.thinking_started = False
+                        self._task_box = None
+                        self._last_task_content = None
+                        ui.add_warning("Cancelled.")
+                        workflow_controller.update_status_bar(ui)
+                        logger.info("message_cancelled_by_user")
+                        break
 
                     # Finish events box only (don't add status to history)
                     if state.thinking_started and events_ctx is not None:
@@ -262,6 +292,42 @@ class MessageProcessor:
                 self._last_task_content if self._task_box else None
             )
 
+    async def _watch_for_cancel(
+        self,
+        proc_task: "asyncio.Task[None]",
+        ui: "ThinkingPromptSession",
+        state: _EventProcessingState,
+    ) -> bool:
+        """Watch a running workflow task and cancel it on Ctrl+C.
+
+        thinking_prompt's Ctrl+C binding finishes all active thinking boxes
+        (so ``ui.is_thinking`` becomes False) but does not cancel the coroutine
+        driving the workflow. We poll for that transition — ignoring the HITL
+        window, when boxes are legitimately absent — and cancel the task when
+        it happens.
+
+        Args:
+            proc_task: Task consuming the workflow event stream.
+            ui: UI session (provides the public ``is_thinking`` box state).
+            state: Shared processing state (``in_hitl`` guards the dialog window).
+
+        Returns:
+            True if the task was cancelled by the user. Otherwise False, after
+            re-raising any exception the task raised.
+        """
+        while True:
+            done, _ = await asyncio.wait({proc_task}, timeout=0.1)
+            if proc_task in done:
+                break
+            if not state.in_hitl and not ui.is_thinking:
+                proc_task.cancel()
+                with suppress(asyncio.CancelledError):
+                    await proc_task
+                return True
+        # Task completed on its own — surface its result/exception.
+        proc_task.result()
+        return False
+
     async def _prompt_user_input(
         self,
         request: "UserInputRequest",