@symerian/symi 3.0.21 → 3.0.22

package/docs/concepts/session.md

@@ -1,199 +0,0 @@
----
-summary: "Session management rules, keys, and persistence for chats"
-read_when:
-  - Modifying session handling or storage
-title: "Session Management"
----
-
-# Session Management
-
-Symi treats **one direct-chat session per agent** as primary. Direct chats collapse to `agent:<agentId>:<mainKey>` (default `main`), while group/channel chats get their own keys. `session.mainKey` is honored.
-
-Use `session.dmScope` to control how **direct messages** are grouped:
-
-- `main` (default): all DMs share the main session for continuity.
-- `per-peer`: isolate by sender id across channels.
-- `per-channel-peer`: isolate by channel + sender (recommended for multi-user inboxes).
-- `per-account-channel-peer`: isolate by account + channel + sender (recommended for multi-account inboxes).
-  Use `session.identityLinks` to map provider-prefixed peer ids to a canonical identity so the same person shares a DM session across channels when using `per-peer`, `per-channel-peer`, or `per-account-channel-peer`.
-
-## Secure DM mode (recommended for multi-user setups)
-
-> **Security Warning:** If your agent can receive DMs from **multiple people**, you should strongly consider enabling secure DM mode. Without it, all users share the same conversation context, which can leak private information between users.
-
-**Example of the problem with default settings:**
-
-- Alice (`<SENDER_A>`) messages your agent about a private topic (for example, a medical appointment)
-- Bob (`<SENDER_B>`) messages your agent asking "What were we talking about?"
-- Because both DMs share the same session, the model may answer Bob using Alice's prior context.
-
-**The fix:** Set `dmScope` to isolate sessions per user:
-
-```json5
-// ~/.symi/symi.json
-{
-  session: {
-    // Secure DM mode: isolate DM context per channel + sender.
-    dmScope: "per-channel-peer",
-  },
-}
-```
-
-**When to enable this:**
-
-- You have pairing approvals for more than one sender
-- You use a DM allowlist with multiple entries
-- You set `dmPolicy: "open"`
-- Multiple phone numbers or accounts can message your agent
-
-Notes:
-
-- Default is `dmScope: "main"` for continuity (all DMs share the main session). This is fine for single-user setups.
-- For multi-account inboxes on the same channel, prefer `per-account-channel-peer`.
-- If the same person contacts you on multiple channels, use `session.identityLinks` to collapse their DM sessions into one canonical identity.
-- You can verify your DM settings with `symi security audit` (see [security](/cli/security)).
-
-## Gateway is the source of truth
-
-All session state is **owned by the gateway** (the “master” Symi). UI clients (macOS app, WebChat, etc.) must query the gateway for session lists and token counts instead of reading local files.
-
-- In **remote mode**, the session store you care about lives on the remote gateway host, not your Mac.
-- Token counts shown in UIs come from the gateway’s store fields (`inputTokens`, `outputTokens`, `totalTokens`, `contextTokens`). Clients do not parse JSONL transcripts to “fix up” totals.
-
-## Where state lives
-
-- On the **gateway host**:
-  - Store file: `~/.symi/agents/<agentId>/sessions/sessions.json` (per agent).
-- Transcripts: `~/.symi/agents/<agentId>/sessions/<SessionId>.jsonl` (Telegram topic sessions use `.../<SessionId>-topic-<threadId>.jsonl`).
-- The store is a map `sessionKey -> { sessionId, updatedAt, ... }`. Deleting entries is safe; they are recreated on demand.
-- Group entries may include `displayName`, `channel`, `subject`, `room`, and `space` to label sessions in UIs.
-- Session entries include `origin` metadata (label + routing hints) so UIs can explain where a session came from.
-- Symi does **not** read legacy Pi/Tau session folders.
-
-## Session pruning
-
-Symi trims **old tool results** from the in-memory context right before LLM calls by default.
-This does **not** rewrite JSONL history. See [/concepts/session-pruning](/concepts/session-pruning).
-
-## Pre-compaction memory flush
-
-When a session nears auto-compaction, Symi can run a **silent memory flush**
-turn that reminds the model to write durable notes to disk. This only runs when
-the workspace is writable. See [Memory](/concepts/memory) and
-[Compaction](/concepts/compaction).
-
-## Mapping transports → session keys
-
-- Direct chats follow `session.dmScope` (default `main`).
-  - `main`: `agent:<agentId>:<mainKey>` (continuity across devices/channels).
-    - Multiple phone numbers and channels can map to the same agent main key; they act as transports into one conversation.
-  - `per-peer`: `agent:<agentId>:dm:<peerId>`.
-  - `per-channel-peer`: `agent:<agentId>:<channel>:dm:<peerId>`.
-  - `per-account-channel-peer`: `agent:<agentId>:<channel>:<accountId>:dm:<peerId>` (accountId defaults to `default`).
-  - If `session.identityLinks` matches a provider-prefixed peer id (for example `telegram:123`), the canonical key replaces `<peerId>` so the same person shares a session across channels.
-- Group chats isolate state: `agent:<agentId>:<channel>:group:<id>` (rooms/channels use `agent:<agentId>:<channel>:channel:<id>`).
-  - Telegram forum topics append `:topic:<threadId>` to the group id for isolation.
-  - Legacy `group:<id>` keys are still recognized for migration.
-- Inbound contexts may still use `group:<id>`; the channel is inferred from `Provider` and normalized to the canonical `agent:<agentId>:<channel>:group:<id>` form.
-- Other sources:
-  - Cron jobs: `cron:<job.id>`
-  - Webhooks: `hook:<uuid>` (unless explicitly set by the hook)
-  - Node runs: `node-<nodeId>`
-
-## Lifecycle
-
-- Reset policy: sessions are reused until they expire, and expiry is evaluated on the next inbound message.
-- Daily reset: defaults to **4:00 AM local time on the gateway host**. A session is stale once its last update is earlier than the most recent daily reset time.
-- Idle reset (optional): `idleMinutes` adds a sliding idle window. When both daily and idle resets are configured, **whichever expires first** forces a new session.
-- Legacy idle-only: if you set `session.idleMinutes` without any `session.reset`/`resetByType` config, Symi stays in idle-only mode for backward compatibility.
-- Per-channel overrides (optional): `resetByChannel` overrides the reset policy for a channel (applies to all session types for that channel and takes precedence over `reset`/`resetByType`).
-- Reset triggers: exact `/new` or `/reset` (plus any extras in `resetTriggers`) start a fresh session id and pass the remainder of the message through. `/new <model>` accepts a model alias, `provider/model`, or provider name (fuzzy match) to set the new session model. If `/new` or `/reset` is sent alone, Symi runs a short “hello” greeting turn to confirm the reset.
-- Manual reset: delete specific keys from the store or remove the JSONL transcript; the next message recreates them.
-- Isolated cron jobs always mint a fresh `sessionId` per run (no idle reuse).
-
-## Send policy (optional)
-
-Block delivery for specific session types without listing individual ids.
-
-```json5
-{
-  session: {
-    sendPolicy: {
-      rules: [
-        { action: "deny", match: { keyPrefix: "cron:" } },
-        // Match the raw session key (including the `agent:<id>:` prefix).
-      ],
-      default: "allow",
-    },
-  },
-}
-```
-
-Runtime override (owner only):
-
-- `/send on` → allow for this session
-- `/send off` → deny for this session
-- `/send inherit` → clear override and use config rules
-  Send these as standalone messages so they register.
-
-## Configuration (optional rename example)
-
-```json5
-// ~/.symi/symi.json
-{
-  session: {
-    scope: "per-sender", // keep group keys separate
-    dmScope: "main", // DM continuity (set per-channel-peer/per-account-channel-peer for shared inboxes)
-    identityLinks: {},
-    reset: {
-      // Defaults: mode=daily, atHour=4 (gateway host local time).
-      // If you also set idleMinutes, whichever expires first wins.
-      mode: "daily",
-      atHour: 4,
-      idleMinutes: 120,
-    },
-    resetByType: {
-      thread: { mode: "daily", atHour: 4 },
-      direct: { mode: "idle", idleMinutes: 240 },
-      group: { mode: "idle", idleMinutes: 120 },
-    },
-    resetByChannel: {},
-    resetTriggers: ["/new", "/reset"],
-    store: "~/.symi/agents/{agentId}/sessions/sessions.json",
-    mainKey: "main",
-  },
-}
-```
-
-## Inspecting
-
-- `symi status` — shows store path and recent sessions.
-- `symi sessions --json` — dumps every entry (filter with `--active <minutes>`).
-- `symi gateway call sessions.list --params '{}'` — fetch sessions from the running gateway (use `--url`/`--token` for remote gateway access).
-- Send `/status` as a standalone message in chat to see whether the agent is reachable, how much of the session context is used, current thinking/verbose toggles, and when your WhatsApp web creds were last refreshed (helps spot relink needs).
-- Send `/context list` or `/context detail` to see what’s in the system prompt and injected workspace files (and the biggest context contributors).
-- Send `/stop` as a standalone message to abort the current run, clear queued followups for that session, and stop any sub-agent runs spawned from it (the reply includes the stopped count).
-- Send `/compact` (optional instructions) as a standalone message to summarize older context and free up window space. See [/concepts/compaction](/concepts/compaction).
-- JSONL transcripts can be opened directly to review full turns.
-
-## Tips
-
-- Keep the primary key dedicated to 1:1 traffic; let groups keep their own keys.
-- When automating cleanup, delete individual keys instead of the whole store to preserve context elsewhere.
-
-## Session origin metadata
-
-Each session entry records where it came from (best-effort) in `origin`:
-
-- `label`: human label (resolved from conversation label + group subject/channel)
-- `provider`: normalized channel id (including extensions)
-- `from`/`to`: raw routing ids from the inbound envelope
-- `accountId`: provider account id (when multi-account)
-- `threadId`: thread/topic id when the channel supports it
-  The origin fields are populated for direct messages, channels, and groups. If a
-  connector only updates delivery routing (for example, to keep a DM main session
-  fresh), it should still provide inbound context so the session keeps its
-  explainer metadata. Extensions can do this by sending `ConversationLabel`,
-  `GroupSubject`, `GroupChannel`, `GroupSpace`, and `SenderName` in the inbound
-  context and calling `recordSessionMetaFromInbound` (or passing the same context
-  to `updateLastRoute`).

package/docs/concepts/sessions.md

@@ -1,10 +0,0 @@
----
-summary: "Alias for session management docs"
-read_when:
-  - You looked for docs/sessions.md; canonical doc lives in docs/session.md
-title: "Sessions"
----
-
-# Sessions
-
-Canonical session management docs live in [Session management](/concepts/session).

package/docs/concepts/streaming.md

@@ -1,129 +0,0 @@
----
-summary: "Streaming + chunking behavior (block replies, Telegram preview streaming, limits)"
-read_when:
-  - Explaining how streaming or chunking works on channels
-  - Changing block streaming or channel chunking behavior
-  - Debugging duplicate/early block replies or Telegram preview streaming
-title: "Streaming and Chunking"
----
-
-# Streaming + chunking
-
-Symi has two separate “streaming” layers:
-
-- **Block streaming (channels):** emit completed **blocks** as the assistant writes. These are normal channel messages (not token deltas).
-- **Token-ish streaming (Telegram only):** update a temporary **preview message** with partial text while generating.
-
-There is **no true token-delta streaming** to channel messages today. Telegram preview streaming is the only partial-stream surface.
-
-## Block streaming (channel messages)
-
-Block streaming sends assistant output in coarse chunks as it becomes available.
-
-```
-Model output
-  └─ text_delta/events
-       ├─ (blockStreamingBreak=text_end)
-       │    └─ chunker emits blocks as buffer grows
-       └─ (blockStreamingBreak=message_end)
-            └─ chunker flushes at message_end
-                   └─ channel send (block replies)
-```
-
-Legend:
-
-- `text_delta/events`: model stream events (may be sparse for non-streaming models).
-- `chunker`: `EmbeddedBlockChunker` applying min/max bounds + break preference.
-- `channel send`: actual outbound messages (block replies).
-
-**Controls:**
-
-- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (default off).
-- Channel overrides: `*.blockStreaming` (and per-account variants) to force `"on"`/`"off"` per channel.
-- `agents.defaults.blockStreamingBreak`: `"text_end"` or `"message_end"`.
-- `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`.
-- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (merge streamed blocks before send).
-- Channel hard cap: `*.textChunkLimit` (e.g., `channels.whatsapp.textChunkLimit`).
-- Channel chunk mode: `*.chunkMode` (`length` default, `newline` splits on blank lines (paragraph boundaries) before length chunking).
-
-**Boundary semantics:**
-
-- `text_end`: stream blocks as soon as chunker emits; flush on each `text_end`.
-- `message_end`: wait until assistant message finishes, then flush buffered output.
-
-`message_end` still uses the chunker if the buffered text exceeds `maxChars`, so it can emit multiple chunks at the end.
-
-## Chunking algorithm (low/high bounds)
-
-Block chunking is implemented by `EmbeddedBlockChunker`:
-
-- **Low bound:** don’t emit until buffer >= `minChars` (unless forced).
-- **High bound:** prefer splits before `maxChars`; if forced, split at `maxChars`.
-- **Break preference:** `paragraph` → `newline` → `sentence` → `whitespace` → hard break.
-- **Code fences:** never split inside fences; when forced at `maxChars`, close + reopen the fence to keep Markdown valid.
-
-`maxChars` is clamped to the channel `textChunkLimit`, so you can’t exceed per-channel caps.
-
-## Coalescing (merge streamed blocks)
-
-When block streaming is enabled, Symi can **merge consecutive block chunks**
-before sending them out. This reduces “single-line spam” while still providing
-progressive output.
-
-- Coalescing waits for **idle gaps** (`idleMs`) before flushing.
-- Buffers are capped by `maxChars` and will flush if they exceed it.
-- `minChars` prevents tiny fragments from sending until enough text accumulates
-  (final flush always sends remaining text).
-- Joiner is derived from `blockStreamingChunk.breakPreference`
-  (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → space).
-- Channel overrides are available via `*.blockStreamingCoalesce` (including per-account configs).
-
-## Human-like pacing between blocks
-
-When block streaming is enabled, you can add a **randomized pause** between
-block replies (after the first block). This makes multi-bubble responses feel
-more natural.
-
-- Config: `agents.defaults.humanDelay` (override per agent via `agents.list[].humanDelay`).
-- Modes: `off` (default), `natural` (800–2500ms), `custom` (`minMs`/`maxMs`).
-- Applies only to **block replies**, not final replies or tool summaries.
-
-## “Stream chunks or everything”
-
-This maps to:
-
-- **Stream chunks:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (emit as you go). Non-Telegram channels also need `*.blockStreaming: true`.
-- **Stream everything at end:** `blockStreamingBreak: "message_end"` (flush once, possibly multiple chunks if very long).
-- **No block streaming:** `blockStreamingDefault: "off"` (only final reply).
-
-**Channel note:** For non-Telegram channels, block streaming is **off unless**
-`*.blockStreaming` is explicitly set to `true`. Telegram can stream a live preview
-(`channels.telegram.streaming`) without block replies.
-
-Config location reminder: the `blockStreaming*` defaults live under
-`agents.defaults`, not the root config.
-
-## Telegram preview streaming (token-ish)
-
-Telegram is the only channel with live preview streaming:
-
-- Uses Bot API `sendMessage` (first update) + `editMessageText` (subsequent updates).
-- `channels.telegram.streaming: true | false` (default: `true`).
-- Preview streaming is separate from block streaming.
-- When Telegram block streaming is explicitly enabled, preview streaming is skipped to avoid double-streaming.
-- Text-only finals are applied by editing the preview message in place.
-- Non-text/complex finals fall back to normal final message delivery.
-- `/reasoning stream` writes reasoning into the live preview (Telegram only).
-
-```
-Telegram
-  └─ sendMessage (temporary preview message)
-       └─ streaming=true → edit latest text
-  └─ final text-only reply → final edit on same message
-  └─ fallback: cleanup preview + normal final delivery (media/complex)
-```
-
-Legend:
-
-- `preview message`: temporary Telegram message updated during generation.
-- `final edit`: in-place edit on the same preview message (text-only).

package/docs/concepts/system-prompt.md

@@ -1,128 +0,0 @@
----
-summary: "What the Symi system prompt contains and how it is assembled"
-read_when:
-  - Editing system prompt text, tools list, or time/heartbeat sections
-  - Changing workspace bootstrap or skills injection behavior
-title: "System Prompt"
----
-
-# System Prompt
-
-Symi builds a custom system prompt for every agent run. The prompt is **Symi-owned** and does not use the pi-coding-agent default prompt.
-
-The prompt is assembled by Symi and injected into each agent run.
-
-## Structure
-
-The prompt is intentionally compact and uses fixed sections:
-
-- **Tooling**: current tool list + short descriptions.
-- **Safety**: short guardrail reminder to avoid power-seeking behavior or bypassing oversight.
-- **Skills** (when available): tells the model how to load skill instructions on demand.
-- **Symi Self-Update**: how to run `config.apply` and `update.run`.
-- **Workspace**: working directory (`agents.defaults.workspace`).
-- **Documentation**: local path to Symi docs (repo or npm package) and when to read them.
-- **Workspace Files (injected)**: indicates bootstrap files are included below.
-- **Sandbox** (when enabled): indicates sandboxed runtime, sandbox paths, and whether elevated exec is available.
-- **Current Date & Time**: user-local time, timezone, and time format.
-- **Reply Tags**: optional reply tag syntax for supported providers.
-- **Heartbeats**: heartbeat prompt and ack behavior.
-- **Runtime**: host, OS, node, model, repo root (when detected), thinking level (one line).
-- **Reasoning**: current visibility level + /reasoning toggle hint.
-
-Safety guardrails in the system prompt are advisory. They guide model behavior but do not enforce policy. Use tool policy, exec approvals, sandboxing, and channel allowlists for hard enforcement; operators can disable these by design.
-
-## Prompt modes
-
-Symi can render smaller system prompts for sub-agents. The runtime sets a
-`promptMode` for each run (not a user-facing config):
-
-- `full` (default): includes all sections above.
-- `minimal`: used for sub-agents; omits **Skills**, **Memory Recall**, **Symi
-  Self-Update**, **Model Aliases**, **User Identity**, **Reply Tags**,
-  **Messaging**, **Silent Replies**, and **Heartbeats**. Tooling, **Safety**,
-  Workspace, Sandbox, Current Date & Time (when known), Runtime, and injected
-  context stay available.
-- `none`: returns only the base identity line.
-
-When `promptMode=minimal`, extra injected prompts are labeled **Subagent
-Context** instead of **Group Chat Context**.
-
-## Workspace bootstrap injection
-
-Bootstrap files are trimmed and appended under **Project Context** so the model sees identity and profile context without needing explicit reads:
-
-- `AGENTS.md`
-- `SYMICORE.md`
-- `TOOLS.md`
-- `IDENTITY.md`
-- `USER.md`
-- `SYMIPULSE.md`
-- `BOOTSTRAP.md` (only on brand-new workspaces)
-- `MEMORY.md` and/or `memory.md` (when present in the workspace; either or both may be injected)
-
-All of these files are **injected into the context window** on every turn, which
-means they consume tokens. Keep them concise — especially `MEMORY.md`, which can
-grow over time and lead to unexpectedly high context usage and more frequent
-compaction.
-
-> **Note:** `memory/*.md` daily files are **not** injected automatically. They
-> are accessed on demand via the `memory_search` and `memory_get` tools, so they
-> do not count against the context window unless the model explicitly reads them.
-
-Large files are truncated with a marker. The max per-file size is controlled by
-`agents.defaults.bootstrapMaxChars` (default: 20000). Total injected bootstrap
-content across files is capped by `agents.defaults.bootstrapTotalMaxChars`
-(default: 150000). Missing files inject a short missing-file marker.
-
-Sub-agent sessions only inject `AGENTS.md` and `TOOLS.md` (other bootstrap files
-are filtered out to keep the sub-agent context small).
-
-Internal hooks can intercept this step via `agent:bootstrap` to mutate or replace
-the injected bootstrap files (for example swapping `SYMICORE.md` for an alternate persona).
-
-To inspect how much each injected file contributes (raw vs injected, truncation, plus tool schema overhead), use `/context list` or `/context detail`. See [Context](/concepts/context).
-
-## Time handling
-
-The system prompt includes a dedicated **Current Date & Time** section when the
-user timezone is known. To keep the prompt cache-stable, it now only includes
-the **time zone** (no dynamic clock or time format).
-
-Use `session_status` when the agent needs the current time; the status card
-includes a timestamp line.
-
-Configure with:
-
-- `agents.defaults.userTimezone`
-- `agents.defaults.timeFormat` (`auto` | `12` | `24`)
-
-See [Date & Time](/date-time) for full behavior details.
-
-## Skills
-
-When eligible skills exist, Symi injects a compact **available skills list**
-(`formatSkillsForPrompt`) that includes the **file path** for each skill. The
-prompt instructs the model to use `read` to load the SKILL.md at the listed
-location (workspace, managed, or bundled). If no skills are eligible, the
-Skills section is omitted.
-
-```
-<available_skills>
-  <skill>
-    <name>...</name>
-    <description>...</description>
-    <location>...</location>
-  </skill>
-</available_skills>
-```
-
-This keeps the base prompt small while still enabling targeted skill usage.
-
-## Documentation
-
-When available, the system prompt includes a **Documentation** section that points to the
-local Symi docs directory (either `docs/` in the repo workspace or the bundled npm
-SymiHub ([https://symihub.com](https://symihub.com)) for skills discovery. The prompt instructs the model to consult local docs first
-for Symi behavior, commands, configuration, or architecture, and to run
-`symi status` itself when possible (asking the user only when it lacks access).

package/docs/concepts/timezone.md

@@ -1,90 +0,0 @@
----
-summary: "Timezone handling for agents, envelopes, and prompts"
-read_when:
-  - You need to understand how timestamps are normalized for the model
-  - Configuring the user timezone for system prompts
-title: "Timezones"
----
-
-# Timezones
-
-Symi standardizes timestamps so the model sees a **single reference time**.
-
-## Message envelopes (local by default)
-
-Inbound messages are wrapped in an envelope like:
-
-```
-[Provider ... 2026-01-05 16:26 PST] message text
-```
-
-The timestamp in the envelope is **host-local by default**, with minutes precision.
-
-You can override this with:
-
-```json5
-{
-  agents: {
-    defaults: {
-      envelopeTimezone: "local", // "utc" | "local" | "user" | IANA timezone
-      envelopeTimestamp: "on", // "on" | "off"
-      envelopeElapsed: "on", // "on" | "off"
-    },
-  },
-}
-```
-
-- `envelopeTimezone: "utc"` uses UTC.
-- `envelopeTimezone: "user"` uses `agents.defaults.userTimezone` (falls back to host timezone).
-- Use an explicit IANA timezone (e.g., `"Europe/Vienna"`) for a fixed offset.
-- `envelopeTimestamp: "off"` removes absolute timestamps from envelope headers.
-- `envelopeElapsed: "off"` removes elapsed time suffixes (the `+2m` style).
-
-### Examples
-
-**Local (default):**
-
-```
-[Signal Alice +1555 2026-01-18 00:19 PST] hello
-```
-
-**Fixed timezone:**
-
-```
-[Signal Alice +1555 2026-01-18 06:19 GMT+1] hello
-```
-
-**Elapsed time:**
-
-```
-[Signal Alice +1555 +2m 2026-01-18T05:19Z] follow-up
-```
-
-## Tool payloads (raw provider data + normalized fields)
-
-We also attach normalized fields for consistency:
-
-- `timestampMs` (UTC epoch milliseconds)
-- `timestampUtc` (ISO 8601 UTC string)
-
-Raw provider fields are preserved.
-
-## User timezone for the system prompt
-
-Set `agents.defaults.userTimezone` to tell the model the user's local time zone. If it is
-unset, Symi resolves the **host timezone at runtime** (no config write).
-
-```json5
-{
-  agents: { defaults: { userTimezone: "America/Chicago" } },
-}
-```
-
-The system prompt includes:
-
-- `Current Date & Time` section with local time and timezone
-- `Time format: 12-hour` or `24-hour`
-
-You can control the prompt format with `agents.defaults.timeFormat` (`auto` | `12` | `24`).
-
-See [Date & Time](/date-time) for the full behavior and examples.