milaidy 1.0.0

package/docs/concepts/secrets.md

@@ -0,0 +1,300 @@
+---
+summary: "Secret key names, aliases, validation patterns, and storage locations"
+read_when:
+  - Configuring API keys or tokens
+  - Migrating secrets from another system
+  - Understanding secret validation errors
+title: "Secrets"
+---
+
+# Secrets
+
+This document covers the canonical secret key names, backward-compatible aliases,
+validation patterns, and storage locations used by Milaidy and ElizaOS.
+
+## Canonical Secret Keys
+
+Use these official key names throughout your configuration:
+
+### Model Provider API Keys
+
+| Key | Provider | Alias Support |
+|-----|----------|---------------|
+| `OPENAI_API_KEY` | OpenAI | `OPENAI_KEY`, `OPENAI_TOKEN` |
+| `ANTHROPIC_API_KEY` | Anthropic | `ANTHROPIC_KEY`, `ANTHROPIC_TOKEN`, `CLAUDE_API_KEY` |
+| `GOOGLE_API_KEY` | Google (Gemini) | `GOOGLE_KEY`, `GOOGLE_AI_KEY`, `GEMINI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY` |
+| `GROQ_API_KEY` | Groq | `GROQ_KEY`, `GROQ_TOKEN` |
+| `XAI_API_KEY` | XAI (Grok) | `XAI_KEY`, `GROK_API_KEY` |
+| `OPENROUTER_API_KEY` | OpenRouter | `OPENROUTER_KEY`, `OPENROUTER_TOKEN` |
+| `MISTRAL_API_KEY` | Mistral | `MISTRAL_KEY`, `MISTRAL_TOKEN` |
+| `COHERE_API_KEY` | Cohere | `COHERE_KEY`, `COHERE_TOKEN` |
+| `TOGETHER_API_KEY` | Together AI | `TOGETHER_KEY`, `TOGETHER_TOKEN` |
+| `FIREWORKS_API_KEY` | Fireworks AI | - |
+| `PERPLEXITY_API_KEY` | Perplexity | - |
+| `DEEPSEEK_API_KEY` | DeepSeek | - |
+
+### Channel/Platform Tokens
+
+| Key | Platform | Alias Support |
+|-----|----------|---------------|
+| `DISCORD_BOT_TOKEN` | Discord | `DISCORD_TOKEN`, `DISCORD_API_TOKEN` |
+| `DISCORD_APPLICATION_ID` | Discord | - |
+| `TELEGRAM_BOT_TOKEN` | Telegram | `TELEGRAM_TOKEN`, `TELEGRAM_API_TOKEN`, `TG_BOT_TOKEN` |
+| `SLACK_BOT_TOKEN` | Slack | `SLACK_TOKEN`, `SLACK_API_TOKEN` |
+| `SLACK_APP_TOKEN` | Slack | - |
+| `WHATSAPP_TOKEN` | WhatsApp | `WHATSAPP_BOT_TOKEN`, `WHATSAPP_API_TOKEN` |
+| `SIGNAL_CLI_PATH` | Signal | - |
+
+### Twitter/X Credentials
+
+| Key | Description |
+|-----|-------------|
+| `TWITTER_USERNAME` | Twitter username |
+| `TWITTER_PASSWORD` | Twitter password |
+| `TWITTER_EMAIL` | Associated email |
+| `TWITTER_2FA_SECRET` | TOTP secret (base32) |
+
+### Media/Voice Services
+
+| Key | Service | Alias Support |
+|-----|---------|---------------|
+| `ELEVENLABS_API_KEY` | ElevenLabs TTS | `ELEVENLABS_KEY`, `ELEVEN_LABS_API_KEY` |
+| `ELEVENLABS_VOICE_ID` | ElevenLabs voice | - |
+
+### Infrastructure
+
+| Key | Description |
+|-----|-------------|
+| `ENCRYPTION_SALT` | Encryption salt (hex) |
+| `DATABASE_URL` | Database connection string |
+| `OLLAMA_BASE_URL` | Ollama server URL |
+
+## Key Aliases
+
+Milaidy supports aliases for backward compatibility. When a secret is looked up,
+aliases are automatically resolved to canonical names:
+
+```typescript
+import { resolveSecretKeyAlias } from "@elizaos/core";
+
+// Returns "DISCORD_BOT_TOKEN"
+resolveSecretKeyAlias("DISCORD_TOKEN");
+
+// Returns "ANTHROPIC_API_KEY"
+resolveSecretKeyAlias("CLAUDE_API_KEY");
+```
+
+### Full Alias Mapping
+
+| Legacy/Alternative | Canonical |
+|-------------------|-----------|
+| `DISCORD_TOKEN` | `DISCORD_BOT_TOKEN` |
+| `DISCORD_API_TOKEN` | `DISCORD_BOT_TOKEN` |
+| `TELEGRAM_TOKEN` | `TELEGRAM_BOT_TOKEN` |
+| `TELEGRAM_API_TOKEN` | `TELEGRAM_BOT_TOKEN` |
+| `TG_BOT_TOKEN` | `TELEGRAM_BOT_TOKEN` |
+| `SLACK_TOKEN` | `SLACK_BOT_TOKEN` |
+| `SLACK_API_TOKEN` | `SLACK_BOT_TOKEN` |
+| `OPENAI_KEY` | `OPENAI_API_KEY` |
+| `OPENAI_TOKEN` | `OPENAI_API_KEY` |
+| `ANTHROPIC_KEY` | `ANTHROPIC_API_KEY` |
+| `ANTHROPIC_TOKEN` | `ANTHROPIC_API_KEY` |
+| `CLAUDE_API_KEY` | `ANTHROPIC_API_KEY` |
+| `GOOGLE_KEY` | `GOOGLE_API_KEY` |
+| `GOOGLE_AI_KEY` | `GOOGLE_API_KEY` |
+| `GEMINI_API_KEY` | `GOOGLE_API_KEY` |
+| `GOOGLE_GENERATIVE_AI_API_KEY` | `GOOGLE_API_KEY` |
+| `GROQ_KEY` | `GROQ_API_KEY` |
+| `GROQ_TOKEN` | `GROQ_API_KEY` |
+| `XAI_KEY` | `XAI_API_KEY` |
+| `GROK_API_KEY` | `XAI_API_KEY` |
+| `OPENROUTER_KEY` | `OPENROUTER_API_KEY` |
+| `OPENROUTER_TOKEN` | `OPENROUTER_API_KEY` |
+| `MISTRAL_KEY` | `MISTRAL_API_KEY` |
+| `MISTRAL_TOKEN` | `MISTRAL_API_KEY` |
+| `COHERE_KEY` | `COHERE_API_KEY` |
+| `COHERE_TOKEN` | `COHERE_API_KEY` |
+| `TOGETHER_KEY` | `TOGETHER_API_KEY` |
+| `TOGETHER_TOKEN` | `TOGETHER_API_KEY` |
+| `ELEVENLABS_KEY` | `ELEVENLABS_API_KEY` |
+| `ELEVEN_LABS_API_KEY` | `ELEVENLABS_API_KEY` |
+| `WHATSAPP_BOT_TOKEN` | `WHATSAPP_TOKEN` |
+| `WHATSAPP_API_TOKEN` | `WHATSAPP_TOKEN` |
+
+## Validation Patterns
+
+ElizaOS validates secret formats without making API calls:
+
+### Model Provider Patterns
+
+| Key | Pattern | Example |
+|-----|---------|---------|
+| `OPENAI_API_KEY` | `sk-[a-zA-Z0-9-_]{20,}` | `sk-proj-xxxx...` |
+| `ANTHROPIC_API_KEY` | `sk-ant-[a-zA-Z0-9-_]{20,}` | `sk-ant-api03-xxxx...` |
+| `GOOGLE_API_KEY` | `AIza[a-zA-Z0-9-_]{30,}` | `AIzaSyxxxx...` |
+| `GROQ_API_KEY` | `gsk_[a-zA-Z0-9]{20,}` | `gsk_xxxx...` |
+| `XAI_API_KEY` | `xai-[a-zA-Z0-9-_]{20,}` | `xai-xxxx...` |
+| `OPENROUTER_API_KEY` | `sk-or-[a-zA-Z0-9-_]{20,}` | `sk-or-v1-xxxx...` |
+| `FIREWORKS_API_KEY` | `fw_[a-zA-Z0-9]{20,}` | `fw_xxxx...` |
+| `PERPLEXITY_API_KEY` | `pplx-[a-zA-Z0-9]{20,}` | `pplx-xxxx...` |
+
+### Channel Token Patterns
+
+| Key | Pattern | Example |
+|-----|---------|---------|
+| `DISCORD_BOT_TOKEN` | `[A-Za-z0-9_-]{24,}.[A-Za-z0-9_-]{6}.[A-Za-z0-9_-]{27,}` | `MTIz...GxxxxX.xxx...` |
+| `DISCORD_APPLICATION_ID` | `\d{17,20}` | `123456789012345678` |
+| `TELEGRAM_BOT_TOKEN` | `\d{8,10}:[A-Za-z0-9_-]{35}` | `123456789:ABC...` |
+| `SLACK_BOT_TOKEN` | `xoxb-[0-9]+-[0-9]+-[a-zA-Z0-9]+` | `xoxb-123...-123...-xxx` |
+| `SLACK_APP_TOKEN` | `xapp-[0-9]+-[a-zA-Z0-9]+-[0-9]+-[a-zA-Z0-9]+` | `xapp-1-A01...-123...` |
+
+### Infrastructure Patterns
+
+| Key | Pattern | Example |
+|-----|---------|---------|
+| `DATABASE_URL` | `(postgres\|mysql\|sqlite\|mongodb)://...` | `postgresql://user:pass@localhost:5432/db` |
+| `OLLAMA_BASE_URL` | `https?://...` | `http://localhost:11434` |
+| `ENCRYPTION_SALT` | `[a-f0-9]{32,64}` | `a1b2c3d4...` |
+
+## Storage Locations
+
+Secrets are stored in multiple locations depending on usage:
+
+### 1. Character Settings (`character.settings.secrets`)
+
+Per-character secrets in `character.json`:
+
+```json
+{
+  "name": "MyAgent",
+  "settings": {
+    "secrets": {
+      "DISCORD_BOT_TOKEN": "MTIz...",
+      "ANTHROPIC_API_KEY": "sk-ant-..."
+    }
+  }
+}
+```
+
+### 2. Environment Variables (`process.env`)
+
+System environment or `.env` files:
+
+```bash
+# ~/.milaidy/.env
+ANTHROPIC_API_KEY=sk-ant-...
+DISCORD_BOT_TOKEN=MTIz...
+```
+
+### 3. Credential Files
+
+OAuth and complex credentials:
+
+```
+~/.milaidy/credentials/
+├── oauth.json           # OAuth tokens
+├── whatsapp/
+│   └── <accountId>/     # WhatsApp session
+└── ...
+```
+
+### 4. Auth Profiles
+
+Per-agent authentication:
+
+```
+~/.milaidy/agents/<agentId>/agent/auth-profiles.json
+```
+
+## Secret Resolution Order
+
+When looking up a secret, ElizaOS checks in order:
+
+1. `character.settings.secrets[key]`
+2. `character.settings.secrets[alias]` (for any known aliases)
+3. `process.env[key]`
+4. `process.env[alias]`
+
+```typescript
+// Resolution example
+const token = getSecret("DISCORD_TOKEN"); // Checks DISCORD_TOKEN, then DISCORD_BOT_TOKEN
+```
+
+## Channel Required Secrets
+
+Each channel has required and optional secrets:
+
+| Channel | Required | Optional |
+|---------|----------|----------|
+| Discord | `DISCORD_BOT_TOKEN` | `DISCORD_APPLICATION_ID` |
+| Telegram | `TELEGRAM_BOT_TOKEN` | - |
+| Slack | `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` | - |
+| WhatsApp | `WHATSAPP_TOKEN` | - |
+| Signal | `SIGNAL_CLI_PATH` | - |
+| Twitter | `TWITTER_USERNAME`, `TWITTER_PASSWORD` | `TWITTER_EMAIL`, `TWITTER_2FA_SECRET` |
+
+## API Usage
+
+### Validate a Secret
+
+```typescript
+import { validateSecretKey } from "@elizaos/core";
+
+const result = validateSecretKey("DISCORD_BOT_TOKEN", "MTIz...");
+if (!result.isValid) {
+  console.error(result.error);
+}
+```
+
+### Check Required Secrets
+
+```typescript
+import { checkRequiredSecrets, CHANNEL_SECRETS } from "@elizaos/core";
+
+const secrets = {
+  DISCORD_BOT_TOKEN: "MTIz...",
+};
+
+const result = checkRequiredSecrets(secrets, CHANNEL_SECRETS.discord);
+if (!result.valid) {
+  console.log("Missing:", result.missing);
+  console.log("Invalid:", result.invalid);
+}
+```
+
+### Get Provider for API Key
+
+```typescript
+import { getProviderForApiKey } from "@elizaos/core";
+
+// Returns "anthropic"
+getProviderForApiKey("ANTHROPIC_API_KEY");
+```
+
+## Security Best Practices
+
+1. **Never commit secrets** - Use `.env` files or secret managers
+2. **Use canonical names** - Ensures consistent validation
+3. **Validate on input** - Catch format errors early
+4. **Scope secrets** - Use per-character secrets when possible
+5. **Rotate regularly** - Especially for production deployments
+
+## Troubleshooting
+
+### "Secret appears to be a placeholder"
+
+The value matches common placeholder patterns like `your_api_key_here` or `TODO`.
+
+### "Key is too short"
+
+The value doesn't meet minimum length requirements for that key type.
+
+### "Pattern mismatch"
+
+The value doesn't match the expected format. Check the prefix (e.g., `sk-` for OpenAI).
+
+## Related Docs
+
+- [Migration: Secret Keys](/migration/secret-keys) - Migrating from legacy keys
+- [Onboarding](/start/onboarding) - Initial secret setup
+- [Channels](/channels) - Channel-specific credentials

package/docs/concepts/session-pruning.md

@@ -0,0 +1,122 @@
+---
+summary: "Session pruning: tool-result trimming to reduce context bloat"
+read_when:
+  - You want to reduce LLM context growth from tool outputs
+  - You are tuning agents.defaults.contextPruning
+---
+
+# Session Pruning
+
+Session pruning trims **old tool results** from the in-memory context right before each LLM call. It does **not** rewrite the on-disk session history (`*.jsonl`).
+
+## When it runs
+
+- When `mode: "cache-ttl"` is enabled and the last Anthropic call for the session is older than `ttl`.
+- Only affects the messages sent to the model for that request.
+- Only active for Anthropic API calls (and OpenRouter Anthropic models).
+- For best results, match `ttl` to your model `cacheControlTtl`.
+- After a prune, the TTL window resets so subsequent requests keep cache until `ttl` expires again.
+
+## Smart defaults (Anthropic)
+
+- **OAuth or setup-token** profiles: enable `cache-ttl` pruning and set heartbeat to `1h`.
+- **API key** profiles: enable `cache-ttl` pruning, set heartbeat to `30m`, and default `cacheControlTtl` to `1h` on Anthropic models.
+- If you set any of these values explicitly, Milaidy does **not** override them.
+
+## What this improves (cost + cache behavior)
+
+- **Why prune:** Anthropic prompt caching only applies within the TTL. If a session goes idle past the TTL, the next request re-caches the full prompt unless you trim it first.
+- **What gets cheaper:** pruning reduces the **cacheWrite** size for that first request after the TTL expires.
+- **Why the TTL reset matters:** once pruning runs, the cache window resets, so follow‑up requests can reuse the freshly cached prompt instead of re-caching the full history again.
+- **What it does not do:** pruning doesn’t add tokens or “double” costs; it only changes what gets cached on that first post‑TTL request.
+
+## What can be pruned
+
+- Only `toolResult` messages.
+- User + assistant messages are **never** modified.
+- The last `keepLastAssistants` assistant messages are protected; tool results after that cutoff are not pruned.
+- If there aren’t enough assistant messages to establish the cutoff, pruning is skipped.
+- Tool results containing **image blocks** are skipped (never trimmed/cleared).
+
+## Context window estimation
+
+Pruning uses an estimated context window (chars ≈ tokens × 4). The base window is resolved in this order:
+
+1. `models.providers.*.models[].contextWindow` override.
+2. Model definition `contextWindow` (from the model registry).
+3. Default `200000` tokens.
+
+If `agents.defaults.contextTokens` is set, it is treated as a cap (min) on the resolved window.
+
+## Mode
+
+### cache-ttl
+
+- Pruning only runs if the last Anthropic call is older than `ttl` (default `5m`).
+- When it runs: same soft-trim + hard-clear behavior as before.
+
+## Soft vs hard pruning
+
+- **Soft-trim**: only for oversized tool results.
+  - Keeps head + tail, inserts `...`, and appends a note with the original size.
+  - Skips results with image blocks.
+- **Hard-clear**: replaces the entire tool result with `hardClear.placeholder`.
+
+## Tool selection
+
+- `tools.allow` / `tools.deny` support `*` wildcards.
+- Deny wins.
+- Matching is case-insensitive.
+- Empty allow list => all tools allowed.
+
+## Interaction with other limits
+
+- Built-in tools already truncate their own output; session pruning is an extra layer that prevents long-running chats from accumulating too much tool output in the model context.
+- Compaction is separate: compaction summarizes and persists, pruning is transient per request. See [/concepts/compaction](/concepts/compaction).
+
+## Defaults (when enabled)
+
+- `ttl`: `"5m"`
+- `keepLastAssistants`: `3`
+- `softTrimRatio`: `0.3`
+- `hardClearRatio`: `0.5`
+- `minPrunableToolChars`: `50000`
+- `softTrim`: `{ maxChars: 4000, headChars: 1500, tailChars: 1500 }`
+- `hardClear`: `{ enabled: true, placeholder: "[Old tool result content cleared]" }`
+
+## Examples
+
+Default (off):
+
+```json5
+{
+  agent: {
+    contextPruning: { mode: "off" },
+  },
+}
+```
+
+Enable TTL-aware pruning:
+
+```json5
+{
+  agent: {
+    contextPruning: { mode: "cache-ttl", ttl: "5m" },
+  },
+}
+```
+
+Restrict pruning to specific tools:
+
+```json5
+{
+  agent: {
+    contextPruning: {
+      mode: "cache-ttl",
+      tools: { allow: ["exec", "read"], deny: ["*image*"] },
+    },
+  },
+}
+```
+
+See config reference: [Gateway Configuration](/gateway/configuration)

package/docs/concepts/session-tool.md

@@ -0,0 +1,193 @@
+---
+summary: "Agent session tools for listing sessions, fetching history, and sending cross-session messages"
+read_when:
+  - Adding or modifying session tools
+title: "Session Tools"
+---
+
+# Session Tools
+
+Goal: small, hard-to-misuse tool set so agents can list sessions, fetch history, and send to another session.
+
+## Tool Names
+
+- `sessions_list`
+- `sessions_history`
+- `sessions_send`
+- `sessions_spawn`
+
+## Key Model
+
+- Main direct chat bucket is always the literal key `"main"` (resolved to the current agent’s main key).
+- Group chats use `agent:<agentId>:<channel>:group:<id>` or `agent:<agentId>:<channel>:channel:<id>` (pass the full key).
+- Cron jobs use `cron:<job.id>`.
+- Hooks use `hook:<uuid>` unless explicitly set.
+- Node sessions use `node-<nodeId>` unless explicitly set.
+
+`global` and `unknown` are reserved values and are never listed. If `session.scope = "global"`, we alias it to `main` for all tools so callers never see `global`.
+
+## sessions_list
+
+List sessions as an array of rows.
+
+Parameters:
+
+- `kinds?: string[]` filter: any of `"main" | "group" | "cron" | "hook" | "node" | "other"`
+- `limit?: number` max rows (default: server default, clamp e.g. 200)
+- `activeMinutes?: number` only sessions updated within N minutes
+- `messageLimit?: number` 0 = no messages (default 0); >0 = include last N messages
+
+Behavior:
+
+- `messageLimit > 0` fetches `chat.history` per session and includes the last N messages.
+- Tool results are filtered out in list output; use `sessions_history` for tool messages.
+- When running in a **sandboxed** agent session, session tools default to **spawned-only visibility** (see below).
+
+Row shape (JSON):
+
+- `key`: session key (string)
+- `kind`: `main | group | cron | hook | node | other`
+- `channel`: `whatsapp | telegram | discord | signal | imessage | webchat | internal | unknown`
+- `displayName` (group display label if available)
+- `updatedAt` (ms)
+- `sessionId`
+- `model`, `contextTokens`, `totalTokens`
+- `thinkingLevel`, `verboseLevel`, `systemSent`, `abortedLastRun`
+- `sendPolicy` (session override if set)
+- `lastChannel`, `lastTo`
+- `deliveryContext` (normalized `{ channel, to, accountId }` when available)
+- `transcriptPath` (best-effort path derived from store dir + sessionId)
+- `messages?` (only when `messageLimit > 0`)
+
+## sessions_history
+
+Fetch transcript for one session.
+
+Parameters:
+
+- `sessionKey` (required; accepts session key or `sessionId` from `sessions_list`)
+- `limit?: number` max messages (server clamps)
+- `includeTools?: boolean` (default false)
+
+Behavior:
+
+- `includeTools=false` filters `role: "toolResult"` messages.
+- Returns messages array in the raw transcript format.
+- When given a `sessionId`, Milaidy resolves it to the corresponding session key (missing ids error).
+
+## sessions_send
+
+Send a message into another session.
+
+Parameters:
+
+- `sessionKey` (required; accepts session key or `sessionId` from `sessions_list`)
+- `message` (required)
+- `timeoutSeconds?: number` (default >0; 0 = fire-and-forget)
+
+Behavior:
+
+- `timeoutSeconds = 0`: enqueue and return `{ runId, status: "accepted" }`.
+- `timeoutSeconds > 0`: wait up to N seconds for completion, then return `{ runId, status: "ok", reply }`.
+- If wait times out: `{ runId, status: "timeout", error }`. Run continues; call `sessions_history` later.
+- If the run fails: `{ runId, status: "error", error }`.
+- Announce delivery runs after the primary run completes and is best-effort; `status: "ok"` does not guarantee the announce was delivered.
+- Waits via gateway `agent.wait` (server-side) so reconnects don't drop the wait.
+- Agent-to-agent message context is injected for the primary run.
+- After the primary run completes, Milaidy runs a **reply-back loop**:
+  - Round 2+ alternates between requester and target agents.
+  - Reply exactly `REPLY_SKIP` to stop the ping‑pong.
+  - Max turns is `session.agentToAgent.maxPingPongTurns` (0–5, default 5).
+- Once the loop ends, Milaidy runs the **agent‑to‑agent announce step** (target agent only):
+  - Reply exactly `ANNOUNCE_SKIP` to stay silent.
+  - Any other reply is sent to the target channel.
+  - Announce step includes the original request + round‑1 reply + latest ping‑pong reply.
+
+## Channel Field
+
+- For groups, `channel` is the channel recorded on the session entry.
+- For direct chats, `channel` maps from `lastChannel`.
+- For cron/hook/node, `channel` is `internal`.
+- If missing, `channel` is `unknown`.
+
+## Security / Send Policy
+
+Policy-based blocking by channel/chat type (not per session id).
+
+```json
+{
+  "session": {
+    "sendPolicy": {
+      "rules": [
+        {
+          "match": { "channel": "discord", "chatType": "group" },
+          "action": "deny"
+        }
+      ],
+      "default": "allow"
+    }
+  }
+}
+```
+
+Runtime override (per session entry):
+
+- `sendPolicy: "allow" | "deny"` (unset = inherit config)
+- Settable via `sessions.patch` or owner-only `/send on|off|inherit` (standalone message).
+
+Enforcement points:
+
+- `chat.send` / `agent` (gateway)
+- auto-reply delivery logic
+
+## sessions_spawn
+
+Spawn a sub-agent run in an isolated session and announce the result back to the requester chat channel.
+
+Parameters:
+
+- `task` (required)
+- `label?` (optional; used for logs/UI)
+- `agentId?` (optional; spawn under another agent id if allowed)
+- `model?` (optional; overrides the sub-agent model; invalid values error)
+- `runTimeoutSeconds?` (default 0; when set, aborts the sub-agent run after N seconds)
+- `cleanup?` (`delete|keep`, default `keep`)
+
+Allowlist:
+
+- `agents.list[].subagents.allowAgents`: list of agent ids allowed via `agentId` (`["*"]` to allow any). Default: only the requester agent.
+
+Discovery:
+
+- Use `agents_list` to discover which agent ids are allowed for `sessions_spawn`.
+
+Behavior:
+
+- Starts a new `agent:<agentId>:subagent:<uuid>` session with `deliver: false`.
+- Sub-agents default to the full tool set **minus session tools** (configurable via `tools.subagents.tools`).
+- Sub-agents are not allowed to call `sessions_spawn` (no sub-agent → sub-agent spawning).
+- Always non-blocking: returns `{ status: "accepted", runId, childSessionKey }` immediately.
+- After completion, Milaidy runs a sub-agent **announce step** and posts the result to the requester chat channel.
+- Reply exactly `ANNOUNCE_SKIP` during the announce step to stay silent.
+- Announce replies are normalized to `Status`/`Result`/`Notes`; `Status` comes from runtime outcome (not model text).
+- Sub-agent sessions are auto-archived after `agents.defaults.subagents.archiveAfterMinutes` (default: 60).
+- Announce replies include a stats line (runtime, tokens, sessionKey/sessionId, transcript path, and optional cost).
+
+## Sandbox Session Visibility
+
+Sandboxed sessions can use session tools, but by default they only see sessions they spawned via `sessions_spawn`.
+
+Config:
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        // default: "spawned"
+        sessionToolsVisibility: "spawned", // or "all"
+      },
+    },
+  },
+}
+```