pascal-agent 1.0.1__tar.gz → 1.2.0__tar.gz

pascal_agent-1.2.0/.omc/scientist/reports/2026-04-01_pascal_quantitative_report.md

@@ -0,0 +1,293 @@
+# Pascal Project -- Quantitative Metrics Report
+
+**Generated:** 2026-04-01
+**Scope:** `src/pascal/` + `tests/` (excluding `tests/test_uia_integration.py`)
+**Python:** 3.14.2
+
+---
+
+## [OBJECTIVE]
+
+Produce a full quantitative analysis of the Pascal codebase covering: test health, size distribution, coverage gaps, code complexity, technical debt markers, and import graph safety.
+
+---
+
+## [DATA]
+
+- **Source modules:** 25 Python files across `src/pascal/` (subdirs: root, `llm/`, `channels/`)
+- **Test files:** 22 unit/integration files + 1 eval file (`eval/test_golden.py`)
+- **Total source LOC:** 10,601 (excluding empty `__init__.py` stubs)
+- **Total test LOC:** 5,333 (4,741 unit + 592 eval)
+- **Test run result:** 332 passed, 0 failed, 0 errors (24.47s)
+
+---
+
+## 1. Test Results
+
+```
+332 passed | 0 failed | 0 errors | 24.47s
+Warnings: 1,099  (all: asyncio.get/set_event_loop_policy deprecated, removed in Python 3.16)
+```
+
+[FINDING] All 332 tests pass with zero failures.
+[STAT:n] n = 332 test cases across 23 test files
+[STAT:p_value] Pass rate = 100.0% (332/332)
+
+[LIMITATION] The asyncio event-loop-policy API used by `pytest-asyncio` is deprecated in Python 3.14 and will be removed in 3.16. This will produce hard test failures without any source changes.
+
+---
+
+## 2. Lines of Code per Source File
+
+| Module | LOC | Tier |
+|---|---:|---|
+| actions.py | 1,580 | LARGE (>1000) |
+| loop.py | 1,442 | LARGE (>1000) |
+| __main__.py | 1,198 | LARGE (>1000) |
+| state.py | 937 | MEDIUM (500-1000) |
+| desk.py | 698 | MEDIUM (500-1000) |
+| tools.py | 670 | MEDIUM (500-1000) |
+| sandbox.py | 436 | small (<500) |
+| schemas.py | 400 | small (<500) |
+| llm/anthropic.py | 354 | small (<500) |
+| types.py | 351 | small (<500) |
+| llm/codex.py | 342 | small (<500) |
+| uia.py | 316 | small (<500) |
+| llm/openai.py | 265 | small (<500) |
+| mcp.py | 206 | small (<500) |
+| daemon.py | 198 | small (<500) |
+| effect.py | 195 | small (<500) |
+| scheduler.py | 180 | small (<500) |
+| prompt.py | 163 | small (<500) |
+| config.py | 151 | small (<500) |
+| trust.py | 150 | small (<500) |
+| channels/telegram.py | 107 | small (<500) |
+| governance.py | 96 | small (<500) |
+| compaction.py | 87 | small (<500) |
+| clipboard.py | 38 | small (<500) |
+| receipts.py | 37 | small (<500) |
+| **TOTAL** | **10,601** | |
+
+Figure: `.omc/scientist/figures/lines_of_code.png`
+
+[FINDING] 3 modules exceed 1,000 LOC: `actions.py` (1,580), `loop.py` (1,442), `__main__.py` (1,198). Together they contain 39.8% of the entire codebase.
+[STAT:n] n = 25 modules; 3 large, 3 medium, 19 small
+[STAT:effect_size] Top-3 modules: 4,220 / 10,601 LOC = 39.8% of total codebase
+
+---
+
+## 3. Test Cases per Test File
+
+| Test File | Cases | LOC |
+|---|---:|---:|
+| eval/test_golden.py | 43 | 592 |
+| test_loop.py | 32 | 862 |
+| test_plan_tree.py | 28 | 465 |
+| test_tools.py | 22 | 288 |
+| test_bugfixes.py | 21 | 438 |
+| test_commitment.py | 19 | 138 |
+| test_heartbeat.py | 16 | 123 |
+| test_phase0.py | 16 | 229 |
+| test_uia.py | 16 | 138 |
+| test_delegate.py | 15 | 365 |
+| test_daemon.py | 14 | 357 |
+| test_hardening.py | 13 | 188 |
+| test_checkpoint.py | 11 | 138 |
+| test_ozma_patterns.py | 10 | 76 |
+| test_stability_fixes.py | 9 | 168 |
+| test_ambient.py | 9 | 121 |
+| test_channels.py | 8 | 90 |
+| test_sandbox_budget.py | 7 | 60 |
+| test_capability.py | 7 | 31 |
+| test_actions.py | 6 | 96 |
+| test_notifications.py | 6 | 211 |
+| test_efficiency.py | 3 | 94 |
+| test_codex_provider.py | 1 | 65 |
+| **TOTAL** | **332** | **5,333** |
+
+Figure: `.omc/scientist/figures/test_cases_per_file.png`
+
+[FINDING] `test_codex_provider.py` has only 1 test case for a 342-LOC source module. It is the thinnest test file relative to its source.
+[STAT:n] n = 23 test files; median = 13 cases/file; mean = 14.4 cases/file
+
+---
+
+## 4. Functions and Classes per Source Module
+
+| Module | Classes | Functions/Methods | Total Callables |
+|---|---:|---:|---:|
+| state.py | 1 | 60 | 61 |
+| actions.py | 1 | 48 | 49 |
+| loop.py | 3 | 45 | 48 |
+| __main__.py | 0 | 37 | 37 |
+| tools.py | 0 | 36 | 36 |
+| types.py | 12 | 14 | 26 |
+| desk.py | 2 | 25 | 27 |
+| sandbox.py | 4 | 21 | 25 |
+| uia.py | 2 | 17 | 19 |
+| llm/codex.py | 1 | 16 | 17 |
+| mcp.py | 4 | 12 | 16 |
+| llm/openai.py | 1 | 13 | 14 |
+| llm/anthropic.py | 1 | 11 | 12 |
+| scheduler.py | 1 | 10 | 11 |
+| daemon.py | 0 | 9 | 9 |
+| config.py | 0 | 8 | 8 |
+| effect.py | 0 | 7 | 7 |
+| channels/telegram.py | 0 | 6 | 6 |
+| trust.py | 1 | 4 | 5 |
+| receipts.py | 1 | 4 | 5 |
+| compaction.py | 0 | 5 | 5 |
+| governance.py | 0 | 3 | 3 |
+| schemas.py | 0 | 3 | 3 |
+| prompt.py | 0 | 3 | 3 |
+| clipboard.py | 0 | 2 | 2 |
+| **TOTALS** | **35** | **~468** | **~503** |
+
+[FINDING] `state.py` leads in callable count (60 functions), followed by `actions.py` (48) and `loop.py` (45). These three form the core orchestration triad.
+[STAT:n] n = 25 modules; total callables ~503; top-3 hold 153/468 = 32.7% of all callables
+[STAT:effect_size] `types.py` holds 12 classes -- highest class density; pure data model file
+
+---
+
+## 5. Test-to-Code Ratio
+
+| Metric | Value |
+|---|---:|
+| Source LOC | 10,601 |
+| Test LOC (unit tests) | 4,741 |
+| Test LOC (eval suite) | 592 |
+| Test LOC (total) | 5,333 |
+| **Test:Code ratio** | **0.503** |
+| Total test cases | 332 |
+| Avg LOC per test case | 16.1 |
+
+Figure: `.omc/scientist/figures/test_to_code_ratio.png`
+
+[FINDING] Test-to-code ratio is 0.50, meaning 1 line of test exists for every 2 lines of source. This is below the 1:1 target but reasonable for an async agent framework with heavy integration surface area.
+[STAT:effect_size] Ratio = 0.503; well-tested Python target >= 1.0; typical agent projects 0.4-0.7
+[STAT:n] 10,601 source LOC vs 5,333 test LOC
+
+[LIMITATION] LOC ratio is a proxy metric. It does not measure branch or path coverage. The 43-case eval suite tests emergent multi-turn behavior rather than logic paths, which inflates apparent coverage quality.
+
+---
+
+## 6. Source Files with NO Dedicated Test Coverage
+
+| Module | LOC | Risk Assessment |
+|---|---:|---|
+| `__main__.py` | 1,198 | **HIGH** -- entry point, 37 functions, zero unit tests |
+| `llm/openai.py` | 265 | **MEDIUM** -- 1 of 3 LLM providers; anthropic + codex tested, openai not |
+| `channels/telegram.py` | 107 | **MEDIUM** -- integration boundary, no test |
+| `governance.py` | 96 | **MEDIUM** -- policy logic, no test file |
+| `clipboard.py` | 38 | LOW -- thin OS wrapper |
+| **Total uncovered** | **1,704** | **16.1% of source LOC** |
+
+Figure: `.omc/scientist/figures/module_coverage.png`
+
+[FINDING] 5 out of 25 modules (20%) have no dedicated test file, totaling 1,704 uncovered source LOC. `__main__.py` is the highest-risk gap at 1,198 LOC.
+[STAT:n] 5/25 uncovered = 20% module coverage gap
+[STAT:effect_size] 1,704 / 10,601 uncovered LOC = 16.1% of total codebase
+
+[LIMITATION] "No dedicated test file" does not equal untested. `__main__.py` is likely exercised indirectly by `test_daemon.py` and `test_loop.py`. Module-to-file mapping is a conservative lower bound on the true coverage gap.
+
+---
+
+## 7. TODO / FIXME / HACK Comment Count
+
+All occurrences found are **domain-semantic** (agent task-list UI text), not developer debt markers. Zero FIXME or HACK comments were found anywhere in the source tree.
+
+| Location | Context |
+|---|---|
+| `desk.py:248` | `# TODOs for active task` -- UI render section comment |
+| `desk.py:256` | `## TODO ({done}/{len} done)` -- prompt section header string |
+| `desk.py:439` | `{"## TODO"}` -- protected section name set |
+| `desk.py:487` | `TODOs: {done}/{len} done` -- compact prompt summary |
+| `state.py:518` | `# TODOs section` -- state layer comment |
+| `loop.py:1424` | `TODOs: {done}/{len} completed` -- loop status string |
+| `schemas.py:264,272` | `"Add a TODO item..."` -- tool schema descriptions |
+
+[FINDING] Zero developer debt comments (TODO/FIXME/HACK) exist in the codebase. All 8 "TODO" occurrences are the framework's own task-list domain vocabulary.
+[STAT:n] 8 occurrences scanned; 0 are programmer debt markers
+[STAT:effect_size] Technical debt comment density = 0.0 per 1,000 LOC (industry median: 2-5 per 1,000 LOC for active codebases)
+
+---
+
+## 8. Import Graph Complexity and Circular Imports
+
+### Internal Dependency Map (`pascal.*` imports only)
+
+| Module | Depends On | Fan-in (# deps) |
+|---|---|---:|
+| `loop` | actions, compaction, desk, effect, governance, mcp, prompt, receipts, sandbox, scheduler, schemas, state, tools, trust, types | 15 |
+| `actions` | effect, mcp, receipts, sandbox, scheduler, state, tools, trust, types | 9 |
+| `daemon` | config, loop, mcp, receipts, scheduler, state, channels | 7 |
+| `desk` | state, types | 2 |
+| `tools` | types, uia | 2 |
+| `config` | llm, types | 2 |
+| `scheduler` | state | 1 |
+| `compaction` | types | 1 |
+| `llm/anthropic` | types | 1 |
+| `llm/codex` | types | 1 |
+| `llm/openai` | types | 1 |
+
+**Leaf modules (zero internal deps):** `types`, `state`, `effect`, `uia`, `mcp`, `sandbox`, `receipts`, `trust`, `governance`, `prompt`, `schemas`, `clipboard`
+
+### Topology (leaf to root)
+
+```
+types (leaf, 9+ importers)
+state (leaf, 7+ importers)
+  -> scheduler -> actions -> loop
+  -> desk -> loop
+  -> actions -> loop
+  -> daemon
+effect (leaf) -> actions -> loop
+llm/* -> config -> daemon
+```
+
+### Circular Import Result
+
+```
+Circular imports detected: 0
+Graph type: strict DAG (directed acyclic graph)
+```
+
+[FINDING] Zero circular imports detected. The import graph is a strict DAG with `types` and `state` as the two shared leaf foundations for all upper layers.
+[STAT:n] 11 non-trivial modules analyzed; 0 cycles
+[STAT:effect_size] `loop.py` fan-in = 15 dependencies (highest coupling); `types` + `state` fan-out = 9+ direct importers each (highest centrality)
+
+[LIMITATION] Analysis covers only top-level `from pascal.*` / `import pascal.*` statements. Dynamic or conditional imports inside function bodies are not captured by static analysis.
+
+---
+
+## Executive Summary
+
+| Metric | Value | Assessment |
+|---|---|---|
+| Test pass rate | 332/332 (100%) | Excellent |
+| Test:code LOC ratio | 0.503 | Below 1.0 target; acceptable |
+| Modules with no tests | 5/25 (20%) | Moderate gap |
+| Uncovered source LOC | 1,704 (16.1%) | Moderate gap |
+| Largest module (LOC) | `actions.py` 1,580 | Refactor candidate |
+| Most coupled module | `loop.py` (15 deps) | Orchestration hub |
+| Developer debt comments | 0 | Clean |
+| Circular imports | 0 | Clean |
+| pytest-asyncio warnings | 1,099 | Fix before Python 3.16 |
+
+---
+
+## Prioritized Recommendations
+
+1. **Add tests for `__main__.py`** -- 1,198 LOC entry point is the highest-risk uncovered module (37 functions, zero tests). CLI argument smoke tests at minimum.
+2. **Add tests for `llm/openai.py`** -- Two of three LLM providers have dedicated tests (anthropic, codex). The OpenAI provider (265 LOC) has none, creating an asymmetric risk.
+3. **Split `actions.py` and `loop.py`** -- Both exceed 1,400 LOC with 45+ functions. This directly aligns with the v1.1 roadmap items (loop isolation, action layer separation).
+4. **Upgrade `pytest-asyncio`** -- 1,099 deprecation warnings target an API removed in Python 3.16. This will cause a complete test infrastructure failure without source changes.
+5. **Monitor `loop.py` coupling** -- At 15 internal imports it is the highest fan-in module. Any change to `state`, `types`, or `effect` has a guaranteed path into the orchestration loop.
+
+---
+
+*Figures saved to:*
+- `C:/Users/laum3/Downloads/Pascal/.omc/scientist/figures/lines_of_code.png`
+- `C:/Users/laum3/Downloads/Pascal/.omc/scientist/figures/test_cases_per_file.png`
+- `C:/Users/laum3/Downloads/Pascal/.omc/scientist/figures/test_to_code_ratio.png`
+- `C:/Users/laum3/Downloads/Pascal/.omc/scientist/figures/module_coverage.png`

pascal_agent-1.2.0/.omc/state/hud-state.json

@@ -0,0 +1,6 @@
+{
+  "timestamp": "2026-04-01T10:29:36.267Z",
+  "backgroundTasks": [],
+  "sessionStartTimestamp": "2026-04-01T10:24:07.674Z",
+  "sessionId": "8085b01e-c415-4355-98da-02cf3a7e17a5"
+}

pascal_agent-1.2.0/.omc/state/hud-stdin-cache.json

@@ -0,0 +1 @@
+{"session_id":"8085b01e-c415-4355-98da-02cf3a7e17a5","transcript_path":"C:\\Users\\laum3\\.claude\\projects\\C--Users-laum3\\8085b01e-c415-4355-98da-02cf3a7e17a5.jsonl","cwd":"C:\\Users\\laum3\\Downloads\\Pascal","model":{"id":"claude-opus-4-6[1m]","display_name":"Opus 4.6 (1M context)"},"workspace":{"current_dir":"C:\\Users\\laum3\\Downloads\\Pascal","project_dir":"C:\\Users\\laum3","added_dirs":[]},"version":"2.1.89","output_style":{"name":"default"},"cost":{"total_cost_usd":65.05081145000004,"total_duration_ms":18130958,"total_api_duration_ms":9177627,"total_lines_added":1295,"total_lines_removed":447},"context_window":{"total_input_tokens":574321,"total_output_tokens":387031,"context_window_size":1000000,"current_usage":{"input_tokens":1,"output_tokens":121,"cache_creation_input_tokens":296,"cache_read_input_tokens":351122},"used_percentage":35,"remaining_percentage":65},"exceeds_200k_tokens":true,"rate_limits":{"five_hour":{"used_percentage":28.000000000000004,"resets_at":1775062800},"seven_day":{"used_percentage":28.000000000000004,"resets_at":1775149200}}}

pascal_agent-1.2.0/ARCHITECTURE.md

@@ -0,0 +1,178 @@
+# Pascal Architecture Reference
+
+## Overview
+
+Pascal is a local autonomous runtime for long-lived task execution. Durable state lives in SQLite. Each turn, Pascal renders a desk from that state, asks the LLM for tool calls, executes one or more actions under governance, records the result, and repeats until it should continue, wait, or escalate.
+
+Pascal is broader than a coding agent:
+
+- The same runtime can operate on shell commands, local files, Windows UI, Telegram notifications, and MCP tools.
+- Claude Code and Codex are delegate targets inside Pascal rather than the main runtime.
+- CLI, REPL, and daemon modes share the same action layer and safety model.
+
+## Runtime Shape
+
+```text
+CLI / REPL / daemon / scheduler
+              |
+              v
+           loop.py
+  (desk render, prompt assembly,
+   LLM call, governance, record)
+              |
+              v
+         actions.py
+ (built-in actions + direct MCP fallback)
+        /         |          \
+       v          v           v
+   tools.py    mcp.py     sandbox.py
+```
+
+Supporting modules:
+
+- `state.py` persists tasks, context, plans, checkpoints, memories, and history.
+- `desk.py` compiles durable state into the model-facing working document.
+- `governance.py`, `effect.py`, and `trust.py` gate actions before side effects happen.
+- `compaction.py` manages prompt budget pressure and restart thresholds.
+- `receipts.py` writes an append-only JSONL ledger beside the SQLite store.
+
+## Core Modules
+
+| Module | Purpose |
+| --- | --- |
+| `src/pascal/__main__.py` | CLI entrypoints, setup/config commands, one-shot run, resume, and REPL wiring. |
+| `src/pascal/actions.py` | Action handlers, declarative plan advancement, delegate lifecycle, verification, and MCP fallback dispatch. |
+| `src/pascal/loop.py` | Main orchestration loop and tool-call execution. |
+| `src/pascal/state.py` | SQLite persistence for tasks, plans, checkpoints, context, memories, rules, and history. |
+| `src/pascal/desk.py` | State-to-prompt compiler. |
+| `src/pascal/schemas.py` | Function schemas for built-in actions and connected MCP tools. |
+| `src/pascal/mcp.py` | MCP connection manager, tool discovery, and tool calls. |
+| `src/pascal/governance.py` | Stagnation detection and repetition handling. |
+| `src/pascal/effect.py` | Effect classification, `max_effect`, and `compute_threshold()`. |
+| `src/pascal/compaction.py` | Token estimation, prompt budget checks, and session summaries. |
+| `src/pascal/sandbox.py` | Shell/code isolation and safe environment setup. |
+| `src/pascal/tools.py` | Built-in editor/computer/UIA/channel tools. |
+| `src/pascal/daemon.py` | Always-on runtime with Telegram, scheduler wakeups, and shared loop execution. |
+| `src/pascal/scheduler.py` | Bounded periodic checks for overdue work, stale work, routines, and webhooks. |
+| `src/pascal/receipts.py` | Append-only JSONL audit ledger. |
+| `src/pascal/types.py` | Shared DTOs, plan tree types, and normalized LLM responses. |
+
+## Governance And Safety
+
+Pascal does not trust the model’s self-reported confidence or effect level. Safety is enforced in code:
+
+1. `effect.py` classifies shell commands and tool calls into `E0` through `E5`.
+2. `effect.py::compute_threshold()` combines effect level with the recent error streak to decide `go`, `caution`, or `block`.
+3. `governance.py` detects repeated actions and stagnation before Pascal loops on the same move.
+4. `trust.py` scans action inputs for injection attempts, credentials, and destructive patterns.
+5. `sandbox.py` and workspace-bounded tools constrain execution.
+
+Important consequence: higher-effect moves are gated by current runtime conditions, not just by the tool that was chosen.
+
+## Declarative Plans
+
+Plans are stored in `tasks.plan_json` using `TaskPlan` and `PlanNode` from `types.py`.
+
+- A plan is a tree, not a hidden executor state machine.
+- Each `plan` call executes exactly one pending leaf.
+- Failed leaves keep attempts and error state.
+- `patch_node_id` lets the model repair only the broken subtree instead of rebuilding the whole plan.
+
+This keeps the plan visible, resumable, and serializable inside the same task record as the rest of the runtime state.
+
+## Delegation
+
+`delegate` launches Claude Code or Codex as a child task.
+
+- In one-shot CLI mode, delegation runs inline and returns the child result directly.
+- In daemon and REPL modes, delegation runs in the background and the parent loop can continue.
+- `check_delegate` retrieves the finished background result and clears its stored payload.
+
+The delegate lifecycle is mode-aware because background work only makes sense in long-lived runtimes.
+
+## MCP Integration
+
+Pascal supports MCP in two ways:
+
+- `execute(tool=...)` can call a remote MCP tool.
+- `schemas.py` can expose connected MCP tools directly by name, and `actions.py::execute_action()` now dispatches those names without a Pascal wrapper action.
+
+This keeps frequent built-ins first-class while letting external systems plug in naturally.
+
+## Desk And Prompt Model
+
+`desk.py` renders the runtime state into a structured working document. Typical sections include:
+
+- identity
+- active task and queue
+- todos
+- notifications
+- rules
+- memories and procedures
+- plan progress and failed nodes
+- recent history
+- working context
+- repetition warnings
+
+`prompt.py` supplies the base system prompt and loads `PASCAL.md` instructions from:
+
+1. `~/.pascal/PASCAL.md`
+2. `<workspace>/PASCAL.md`
+
+Project instructions come second, so they override global instructions when both are present.
+
+## Execution Flow
+
+```text
+state.py + desk.py
+    -> prompt.py + schemas.py
+    -> LLM provider
+    -> action/tool call
+    -> actions.py dispatch
+    -> governance/effect/trust checks
+    -> built-in tool, sandbox, or MCP execution
+    -> normalized observation + history/ledger write
+    -> compaction check
+    -> next loop turn
+```
+
+`loop.py` also refreshes tool schemas when MCP connectivity changes, so newly connected MCP tools can appear in later turns without restarting the process.
+
+## Runtime Modes
+
+- One-shot CLI: runs until completion, wait, or escalation.
+- REPL: persistent loop with wake events from user input.
+- Daemon: persistent loop with wake events from Telegram and scheduler signals.
+
+All three share the same action handlers and storage model.
+
+## Configuration
+
+Resolved by `config.py` in this order:
+
+1. CLI overrides
+2. Environment variables
+3. TOML config (`<cwd>/pascal.toml`, then `~/.pascal/pascal.toml`)
+4. `PascalConfig` defaults
+
+Common runtime files under `~/.pascal/`:
+
+- `pascal.toml`
+- `.env`
+- `PASCAL.md`
+- `state.db`
+- `telegram.json`
+- `mcp.json`
+- `audit.jsonl`
+- `STOP` / `PAUSE`
+
+Temporary run data lives under `.pascal_tmp` inside the active workspace.
+
+## Key Design Decisions
+
+- Desk-as-prompt instead of raw transcript. The model sees the current working state, not an ever-growing chat log.
+- Declarative plans instead of hidden auto-execution. Advancing one leaf per `plan` call keeps failures local and repairable.
+- First-class common tools plus direct MCP extension. Core actions stay precise while external systems plug in by name.
+- Shared runtime across modes. CLI, REPL, and daemon reuse the same loop and dispatch layer.
+- Separate mutable state and append-only ledger. SQLite is optimized for live runtime state; JSONL is optimized for simple audit traces.
+- Compaction as a first-class concern. Prompt budget and restart handling live in `compaction.py`, not as scattered ad hoc logic.

{pascal_agent-1.0.1 → pascal_agent-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pascal-agent
-Version: 1.0.1
+Version: 1.2.0
 Summary: Pascal — autonomous AI employee runtime
 Project-URL: Homepage, https://gitlab.com/laum0621/pascal
 Project-URL: Repository, https://gitlab.com/laum0621/pascal
@@ -182,23 +182,38 @@ Instructions for Pascal when this skill is activated...
 pascal "Do something"
     |
     v
-+---------------------------+
-|  Desk compiles state      |  SQLite -> text prompt
-|  LLM decides next action  |  22 action types via function calling
-|  Execute through safety   |  Effect Ladder + Trust Scanner + Sandbox
-|  Record to audit ledger   |  Hash-chained, append-only
-|  Repeat                   |
-+---------------------------+
+Desk render (state.py + desk.py)
+    ->
+Prompt + tool schemas (prompt.py + schemas.py)
+    ->
+LLM picks one action or tool call
+    ->
+actions.py dispatches built-ins or named MCP tools
+    ->
+governance.py + effect.py + trust.py gate execution
+    ->
+tools.py / sandbox.py / mcp.py execute
+    ->
+state.py + receipts.py persist outcome
+    ->
+compaction.py trims prompt pressure when needed
     |
     v
 Task complete / wait / escalate
 ```
 
-**22 actions**: think, execute, plan, delegate, pick_task, create_task, create_subtask, complete_task, fail_task, pause_task, block_task, handle_notification, dismiss_notification, add_todo, complete_todo, memorize, add_rule, remove_rule, set_context, wait, escalate
+Plans are declarative: `plan` stores a tree on the active task, and each `plan` call executes one pending leaf before returning the next frontier.
 
-**3 LLM providers**: OpenAI, Anthropic Claude, Codex (ChatGPT Pro)
+Delegation is mode-aware: one-shot CLI runs delegate inline, while daemon/REPL modes spawn a background child task and use `check_delegate` to collect the result.
 
-**4-layer safety**: Effect Ladder (E0-E5) | Trust Scanner | Sandbox (Docker/Restricted) | TrustMap + Audit Ledger
+Built-in actions cover shell, editor, computer, UIA, code, task management, planning, delegation, reply, and memory/rule updates. Connected MCP tools can also be exposed directly by name.
+
+Safety is layered:
+- `effect.py` classifies side effects and applies `compute_threshold()`
+- `governance.py` blocks stagnation and repeated bad loops
+- `trust.py` scans for injection, credentials, and destructive patterns
+- `sandbox.py` and workspace-bounded tools constrain execution
+- `receipts.py` writes an append-only JSONL ledger
 
 ## Daemon Mode
 
@@ -225,36 +240,37 @@ git clone https://gitlab.com/laum0621/pascal.git
 cd pascal
 pip install -e ".[dev]"
 
-# Tests (245 pass)
-pytest
+# Tests
+python -m pytest tests/ --ignore=tests/test_uia_integration.py -q
 
-# Lint (0 errors)
-ruff check src/ tests/
+# Lint
+python -m ruff check src/ tests/
 
-# Type check (0 errors)
-mypy src/pascal/
+# Type check
+python -m mypy src/pascal/
 ```
 
 ## Project Structure
 
 ```
 src/pascal/
-  loop.py ........... Core tool-use loop (LoopRunner)
-  actions.py ........ 22 action handlers (ActionContext)
-  state.py .......... SQLite persistence (9 tables, FTS5)
-  desk.py ........... State -> LLM prompt compiler
-  tools.py .......... Built-in tools (file, desktop, UIA, clipboard)
-  effect.py ......... Effect Ladder (E0-E5, hard regex rules)
-  trust.py .......... Input scanner (injection, credentials, destructive)
-  capability.py ..... Domain trust map (asymmetric learning)
-  sandbox.py ........ Docker + Restricted sandbox
-  receipts.py ....... Hash-chained audit ledger
-  scheduler.py ...... Cron tick + self-evolution
-  daemon.py ......... Always-on mode (Telegram + loop + scheduler)
-  config.py ......... Config loader (CLI > env > TOML > defaults)
-  schemas.py ........ Tool JSON schemas for LLM function calling
-  prompt.py ......... System prompt
-  types.py .......... Shared DTOs
+  loop.py ........... Main orchestration loop
+  actions.py ........ Action dispatch, plan execution, delegate lifecycle
+  state.py .......... SQLite state, checkpoints, plans, memories
+  desk.py ........... State -> prompt compiler
+  tools.py .......... Built-in editor/computer/uia/channel tools
+  mcp.py ............ MCP connections, discovery, and tool calls
+  governance.py ..... Stagnation and repetition checks
+  effect.py ......... Effect classification + compute_threshold()
+  compaction.py ..... Token budgeting and session summaries
+  sandbox.py ........ Shell/code isolation
+  receipts.py ....... Append-only JSONL ledger
+  scheduler.py ...... Bounded periodic checks and webhooks
+  daemon.py ......... Always-on Telegram runtime
+  config.py ......... Config loader and LLM factory
+  schemas.py ........ Tool schemas, including named MCP tools
+  prompt.py ......... Base system prompt + PASCAL.md loading
+  types.py .......... Shared DTOs and plan tree types
   llm/ .............. OpenAI, Anthropic, Codex providers
   channels/ ......... Telegram adapter
   uia.py ............ Windows UI Automation