@symerian/symi 3.0.20 → 3.0.22

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

@@ -1,286 +0,0 @@
----
-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.
-
-## 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 `SYMIPULSE_OK` and no message is delivered.
-- **Natural timing**: Drifts slightly based on queue load, which is fine for most monitoring.
-
-### Heartbeat example: SYMIPULSE.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", // where to deliver alerts
-        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.
-
-### Cron example: Daily morning briefing
-
-```bash
-symi 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
-symi 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 SYMIPULSE.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
-
-**SYMIPULSE.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
-symi cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --announce
-
-# Weekly project review on Mondays at 9am
-symi cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus
-
-# One-shot reminder
-symi cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now
-```
-
-## Pipeline: Deterministic workflows with approvals
-
-Pipeline 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 Pipeline 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.
-- **Pipeline** defines _what steps_ happen once the run starts.
-
-For scheduled workflows, use cron or heartbeat to trigger an agent turn that calls Pipeline.
-For ad-hoc workflows, call Pipeline directly.
-
-### Operational notes (from the code)
-
-- Pipeline runs as a **local subprocess** (`pipeline` 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: ["pipeline"]` (recommended).
-- Pipeline expects the `pipeline` CLI to be available on `PATH`.
-
-See [Pipeline](/tools/pipeline) 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>`             |
-| History | Shared                          | Shared                   | Fresh each run             |
-| Context | Full                            | Full                     | None (starts clean)        |
-| Model   | Main session model              | Main session model       | Can override               |
-| Output  | Delivered if not `SYMIPULSE_OK` | Heartbeat prompt + event | Announce summary (default) |
-
-### 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
-symi 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
-symi 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 SYMIPULSE.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 `SYMIPULSE.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
-
-- [Heartbeat](/gateway/heartbeat) - full heartbeat configuration
-- [Cron jobs](/automation/cron-jobs) - full cron CLI and API reference
-- [System](/cli/system) - system events + heartbeat controls

package/docs/automation/gmail-pubsub.md

@@ -1,256 +0,0 @@
----
-summary: "Gmail Pub/Sub push wired into Symi webhooks via gogcli"
-read_when:
-  - Wiring Gmail inbox triggers to Symi
-  - Setting up Pub/Sub push for agent wake
-title: "Gmail PubSub"
----
-
-# Gmail Pub/Sub -> Symi
-
-Goal: Gmail watch -> Pub/Sub push -> `gog gmail watch serve` -> Symi 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/)).
-- Symi 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: "SYMI_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: "SYMI_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 `~/.symi/hooks/transforms` (see [Webhooks](/automation/webhook)).
-
-## Wizard (recommended)
-
-Use the Symi helper to wire everything together (installs deps on macOS via brew):
-
-```bash
-symi webhooks gmail setup \
-  --account symi@gmail.com
-```
-
-Defaults:
-
-- Uses Tailscale Funnel for the public push endpoint.
-- Writes `hooks.gmail` config for `symi webhooks gmail run`.
-- Enables the Gmail hook preset (`hooks.presets: ["gmail"]`).
-
-Path note: when `tailscale.mode` is enabled, Symi 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 `SYMI_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
-symi 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 symi@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 symi@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 SYMI_HOOK_TOKEN \
-  --include-body \
-  --max-bytes 20000
-```
-
-Notes:
-
-- `--token` protects the push endpoint (`x-gog-token` or `?token=`).
-- `--hook-url` points to Symi `/hooks/gmail` (mapped; isolated run + summary to main).
-- `--include-body` and `--max-bytes` control the body snippet sent to Symi.
-
-Recommended: `symi 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 symi@gmail.com \
-  --to symi@gmail.com \
-  --subject "watch test" \
-  --body "ping"
-```
-
-Check watch state and history:
-
-```bash
-gog gmail watch status --account symi@gmail.com
-gog gmail history --account symi@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 symi@gmail.com
-gcloud pubsub subscriptions delete gog-gmail-watch-push
-gcloud pubsub topics delete gog-gmail-watch
-```