vora-ai 0.1.0

package/docs/automation/cron-vs-heartbeat.md

@@ -0,0 +1,299 @@
+---
+summary: "Guidance for choosing between heartbeat and cron jobs for automation"
+read_when:
+  - Deciding how to schedule recurring tasks
+  - Setting up background monitoring or notifications
+  - Optimizing token usage for periodic checks
+title: "Cron vs Heartbeat"
+---
+
+# Cron vs Heartbeat: When to Use Each
+
+Both heartbeats and cron jobs let you run tasks on a schedule. This guide helps you choose the right mechanism for your use case.
+
+One important distinction:
+
+- **Heartbeat** is a scheduled **main-session turn** — no task record created.
+- **Cron (main)** is a scheduled **system event into the main session** — creates a task record with `silent` notify policy.
+- **Cron (isolated)** is a scheduled **background run** — creates a task record tracked in `vora tasks`.
+
+All cron job executions (main and isolated) create [task records](/automation/tasks). Heartbeat turns do not. Main-session cron tasks use `silent` notify policy by default so they do not generate notifications.
+
+## Quick Decision Guide
+
+| Use Case                             | Recommended         | Why                                      |
+| ------------------------------------ | ------------------- | ---------------------------------------- |
+| Check inbox every 30 min             | Heartbeat           | Batches with other checks, context-aware |
+| Send daily report at 9am sharp       | Cron (isolated)     | Exact timing needed                      |
+| Monitor calendar for upcoming events | Heartbeat           | Natural fit for periodic awareness       |
+| Run weekly deep analysis             | Cron (isolated)     | Standalone task, can use different model |
+| Remind me in 20 minutes              | Cron (main, `--at`) | One-shot with precise timing             |
+| Background project health check      | Heartbeat           | Piggybacks on existing cycle             |
+
+## Heartbeat: Periodic Awareness
+
+Heartbeats run in the **main session** at a regular interval (default: 30 min). They're designed for the agent to check on things and surface anything important.
+
+### When to use heartbeat
+
+- **Multiple periodic checks**: Instead of 5 separate cron jobs checking inbox, calendar, weather, notifications, and project status, a single heartbeat can batch all of these.
+- **Context-aware decisions**: The agent has full main-session context, so it can make smart decisions about what's urgent vs. what can wait.
+- **Conversational continuity**: Heartbeat runs share the same session, so the agent remembers recent conversations and can follow up naturally.
+- **Low-overhead monitoring**: One heartbeat replaces many small polling tasks.
+
+### Heartbeat advantages
+
+- **Batches multiple checks**: One agent turn can review inbox, calendar, and notifications together.
+- **Reduces API calls**: A single heartbeat is cheaper than 5 isolated cron jobs.
+- **Context-aware**: The agent knows what you've been working on and can prioritize accordingly.
+- **Smart suppression**: If nothing needs attention, the agent replies `HEARTBEAT_OK` and no message is delivered.
+- **Natural timing**: Drifts slightly based on queue load, which is fine for most monitoring.
+- **No task record**: heartbeat turns stay in main-session history (see [Background Tasks](/automation/tasks)).
+
+### Heartbeat example: HEARTBEAT.md checklist
+
+```md
+# Heartbeat checklist
+
+- Check email for urgent messages
+- Review calendar for events in next 2 hours
+- If a background task finished, summarize results
+- If idle for 8+ hours, send a brief check-in
+```
+
+The agent reads this on each heartbeat and handles all items in one turn.
+
+### Configuring heartbeat
+
+```json5
+{
+  agents: {
+    defaults: {
+      heartbeat: {
+        every: "30m", // interval
+        target: "last", // explicit alert delivery target (default is "none")
+        activeHours: { start: "08:00", end: "22:00" }, // optional
+      },
+    },
+  },
+}
+```
+
+See [Heartbeat](/gateway/heartbeat) for full configuration.
+
+## Cron: Precise Scheduling
+
+Cron jobs run at precise times and can run in isolated sessions without affecting main context.
+Recurring top-of-hour schedules are automatically spread by a deterministic
+per-job offset in a 0-5 minute window.
+
+### When to use cron
+
+- **Exact timing required**: "Send this at 9:00 AM every Monday" (not "sometime around 9").
+- **Standalone tasks**: Tasks that don't need conversational context.
+- **Different model/thinking**: Heavy analysis that warrants a more powerful model.
+- **One-shot reminders**: "Remind me in 20 minutes" with `--at`.
+- **Noisy/frequent tasks**: Tasks that would clutter main session history.
+- **External triggers**: Tasks that should run independently of whether the agent is otherwise active.
+
+### Cron advantages
+
+- **Precise timing**: 5-field or 6-field (seconds) cron expressions with timezone support.
+- **Built-in load spreading**: recurring top-of-hour schedules are staggered by up to 5 minutes by default.
+- **Per-job control**: override stagger with `--stagger <duration>` or force exact timing with `--exact`.
+- **Session isolation**: Runs in `cron:<jobId>` without polluting main history.
+- **Model overrides**: Use a cheaper or more powerful model per job.
+- **Delivery control**: Isolated jobs default to `announce` (summary); choose `none` as needed.
+- **Immediate delivery**: Announce mode posts directly without waiting for heartbeat.
+- **No agent context needed**: Runs even if main session is idle or compacted.
+- **One-shot support**: `--at` for precise future timestamps.
+- **Task tracking**: isolated jobs create [background task](/automation/tasks) records visible in `vora tasks` and `vora tasks audit`.
+
+### Cron example: Daily morning briefing
+
+```bash
+vora cron add \
+  --name "Morning briefing" \
+  --cron "0 7 * * *" \
+  --tz "America/New_York" \
+  --session isolated \
+  --message "Generate today's briefing: weather, calendar, top emails, news summary." \
+  --model opus \
+  --announce \
+  --channel whatsapp \
+  --to "+15551234567"
+```
+
+This runs at exactly 7:00 AM New York time, uses Opus for quality, and announces a summary directly to WhatsApp.
+
+### Cron example: One-shot reminder
+
+```bash
+vora cron add \
+  --name "Meeting reminder" \
+  --at "20m" \
+  --session main \
+  --system-event "Reminder: standup meeting starts in 10 minutes." \
+  --wake now \
+  --delete-after-run
+```
+
+See [Cron jobs](/automation/cron-jobs) for full CLI reference.
+
+## Decision Flowchart
+
+```
+Does the task need to run at an EXACT time?
+  YES -> Use cron
+  NO  -> Continue...
+
+Does the task need isolation from main session?
+  YES -> Use cron (isolated)
+  NO  -> Continue...
+
+Can this task be batched with other periodic checks?
+  YES -> Use heartbeat (add to HEARTBEAT.md)
+  NO  -> Use cron
+
+Is this a one-shot reminder?
+  YES -> Use cron with --at
+  NO  -> Continue...
+
+Does it need a different model or thinking level?
+  YES -> Use cron (isolated) with --model/--thinking
+  NO  -> Use heartbeat
+```
+
+## Combining Both
+
+The most efficient setup uses **both**:
+
+1. **Heartbeat** handles routine monitoring (inbox, calendar, notifications) in one batched turn every 30 minutes.
+2. **Cron** handles precise schedules (daily reports, weekly reviews) and one-shot reminders.
+
+### Example: Efficient automation setup
+
+**HEARTBEAT.md** (checked every 30 min):
+
+```md
+# Heartbeat checklist
+
+- Scan inbox for urgent emails
+- Check calendar for events in next 2h
+- Review any pending tasks
+- Light check-in if quiet for 8+ hours
+```
+
+**Cron jobs** (precise timing):
+
+```bash
+# Daily morning briefing at 7am
+vora cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --announce
+
+# Weekly project review on Mondays at 9am
+vora cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus
+
+# One-shot reminder
+vora cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now
+```
+
+## Lobster: Deterministic workflows with approvals
+
+Lobster is the workflow runtime for **multi-step tool pipelines** that need deterministic execution and explicit approvals.
+Use it when the task is more than a single agent turn, and you want a resumable workflow with human checkpoints.
+
+### When Lobster fits
+
+- **Multi-step automation**: You need a fixed pipeline of tool calls, not a one-off prompt.
+- **Approval gates**: Side effects should pause until you approve, then resume.
+- **Resumable runs**: Continue a paused workflow without re-running earlier steps.
+
+### How it pairs with heartbeat and cron
+
+- **Heartbeat/cron** decide _when_ a run happens.
+- **Lobster** defines _what steps_ happen once the run starts.
+
+For scheduled workflows, use cron or heartbeat to trigger an agent turn that calls Lobster.
+For ad-hoc workflows, call Lobster directly.
+
+### Operational notes (from the code)
+
+- Lobster runs as a **local subprocess** (`lobster` CLI) in tool mode and returns a **JSON envelope**.
+- If the tool returns `needs_approval`, you resume with a `resumeToken` and `approve` flag.
+- The tool is an **optional plugin**; enable it additively via `tools.alsoAllow: ["lobster"]` (recommended).
+- Lobster expects the `lobster` CLI to be available on `PATH`.
+
+See [Lobster](/tools/lobster) for full usage and examples.
+
+## Main Session vs Isolated Session
+
+Both heartbeat and cron can interact with the main session, but differently:
+
+|                            | Heartbeat                       | Cron (main)              | Cron (isolated)                                 |
+| -------------------------- | ------------------------------- | ------------------------ | ----------------------------------------------- |
+| Session                    | Main                            | Main (via system event)  | `cron:<jobId>` or custom session                |
+| History                    | Shared                          | Shared                   | Fresh each run (isolated) / Persistent (custom) |
+| Context                    | Full                            | Full                     | None (isolated) / Cumulative (custom)           |
+| Model                      | Main session model              | Main session model       | Can override                                    |
+| Output                     | Delivered if not `HEARTBEAT_OK` | Heartbeat prompt + event | Announce summary (default)                      |
+| [Tasks](/automation/tasks) | No task record                  | Task record (silent)     | Task record (visible in `vora tasks`)       |
+
+### When to use main session cron
+
+Use `--session main` with `--system-event` when you want:
+
+- The reminder/event to appear in main session context
+- The agent to handle it during the next heartbeat with full context
+- No separate isolated run
+
+```bash
+vora cron add \
+  --name "Check project" \
+  --every "4h" \
+  --session main \
+  --system-event "Time for a project health check" \
+  --wake now
+```
+
+### When to use isolated cron
+
+Use `--session isolated` when you want:
+
+- A clean slate without prior context
+- Different model or thinking settings
+- Announce summaries directly to a channel
+- History that doesn't clutter main session
+
+```bash
+vora cron add \
+  --name "Deep analysis" \
+  --cron "0 6 * * 0" \
+  --session isolated \
+  --message "Weekly codebase analysis..." \
+  --model opus \
+  --thinking high \
+  --announce
+```
+
+## Cost Considerations
+
+| Mechanism       | Cost Profile                                            |
+| --------------- | ------------------------------------------------------- |
+| Heartbeat       | One turn every N minutes; scales with HEARTBEAT.md size |
+| Cron (main)     | Adds event to next heartbeat (no isolated turn)         |
+| Cron (isolated) | Full agent turn per job; can use cheaper model          |
+
+**Tips**:
+
+- Keep `HEARTBEAT.md` small to minimize token overhead.
+- Batch similar checks into heartbeat instead of multiple cron jobs.
+- Use `target: "none"` on heartbeat if you only want internal processing.
+- Use isolated cron with a cheaper model for routine tasks.
+
+## Related
+
+- [Automation Overview](/automation) — all automation mechanisms at a glance
+- [Heartbeat](/gateway/heartbeat) — full heartbeat configuration
+- [Cron jobs](/automation/cron-jobs) — full cron CLI and API reference
+- [Background Tasks](/automation/tasks) — task ledger, audit, and lifecycle
+- [System](/cli/system) — system events + heartbeat controls

package/docs/automation/gmail-pubsub.md

@@ -0,0 +1,256 @@
+---
+summary: "Gmail Pub/Sub push wired into Vora webhooks via gogcli"
+read_when:
+  - Wiring Gmail inbox triggers to Vora
+  - Setting up Pub/Sub push for agent wake
+title: "Gmail PubSub"
+---
+
+# Gmail Pub/Sub -> Vora
+
+Goal: Gmail watch -> Pub/Sub push -> `gog gmail watch serve` -> Vora webhook.
+
+## Prereqs
+
+- `gcloud` installed and logged in ([install guide](https://docs.cloud.google.com/sdk/docs/install-sdk)).
+- `gog` (gogcli) installed and authorized for the Gmail account ([gogcli.sh](https://gogcli.sh/)).
+- Vora hooks enabled (see [Webhooks](/automation/webhook)).
+- `tailscale` logged in ([tailscale.com](https://tailscale.com/)). Supported setup uses Tailscale Funnel for the public HTTPS endpoint.
+  Other tunnel services can work, but are DIY/unsupported and require manual wiring.
+  Right now, Tailscale is what we support.
+
+Example hook config (enable Gmail preset mapping):
+
+```json5
+{
+  hooks: {
+    enabled: true,
+    token: "VORA_HOOK_TOKEN",
+    path: "/hooks",
+    presets: ["gmail"],
+  },
+}
+```
+
+To deliver the Gmail summary to a chat surface, override the preset with a mapping
+that sets `deliver` + optional `channel`/`to`:
+
+```json5
+{
+  hooks: {
+    enabled: true,
+    token: "VORA_HOOK_TOKEN",
+    presets: ["gmail"],
+    mappings: [
+      {
+        match: { path: "gmail" },
+        action: "agent",
+        wakeMode: "now",
+        name: "Gmail",
+        sessionKey: "hook:gmail:{{messages[0].id}}",
+        messageTemplate: "New email from {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}\n{{messages[0].body}}",
+        model: "openai/gpt-5.2-mini",
+        deliver: true,
+        channel: "last",
+        // to: "+15551234567"
+      },
+    ],
+  },
+}
+```
+
+If you want a fixed channel, set `channel` + `to`. Otherwise `channel: "last"`
+uses the last delivery route (falls back to WhatsApp).
+
+To force a cheaper model for Gmail runs, set `model` in the mapping
+(`provider/model` or alias). If you enforce `agents.defaults.models`, include it there.
+
+To set a default model and thinking level specifically for Gmail hooks, add
+`hooks.gmail.model` / `hooks.gmail.thinking` in your config:
+
+```json5
+{
+  hooks: {
+    gmail: {
+      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
+      thinking: "off",
+    },
+  },
+}
+```
+
+Notes:
+
+- Per-hook `model`/`thinking` in the mapping still overrides these defaults.
+- Fallback order: `hooks.gmail.model` → `agents.defaults.model.fallbacks` → primary (auth/rate-limit/timeouts).
+- If `agents.defaults.models` is set, the Gmail model must be in the allowlist.
+- Gmail hook content is wrapped with external-content safety boundaries by default.
+  To disable (dangerous), set `hooks.gmail.allowUnsafeExternalContent: true`.
+
+To customize payload handling further, add `hooks.mappings` or a JS/TS transform module
+under `~/.vora/hooks/transforms` (see [Webhooks](/automation/webhook)).
+
+## Wizard (recommended)
+
+Use the Vora helper to wire everything together (installs deps on macOS via brew):
+
+```bash
+vora webhooks gmail setup \
+  --account vora@gmail.com
+```
+
+Defaults:
+
+- Uses Tailscale Funnel for the public push endpoint.
+- Writes `hooks.gmail` config for `vora webhooks gmail run`.
+- Enables the Gmail hook preset (`hooks.presets: ["gmail"]`).
+
+Path note: when `tailscale.mode` is enabled, Vora automatically sets
+`hooks.gmail.serve.path` to `/` and keeps the public path at
+`hooks.gmail.tailscale.path` (default `/gmail-pubsub`) because Tailscale
+strips the set-path prefix before proxying.
+If you need the backend to receive the prefixed path, set
+`hooks.gmail.tailscale.target` (or `--tailscale-target`) to a full URL like
+`http://127.0.0.1:8788/gmail-pubsub` and match `hooks.gmail.serve.path`.
+
+Want a custom endpoint? Use `--push-endpoint <url>` or `--tailscale off`.
+
+Platform note: on macOS the wizard installs `gcloud`, `gogcli`, and `tailscale`
+via Homebrew; on Linux install them manually first.
+
+Gateway auto-start (recommended):
+
+- When `hooks.enabled=true` and `hooks.gmail.account` is set, the Gateway starts
+  `gog gmail watch serve` on boot and auto-renews the watch.
+- Set `VORA_SKIP_GMAIL_WATCHER=1` to opt out (useful if you run the daemon yourself).
+- Do not run the manual daemon at the same time, or you will hit
+  `listen tcp 127.0.0.1:8788: bind: address already in use`.
+
+Manual daemon (starts `gog gmail watch serve` + auto-renew):
+
+```bash
+vora webhooks gmail run
+```
+
+## One-time setup
+
+1. Select the GCP project **that owns the OAuth client** used by `gog`.
+
+```bash
+gcloud auth login
+gcloud config set project <project-id>
+```
+
+Note: Gmail watch requires the Pub/Sub topic to live in the same project as the OAuth client.
+
+2. Enable APIs:
+
+```bash
+gcloud services enable gmail.googleapis.com pubsub.googleapis.com
+```
+
+3. Create a topic:
+
+```bash
+gcloud pubsub topics create gog-gmail-watch
+```
+
+4. Allow Gmail push to publish:
+
+```bash
+gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
+  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
+  --role=roles/pubsub.publisher
+```
+
+## Start the watch
+
+```bash
+gog gmail watch start \
+  --account vora@gmail.com \
+  --label INBOX \
+  --topic projects/<project-id>/topics/gog-gmail-watch
+```
+
+Save the `history_id` from the output (for debugging).
+
+## Run the push handler
+
+Local example (shared token auth):
+
+```bash
+gog gmail watch serve \
+  --account vora@gmail.com \
+  --bind 127.0.0.1 \
+  --port 8788 \
+  --path /gmail-pubsub \
+  --token <shared> \
+  --hook-url http://127.0.0.1:18789/hooks/gmail \
+  --hook-token VORA_HOOK_TOKEN \
+  --include-body \
+  --max-bytes 20000
+```
+
+Notes:
+
+- `--token` protects the push endpoint (`x-gog-token` or `?token=`).
+- `--hook-url` points to Vora `/hooks/gmail` (mapped; isolated run + summary to main).
+- `--include-body` and `--max-bytes` control the body snippet sent to Vora.
+
+Recommended: `vora webhooks gmail run` wraps the same flow and auto-renews the watch.
+
+## Expose the handler (advanced, unsupported)
+
+If you need a non-Tailscale tunnel, wire it manually and use the public URL in the push
+subscription (unsupported, no guardrails):
+
+```bash
+cloudflared tunnel --url http://127.0.0.1:8788 --no-autoupdate
+```
+
+Use the generated URL as the push endpoint:
+
+```bash
+gcloud pubsub subscriptions create gog-gmail-watch-push \
+  --topic gog-gmail-watch \
+  --push-endpoint "https://<public-url>/gmail-pubsub?token=<shared>"
+```
+
+Production: use a stable HTTPS endpoint and configure Pub/Sub OIDC JWT, then run:
+
+```bash
+gog gmail watch serve --verify-oidc --oidc-email <svc@...>
+```
+
+## Test
+
+Send a message to the watched inbox:
+
+```bash
+gog gmail send \
+  --account vora@gmail.com \
+  --to vora@gmail.com \
+  --subject "watch test" \
+  --body "ping"
+```
+
+Check watch state and history:
+
+```bash
+gog gmail watch status --account vora@gmail.com
+gog gmail history --account vora@gmail.com --since <historyId>
+```
+
+## Troubleshooting
+
+- `Invalid topicName`: project mismatch (topic not in the OAuth client project).
+- `User not authorized`: missing `roles/pubsub.publisher` on the topic.
+- Empty messages: Gmail push only provides `historyId`; fetch via `gog gmail history`.
+
+## Cleanup
+
+```bash
+gog gmail watch stop --account vora@gmail.com
+gcloud pubsub subscriptions delete gog-gmail-watch-push
+gcloud pubsub topics delete gog-gmail-watch
+```