@symerian/symi 3.0.20 → 3.0.22

package/docs/concepts/messages.md

@@ -1,153 +0,0 @@
----
-summary: "Message flow, sessions, queueing, and reasoning visibility"
-read_when:
-  - Explaining how inbound messages become replies
-  - Clarifying sessions, queueing modes, or streaming behavior
-  - Documenting reasoning visibility and usage implications
-title: "Messages"
----
-
-# Messages
-
-This page ties together how Symi handles inbound messages, sessions, queueing,
-streaming, and reasoning visibility.
-
-## Message flow (high level)
-
-```
-Inbound message
-  -> routing/bindings -> session key
-  -> queue (if a run is active)
-  -> agent run (streaming + tools)
-  -> outbound replies (channel limits + chunking)
-```
-
-Key knobs live in configuration:
-
-- `messages.*` for prefixes, queueing, and group behavior.
-- `agents.defaults.*` for block streaming and chunking defaults.
-- Channel overrides (`channels.whatsapp.*`, `channels.telegram.*`, etc.) for caps and streaming toggles.
-
-See [Configuration](/gateway/configuration) for full schema.
-
-## Inbound dedupe
-
-Channels can redeliver the same message after reconnects. Symi keeps a
-short-lived cache keyed by channel/account/peer/session/message id so duplicate
-deliveries do not trigger another agent run.
-
-## Inbound debouncing
-
-Rapid consecutive messages from the **same sender** can be batched into a single
-agent turn via `messages.inbound`. Debouncing is scoped per channel + conversation
-and uses the most recent message for reply threading/IDs.
-
-Config (global default + per-channel overrides):
-
-```json5
-{
-  messages: {
-    inbound: {
-      debounceMs: 2000,
-      byChannel: {
-        whatsapp: 5000,
-        slack: 1500,
-      },
-    },
-  },
-}
-```
-
-Notes:
-
-- Debounce applies to **text-only** messages; media/attachments flush immediately.
-- Control commands bypass debouncing so they remain standalone.
-
-## Sessions and devices
-
-Sessions are owned by the gateway, not by clients.
-
-- Direct chats collapse into the agent main session key.
-- Groups/channels get their own session keys.
-- The session store and transcripts live on the gateway host.
-
-Multiple devices/channels can map to the same session, but history is not fully
-synced back to every client. Recommendation: use one primary device for long
-conversations to avoid divergent context. The Control UI and TUI always show the
-gateway-backed session transcript, so they are the source of truth.
-
-Details: [Session management](/concepts/session).
-
-## Inbound bodies and history context
-
-Symi separates the **prompt body** from the **command body**:
-
-- `Body`: prompt text sent to the agent. This may include channel envelopes and
-  optional history wrappers.
-- `CommandBody`: raw user text for directive/command parsing.
-- `RawBody`: legacy alias for `CommandBody` (kept for compatibility).
-
-When a channel supplies history, it uses a shared wrapper:
-
-- `[Chat messages since your last reply - for context]`
-- `[Current message - respond to this]`
-
-For **non-direct chats** (groups/channels/rooms), the **current message body** is prefixed with the
-sender label (same style used for history entries). This keeps real-time and queued/history
-messages consistent in the agent prompt.
-
-History buffers are **pending-only**: they include group messages that did _not_
-trigger a run (for example, mention-gated messages) and **exclude** messages
-already in the session transcript.
-
-Directive stripping only applies to the **current message** section so history
-remains intact. Channels that wrap history should set `CommandBody` (or
-`RawBody`) to the original message text and keep `Body` as the combined prompt.
-History buffers are configurable via `messages.groupChat.historyLimit` (global
-default) and per-channel overrides like `channels.slack.historyLimit` or
-`channels.telegram.accounts.<id>.historyLimit` (set `0` to disable).
-
-## Queueing and followups
-
-If a run is already active, inbound messages can be queued, steered into the
-current run, or collected for a followup turn.
-
-- Configure via `messages.queue` (and `messages.queue.byChannel`).
-- Modes: `interrupt`, `steer`, `followup`, `collect`, plus backlog variants.
-
-Details: [Queueing](/concepts/queue).
-
-## Streaming, chunking, and batching
-
-Block streaming sends partial replies as the model produces text blocks.
-Chunking respects channel text limits and avoids splitting fenced code.
-
-Key settings:
-
-- `agents.defaults.blockStreamingDefault` (`on|off`, default off)
-- `agents.defaults.blockStreamingBreak` (`text_end|message_end`)
-- `agents.defaults.blockStreamingChunk` (`minChars|maxChars|breakPreference`)
-- `agents.defaults.blockStreamingCoalesce` (idle-based batching)
-- `agents.defaults.humanDelay` (human-like pause between block replies)
-- Channel overrides: `*.blockStreaming` and `*.blockStreamingCoalesce` (non-Telegram channels require explicit `*.blockStreaming: true`)
-
-Details: [Streaming + chunking](/concepts/streaming).
-
-## Reasoning visibility and tokens
-
-Symi can expose or hide model reasoning:
-
-- `/reasoning on|off|stream` controls visibility.
-- Reasoning content still counts toward token usage when produced by the model.
-- Telegram supports reasoning stream into the draft bubble.
-
-Details: [Thinking + reasoning directives](/tools/thinking) and [Token use](/reference/token-use).
-
-## Prefixes, threading, and replies
-
-Outbound message formatting is centralized in `messages`:
-
-- `messages.responsePrefix`, `channels.<channel>.responsePrefix`, and `channels.<channel>.accounts.<id>.responsePrefix` (outbound prefix cascade), plus `channels.whatsapp.messagePrefix` (WhatsApp inbound prefix)
-- Reply threading via `replyToMode` and per-channel defaults
-
-Details: [Configuration](/gateway/configuration#messages) and channel docs.

package/docs/concepts/model-failover.md

@@ -1,149 +0,0 @@
----
-summary: "How Symi rotates auth profiles and falls back across models"
-read_when:
-  - Diagnosing auth profile rotation, cooldowns, or model fallback behavior
-  - Updating failover rules for auth profiles or models
-title: "Model Failover"
----
-
-# Model failover
-
-Symi handles failures in two stages:
-
-1. **Auth profile rotation** within the current provider.
-2. **Model fallback** to the next model in `agents.defaults.model.fallbacks`.
-
-This doc explains the runtime rules and the data that backs them.
-
-## Auth storage (keys + OAuth)
-
-Symi uses **auth profiles** for both API keys and OAuth tokens.
-
-- Secrets live in `~/.symi/agents/<agentId>/agent/auth-profiles.json` (legacy: `~/.symi/agent/auth-profiles.json`).
-- Config `auth.profiles` / `auth.order` are **metadata + routing only** (no secrets).
-- Legacy import-only OAuth file: `~/.symi/credentials/oauth.json` (imported into `auth-profiles.json` on first use).
-
-More detail: [/concepts/oauth](/concepts/oauth)
-
-Credential types:
-
-- `type: "api_key"` → `{ provider, key }`
-- `type: "oauth"` → `{ provider, access, refresh, expires, email? }` (+ `projectId`/`enterpriseUrl` for some providers)
-
-## Profile IDs
-
-OAuth logins create distinct profiles so multiple accounts can coexist.
-
-- Default: `provider:default` when no email is available.
-- OAuth with email: `provider:<email>` (for example `google-antigravity:user@gmail.com`).
-
-Profiles live in `~/.symi/agents/<agentId>/agent/auth-profiles.json` under `profiles`.
-
-## Rotation order
-
-When a provider has multiple profiles, Symi chooses an order like this:
-
-1. **Explicit config**: `auth.order[provider]` (if set).
-2. **Configured profiles**: `auth.profiles` filtered by provider.
-3. **Stored profiles**: entries in `auth-profiles.json` for the provider.
-
-If no explicit order is configured, Symi uses a round‑robin order:
-
-- **Primary key:** profile type (**OAuth before API keys**).
-- **Secondary key:** `usageStats.lastUsed` (oldest first, within each type).
-- **Cooldown/disabled profiles** are moved to the end, ordered by soonest expiry.
-
-### Session stickiness (cache-friendly)
-
-Symi **pins the chosen auth profile per session** to keep provider caches warm.
-It does **not** rotate on every request. The pinned profile is reused until:
-
-- the session is reset (`/new` / `/reset`)
-- a compaction completes (compaction count increments)
-- the profile is in cooldown/disabled
-
-Manual selection via `/model …@<profileId>` sets a **user override** for that session
-and is not auto‑rotated until a new session starts.
-
-Auto‑pinned profiles (selected by the session router) are treated as a **preference**:
-they are tried first, but Symi may rotate to another profile on rate limits/timeouts.
-User‑pinned profiles stay locked to that profile; if it fails and model fallbacks
-are configured, Symi moves to the next model instead of switching profiles.
-
-### Why OAuth can “look lost”
-
-If you have both an OAuth profile and an API key profile for the same provider, round‑robin can switch between them across messages unless pinned. To force a single profile:
-
-- Pin with `auth.order[provider] = ["provider:profileId"]`, or
-- Use a per-session override via `/model …` with a profile override (when supported by your UI/chat surface).
-
-## Cooldowns
-
-When a profile fails due to auth/rate‑limit errors (or a timeout that looks
-like rate limiting), Symi marks it in cooldown and moves to the next profile.
-Format/invalid‑request errors (for example Cloud Code Assist tool call ID
-validation failures) are treated as failover‑worthy and use the same cooldowns.
-
-Cooldowns use exponential backoff:
-
-- 1 minute
-- 5 minutes
-- 25 minutes
-- 1 hour (cap)
-
-State is stored in `auth-profiles.json` under `usageStats`:
-
-```json
-{
-  "usageStats": {
-    "provider:profile": {
-      "lastUsed": 1736160000000,
-      "cooldownUntil": 1736160600000,
-      "errorCount": 2
-    }
-  }
-}
-```
-
-## Billing disables
-
-Billing/credit failures (for example “insufficient credits” / “credit balance too low”) are treated as failover‑worthy, but they’re usually not transient. Instead of a short cooldown, Symi marks the profile as **disabled** (with a longer backoff) and rotates to the next profile/provider.
-
-State is stored in `auth-profiles.json`:
-
-```json
-{
-  "usageStats": {
-    "provider:profile": {
-      "disabledUntil": 1736178000000,
-      "disabledReason": "billing"
-    }
-  }
-}
-```
-
-Defaults:
-
-- Billing backoff starts at **5 hours**, doubles per billing failure, and caps at **24 hours**.
-- Backoff counters reset if the profile hasn’t failed for **24 hours** (configurable).
-
-## Model fallback
-
-If all profiles for a provider fail, Symi moves to the next model in
-`agents.defaults.model.fallbacks`. This applies to auth failures, rate limits, and
-timeouts that exhausted profile rotation (other errors do not advance fallback).
-
-When a run starts with a model override (hooks or CLI), fallbacks still end at
-`agents.defaults.model.primary` after trying any configured fallbacks.
-
-## Related config
-
-See [Gateway configuration](/gateway/configuration) for:
-
-- `auth.profiles` / `auth.order`
-- `auth.cooldowns.billingBackoffHours` / `auth.cooldowns.billingBackoffHoursByProvider`
-- `auth.cooldowns.billingMaxHours` / `auth.cooldowns.failureWindowHours`
-- `agents.defaults.model.primary` / `agents.defaults.model.fallbacks`
-- `agents.defaults.imageModel` routing
-
-See [Models](/concepts/models) for the broader model selection and fallback overview.