@symerian/symi 3.0.21 → 3.0.22

package/docs/tools/subagents.md

@@ -1,232 +0,0 @@
----
-summary: "Sub-agents: spawning isolated agent runs that announce results back to the requester chat"
-read_when:
-  - You want background/parallel work via the agent
-  - You are changing sessions_spawn or sub-agent tool policy
-title: "Sub-Agents"
----
-
-# Sub-agents
-
-Sub-agents are background agent runs spawned from an existing agent run. They run in their own session (`agent:<agentId>:subagent:<uuid>`) and, when finished, **announce** their result back to the requester chat channel.
-
-## Slash command
-
-Use `/subagents` to inspect or control sub-agent runs for the **current session**:
-
-- `/subagents list`
-- `/subagents kill <id|#|all>`
-- `/subagents log <id|#> [limit] [tools]`
-- `/subagents info <id|#>`
-- `/subagents send <id|#> <message>`
-- `/subagents steer <id|#> <message>`
-- `/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]`
-
-`/subagents info` shows run metadata (status, timestamps, session id, transcript path, cleanup).
-
-### Spawn behavior
-
-`/subagents spawn` starts a background sub-agent as a user command, not an internal relay, and it sends one final completion update back to the requester chat when the run finishes.
-
-- The spawn command is non-blocking; it returns a run id immediately.
-- On completion, the sub-agent announces a summary/result message back to the requester chat channel.
-- For manual spawns, delivery is resilient:
-  - Symi tries direct `agent` delivery first with a stable idempotency key.
-  - If direct delivery fails, it falls back to queue routing.
-  - If queue routing is still not available, the announce is retried with a short exponential backoff before final give-up.
-- The completion message is a system message and includes:
-  - `Result` (`assistant` reply text, or latest `toolResult` if the assistant reply is empty)
-  - `Status` (`completed successfully` / `failed` / `timed out`)
-  - compact runtime/token stats
-- `--model` and `--thinking` override defaults for that specific run.
-- Use `info`/`log` to inspect details and output after completion.
-
-Primary goals:
-
-- Parallelize "research / long task / slow tool" work without blocking the main run.
-- Keep sub-agents isolated by default (session separation + optional sandboxing).
-- Keep the tool surface hard to misuse: sub-agents do **not** get session tools by default.
-- Support configurable nesting depth for orchestrator patterns.
-
-Cost note: each sub-agent has its **own** context and token usage. For heavy or repetitive
-tasks, set a cheaper model for sub-agents and keep your main agent on a higher-quality model.
-You can configure this via `agents.defaults.subagents.model` or per-agent overrides.
-
-## Tool
-
-Use `sessions_spawn`:
-
-- Starts a sub-agent run (`deliver: false`, global lane: `subagent`)
-- Then runs an announce step and posts the announce reply to the requester chat channel
-- Default model: inherits the caller unless you set `agents.defaults.subagents.model` (or per-agent `agents.list[].subagents.model`); an explicit `sessions_spawn.model` still wins.
-- Default thinking: inherits the caller unless you set `agents.defaults.subagents.thinking` (or per-agent `agents.list[].subagents.thinking`); an explicit `sessions_spawn.thinking` still wins.
-
-Tool params:
-
-- `task` (required)
-- `label?` (optional)
-- `agentId?` (optional; spawn under another agent id if allowed)
-- `model?` (optional; overrides the sub-agent model; invalid values are skipped and the sub-agent runs on the default model with a warning in the tool result)
-- `thinking?` (optional; overrides thinking level for the sub-agent run)
-- `runTimeoutSeconds?` (default `0`; when set, the sub-agent run is aborted after N seconds)
-- `cleanup?` (`delete|keep`, default `keep`)
-
-Allowlist:
-
-- `agents.list[].subagents.allowAgents`: list of agent ids that can be targeted via `agentId` (`["*"]` to allow any). Default: only the requester agent.
-
-Discovery:
-
-- Use `agents_list` to see which agent ids are currently allowed for `sessions_spawn`.
-
-Auto-archive:
-
-- Sub-agent sessions are automatically archived after `agents.defaults.subagents.archiveAfterMinutes` (default: 60).
-- Archive uses `sessions.delete` and renames the transcript to `*.deleted.<timestamp>` (same folder).
-- `cleanup: "delete"` archives immediately after announce (still keeps the transcript via rename).
-- Auto-archive is best-effort; pending timers are lost if the gateway restarts.
-- `runTimeoutSeconds` does **not** auto-archive; it only stops the run. The session remains until auto-archive.
-- Auto-archive applies equally to depth-1 and depth-2 sessions.
-
-## Nested Sub-Agents
-
-By default, sub-agents cannot spawn their own sub-agents (`maxSpawnDepth: 1`). You can enable one level of nesting by setting `maxSpawnDepth: 2`, which allows the **orchestrator pattern**: main → orchestrator sub-agent → worker sub-sub-agents.
-
-### How to enable
-
-```json5
-{
-  agents: {
-    defaults: {
-      subagents: {
-        maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)
-        maxChildrenPerAgent: 5, // max active children per agent session (default: 5)
-        maxConcurrent: 8, // global concurrency lane cap (default: 8)
-      },
-    },
-  },
-}
-```
-
-### Depth levels
-
-| Depth | Session key shape                            | Role                                          | Can spawn?                   |
-| ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- |
-| 0     | `agent:<id>:main`                            | Main agent                                    | Always                       |
-| 1     | `agent:<id>:subagent:<uuid>`                 | Sub-agent (orchestrator when depth 2 allowed) | Only if `maxSpawnDepth >= 2` |
-| 2     | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Sub-sub-agent (leaf worker)                   | Never                        |
-
-### Announce chain
-
-Results flow back up the chain:
-
-1. Depth-2 worker finishes → announces to its parent (depth-1 orchestrator)
-2. Depth-1 orchestrator receives the announce, synthesizes results, finishes → announces to main
-3. Main agent receives the announce and delivers to the user
-
-Each level only sees announces from its direct children.
-
-### Tool policy by depth
-
-- **Depth 1 (orchestrator, when `maxSpawnDepth >= 2`)**: Gets `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` so it can manage its children. Other session/system tools remain denied.
-- **Depth 1 (leaf, when `maxSpawnDepth == 1`)**: No session tools (current default behavior).
-- **Depth 2 (leaf worker)**: No session tools — `sessions_spawn` is always denied at depth 2. Cannot spawn further children.
-
-### Per-agent spawn limit
-
-Each agent session (at any depth) can have at most `maxChildrenPerAgent` (default: 5) active children at a time. This prevents runaway fan-out from a single orchestrator.
-
-### Cascade stop
-
-Stopping a depth-1 orchestrator automatically stops all its depth-2 children:
-
-- `/stop` in the main chat stops all depth-1 agents and cascades to their depth-2 children.
-- `/subagents kill <id>` stops a specific sub-agent and cascades to its children.
-- `/subagents kill all` stops all sub-agents for the requester and cascades.
-
-## Authentication
-
-Sub-agent auth is resolved by **agent id**, not by session type:
-
-- The sub-agent session key is `agent:<agentId>:subagent:<uuid>`.
-- The auth store is loaded from that agent's `agentDir`.
-- The main agent's auth profiles are merged in as a **fallback**; agent profiles override main profiles on conflicts.
-
-Note: the merge is additive, so main profiles are always available as fallbacks. Fully isolated auth per agent is not supported yet.
-
-## Announce
-
-Sub-agents report back via an announce step:
-
-- The announce step runs inside the sub-agent session (not the requester session).
-- If the sub-agent replies exactly `ANNOUNCE_SKIP`, nothing is posted.
-- Otherwise the announce reply is posted to the requester chat channel via a follow-up `agent` call (`deliver=true`).
-- Announce replies preserve thread/topic routing when available (Slack threads, Telegram topics, Matrix threads).
-- Announce messages are normalized to a stable template:
-  - `Status:` derived from the run outcome (`success`, `error`, `timeout`, or `unknown`).
-  - `Result:` the summary content from the announce step (or `(not available)` if missing).
-  - `Notes:` error details and other useful context.
-- `Status` is not inferred from model output; it comes from runtime outcome signals.
-
-Announce payloads include a stats line at the end (even when wrapped):
-
-- Runtime (e.g., `runtime 5m12s`)
-- Token usage (input/output/total)
-- Estimated cost when model pricing is configured (`models.providers.*.models[].cost`)
-- `sessionKey`, `sessionId`, and transcript path (so the main agent can fetch history via `sessions_history` or inspect the file on disk)
-
-## Tool Policy (sub-agent tools)
-
-By default, sub-agents get **all tools except session tools** and system tools:
-
-- `sessions_list`
-- `sessions_history`
-- `sessions_send`
-- `sessions_spawn`
-
-When `maxSpawnDepth >= 2`, depth-1 orchestrator sub-agents additionally receive `sessions_spawn`, `subagents`, `sessions_list`, and `sessions_history` so they can manage their children.
-
-Override via config:
-
-```json5
-{
-  agents: {
-    defaults: {
-      subagents: {
-        maxConcurrent: 1,
-      },
-    },
-  },
-  tools: {
-    subagents: {
-      tools: {
-        // deny wins
-        deny: ["gateway", "cron"],
-        // if allow is set, it becomes allow-only (deny still wins)
-        // allow: ["read", "exec", "process"]
-      },
-    },
-  },
-}
-```
-
-## Concurrency
-
-Sub-agents use a dedicated in-process queue lane:
-
-- Lane name: `subagent`
-- Concurrency: `agents.defaults.subagents.maxConcurrent` (default `8`)
-
-## Stopping
-
-- Sending `/stop` in the requester chat aborts the requester session and stops any active sub-agent runs spawned from it, cascading to nested children.
-- `/subagents kill <id>` stops a specific sub-agent and cascades to its children.
-
-## Limitations
-
-- Sub-agent announce is **best-effort**. If the gateway restarts, pending "announce back" work is lost.
-- Sub-agents still share the same gateway process resources; treat `maxConcurrent` as a safety valve.
-- `sessions_spawn` is always non-blocking: it returns `{ status: "accepted", runId, childSessionKey }` immediately.
-- Sub-agent context only injects `AGENTS.md` + `TOOLS.md` (no `SYMICORE.md`, `IDENTITY.md`, `USER.md`, `SYMIPULSE.md`, or `BOOTSTRAP.md`).
-- Maximum nesting depth is 5 (`maxSpawnDepth` range: 1–5). Depth 2 is recommended for most use cases.
-- `maxChildrenPerAgent` caps active children per session (default: 5, range: 1–20).

package/docs/tools/symihub.md

@@ -1,256 +0,0 @@
----
-summary: "SymiHub guide: public skills registry + CLI workflows"
-read_when:
-  - Introducing SymiHub to new users
-  - Installing, searching, or publishing skills
-  - Explaining SymiHub CLI flags and sync behavior
-title: "SymiHub"
----
-
-# SymiHub
-
-SymiHub is the **public skill registry for Symi**. It is a free service: all skills are public, open, and visible to everyone for sharing and reuse. A skill is just a folder with a `SKILL.md` file (plus supporting text files). You can browse skills in the web app or use the CLI to search, install, update, and publish skills.
-
-Site: [symihub.ai](https://symihub.ai)
-
-## What SymiHub is
-
-- A public registry for Symi skills.
-- A versioned store of skill bundles and metadata.
-- A discovery surface for search, tags, and usage signals.
-
-## How it works
-
-1. A user publishes a skill bundle (files + metadata).
-2. SymiHub stores the bundle, parses metadata, and assigns a version.
-3. The registry indexes the skill for search and discovery.
-4. Users browse, download, and install skills in Symi.
-
-## What you can do
-
-- Publish new skills and new versions of existing skills.
-- Discover skills by name, tags, or search.
-- Download skill bundles and inspect their files.
-- Report skills that are abusive or unsafe.
-- If you are a moderator, hide, unhide, delete, or ban.
-
-## Who this is for (beginner-friendly)
-
-If you want to add new capabilities to your Symi agent, SymiHub is the easiest way to find and install skills. You do not need to know how the backend works. You can:
-
-- Search for skills by plain language.
-- Install a skill into your workspace.
-- Update skills later with one command.
-- Back up your own skills by publishing them.
-
-## Quick start (non-technical)
-
-1. Install the CLI (see next section).
-2. Search for something you need:
-   - `symihub search "calendar"`
-3. Install a skill:
-   - `symihub install <skill-slug>`
-4. Start a new Symi session so it picks up the new skill.
-
-## Install the CLI
-
-Pick one:
-
-```bash
-npm i -g symihub
-```
-
-```bash
-pnpm add -g symihub
-```
-
-## How it fits into Symi
-
-By default, the CLI installs skills into `./skills` under your current working directory. If a Symi workspace is configured, `symihub` falls back to that workspace unless you override `--workdir` (or `SYMIHUB_WORKDIR`). Symi loads workspace skills from `<workspace>/skills` and will pick them up in the **next** session. If you already use `~/.symi/skills` or bundled skills, workspace skills take precedence.
-
-For more detail on how skills are loaded, shared, and gated, see
-[Skills](/tools/skills).
-
-## Skill system overview
-
-A skill is a versioned bundle of files that teaches Symi how to perform a
-specific task. Each publish creates a new version, and the registry keeps a
-history of versions so users can audit changes.
-
-A typical skill includes:
-
-- A `SKILL.md` file with the primary description and usage.
-- Optional configs, scripts, or supporting files used by the skill.
-- Metadata such as tags, summary, and install requirements.
-
-SymiHub uses metadata to power discovery and safely expose skill capabilities.
-The registry also tracks usage signals (such as stars and downloads) to improve
-ranking and visibility.
-
-## What the service provides (features)
-
-- **Public browsing** of skills and their `SKILL.md` content.
-- **Search** powered by embeddings (vector search), not just keywords.
-- **Versioning** with semver, changelogs, and tags (including `latest`).
-- **Downloads** as a zip per version.
-- **Stars and comments** for community feedback.
-- **Moderation** hooks for approvals and audits.
-- **CLI-friendly API** for automation and scripting.
-
-## Security and moderation
-
-SymiHub is open by default. Anyone can upload skills, but a GitHub account must
-be at least one week old to publish. This helps slow down abuse without blocking
-legitimate contributors.
-
-Reporting and moderation:
-
-- Any signed in user can report a skill.
-- Report reasons are required and recorded.
-- Each user can have up to 20 active reports at a time.
-- Skills with more than 3 unique reports are auto hidden by default.
-- Moderators can view hidden skills, unhide them, delete them, or ban users.
-- Abusing the report feature can result in account bans.
-
-moderator or maintainer.
-
-## CLI commands and parameters
-
-Global options (apply to all commands):
-
-- `--workdir <dir>`: Working directory (default: current dir; falls back to Symi workspace).
-- `--dir <dir>`: Skills directory, relative to workdir (default: `skills`).
-- `--site <url>`: Site base URL (browser login).
-- `--registry <url>`: Registry API base URL.
-- `--no-input`: Disable prompts (non-interactive).
-- `-V, --cli-version`: Print CLI version.
-
-Auth:
-
-- `symihub login` (browser flow) or `symihub login --token <token>`
-- `symihub logout`
-- `symihub whoami`
-
-Options:
-
-- `--token <token>`: Paste an API token.
-- `--label <label>`: Label stored for browser login tokens (default: `CLI token`).
-- `--no-browser`: Do not open a browser (requires `--token`).
-
-Search:
-
-- `symihub search "query"`
-- `--limit <n>`: Max results.
-
-Install:
-
-- `symihub install <slug>`
-- `--version <version>`: Install a specific version.
-- `--force`: Overwrite if the folder already exists.
-
-Update:
-
-- `symihub update <slug>`
-- `symihub update --all`
-- `--version <version>`: Update to a specific version (single slug only).
-- `--force`: Overwrite when local files do not match any published version.
-
-List:
-
-- `symihub list` (reads `.symihub/lock.json`)
-
-Publish:
-
-- `symihub publish <path>`
-- `--slug <slug>`: Skill slug.
-- `--name <name>`: Display name.
-- `--version <version>`: Semver version.
-- `--changelog <text>`: Changelog text (can be empty).
-- `--tags <tags>`: Comma-separated tags (default: `latest`).
-
-Delete/undelete (owner/admin only):
-
-- `symihub delete <slug> --yes`
-- `symihub undelete <slug> --yes`
-
-Sync (scan local skills + publish new/updated):
-
-- `symihub sync`
-- `--root <dir...>`: Extra scan roots.
-- `--all`: Upload everything without prompts.
-- `--dry-run`: Show what would be uploaded.
-- `--bump <type>`: `patch|minor|major` for updates (default: `patch`).
-- `--changelog <text>`: Changelog for non-interactive updates.
-- `--tags <tags>`: Comma-separated tags (default: `latest`).
-- `--concurrency <n>`: Registry checks (default: 4).
-
-## Common workflows for agents
-
-### Search for skills
-
-```bash
-symihub search "postgres backups"
-```
-
-### Download new skills
-
-```bash
-symihub install my-skill-pack
-```
-
-### Update installed skills
-
-```bash
-symihub update --all
-```
-
-### Back up your skills (publish or sync)
-
-For a single skill folder:
-
-```bash
-symihub publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0 --tags latest
-```
-
-To scan and back up many skills at once:
-
-```bash
-symihub sync --all
-```
-
-## Advanced details (technical)
-
-### Versioning and tags
-
-- Each publish creates a new **semver** `SkillVersion`.
-- Tags (like `latest`) point to a version; moving tags lets you roll back.
-- Changelogs are attached per version and can be empty when syncing or publishing updates.
-
-### Local changes vs registry versions
-
-Updates compare the local skill contents to registry versions using a content hash. If local files do not match any published version, the CLI asks before overwriting (or requires `--force` in non-interactive runs).
-
-### Sync scanning and fallback roots
-
-`symihub sync` scans your current workdir first. If no skills are found, it falls back to known legacy locations (for example `~/symi/skills` and `~/.symi/skills`). This is designed to find older skill installs without extra flags.
-
-### Storage and lockfile
-
-- Installed skills are recorded in `.symihub/lock.json` under your workdir.
-- Auth tokens are stored in the SymiHub CLI config file (override via `SYMIHUB_CONFIG_PATH`).
-
-### Telemetry (install counts)
-
-When you run `symihub sync` while logged in, the CLI sends a minimal snapshot to compute install counts. You can disable this entirely:
-
-```bash
-export SYMIHUB_DISABLE_TELEMETRY=1
-```
-
-## Environment variables
-
-- `SYMIHUB_SITE`: Override the site URL.
-- `SYMIHUB_REGISTRY`: Override the registry API URL.
-- `SYMIHUB_CONFIG_PATH`: Override where the CLI stores the token/config.
-- `SYMIHUB_WORKDIR`: Override the default workdir.
-- `SYMIHUB_DISABLE_TELEMETRY=1`: Disable telemetry on `sync`.

package/docs/tools/thinking.md

@@ -1,75 +0,0 @@
----
-summary: "Directive syntax for /think + /verbose and how they affect model reasoning"
-read_when:
-  - Adjusting thinking or verbose directive parsing or defaults
-title: "Thinking Levels"
----
-
-# Thinking Levels (/think directives)
-
-## What it does
-
-- Inline directive in any inbound body: `/t <level>`, `/think:<level>`, or `/thinking <level>`.
-- Levels (aliases): `off | minimal | low | medium | high | xhigh` (GPT-5.2 + Codex models only)
-  - minimal → “think”
-  - low → “think hard”
-  - medium → “think harder”
-  - high → “ultrathink” (max budget)
-  - xhigh → “ultrathink+” (GPT-5.2 + Codex models only)
-  - `x-high`, `x_high`, `extra-high`, `extra high`, and `extra_high` map to `xhigh`.
-  - `highest`, `max` map to `high`.
-- Provider notes:
-  - Z.AI (`zai/*`) only supports binary thinking (`on`/`off`). Any non-`off` level is treated as `on` (mapped to `low`).
-
-## Resolution order
-
-1. Inline directive on the message (applies only to that message).
-2. Session override (set by sending a directive-only message).
-3. Global default (`agents.defaults.thinkingDefault` in config).
-4. Fallback: low for reasoning-capable models; off otherwise.
-
-## Setting a session default
-
-- Send a message that is **only** the directive (whitespace allowed), e.g. `/think:medium` or `/t high`.
-- That sticks for the current session (per-sender by default); cleared by `/think:off` or session idle reset.
-- Confirmation reply is sent (`Thinking level set to high.` / `Thinking disabled.`). If the level is invalid (e.g. `/thinking big`), the command is rejected with a hint and the session state is left unchanged.
-- Send `/think` (or `/think:`) with no argument to see the current thinking level.
-
-## Application by agent
-
-- **Embedded Pi**: the resolved level is passed to the in-process Pi agent runtime.
-
-## Verbose directives (/verbose or /v)
-
-- Levels: `on` (minimal) | `full` | `off` (default).
-- Directive-only message toggles session verbose and replies `Verbose logging enabled.` / `Verbose logging disabled.`; invalid levels return a hint without changing state.
-- `/verbose off` stores an explicit session override; clear it via the Sessions UI by choosing `inherit`.
-- Inline directive affects only that message; session/global defaults apply otherwise.
-- Send `/verbose` (or `/verbose:`) with no argument to see the current verbose level.
-- When verbose is on, agents that emit structured tool results (Pi, other JSON agents) send each tool call back as its own metadata-only message, prefixed with `<emoji> <tool-name>: <arg>` when available (path/command). These tool summaries are sent as soon as each tool starts (separate bubbles), not as streaming deltas.
-- When verbose is `full`, tool outputs are also forwarded after completion (separate bubble, truncated to a safe length). If you toggle `/verbose on|full|off` while a run is in-flight, subsequent tool bubbles honor the new setting.
-
-## Reasoning visibility (/tools/thinking#reasoning-visibility-reasoning)
-
-- Levels: `on|off|stream`.
-- Directive-only message toggles whether thinking blocks are shown in replies.
-- When enabled, reasoning is sent as a **separate message** prefixed with `Reasoning:`.
-- `stream` (Telegram only): streams reasoning into the Telegram draft bubble while the reply is generating, then sends the final answer without reasoning.
-- Alias: `/reason`.
-- Send `/reasoning` (or `/reasoning:`) with no argument to see the current reasoning level.
-
-## Related
-
-- Elevated mode docs live in [Elevated mode](/tools/elevated).
-- Reasoning visibility behavior is documented in [Reasoning visibility](/tools/thinking#reasoning-visibility-reasoning).
-
-## Heartbeats
-
-- Heartbeat probe body is the configured heartbeat prompt (default: `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.`). Inline directives in a heartbeat message apply as usual (but avoid changing session defaults from heartbeats).
-- Heartbeat delivery defaults to the final payload only. To also send the separate `Reasoning:` message (when available), set `agents.defaults.heartbeat.includeReasoning: true` or per-agent `agents.list[].heartbeat.includeReasoning: true`.
-
-## Web chat UI
-
-- The web chat thinking selector mirrors the session's stored level from the inbound session store/config when the page loads.
-- Picking another level applies only to the next message (`thinkingOnce`); after sending, the selector snaps back to the stored session level.
-- To change the session default, send a `/think:<level>` directive (as before); the selector will reflect it after the next reload.