open-agents-ai 0.36.0 → 0.37.1

package/README.md

@@ -29,7 +29,7 @@ An autonomous multi-turn tool-calling agent that reads your code, makes changes,
 
 ## Features
 
-- **48 autonomous tools** — file I/O, shell, grep, web search/fetch/crawl, memory (read/write/search), sub-agents, background tasks, image/OCR/PDF, git, diagnostics, vision, desktop automation, browser automation, structured files, code sandbox, transcription, skills
+- **51 autonomous tools** — file I/O, shell, grep, web search/fetch/crawl, memory (read/write/search), sub-agents, background tasks, image/OCR/PDF, git, diagnostics, vision, desktop automation, browser automation, temporal agency (scheduler/reminders/agenda), structured files, code sandbox, transcription, skills
 - **Moondream vision** — see and interact with the desktop via Moondream VLM (caption, query, detect, point-and-click)
 - **Desktop automation** — vision-guided clicking: describe a UI element in natural language, the agent finds and clicks it
 - **Auto-install desktop deps** — screenshot, mouse, OCR, and image tools auto-install missing system packages (scrot, xdotool, tesseract, imagemagick) on first use
@@ -49,6 +49,7 @@ An autonomous multi-turn tool-calling agent that reads your code, makes changes,
 - **Structured file reading** — parse CSV, TSV, JSON, Markdown tables with binary format detection
 - **Multi-provider web search** — DuckDuckGo (free), Tavily (structured), Jina AI (markdown) with auto-detection
 - **Browser automation** — headless Chrome control via Selenium: navigate, click, type, screenshot, read DOM — auto-starts on first use with self-bootstrapping Python venv
+- **Temporal agency** — schedule future tasks via OS cron, set cross-session reminders, flag attention items — startup injection surfaces due items automatically
 - **Web crawling** — multi-page web scraping with Crawlee/Playwright for deep documentation extraction
 - **Task templates** — specialized system prompts and tool recommendations for code, document, analysis, plan tasks
 - **Auto-expanding context** — detects RAM/VRAM and creates an optimized model variant on first run
@@ -378,6 +379,64 @@ Available actions:
 
 The service runs on `localhost:8130` and uses headless Chrome/Chromium. Requires Python 3.9+ and Chrome or Chromium installed on the system.
 
+### Temporal Agency — Scheduling, Reminders & Attention
+
+The agent has persistent temporal awareness across sessions. Three tools work together to let the agent schedule future work, leave notes for its future self, and track items that need attention.
+
+**Scheduler** — Create OS-level cron jobs that auto-launch the agent:
+
+```
+Agent: scheduler(action="create", task="run npm audit and fix vulnerabilities", schedule="weekly")
+       → Scheduled task created: sched-a1b2c3d4
+         Schedule: weekly on day 1 at 9:00
+
+Agent: scheduler(action="create", task="check API health", schedule="every 30 minutes")
+       → Scheduled task created: sched-e5f6a7b8
+```
+
+Schedule formats: presets (`daily`, `hourly`, `every 5 minutes`, `weekly`), natural language (`in 30m`, `at 14:30`), or raw cron (`0 */2 * * *`).
+
+**Reminder** — Cross-session messages-in-a-bottle:
+
+```
+Agent: reminder(action="set", message="Verify auth migration tokens after deploy", priority="high", due="tomorrow")
+       → Reminder set: rem-c4d5e6f7 (due: tomorrow morning)
+
+# Next startup:
+⚠ 1 urgent item(s) need attention
+  Reminder: Verify auth migration tokens after deploy
+```
+
+Reminders support priority levels (`low`/`normal`/`high`/`critical`), due dates, tags, context, snoozing, and auto-surface at startup.
+
+**Agenda** — Unified temporal dashboard:
+
+```
+Agent: agenda()
+       → AGENT AGENDA
+         ──────────────────────────────────────────────
+         REMINDERS DUE (2):
+           [!!] [rem-a1b2] Verify auth migration tokens
+           [*]  [rem-c3d4] Update API docs
+
+         ATTENTION ITEMS (1):
+           [!!] [attn-e5f6] (followup) PR #42 needs re-review
+
+         SCHEDULED TASKS (1 active):
+           [sched-g7h8] weekly on day 1 at 9:00: run npm audit
+```
+
+**Design decisions backed by research:**
+
+| Decision | Research Basis | Key Finding |
+|----------|---------------|-------------|
+| Separate directive store (`.oa/scheduled/`, not `.oa/memory/`) | SSGM (arXiv:2603.11768, 2026) | Directives in summarizable memory corrupt via compaction — semantic drift degrades scheduling data |
+| File-based persistence survives process death | MemGPT/Letta (Packer et al. 2023, arXiv:2310.08560) | Agents are ephemeral; state must be external to the process |
+| Priority-based startup surfacing | A-MAC (arXiv:2603.04549, 2026) | 5-factor attention scoring; content type prior is most influential factor (31% latency reduction) |
+| Cross-session self-reflection | Reflexion (Shinn et al. 2023, arXiv:2303.11366) | Persistent self-reflection stored as text improves task success 20-30% |
+| Time-weighted memory retrieval | Generative Agents (Park et al. 2023, arXiv:2304.03442) | `score = α·recency + β·importance + γ·relevance` — canonical formula for attention queues |
+| OS-level cron for invocation | Zep (arXiv:2501.13956, 2025), ELT survey (arXiv:2602.21568, 2026) | cron has known silent failure modes; future work: systemd timers with `Persistent=true` |
+
 ### Setup
 
 Moondream runs locally — no API keys, no cloud, your screen data never leaves your machine:
@@ -547,6 +606,10 @@ While the agent is working (shown by the `+` prompt), type to add context:
 | `manage_tools` | List, inspect, delete custom tools |
 | `skill_list` | Discover available AIWG skills |
 | `skill_execute` | Run an AIWG skill |
+| **Temporal Agency** | |
+| `scheduler` | Schedule tasks for automatic future execution via OS cron (presets, natural language, raw cron) |
+| `reminder` | Set cross-session reminders with priority, due dates, tags — surfaces at startup |
+| `agenda` | Unified view of reminders, schedules, and attention items with startup brief |
 | **AIWG SDLC** | |
 | `aiwg_setup` | Deploy AIWG SDLC framework |
 | `aiwg_health` | Analyze project SDLC health and readiness |