catui-agent 1.0.0-beta.0

package/dist/extensions/builtin/link-world/link-world-agent.md

@@ -0,0 +1,82 @@
+---
+name: link-world
+description: Built-in internet access bridge for Catui. Use when a task needs agent-reach backed web search, browsing, or remote internet actions.
+---
+
+# Link-world
+
+Catui exposes link-world as first-class tools. Prefer these tools over calling `agent-reach` through `bash`.
+
+## Tool Selection
+
+- Use `web_search` for ordinary search and lightweight web research, but only if the tool is available in the current session.
+- Use `web_fetch` when you already have the target URL and need its content, but only if the tool is available in the current session.
+- Use `link_world_admin` first when you need setup status, version, install help, or diagnostics.
+- Use `link_world_exec` only when you need a lower-level `agent-reach` command that `web_search` does not model.
+- If the task is about interacting with a live page rather than retrieving knowledge, switch to the `browser` tool family instead of forcing link-world.
+- Do not hand-build shell strings for `agent-reach` unless the dedicated tools are unavailable.
+
+## Recommended Flow
+
+1. Check readiness with `link_world_admin` action `status` or `doctor`.
+2. If the runtime is missing, use `link_world_admin` action `install_help` or `/link-world install`.
+3. If `web_search` is available, use it for ordinary search.
+4. If `web_fetch` is available and the exact URL is already known, use it.
+5. If high-level link-world tools are unavailable, call `link_world_exec` with explicit argv-style arguments.
+6. Prefer bundled site or domain skills before inventing a new web workflow.
+
+## Examples
+
+Admin:
+
+```json
+{
+  "action": "status"
+}
+```
+
+Execution:
+
+High-level search:
+
+```json
+{
+  "query": "OpenAI Responses API"
+}
+```
+
+```json
+{
+  "query": "Playwright file upload",
+  "provider": "web",
+  "limit": 5
+}
+```
+
+High-level fetch:
+
+```json
+{
+  "url": "https://example.com/docs"
+}
+```
+
+Lower-level execution:
+
+```json
+{
+  "args": ["doctor"]
+}
+```
+
+```json
+{
+  "args": ["search", "OpenAI Responses API"]
+}
+```
+
+## Notes
+
+- Pass `args` as an array of tokens, not as one shell command string.
+- If `agent-reach` is not installed, the tools will return install guidance.
+- Keep Catui as the integration boundary: diagnostics through `link_world_admin`, search through `web_search`, direct retrieval through `web_fetch`, lower-level execution through `link_world_exec`.

package/dist/extensions/builtin/link-world/linkworld.md

@@ -0,0 +1,313 @@
+# link-world — Installation Guide
+
+## For Humans
+
+Copy this to your AI Agent:
+
+```
+帮我安装 link-world：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
+```
+
+> 🛡️ **Security-conscious?** Use safe mode — it won't auto-install system packages:
+> ```
+> 帮我安装 link-world（安全模式）：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
+> 安装时使用 --safe 参数
+> ```
+
+---
+
+## For AI Agents
+
+### Goal
+
+Install link-world and all upstream tools so your user's agent has full internet access. After installation, you'll use the upstream tools directly (xreach CLI, yt-dlp, mcporter, gh CLI, etc.) — link-world is just the installer and health checker.
+
+### ⚠️ Boundaries
+
+When fixing issues, stay within these limits:
+
+- **DO NOT** run commands with `sudo` unless the user explicitly approved
+- **DO NOT** modify system files outside `~/.agent-reach/`
+- **DO NOT** install packages not listed in this guide
+- **DO NOT** disable firewalls, security settings, or system protections
+- **DO NOT** clone repos, create files, or run commands inside the agent workspace / working directory
+- If something requires elevated permissions, **tell the user** what's needed and let them decide
+
+### 📁 Directory Rules
+
+All link-world files go in dedicated directories — **never in the agent workspace**:
+
+| Purpose | Directory | Example |
+|---------|-----------|---------|
+| Config & tokens | `~/.agent-reach/` | `~/.agent-reach/config.json` |
+| Upstream tool repos | `~/.agent-reach/tools/` | `~/.agent-reach/tools/douyin-mcp-server/` |
+| Temporary files | `/tmp/` | `/tmp/yt-dlp-output/` |
+| Skills | `~/.openclaw/skills/agent-reach/` | SKILL.md |
+
+**Why?** If you clone repos or create files in the workspace, it pollutes the user's project directory and can break their agent over time. Keep the workspace clean.
+
+### Step 1: Install
+
+**Default (fully automatic):**
+
+```bash
+pip install https://github.com/Panniantong/agent-reach/archive/main.zip
+agent-reach install --env=auto
+```
+
+This auto-installs system dependencies (gh CLI, Node.js, mcporter, xreach), configures Exa search, detects environment, and tests all channels.
+
+**Safe mode (no automatic system changes):**
+
+If the user asked for safe mode, or you're on a production machine:
+
+```bash
+pip install https://github.com/Panniantong/agent-reach/archive/main.zip
+agent-reach install --env=auto --safe
+```
+
+Safe mode checks what's installed and tells you what's missing, but doesn't auto-install system packages. You can then install each dependency manually.
+
+**Dry run (preview only):**
+
+```bash
+agent-reach install --env=auto --dry-run
+```
+
+Shows what would be done without making any changes.
+
+**Read the output carefully**, then run:
+
+```bash
+agent-reach doctor
+```
+
+### Step 2: Fix what's broken
+
+`agent-reach doctor` shows you which channels are active and which aren't.
+
+Try to get as many channels to ✅ as possible. If something failed during install or shows as ❌/⚠️ in doctor, diagnose the problem and try to fix it — but stay within the boundaries above. If a fix requires elevated permissions or system changes, ask the user first.
+
+Only ask the user when you genuinely need their input (credentials, permissions, etc.).
+
+### Step 3: Configure things that need user input
+
+Some channels need credentials only the user can provide. Based on the doctor output, ask for what's missing:
+
+> 🔒 **Security tip:** For platforms that need cookies (Twitter, XiaoHongShu), we recommend using a **dedicated/secondary account** rather than your main account. Cookie-based auth carries two risks:
+> 1. **Account ban** — platforms may detect non-browser API calls and restrict or ban the account
+> 2. **Credential exposure** — cookies grant full account access; using a secondary account limits the blast radius if credentials are ever compromised
+
+> 🍪 **Cookie 导入（所有需要登录的平台通用）：**
+>
+> 所有需要 Cookie 的平台（Twitter、小红书等），**优先使用 Cookie-Editor 导入**，这是最简单最可靠的方式：
+> 1. 用户在自己的浏览器上登录对应平台
+> 2. 安装 [Cookie-Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm) Chrome 插件
+> 3. 点击插件 → Export → Header String
+> 4. 把导出的字符串发给 Agent
+>
+> **本地电脑用户**也可以用 `agent-reach configure --from-browser chrome` 一键自动提取（支持 Twitter + 小红书）。
+
+**Twitter search & posting:**
+> "To unlock Twitter search, I need your Twitter cookies. Install the Cookie-Editor Chrome extension, go to x.com/twitter.com, click the extension → Export → Header String, and paste it to me."
+
+```bash
+agent-reach configure twitter-cookies "PASTED_STRING"
+```
+
+> **代理说明（中国大陆等需要翻墙的网络环境）：**
+>
+> xreach CLI 使用 Node.js 原生 `fetch()`，默认不走系统代理（`HTTP_PROXY`/`HTTPS_PROXY`）。link-world 已内置解决方案：安装时会自动安装 `undici`（`npm install -g undici`），运行 xreach 时自动注入 `EnvHttpProxyAgent`，让 fetch 走用户配置的代理。
+>
+> **你（Agent）需要做的：**
+> 1. 确认 `undici` 已全局安装：`npm list -g undici`，没有就装：`npm install -g undici`
+> 2. 确认用户配了代理：`agent-reach configure proxy http://user:pass@ip:port`
+> 3. link-world 会自动处理剩下的，不需要用户做额外操作
+>
+> 如果用户报告 "fetch failed"，参考 [troubleshooting.md](troubleshooting.md)
+
+**Reddit & Bilibili full access (server users):**
+> "Reddit and Bilibili block server IPs. To unlock full access, I need a residential proxy. You can get one at https://webshare.io ($1/month). Send me the proxy address."
+
+```bash
+agent-reach configure proxy http://user:pass@ip:port
+```
+
+**XiaoHongShu / 小红书 (需要 Docker):**
+> "小红书需要一个 MCP 服务。需要你的机器上有 Docker。安装好 Docker 后我来搞定剩下的。"
+
+```bash
+docker run -d --name xiaohongshu-mcp -p 18060:18060 xpzouying/xiaohongshu-mcp
+mcporter config add xiaohongshu http://localhost:18060/mcp
+```
+
+> 如果在服务器上，建议加代理避免 IP 风控：
+> `docker run -d --name xiaohongshu-mcp -p 18060:18060 -e XHS_PROXY=http://user:pass@ip:port xpzouying/xiaohongshu-mcp`
+>
+> **登录方式（优先用 Cookie-Editor，最简单）：**
+> 1. 用户在自己的浏览器登录小红书 (xiaohongshu.com)
+> 2. 用 [Cookie-Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm) 插件导出 Cookie（JSON 或 Header String 格式均可）
+> 3. 把 Cookie 字符串发给 Agent
+> 4. Agent 运行命令完成登录：
+>
+> ```bash
+> # JSON 格式（Cookie-Editor → Export → JSON）
+> agent-reach configure xhs-cookies '[{"name":"web_session","value":"xxx","domain":".xiaohongshu.com",...}]'
+>
+> # 或 Header String 格式（Cookie-Editor → Export → Header String）
+> agent-reach configure xhs-cookies "key1=val1; key2=val2; ..."
+> ```
+>
+> **备选：** 本地电脑如果有浏览器，也可以打开 http://localhost:18060 扫码登录。
+
+**抖音 / Douyin (douyin-mcp-server):**
+> "抖音视频解析需要一个 MCP 服务。安装 douyin-mcp-server 后即可解析视频、获取无水印下载链接。"
+
+```bash
+# 1. 安装
+pip install douyin-mcp-server
+
+# 2. 启动 HTTP 服务（端口 18070）
+# 方式一：用 uv（推荐）
+mkdir -p ~/.agent-reach/tools && cd ~/.agent-reach/tools
+git clone https://github.com/yzfly/douyin-mcp-server.git && cd douyin-mcp-server
+uv sync && uv run python run_http.py
+
+# 方式二：直接用 Python 启动
+python -c "
+from douyin_mcp_server.server import mcp
+mcp.settings.host = '127.0.0.1'
+mcp.settings.port = 18070
+mcp.run(transport='streamable-http')
+"
+
+# 3. 注册到 mcporter
+mcporter config add douyin http://localhost:18070/mcp
+```
+
+> 无需认证即可解析视频信息和获取下载链接。
+> 如需 AI 语音识别提取文案功能，需要配置硅基流动 API Key（`export API_KEY="sk-xxx"`）。
+>
+> 详见 https://github.com/yzfly/douyin-mcp-server
+
+**LinkedIn (可选 — linkedin-scraper-mcp):**
+> "LinkedIn 基本内容可通过 Jina Reader 读取。完整功能（Profile 详情、职位搜索）需要 linkedin-scraper-mcp。"
+
+```bash
+pip install linkedin-scraper-mcp
+```
+
+> **登录方式（需要浏览器界面）：**
+>
+> linkedin-scraper-mcp 使用 Chromium 浏览器登录，需要你能看到浏览器窗口。
+>
+> - **本地电脑（有桌面）：** 直接运行：
+>   ```bash
+>   linkedin-scraper-mcp --login --no-headless
+>   ```
+>   浏览器会弹出来，手动登录 LinkedIn 即可。
+>
+> - **服务器（无 UI）：** 需要通过 VNC 远程桌面操作：
+>   ```bash
+>   # 1. 服务器上安装并启动 VNC（如已有可跳过）
+>   apt install -y tigervnc-standalone-server
+>   vncserver :1 -geometry 1280x720
+>
+>   # 2. 用 VNC 客户端连接 服务器IP:5901
+>
+>   # 3. 在 VNC 桌面的终端里运行：
+>   export DISPLAY=:1
+>   linkedin-scraper-mcp --login --no-headless
+>   ```
+>   在 VNC 里看到浏览器后手动登录。登录成功后 session 会保存到 `~/.linkedin-mcp/profile/`。
+>
+> **登录后启动 MCP 服务：**
+> ```bash
+> linkedin-scraper-mcp --transport streamable-http --port 8001
+> mcporter config add linkedin http://localhost:8001/mcp
+> ```
+>
+> 详见 https://github.com/stickerdaniel/linkedin-mcp-server
+
+**Boss直聘 (可选 — mcp-bosszp):**
+> "Boss直聘职位页面可直接读取。完整搜索和打招呼功能需要 mcp-bosszp。"
+
+```bash
+mkdir -p ~/.agent-reach/tools && cd ~/.agent-reach/tools
+git clone https://github.com/mucsbr/mcp-bosszp.git && cd mcp-bosszp
+pip install -r requirements.txt && playwright install chromium
+```
+
+> **登录方式（手机 App 扫码）：**
+>
+> mcp-bosszp 使用二维码登录，需要 Boss直聘 App 扫码。
+>
+> ```bash
+> # 1. 启动 MCP 服务
+> python boss_zhipin_fastmcp_v2.py
+>
+> # 2. 通过 MCP 触发登录（会生成二维码图片）
+> mcporter call 'bosszhipin.start_login()'
+>
+> # 3. 浏览器打开二维码图片（服务器上用 http://服务器IP:8000/static/qrcode_xxx.png）
+> # 4. 用 Boss直聘 App 扫码确认
+> ```
+>
+> 扫码成功后 session 自动保存，之后可以搜索职位和自动打招呼。
+>
+> 或用 Docker：`docker-compose up -d`
+>
+> 详见 https://github.com/mucsbr/mcp-bosszp
+
+### Step 4: Final check
+
+Run `agent-reach doctor` one final time and report the results to your user.
+
+### Step 5: Set up daily monitoring (OpenClaw only)
+
+If you are running inside **OpenClaw**, ask your user:
+
+> "link-world 安装好了。要不要我设一个每天自动检查的任务？它会帮你盯着这些渠道是否正常、有没有新版本。有问题才会通知你，没问题不打扰。"
+
+If the user agrees, create a **cron job** (daily, `sessionTarget: "isolated"`, `delivery: "announce"`) with this task:
+
+```
+运行 agent-reach watch 命令。
+如果输出包含"全部正常"，不需要通知用户，静默结束。
+如果输出包含问题（❌ ⚠️）或新版本（🆕），把完整报告发给用户，并建议修复方案。
+如果有新版本可用，问用户是否要升级（升级命令：pip install --upgrade https://github.com/Panniantong/agent-reach/archive/main.zip）。
+```
+
+If the user wants a different agent to handle it, let them choose.
+
+---
+
+## Quick Reference
+
+| Command | What it does |
+|---------|-------------|
+| `agent-reach install --env=auto` | Full auto-setup (installs deps + configures) |
+| `agent-reach install --env=auto --safe` | Safe setup (no auto system changes) |
+| `agent-reach install --env=auto --dry-run` | Preview what would be done |
+| `agent-reach doctor` | Show channel status |
+| `agent-reach watch` | Quick health + update check (for scheduled tasks) |
+| `agent-reach check-update` | Check for new versions |
+| `agent-reach configure twitter-cookies "..."` | Unlock Twitter search + posting |
+| `agent-reach configure proxy URL` | Unlock Reddit + Bilibili on servers |
+
+After installation, use upstream tools directly. See SKILL.md for the full command reference:
+
+| Platform | Upstream Tool | Example |
+|----------|---------------|---------|
+| Twitter/X | `xreach` | `xreach search "query" --json` |
+| YouTube | `yt-dlp` | `yt-dlp --dump-json URL` |
+| Bilibili | `yt-dlp` | `yt-dlp --dump-json URL` |
+| Reddit | `curl` | `curl -s "https://reddit.com/r/xxx.json"` |
+| GitHub | `gh` | `gh search repos "query"` |
+| Web | `curl` + Jina | `curl -s "https://r.jina.ai/URL"` |
+| Exa Search | `mcporter` | `mcporter call 'exa.web_search_exa(...)'` |
+| 小红书 | `mcporter` | `mcporter call 'xiaohongshu.search_feeds(...)'` |
+| 抖音 | `mcporter` | `mcporter call 'douyin.parse_douyin_video_info(...)'` |
+| LinkedIn | `mcporter` | `mcporter call 'linkedin.get_person_profile(...)'` |
+| Boss直聘 | `mcporter` | `mcporter call 'bosszhipin.search_jobs_tool(...)'` |
+| RSS | `feedparser` | `python3 -c "import feedparser; ..."` |

package/dist/extensions/builtin/link-world/network-routing/network-routing.md

@@ -0,0 +1,67 @@
+---
+name: network-routing
+description: Decide whether a task should use Catui's web_search, link_world tools, or browser automation.
+---
+
+# Network Routing
+
+Catui has two different network paths:
+
+- `web_search` and `web_fetch` when those high-level tools are actually available in the current session
+- `link_world_*` as the durable lower-level integration path
+- `browser` and `browser_admin` for direct browser control and page interaction
+
+Choose the path by task shape, not by habit.
+
+## Use `web_search` First
+
+Use `web_search` when it is available and the user needs:
+
+- current facts
+- recent news
+- API/library documentation lookup
+- general web research
+- "what is", "find", "latest", "look up", "compare", or "summarize" style requests
+
+If setup is uncertain, call `link_world_admin` with `status` or `doctor` first.
+
+## Use `web_fetch` When The URL Is Known
+
+Use `web_fetch` when it is available and:
+
+- the user already gave a URL
+- a prior search step found the exact page you need
+- you need page content, not browser interaction
+- the task is fetch-and-read rather than click-and-drive
+
+## Use `browser` First
+
+Use `browser` when the user needs:
+
+- login-gated pages
+- clicking, typing, uploads, downloads, tabs, screenshots
+- form submission
+- navigating a live web app
+- inspecting visible UI state
+- browser-based verification
+
+If setup is uncertain, call `browser_admin` with `status` or `setup` first.
+
+## Fallback Order
+
+1. If `web_search` is available, use it for current knowledge discovery.
+2. If `web_fetch` is available and the target URL is already known, use it.
+3. If the answer requires interacting with a page, switch to `browser`.
+4. If high-level link-world tools are unavailable but internet runtime is present, use `link_world_exec`.
+5. Only fall back to `bash` for external CLIs when the dedicated tools are unavailable.
+
+## Working Rule
+
+Prefer Catui's named tools over raw shell commands. The integration boundary should stay inside:
+
+- `link_world_admin`
+- `web_search`
+- `web_fetch`
+- `link_world_exec`
+- `browser_admin`
+- `browser`

package/dist/extensions/builtin/loop/README.md

@@ -0,0 +1,92 @@
+# Loop Extension
+
+`/loop` schedules a recurring prompt or slash command for the current session.
+Uses the unified **cron scheduler** architecture per the refactoring plan.
+
+For the autonomous "keep digging until done" runner, see the sibling
+[`grub` extension](../grub/README.md).
+
+## Architecture
+
+```
+/loop command ──→ addCronTask ──→ unified store ──→ cron scheduler ──→ onFire ──→ dispatch
+                     │                                  │
+              CronCreate tool                    file watcher (3s reload)
+              CronDelete tool                    jitter + lock
+              CronList tool                      7-day expiry
+```
+
+**Key design decisions**:
+- Single scheduler (cron scheduler) for all tasks
+- Single storage (`.catui/cron-tasks.json` for durable, memory for session)
+- `/loop` command and CronCreate tool both use `addCronTask`
+- Enhanced features (--name, --max, --quiet, pause/resume) built on top
+
+## Quick start
+
+```
+/loop check the build                       # every 10m (default)
+/loop 5m /grub status                       # slash command every 5 minutes
+/loop every 10m Review test failures
+/loop Drink water every 30m --name hydrate --max 8 --quiet
+/loop Check build every 5m --durable        # persists across sessions
+```
+
+## Manage
+
+```
+/loop list                  # all scheduled loops
+/loop status <ref>          # detail one loop (ref = name or id)
+/loop pause <ref>
+/loop resume <ref>
+/loop run <ref>             # fire immediately
+/loop cancel <ref>          # remove one
+/loop clear                 # remove all
+```
+
+`<ref>` can be either the auto-generated id or the `--name` slug.
+
+## Flags
+
+- `--name <slug>` — give the loop a friendly handle so you can `pause hydrate`
+  instead of memorising hex ids.
+- `--max <n>` — auto-cancel after `n` runs.
+- `--quiet` (or `-q`) — suppress per-tick UI messages. Errors and terminal
+  events still surface; routine ticks are still recorded via `appendEntry`.
+- `--durable` (or `-d`) — persist the loop across sessions. Durable loops are
+  saved to `.catui/cron-tasks.json` and will resume when you reopen the
+  project.
+
+## Notes
+
+- By default, loops are **session-scoped**: closing the session clears them.
+- Use `--durable` to persist loops across sessions.
+- Durable loops are stored in `.catui/cron-tasks.json` in your project
+  directory.
+- **Auto-expiry**: Durable loops automatically expire after 7 days to prevent
+  zombie tasks from accumulating.
+- Due tasks wait for the agent to be idle; missed intervals collapse to one
+  pending run.
+- Slash-command payloads are detected at parse time and dispatched through
+  `executeCommand`; everything else is delivered through `sendUserMessage` as
+  a follow-up turn.
+- After each loop tick the last assistant message is captured (truncated to
+  120 chars) and shown in `/loop status <ref>` as `Last output`.
+- Supports `s/m/h/d` durations and `hourly`/`daily` shortcuts.
+- **Jitter**: Tasks have deterministic jitter (based on task ID) to avoid
+  traffic spikes at round times.
+- **Scheduler lock**: Multiple sessions in the same project use proper-lockfile
+  to prevent duplicate task execution.
+
+## Cron Tools
+
+The extension also registers three tools for the model to use directly:
+
+| Tool | Purpose |
+|------|---------|
+| `CronCreate` | Create a scheduled task with cron expression |
+| `CronDelete` | Delete a scheduled task by ID |
+| `CronList` | List all active scheduled tasks |
+
+This allows the model to create and manage scheduled tasks through natural
+language understanding, following the refactoring plan's architecture.

package/dist/extensions/builtin/loop/cron/cron-parser.d.ts

@@ -0,0 +1,56 @@
+/**
+ * [WHO]: CronFields, parseCronExpression, computeNextCronRun, cronToHuman, intervalToCron
+ * [FROM]: No first-party dependencies
+ * [TO]: Consumed by ./cron-scheduler, ./cron-tasks, ./index
+ * [HERE]: extensions/builtin/loop/cron/cron-parser.ts - cron expression parsing and next-run calculation
+ *
+ * Minimal cron expression parsing and next-run calculation.
+ *
+ * 1:1 port of Claude Code src/utils/cron.ts
+ *
+ * Supports the standard 5-field cron subset:
+ *   minute hour day-of-month month day-of-week
+ *
+ * Field syntax: wildcard, N, step (star-slash-N), range (N-M), list (N,M,...).
+ * No L, W, ?, or name aliases. All times are interpreted in the process's
+ * local timezone — "0 9 * * *" means 9am wherever the CLI is running.
+ */
+export type CronFields = {
+    minute: number[];
+    hour: number[];
+    dayOfMonth: number[];
+    month: number[];
+    dayOfWeek: number[];
+};
+/**
+ * Parse a 5-field cron expression into expanded number arrays.
+ * Returns null if invalid or unsupported syntax.
+ */
+export declare function parseCronExpression(expr: string): CronFields | null;
+/**
+ * Compute the next Date strictly after `from` that matches the cron fields,
+ * using the process's local timezone. Walks forward minute-by-minute. Bounded
+ * at 366 days; returns null if no match (impossible for valid cron, but
+ * satisfies the type).
+ *
+ * Standard cron semantics: when both dayOfMonth and dayOfWeek are constrained
+ * (neither is the full range), a date matches if EITHER matches.
+ *
+ * DST: fixed-hour crons targeting a spring-forward gap (e.g. `30 2 * * *`
+ * in a US timezone) skip the transition day — the gap hour never appears
+ * in local time, so the hour-set check fails and the loop moves on.
+ * Wildcard-hour crons (`30 * * * *`) fire at the first valid minute after
+ * the gap. Fall-back repeats fire once (the step-forward logic jumps past
+ * the second occurrence). This matches vixie-cron behavior.
+ */
+export declare function computeNextCronRun(fields: CronFields, from: Date): Date | null;
+export declare function cronToHuman(cron: string, opts?: {
+    utc?: boolean;
+}): string;
+/**
+ * Convert interval string (e.g., "5m", "1h", "30s") to cron expression.
+ * Supports s, m, h, d units.
+ *
+ * Kept as a utility for the /loop skill (CC does this conversion in the skill layer).
+ */
+export declare function intervalToCron(interval: string): string | null;

package/dist/extensions/builtin/loop/cron/cron-parser.js

@@ -0,0 +1 @@
+var S=Object.defineProperty;var g=(e,s)=>S(e,"name",{value:s,configurable:!0});const x=[{min:0,max:59},{min:0,max:23},{min:1,max:31},{min:1,max:12},{min:0,max:6}];function w(e,s){const{min:n,max:a}=s,r=new Set;for(const u of e.split(",")){const i=u.match(/^\*(?:\/(\d+))?$/);if(i){const t=i[1]?parseInt(i[1],10):1;if(t<1)return null;for(let m=n;m<=a;m+=t)r.add(m);continue}const c=u.match(/^(\d+)-(\d+)(?:\/(\d+))?$/);if(c){const t=parseInt(c[1],10),m=parseInt(c[2],10),d=c[3]?parseInt(c[3],10):1,f=n===0&&a===6,l=f?7:a;if(t>m||d<1||t<n||m>l)return null;for(let o=t;o<=m;o+=d)r.add(f&&o===7?0:o);continue}if(u.match(/^\d+$/)){let t=parseInt(u,10);if(n===0&&a===6&&t===7&&(t=0),t<n||t>a)return null;r.add(t);continue}return null}return r.size===0?null:Array.from(r).sort((u,i)=>u-i)}g(w,"expandField");function v(e){const s=e.trim().split(/\s+/);if(s.length!==5)return null;const n=[];for(let a=0;a<5;a++){const r=w(s[a],x[a]);if(!r)return null;n.push(r)}return{minute:n[0],hour:n[1],dayOfMonth:n[2],month:n[3],dayOfWeek:n[4]}}g(v,"parseCronExpression");function E(e,s){const n=new Set(e.minute),a=new Set(e.hour),r=new Set(e.dayOfMonth),u=new Set(e.month),i=new Set(e.dayOfWeek),c=e.dayOfMonth.length===31,h=e.dayOfWeek.length===7,t=new Date(s.getTime());t.setSeconds(0,0),t.setMinutes(t.getMinutes()+1);const m=366*24*60;for(let d=0;d<m;d++){const f=t.getMonth()+1;if(!u.has(f)){t.setMonth(t.getMonth()+1,1),t.setHours(0,0,0,0);continue}const l=t.getDate(),o=t.getDay();if(!(c&&h?!0:c?i.has(o):h?r.has(l):r.has(l)||i.has(o))){t.setDate(t.getDate()+1),t.setHours(0,0,0,0);continue}if(!a.has(t.getHours())){t.setHours(t.getHours()+1,0,0,0);continue}if(!n.has(t.getMinutes())){t.setMinutes(t.getMinutes()+1);continue}return t}return null}g(E,"computeNextCronRun");const M=["Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday"];function I(e,s){return new Date(2e3,0,1,s,e).toLocaleTimeString("en-US",{hour:"numeric",minute:"2-digit"})}g(I,"formatLocalTime");function T(e,s){const n=new Date;return n.setUTCHours(s,e,0,0),n.toLocaleTimeString("en-US",{hour:"numeric",minute:"2-digit",timeZoneName:"short"})}g(T,"formatUtcTimeAsLocal");function C(e,s){const n=s?.utc??!1,a=e.trim().split(/\s+/);if(a.length!==5)return e;const[r,u,i,c,h]=a,t=r.match(/^\*\/(\d+)$/);if(t&&u==="*"&&i==="*"&&c==="*"&&h==="*"){const o=parseInt(t[1],10);return o===1?"Every minute":`Every ${o} minutes`}if(r.match(/^\d+$/)&&u==="*"&&i==="*"&&c==="*"&&h==="*"){const o=parseInt(r,10);return o===0?"Every hour":`Every hour at :${o.toString().padStart(2,"0")}`}const m=u.match(/^\*\/(\d+)$/);if(r.match(/^\d+$/)&&m&&i==="*"&&c==="*"&&h==="*"){const o=parseInt(m[1],10),y=parseInt(r,10),p=y===0?"":` at :${y.toString().padStart(2,"0")}`;return o===1?`Every hour${p}`:`Every ${o} hours${p}`}if(!r.match(/^\d+$/)||!u.match(/^\d+$/))return e;const d=parseInt(r,10),f=parseInt(u,10),l=n?T:I;if(i==="*"&&c==="*"&&h==="*")return`Every day at ${l(d,f)}`;if(i==="*"&&c==="*"&&h.match(/^\d$/)){const o=parseInt(h,10)%7;let y;if(n){const p=new Date,$=(o-p.getUTCDay()+7)%7;p.setUTCDate(p.getUTCDate()+$),p.setUTCHours(f,d,0,0),y=M[p.getDay()]}else y=M[o];if(y)return`Every ${y} at ${l(d,f)}`}return i==="*"&&c==="*"&&h==="1-5"?`Weekdays at ${l(d,f)}`:e}g(C,"cronToHuman");function H(e){const s=e.match(/^(\d+)(s|m|h|d)$/i);if(!s)return null;const n=Number.parseInt(s[1],10),a=s[2].toLowerCase();if(!Number.isFinite(n)||n<=0)return null;switch(a){case"s":return`*/${Math.max(1,Math.ceil(n/60))} * * * *`;case"m":{if(n>=60){const r=Math.floor(n/60);return n%60===0?`0 */${r} * * *`:`*/${n} * * * *`}return`*/${n} * * * *`}case"h":return n>=24?`0 0 */${Math.floor(n/24)} * *`:`0 */${n} * * *`;case"d":return`0 0 */${n} * *`;default:return null}}g(H,"intervalToCron");export{E as computeNextCronRun,C as cronToHuman,H as intervalToCron,v as parseCronExpression};