Impri

Poll until the human approves, rejects, or the timeout elapses.

Checks GET /actions/:id every 5 seconds and returns as soon as the action leaves the pending state.

Decision meanings: "approved" — proceed with the action; any reviewer edits are included in preview/payload "rejected" — abort; respect the decision and do not proceed "expired" — the approval window closed; create a new action if the task is still relevant

On timeout the action stays pending in the inbox. Call impri_inbox_status to check queue depth and consider pausing further submissions.

Typical usage:

1. impri_push_action → get action_id

2. impri_await_decision(action_id) → wait for human decision

3. If approved: execute the action, then impri_report_result(action_id, "executed")

Create a watcher that monitors external sources (RSS feeds, Reddit, URL diffs) and delivers matching items to the approval inbox or a webhook.

The watcher runs on the schedule you specify, deduplicates items by URL/content-hash, and delivers only new matches. The first run establishes a baseline and does not generate alerts.

Example — watch an RSS feed for AI-related news: spec: { name: "AI launches radar", kind: "rss", config: { url: "https://openai.com/news/rss.xml" }, keywords: ["launch", "gpt-", "voice"], keywords_none: ["funding", "benchmark"], min_score: 1, schedule: { every: "8h", jitter: "4h" } }

Returns { watcher_id, name, kind, status, next_run_at }.

Create a watcher from a preset template by supplying the preset id and param values.

Presets handle all watcher config construction — URL building, keyword setup, SSRF validation — so you only provide the param values listed by impri_list_watcher_presets.

The schedule defaults to the preset's recommended interval but can be overridden. The name defaults to "{preset title}: {primary param value}" if omitted.

Returns { watcher_id, name, kind, status, next_run_at }.

Examples:

Watch the HN front page (no params needed): preset_id: "hn-front-page" params: {}

Watch a subreddit for new posts: preset_id: "reddit-subreddit" params: { subreddit: "MachineLearning" }

Watch a GitHub repo for new releases, check every 2 hours: preset_id: "github-releases" params: { owner: "fastify", repo: "fastify" } schedule: { every: "2h" }

Watch HN for keyword with a custom min_points threshold: preset_id: "hn-keyword" params: { keyword: "rust programming", min_points: "25" }

Check how many actions are waiting for human decisions.

Returns the pending count and a brief list of pending action titles. Call this before starting a large batch of tasks — if the inbox is backed up, pause and let the operator catch up to avoid actions expiring before they are reviewed.

List all available watcher presets with their parameters.

Presets are pre-configured watcher templates for common sources (Hacker News, Reddit, GitHub, npm, YouTube, arXiv, etc.). Each preset has an id, a human-readable title, required and optional params, and a default schedule.

Call this first to discover which preset fits your monitoring goal, then use impri_create_watcher_from_preset to create the watcher by supplying only the preset_id and param values. No deep knowledge of watcher config schemas is needed.

Example output: Community: - hn-front-page: "Hacker News Front Page" (rss) — no params required - reddit-keyword: "Reddit – Keyword Search" (reddit_search) — params: query, [subreddit]

List all configured watchers, optionally filtered by status.

Returns the watcher count and a summary line per watcher (id, name, kind, status). Use this to audit what is being monitored, check for degraded watchers, or find a watcher_id for further operations.

Submit an action to the Impri human-approval inbox.

The action appears in the operator's web and mobile inbox as a card with a title, formatted preview, and optional tap-to-edit fields. The operator approves or rejects with one tap; you poll for the decision with impri_await_decision.

Returns { action_id, status: "pending", inbox_url }. Save action_id — you need it for all follow-up calls.

Example — send a draft Reddit reply for review: kind: "reddit.comment" title: "Reply: Why is resume advice so conflicting?" preview: { format: "markdown", body: "The advice conflicts because different advisors optimise for different audiences..." } target_url: "https://reddit.com/r/cscareerquestions/comments/..." editable: ["preview.body"] // lets the reviewer tweak wording before approving

Report whether you successfully executed an approved action.

Closes the audit loop — the operator sees 'executed' or 'execute_failed' in the inbox alongside the original action and decision. Always call this after attempting an approved action, even on failure.

Statuses: "executed" — action was carried out successfully "execute_failed" — execution attempt failed (include the error in detail)