@symerian/symi 3.0.20 → 3.0.22

package/docs/gateway/heartbeat.md

@@ -1,374 +0,0 @@
----
-summary: "Heartbeat polling messages and notification rules"
-read_when:
-  - Adjusting heartbeat cadence or messaging
-  - Deciding between heartbeat and cron for scheduled tasks
-title: "Heartbeat"
----
-
-# Heartbeat (Gateway)
-
-> **Heartbeat vs Cron?** See [Cron vs Heartbeat](/automation/cron-vs-heartbeat) for guidance on when to use each.
-
-Heartbeat runs **periodic agent turns** in the main session so the model can
-surface anything that needs attention without spamming you.
-
-Troubleshooting: [/automation/troubleshooting](/automation/troubleshooting)
-
-## Quick start (beginner)
-
-1. Leave heartbeats enabled (default is `30m`, or `1h` for Anthropic OAuth/setup-token) or set your own cadence.
-2. Create a tiny `SYMIPULSE.md` checklist in the agent workspace (optional but recommended).
-3. Decide where heartbeat messages should go (`target: "last"` is the default).
-4. Optional: enable heartbeat reasoning delivery for transparency.
-5. Optional: restrict heartbeats to active hours (local time).
-
-Example config:
-
-```json5
-{
-  agents: {
-    defaults: {
-      heartbeat: {
-        every: "30m",
-        target: "last",
-        // activeHours: { start: "08:00", end: "24:00" },
-        // includeReasoning: true, // optional: send separate `Reasoning:` message too
-      },
-    },
-  },
-}
-```
-
-## Defaults
-
-- Interval: `30m` (or `1h` when Anthropic OAuth/setup-token is the detected auth mode). Set `agents.defaults.heartbeat.every` or per-agent `agents.list[].heartbeat.every`; use `0m` to disable.
-- Prompt body (configurable via `agents.defaults.heartbeat.prompt`):
-  `Read SYMIPULSE.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply SYMIPULSE_OK.`
-- The heartbeat prompt is sent **verbatim** as the user message. The system
-  prompt includes a “Heartbeat” section and the run is flagged internally.
-- Active hours (`heartbeat.activeHours`) are checked in the configured timezone.
-  Outside the window, heartbeats are skipped until the next tick inside the window.
-
-## What the heartbeat prompt is for
-
-The default prompt is intentionally broad:
-
-- **Background tasks**: “Consider outstanding tasks” nudges the agent to review
-  follow-ups (inbox, calendar, reminders, queued work) and surface anything urgent.
-- **Human check-in**: “Checkup sometimes on your human during day time” nudges an
-  occasional lightweight “anything you need?” message, but avoids night-time spam
-  by using your configured local timezone (see [/concepts/timezone](/concepts/timezone)).
-
-If you want a heartbeat to do something very specific (e.g. “check Gmail PubSub
-stats” or “verify gateway health”), set `agents.defaults.heartbeat.prompt` (or
-`agents.list[].heartbeat.prompt`) to a custom body (sent verbatim).
-
-## Response contract
-
-- If nothing needs attention, reply with **`SYMIPULSE_OK`**.
-- During heartbeat runs, Symi treats `SYMIPULSE_OK` as an ack when it appears
-  at the **start or end** of the reply. The token is stripped and the reply is
-  dropped if the remaining content is **≤ `ackMaxChars`** (default: 300).
-- If `SYMIPULSE_OK` appears in the **middle** of a reply, it is not treated
-  specially.
-- For alerts, **do not** include `SYMIPULSE_OK`; return only the alert text.
-
-Outside heartbeats, stray `SYMIPULSE_OK` at the start/end of a message is stripped
-and logged; a message that is only `SYMIPULSE_OK` is dropped.
-
-## Config
-
-```json5
-{
-  agents: {
-    defaults: {
-      heartbeat: {
-        every: "30m", // default: 30m (0m disables)
-        model: "anthropic/claude-opus-4-6",
-        includeReasoning: false, // default: false (deliver separate Reasoning: message when available)
-        target: "last", // last | none | <channel id> (core or plugin, e.g. "bluebubbles")
-        to: "+15551234567", // optional channel-specific override
-        accountId: "ops-bot", // optional multi-account channel id
-        prompt: "Read SYMIPULSE.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply SYMIPULSE_OK.",
-        ackMaxChars: 300, // max chars allowed after SYMIPULSE_OK
-      },
-    },
-  },
-}
-```
-
-### Scope and precedence
-
-- `agents.defaults.heartbeat` sets global heartbeat behavior.
-- `agents.list[].heartbeat` merges on top; if any agent has a `heartbeat` block, **only those agents** run heartbeats.
-- `channels.defaults.heartbeat` sets visibility defaults for all channels.
-- `channels.<channel>.heartbeat` overrides channel defaults.
-- `channels.<channel>.accounts.<id>.heartbeat` (multi-account channels) overrides per-channel settings.
-
-### Per-agent heartbeats
-
-If any `agents.list[]` entry includes a `heartbeat` block, **only those agents**
-run heartbeats. The per-agent block merges on top of `agents.defaults.heartbeat`
-(so you can set shared defaults once and override per agent).
-
-Example: two agents, only the second agent runs heartbeats.
-
-```json5
-{
-  agents: {
-    defaults: {
-      heartbeat: {
-        every: "30m",
-        target: "last",
-      },
-    },
-    list: [
-      { id: "main", default: true },
-      {
-        id: "ops",
-        heartbeat: {
-          every: "1h",
-          target: "whatsapp",
-          to: "+15551234567",
-          prompt: "Read SYMIPULSE.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply SYMIPULSE_OK.",
-        },
-      },
-    ],
-  },
-}
-```
-
-### Active hours example
-
-Restrict heartbeats to business hours in a specific timezone:
-
-```json5
-{
-  agents: {
-    defaults: {
-      heartbeat: {
-        every: "30m",
-        target: "last",
-        activeHours: {
-          start: "09:00",
-          end: "22:00",
-          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz
-        },
-      },
-    },
-  },
-}
-```
-
-Outside this window (before 9am or after 10pm Eastern), heartbeats are skipped. The next scheduled tick inside the window will run normally.
-
-### 24/7 setup
-
-If you want heartbeats to run all day, use one of these patterns:
-
-- Omit `activeHours` entirely (no time-window restriction; this is the default behavior).
-- Set a full-day window: `activeHours: { start: "00:00", end: "24:00" }`.
-
-Do not set the same `start` and `end` time (for example `08:00` to `08:00`).
-That is treated as a zero-width window, so heartbeats are always skipped.
-
-### Multi account example
-
-Use `accountId` to target a specific account on multi-account channels like Telegram:
-
-```json5
-{
-  agents: {
-    list: [
-      {
-        id: "ops",
-        heartbeat: {
-          every: "1h",
-          target: "telegram",
-          to: "12345678:topic:42", // optional: route to a specific topic/thread
-          accountId: "ops-bot",
-        },
-      },
-    ],
-  },
-  channels: {
-    telegram: {
-      accounts: {
-        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
-      },
-    },
-  },
-}
-```
-
-### Field notes
-
-- `every`: heartbeat interval (duration string; default unit = minutes).
-- `model`: optional model override for heartbeat runs (`provider/model`).
-- `includeReasoning`: when enabled, also deliver the separate `Reasoning:` message when available (same shape as `/reasoning on`).
-- `session`: optional session key for heartbeat runs.
-  - `main` (default): agent main session.
-  - Explicit session key (copy from `symi sessions --json` or the [sessions CLI](/cli/sessions)).
-  - Session key formats: see [Sessions](/concepts/session) and [Groups](/channels/groups).
-- `target`:
-  - `last` (default): deliver to the last used external channel.
-  - `none`: run the heartbeat but **do not deliver** externally.
-- `to`: optional recipient override (channel-specific id, e.g. E.164 for WhatsApp or a Telegram chat id). For Telegram topics/threads, use `<chatId>:topic:<messageThreadId>`.
-- `accountId`: optional account id for multi-account channels. When `target: "last"`, the account id applies to the resolved last channel if it supports accounts; otherwise it is ignored. If the account id does not match a configured account for the resolved channel, delivery is skipped.
-- `prompt`: overrides the default prompt body (not merged).
-- `ackMaxChars`: max chars allowed after `SYMIPULSE_OK` before delivery.
-- `suppressToolErrorWarnings`: when true, suppresses tool error warning payloads during heartbeat runs.
-- `activeHours`: restricts heartbeat runs to a time window. Object with `start` (HH:MM, inclusive; use `00:00` for start-of-day), `end` (HH:MM exclusive; `24:00` allowed for end-of-day), and optional `timezone`.
-  - Omitted or `"user"`: uses your `agents.defaults.userTimezone` if set, otherwise falls back to the host system timezone.
-  - `"local"`: always uses the host system timezone.
-  - Any IANA identifier (e.g. `America/New_York`): used directly; if invalid, falls back to the `"user"` behavior above.
-  - `start` and `end` must not be equal for an active window; equal values are treated as zero-width (always outside the window).
-  - Outside the active window, heartbeats are skipped until the next tick inside the window.
-
-## Delivery behavior
-
-- Heartbeats run in the agent’s main session by default (`agent:<id>:<mainKey>`),
-  or `global` when `session.scope = "global"`. Set `session` to override to a
-- `session` only affects the run context; delivery is controlled by `target` and `to`.
-- To deliver to a specific channel/recipient, set `target` + `to`. With
-  `target: "last"`, delivery uses the last external channel for that session.
-- If the main queue is busy, the heartbeat is skipped and retried later.
-- If `target` resolves to no external destination, the run still happens but no
-  outbound message is sent.
-- Heartbeat-only replies do **not** keep the session alive; the last `updatedAt`
-  is restored so idle expiry behaves normally.
-
-## Visibility controls
-
-By default, `SYMIPULSE_OK` acknowledgments are suppressed while alert content is
-delivered. You can adjust this per channel or per account:
-
-```yaml
-channels:
-  defaults:
-    heartbeat:
-      showOk: false # Hide SYMIPULSE_OK (default)
-      showAlerts: true # Show alert messages (default)
-      useIndicator: true # Emit indicator events (default)
-  telegram:
-    heartbeat:
-      showOk: true # Show OK acknowledgments on Telegram
-  whatsapp:
-    accounts:
-      work:
-        heartbeat:
-          showAlerts: false # Suppress alert delivery for this account
-```
-
-Precedence: per-account → per-channel → channel defaults → built-in defaults.
-
-### What each flag does
-
-- `showOk`: sends a `SYMIPULSE_OK` acknowledgment when the model returns an OK-only reply.
-- `showAlerts`: sends the alert content when the model returns a non-OK reply.
-- `useIndicator`: emits indicator events for UI status surfaces.
-
-If **all three** are false, Symi skips the heartbeat run entirely (no model call).
-
-### Per-channel vs per-account examples
-
-```yaml
-channels:
-  defaults:
-    heartbeat:
-      showOk: false
-      showAlerts: true
-      useIndicator: true
-  slack:
-    heartbeat:
-      showOk: true # all Slack accounts
-    accounts:
-      ops:
-        heartbeat:
-          showAlerts: false # suppress alerts for the ops account only
-  telegram:
-    heartbeat:
-      showOk: true
-```
-
-### Common patterns
-
-| Goal                                     | Config                                                                                   |
-| ---------------------------------------- | ---------------------------------------------------------------------------------------- |
-| Default behavior (silent OKs, alerts on) | _(no config needed)_                                                                     |
-| Fully silent (no messages, no indicator) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` |
-| Indicator-only (no messages)             | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }`  |
-| OKs in one channel only                  | `channels.telegram.heartbeat: { showOk: true }`                                          |
-
-## SYMIPULSE.md (optional)
-
-If a `SYMIPULSE.md` file exists in the workspace, the default prompt tells the
-agent to read it. Think of it as your "heartbeat checklist": small, stable, and
-safe to include every 30 minutes.
-
-If `SYMIPULSE.md` exists but is effectively empty (only blank lines and markdown
-headers like `# Heading`), Symi skips the heartbeat run to save API calls.
-If the file is missing, the heartbeat still runs and the model decides what to do.
-
-Keep it tiny (short checklist or reminders) to avoid prompt bloat.
-
-Example `SYMIPULSE.md`:
-
-```md
-# Heartbeat checklist
-
-- Quick scan: anything urgent in inboxes?
-- If it’s daytime, do a lightweight check-in if nothing else is pending.
-- If a task is blocked, write down _what is missing_ and ask Peter next time.
-```
-
-### Can the agent update SYMIPULSE.md?
-
-Yes — if you ask it to.
-
-`SYMIPULSE.md` is just a normal file in the agent workspace, so you can tell the
-agent (in a normal chat) something like:
-
-- "Update `SYMIPULSE.md` to add a daily calendar check."
-- "Rewrite `SYMIPULSE.md` so it's shorter and focused on inbox follow-ups."
-
-If you want this to happen proactively, you can also include an explicit line in
-your heartbeat prompt like: "If the checklist becomes stale, update SYMIPULSE.md
-with a better one."
-
-Safety note: don't put secrets (API keys, phone numbers, private tokens) into
-`SYMIPULSE.md` — it becomes part of the prompt context.
-
-## Manual wake (on-demand)
-
-You can enqueue a system event and trigger an immediate heartbeat with:
-
-```bash
-symi system event --text "Check for urgent follow-ups" --mode now
-```
-
-If multiple agents have `heartbeat` configured, a manual wake runs each of those
-agent heartbeats immediately.
-
-Use `--mode next-heartbeat` to wait for the next scheduled tick.
-
-## Reasoning delivery (optional)
-
-By default, heartbeats deliver only the final “answer” payload.
-
-If you want transparency, enable:
-
-- `agents.defaults.heartbeat.includeReasoning: true`
-
-When enabled, heartbeats will also deliver a separate message prefixed
-`Reasoning:` (same shape as `/reasoning on`). This can be useful when the agent
-is managing multiple sessions/codexes and you want to see why it decided to ping
-you — but it can also leak more internal detail than you want. Prefer keeping it
-off in group chats.
-
-## Cost awareness
-
-Heartbeats run full agent turns. Shorter intervals burn more tokens. Keep
-`SYMIPULSE.md` small and consider a cheaper `model` or `target: "none"` if you
-only want internal state updates.

package/docs/gateway/index.md

@@ -1,254 +0,0 @@
----
-summary: "Runbook for the Gateway service, lifecycle, and operations"
-read_when:
-  - Running or debugging the gateway process
-title: "Gateway Runbook"
----
-
-# Gateway runbook
-
-Use this page for day-1 startup and day-2 operations of the Gateway service.
-
-<CardGroup cols={2}>
-  <Card title="Deep troubleshooting" icon="siren" href="/gateway/troubleshooting">
-    Symptom-first diagnostics with exact command ladders and log signatures.
-  </Card>
-  <Card title="Configuration" icon="sliders" href="/gateway/configuration">
-    Task-oriented setup guide + full configuration reference.
-  </Card>
-</CardGroup>
-
-## 5-minute local startup
-
-<Steps>
-  <Step title="Start the Gateway">
-
-```bash
-symi gateway --port 18789
-# debug/trace mirrored to stdio
-symi gateway --port 18789 --verbose
-# force-kill listener on selected port, then start
-symi gateway --force
-```
-
-  </Step>
-
-  <Step title="Verify service health">
-
-```bash
-symi gateway status
-symi status
-symi logs --follow
-```
-
-Healthy baseline: `Runtime: running` and `RPC probe: ok`.
-
-  </Step>
-
-  <Step title="Validate channel readiness">
-
-```bash
-symi channels status --probe
-```
-
-  </Step>
-</Steps>
-
-<Note>
-Gateway config reload watches the active config file path (resolved from profile/state defaults, or `SYMI_CONFIG_PATH` when set).
-Default mode is `gateway.reload.mode="hybrid"`.
-</Note>
-
-## Runtime model
-
-- One always-on process for routing, control plane, and channel connections.
-- Single multiplexed port for:
-  - WebSocket control/RPC
-  - HTTP APIs (OpenAI-compatible, Responses, tools invoke)
-  - Control UI and hooks
-- Default bind mode: `loopback`.
-- Auth is required by default (`gateway.auth.token` / `gateway.auth.password`, or `SYMI_GATEWAY_TOKEN` / `SYMI_GATEWAY_PASSWORD`).
-
-### Port and bind precedence
-
-| Setting      | Resolution order                                          |
-| ------------ | --------------------------------------------------------- |
-| Gateway port | `--port` → `SYMI_GATEWAY_PORT` → `gateway.port` → `18789` |
-| Bind mode    | CLI/override → `gateway.bind` → `loopback`                |
-
-### Hot reload modes
-
-| `gateway.reload.mode` | Behavior                                   |
-| --------------------- | ------------------------------------------ |
-| `off`                 | No config reload                           |
-| `hot`                 | Apply only hot-safe changes                |
-| `restart`             | Restart on reload-required changes         |
-| `hybrid` (default)    | Hot-apply when safe, restart when required |
-
-## Operator command set
-
-```bash
-symi gateway status
-symi gateway status --deep
-symi gateway status --json
-symi gateway install
-symi gateway restart
-symi gateway stop
-symi logs --follow
-symi doctor
-```
-
-## Remote access
-
-Preferred: Tailscale/VPN.
-Fallback: SSH tunnel.
-
-```bash
-ssh -N -L 18789:127.0.0.1:18789 user@host
-```
-
-Then connect clients to `ws://127.0.0.1:18789` locally.
-
-<Warning>
-If gateway auth is configured, clients still must send auth (`token`/`password`) even over SSH tunnels.
-</Warning>
-
-See: [Remote Gateway](/gateway/remote), [Authentication](/gateway/authentication), [Tailscale](/gateway/tailscale).
-
-## Supervision and service lifecycle
-
-Use supervised runs for production-like reliability.
-
-<Tabs>
-  <Tab title="macOS (launchd)">
-
-```bash
-symi gateway install
-symi gateway status
-symi gateway restart
-symi gateway stop
-```
-
-LaunchAgent labels are `ai.symi.gateway` (default) or `ai.symi.<profile>` (named profile). `symi doctor` audits and repairs service config drift.
-
-  </Tab>
-
-  <Tab title="Linux (systemd user)">
-
-```bash
-symi gateway install
-systemctl --user enable --now symi-gateway[-<profile>].service
-symi gateway status
-```
-
-For persistence after logout, enable lingering:
-
-```bash
-sudo loginctl enable-linger <user>
-```
-
-  </Tab>
-
-  <Tab title="Linux (system service)">
-
-Use a system unit for multi-user/always-on hosts.
-
-```bash
-sudo systemctl daemon-reload
-sudo systemctl enable --now symi-gateway[-<profile>].service
-```
-
-  </Tab>
-</Tabs>
-
-## Multiple gateways on one host
-
-Most setups should run **one** Gateway.
-Use multiple only for strict isolation/redundancy (for example a rescue profile).
-
-Checklist per instance:
-
-- Unique `gateway.port`
-- Unique `SYMI_CONFIG_PATH`
-- Unique `SYMI_STATE_DIR`
-- Unique `agents.defaults.workspace`
-
-Example:
-
-```bash
-SYMI_CONFIG_PATH=~/.symi/a.json SYMI_STATE_DIR=~/.symi-a symi gateway --port 19001
-SYMI_CONFIG_PATH=~/.symi/b.json SYMI_STATE_DIR=~/.symi-b symi gateway --port 19002
-```
-
-See: [Multiple gateways](/gateway/multiple-gateways).
-
-### Dev profile quick path
-
-```bash
-symi --dev setup
-symi --dev gateway --allow-unconfigured
-symi --dev status
-```
-
-Defaults include isolated state/config and base gateway port `19001`.
-
-## Protocol quick reference (operator view)
-
-- First client frame must be `connect`.
-- Gateway returns `hello-ok` snapshot (`presence`, `health`, `stateVersion`, `uptimeMs`, limits/policy).
-- Requests: `req(method, params)` → `res(ok/payload|error)`.
-- Common events: `connect.challenge`, `agent`, `chat`, `presence`, `tick`, `health`, `heartbeat`, `shutdown`.
-
-Agent runs are two-stage:
-
-1. Immediate accepted ack (`status:"accepted"`)
-2. Final completion response (`status:"ok"|"error"`), with streamed `agent` events in between.
-
-See full protocol docs: [Gateway Protocol](/gateway/protocol).
-
-## Operational checks
-
-### Liveness
-
-- Open WS and send `connect`.
-- Expect `hello-ok` response with snapshot.
-
-### Readiness
-
-```bash
-symi gateway status
-symi channels status --probe
-symi health
-```
-
-### Gap recovery
-
-Events are not replayed. On sequence gaps, refresh state (`health`, `system-presence`) before continuing.
-
-## Common failure signatures
-
-| Signature                                                      | Likely issue                             |
-| -------------------------------------------------------------- | ---------------------------------------- |
-| `refusing to bind gateway ... without auth`                    | Non-loopback bind without token/password |
-| `another gateway instance is already listening` / `EADDRINUSE` | Port conflict                            |
-| `Gateway start blocked: set gateway.mode=local`                | Config set to remote mode                |
-| `unauthorized` during connect                                  | Auth mismatch between client and gateway |
-
-For full diagnosis ladders, use [Gateway Troubleshooting](/gateway/troubleshooting).
-
-## Safety guarantees
-
-- Gateway protocol clients fail fast when Gateway is unavailable (no implicit direct-channel fallback).
-- Invalid/non-connect first frames are rejected and closed.
-- Graceful shutdown emits `shutdown` event before socket close.
-
----
-
-Related:
-
-- [Troubleshooting](/gateway/troubleshooting)
-- [Background Process](/gateway/background-process)
-- [Configuration](/gateway/configuration)
-- [Health](/gateway/health)
-- [Doctor](/gateway/doctor)
-- [Authentication](/gateway/authentication)