milaidy 1.0.0

package/docs/concepts/plugins.md

@@ -0,0 +1,454 @@
+---
+summary: "ElizaOS plugin system: discovery, auto-enable, manifests, and configuration"
+read_when:
+  - Installing or configuring plugins
+  - Building a custom plugin
+  - Understanding plugin auto-enable behavior
+title: "Plugins"
+---
+
+# Plugins
+
+Milaidy uses the ElizaOS plugin system for extensibility. Plugins provide
+channels, providers, actions, evaluators, and services that extend agent
+capabilities.
+
+## Plugin Discovery
+
+Plugins are discovered from multiple locations:
+
+| Origin | Location | Priority |
+|--------|----------|----------|
+| `bundled` | Shipped with ElizaOS | Lowest |
+| `global` | `~/.milaidy/plugins/` | Medium |
+| `workspace` | `<workspace>/plugins/` | High |
+| `config` | Explicit in `character.json` | Highest |
+| `npm` | Installed via npm | Varies |
+
+Install plugins via CLI:
+
+```bash
+milaidy plugins install @elizaos/plugin-discord
+milaidy plugins install @elizaos/plugin-telegram
+milaidy plugins install ./my-local-plugin
+```
+
+## Plugin Manifest (`elizaos.plugin.json`)
+
+Every plugin must ship a manifest file in the plugin root:
+
+```json
+{
+  "id": "my-plugin",
+  "name": "My Plugin",
+  "description": "A custom plugin",
+  "version": "1.0.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiKey": { "type": "string" },
+      "endpoint": { "type": "string" }
+    },
+    "required": ["apiKey"]
+  },
+  "channels": ["my-channel"],
+  "providers": ["my-provider"],
+  "skills": ["skills/my-skill"],
+  "requiredSecrets": ["MY_PLUGIN_API_KEY"],
+  "optionalSecrets": ["MY_PLUGIN_OPTIONAL_KEY"]
+}
+```
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique plugin identifier |
+| `configSchema` | object | JSON Schema for plugin config |
+
+### Optional Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Display name |
+| `description` | string | Short summary |
+| `version` | string | Semver version |
+| `kind` | string | Plugin kind (`memory`, `channel`, `provider`, `skill`, `database`) |
+| `channels` | string[] | Channel IDs provided |
+| `providers` | string[] | Provider IDs provided |
+| `skills` | string[] | Skill directories (relative paths) |
+| `gatewayMethods` | string[] | Gateway RPC methods |
+| `cliCommands` | string[] | CLI commands |
+| `requiredSecrets` | string[] | Required API keys |
+| `optionalSecrets` | string[] | Optional API keys |
+| `dependencies` | string[] | Other plugin IDs required |
+| `minElizaVersion` | string | Minimum ElizaOS version |
+| `uiHints` | object | Config field UI hints |
+
+## Auto-Enable Behavior
+
+Plugins can auto-enable based on detected secrets:
+
+```typescript
+// Plugin auto-enables when DISCORD_BOT_TOKEN is present
+if (process.env.DISCORD_BOT_TOKEN) {
+  // Plugin is enabled
+}
+```
+
+### Auto-Enable Rules
+
+1. **Secret Detection** - If a plugin's `requiredSecrets` are all present, it auto-enables
+2. **Character Config** - Explicit enable/disable in `character.json` overrides auto-enable
+3. **Allow/Deny Lists** - Global plugin filtering via `plugins.allow` / `plugins.deny`
+
+### Configuration Priority
+
+```
+character.json plugins → allow/deny lists → auto-enable → disabled
+```
+
+## Character Configuration
+
+Configure plugins in your `character.json`:
+
+```json
+{
+  "name": "MyAgent",
+  "plugins": [
+    "@elizaos/plugin-discord",
+    "@elizaos/plugin-telegram",
+    "./my-local-plugin"
+  ],
+  "settings": {
+    "plugins": {
+      "discord": {
+        "enabled": true,
+        "guildId": "123456789"
+      },
+      "telegram": {
+        "enabled": true,
+        "webhookMode": false
+      }
+    }
+  }
+}
+```
+
+### Allow/Deny Lists
+
+Control which plugins can load:
+
+```json
+{
+  "settings": {
+    "plugins": {
+      "allow": ["@elizaos/plugin-discord", "@elizaos/plugin-telegram"],
+      "deny": ["@elizaos/plugin-dangerous"]
+    }
+  }
+}
+```
+
+Rules:
+- If `allow` is set, only listed plugins can load
+- `deny` takes precedence over `allow`
+- Patterns support glob matching
+
+## Plugin Kinds
+
+### Channel Plugins
+
+Provide messaging channels:
+
+```json
+{
+  "id": "my-channel",
+  "kind": "channel",
+  "channels": ["my-channel"]
+}
+```
+
+Examples:
+- `@elizaos/plugin-discord`
+- `@elizaos/plugin-telegram`
+- `@elizaos/plugin-slack`
+- `@elizaos/plugin-whatsapp`
+
+### Provider Plugins
+
+Provide model or service providers:
+
+```json
+{
+  "id": "my-provider",
+  "kind": "provider",
+  "providers": ["my-provider"]
+}
+```
+
+Examples:
+- `@elizaos/plugin-openai`
+- `@elizaos/plugin-anthropic`
+- `@elizaos/plugin-ollama`
+
+### Memory Plugins
+
+Provide memory/storage backends:
+
+```json
+{
+  "id": "my-memory",
+  "kind": "memory"
+}
+```
+
+Examples:
+- `@elizaos/plugin-sqlite`
+- `@elizaos/plugin-postgres`
+
+### Skill Plugins
+
+Provide agent skills:
+
+```json
+{
+  "id": "my-skills",
+  "kind": "skill",
+  "skills": ["skills/tool-a", "skills/tool-b"]
+}
+```
+
+## Config Schema Validation
+
+Plugin configuration is validated against the `configSchema`:
+
+```json
+{
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "description": "API key for the service"
+      },
+      "endpoint": {
+        "type": "string",
+        "format": "uri",
+        "default": "https://api.example.com"
+      },
+      "maxRetries": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 10,
+        "default": 3
+      }
+    },
+    "required": ["apiKey"]
+  }
+}
+```
+
+### Validation Rules
+
+- Unknown config keys are **errors** unless `additionalProperties: true`
+- Missing required fields are **errors**
+- Type mismatches are **errors**
+- Invalid plugins block config validation
+
+### Empty Schema
+
+Plugins accepting no config must still provide a schema:
+
+```json
+{
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false
+  }
+}
+```
+
+## UI Hints
+
+Provide hints for configuration UIs:
+
+```json
+{
+  "uiHints": {
+    "apiKey": {
+      "label": "API Key",
+      "help": "Get your API key from https://example.com/keys",
+      "sensitive": true,
+      "type": "password",
+      "placeholder": "sk-..."
+    },
+    "endpoint": {
+      "label": "API Endpoint",
+      "type": "text",
+      "advanced": true
+    }
+  }
+}
+```
+
+### UI Hint Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `label` | string | Display label |
+| `help` | string | Help text |
+| `sensitive` | boolean | Mask in UI |
+| `type` | string | `text`, `password`, `number`, `boolean`, `select`, `textarea` |
+| `placeholder` | string | Placeholder text |
+| `advanced` | boolean | Hide in basic view |
+| `options` | array | Options for select fields |
+
+## Plugin Development
+
+### Basic Plugin Structure
+
+```
+my-plugin/
+├── elizaos.plugin.json    # Plugin manifest (required)
+├── package.json           # Node package config
+├── src/
+│   ├── index.ts           # Main entry point
+│   ├── actions/           # Plugin actions
+│   ├── providers/         # Plugin providers
+│   └── services/          # Plugin services
+└── skills/                # Optional skill directories
+    └── my-skill/
+        └── SKILL.md
+```
+
+### Plugin Entry Point
+
+```typescript
+// src/index.ts
+import type { Plugin } from "@elizaos/core";
+
+const myPlugin: Plugin = {
+  name: "my-plugin",
+  description: "My custom plugin",
+  actions: [
+    // ... action definitions
+  ],
+  providers: [
+    // ... provider definitions
+  ],
+  services: [
+    // ... service definitions
+  ],
+};
+
+export default myPlugin;
+```
+
+### Registering Actions
+
+```typescript
+import { Action, ActionContext } from "@elizaos/core";
+
+const myAction: Action = {
+  name: "my_action",
+  description: "Does something useful",
+  validate: async (runtime, message) => {
+    return true; // Validation logic
+  },
+  handler: async (runtime, message, state, options, callback) => {
+    // Action logic
+    callback({ text: "Done!" });
+    return true;
+  },
+};
+```
+
+## Gateway Plugin
+
+The Gateway plugin provides HTTP API endpoints:
+
+```json
+{
+  "id": "gateway",
+  "gatewayMethods": [
+    "gateway.status",
+    "gateway.restart",
+    "gateway.config"
+  ]
+}
+```
+
+Configure via character settings:
+
+```json
+{
+  "settings": {
+    "gateway": {
+      "port": 18789,
+      "bind": "loopback",
+      "auth": { "mode": "token" }
+    }
+  }
+}
+```
+
+## CLI Commands
+
+Manage plugins via CLI:
+
+```bash
+# List installed plugins
+milaidy plugins list
+
+# Install a plugin
+milaidy plugins install @elizaos/plugin-discord
+
+# Remove a plugin
+milaidy plugins remove @elizaos/plugin-discord
+
+# Update plugins
+milaidy plugins update
+
+# Check plugin health
+milaidy doctor --plugins
+```
+
+## Migration from `milaidy.plugin.json`
+
+If migrating from legacy Milaidy plugins:
+
+| Old | New |
+|-----|-----|
+| `milaidy.plugin.json` | `elizaos.plugin.json` |
+| `channels.*.config` | `character.settings.plugins.*` |
+| Plugin-specific config | Unified schema validation |
+
+See [Migration: Plugins](/migration/plugins) for detailed steps.
+
+## Troubleshooting
+
+### "Plugin manifest not found"
+
+Ensure `elizaos.plugin.json` exists in plugin root with required fields.
+
+### "Config validation failed"
+
+Check plugin config against the manifest's `configSchema`.
+
+### "Plugin disabled despite secrets present"
+
+Check `plugins.deny` list and explicit `enabled: false` in config.
+
+### "Unknown channel"
+
+The channel ID isn't declared in any loaded plugin manifest.
+
+## Related Docs
+
+- [Plugin Manifest](/plugins/manifest) - Detailed manifest reference
+- [Migration: Plugins](/migration/plugins) - Migration guide
+- [Skills](/concepts/skills) - Plugin-provided skills
+- [Tools](/tools) - Available tools and actions

package/docs/concepts/presence.md

@@ -0,0 +1,102 @@
+---
+summary: "How Milaidy presence entries are produced, merged, and displayed"
+read_when:
+  - Debugging the Instances tab
+  - Investigating duplicate or stale instance rows
+  - Changing gateway WS connect or system-event beacons
+title: "Presence"
+---
+
+# Presence
+
+Milaidy “presence” is a lightweight, best‑effort view of:
+
+- the **Gateway** itself, and
+- **clients connected to the Gateway** (mac app, WebChat, CLI, etc.)
+
+Presence is used primarily to render the macOS app’s **Instances** tab and to
+provide quick operator visibility.
+
+## Presence fields (what shows up)
+
+Presence entries are structured objects with fields like:
+
+- `instanceId` (optional but strongly recommended): stable client identity (usually `connect.client.instanceId`)
+- `host`: human‑friendly host name
+- `ip`: best‑effort IP address
+- `version`: client version string
+- `deviceFamily` / `modelIdentifier`: hardware hints
+- `mode`: `ui`, `webchat`, `cli`, `backend`, `probe`, `test`, `node`, ...
+- `lastInputSeconds`: “seconds since last user input” (if known)
+- `reason`: `self`, `connect`, `node-connected`, `periodic`, ...
+- `ts`: last update timestamp (ms since epoch)
+
+## Producers (where presence comes from)
+
+Presence entries are produced by multiple sources and **merged**.
+
+### 1) Gateway self entry
+
+The Gateway always seeds a “self” entry at startup so UIs show the gateway host
+even before any clients connect.
+
+### 2) WebSocket connect
+
+Every WS client begins with a `connect` request. On successful handshake the
+Gateway upserts a presence entry for that connection.
+
+#### Why one‑off CLI commands don’t show up
+
+The CLI often connects for short, one‑off commands. To avoid spamming the
+Instances list, `client.mode === "cli"` is **not** turned into a presence entry.
+
+### 3) `system-event` beacons
+
+Clients can send richer periodic beacons via the `system-event` method. The mac
+app uses this to report host name, IP, and `lastInputSeconds`.
+
+### 4) Node connects (role: node)
+
+When a node connects over the Gateway WebSocket with `role: node`, the Gateway
+upserts a presence entry for that node (same flow as other WS clients).
+
+## Merge + dedupe rules (why `instanceId` matters)
+
+Presence entries are stored in a single in‑memory map:
+
+- Entries are keyed by a **presence key**.
+- The best key is a stable `instanceId` (from `connect.client.instanceId`) that survives restarts.
+- Keys are case‑insensitive.
+
+If a client reconnects without a stable `instanceId`, it may show up as a
+**duplicate** row.
+
+## TTL and bounded size
+
+Presence is intentionally ephemeral:
+
+- **TTL:** entries older than 5 minutes are pruned
+- **Max entries:** 200 (oldest dropped first)
+
+This keeps the list fresh and avoids unbounded memory growth.
+
+## Remote/tunnel caveat (loopback IPs)
+
+When a client connects over an SSH tunnel / local port forward, the Gateway may
+see the remote address as `127.0.0.1`. To avoid overwriting a good client‑reported
+IP, loopback remote addresses are ignored.
+
+## Consumers
+
+### macOS Instances tab
+
+The macOS app renders the output of `system-presence` and applies a small status
+indicator (Active/Idle/Stale) based on the age of the last update.
+
+## Debugging tips
+
+- To see the raw list, call `system-presence` against the Gateway.
+- If you see duplicates:
+  - confirm clients send a stable `client.instanceId` in the handshake
+  - confirm periodic beacons use the same `instanceId`
+  - check whether the connection‑derived entry is missing `instanceId` (duplicates are expected)

package/docs/concepts/queue.md

@@ -0,0 +1,89 @@
+---
+summary: "Command queue design that serializes inbound auto-reply runs"
+read_when:
+  - Changing auto-reply execution or concurrency
+title: "Command Queue"
+---
+
+# Command Queue (2026-01-16)
+
+We serialize inbound auto-reply runs (all channels) through a tiny in-process queue to prevent multiple agent runs from colliding, while still allowing safe parallelism across sessions.
+
+## Why
+
+- Auto-reply runs can be expensive (LLM calls) and can collide when multiple inbound messages arrive close together.
+- Serializing avoids competing for shared resources (session files, logs, CLI stdin) and reduces the chance of upstream rate limits.
+
+## How it works
+
+- A lane-aware FIFO queue drains each lane with a configurable concurrency cap (default 1 for unconfigured lanes; main defaults to 4, subagent to 8).
+- `runEmbeddedElizaAgent` enqueues by **session key** (lane `session:<key>`) to guarantee only one active run per session.
+- Each session run is then queued into a **global lane** (`main` by default) so overall parallelism is capped by `agents.defaults.maxConcurrent`.
+- When verbose logging is enabled, queued runs emit a short notice if they waited more than ~2s before starting.
+- Typing indicators still fire immediately on enqueue (when supported by the channel) so user experience is unchanged while we wait our turn.
+
+## Queue modes (per channel)
+
+Inbound messages can steer the current run, wait for a followup turn, or do both:
+
+- `steer`: inject immediately into the current run (cancels pending tool calls after the next tool boundary). If not streaming, falls back to followup.
+- `followup`: enqueue for the next agent turn after the current run ends.
+- `collect`: coalesce all queued messages into a **single** followup turn (default). If messages target different channels/threads, they drain individually to preserve routing.
+- `steer-backlog` (aka `steer+backlog`): steer now **and** preserve the message for a followup turn.
+- `interrupt` (legacy): abort the active run for that session, then run the newest message.
+- `queue` (legacy alias): same as `steer`.
+
+Steer-backlog means you can get a followup response after the steered run, so
+streaming surfaces can look like duplicates. Prefer `collect`/`steer` if you want
+one response per inbound message.
+Send `/queue collect` as a standalone command (per-session) or set `messages.queue.byChannel.discord: "collect"`.
+
+Defaults (when unset in config):
+
+- All surfaces → `collect`
+
+Configure globally or per channel via `messages.queue`:
+
+```json5
+{
+  messages: {
+    queue: {
+      mode: "collect",
+      debounceMs: 1000,
+      cap: 20,
+      drop: "summarize",
+      byChannel: { discord: "collect" },
+    },
+  },
+}
+```
+
+## Queue options
+
+Options apply to `followup`, `collect`, and `steer-backlog` (and to `steer` when it falls back to followup):
+
+- `debounceMs`: wait for quiet before starting a followup turn (prevents “continue, continue”).
+- `cap`: max queued messages per session.
+- `drop`: overflow policy (`old`, `new`, `summarize`).
+
+Summarize keeps a short bullet list of dropped messages and injects it as a synthetic followup prompt.
+Defaults: `debounceMs: 1000`, `cap: 20`, `drop: summarize`.
+
+## Per-session overrides
+
+- Send `/queue <mode>` as a standalone command to store the mode for the current session.
+- Options can be combined: `/queue collect debounce:2s cap:25 drop:summarize`
+- `/queue default` or `/queue reset` clears the session override.
+
+## Scope and guarantees
+
+- Applies to auto-reply agent runs across all inbound channels that use the gateway reply pipeline (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat, etc.).
+- Default lane (`main`) is process-wide for inbound + main heartbeats; set `agents.defaults.maxConcurrent` to allow multiple sessions in parallel.
+- Additional lanes may exist (e.g. `cron`, `subagent`) so background jobs can run in parallel without blocking inbound replies.
+- Per-session lanes guarantee that only one agent run touches a given session at a time.
+- No external dependencies or background worker threads; pure TypeScript + promises.
+
+## Troubleshooting
+
+- If commands seem stuck, enable verbose logs and look for “queued for …ms” lines to confirm the queue is draining.
+- If you need queue depth, enable verbose logs and watch for queue timing lines.

package/docs/concepts/retry.md

@@ -0,0 +1,69 @@
+---
+summary: "Retry policy for outbound provider calls"
+read_when:
+  - Updating provider retry behavior or defaults
+  - Debugging provider send errors or rate limits
+title: "Retry Policy"
+---
+
+# Retry policy
+
+## Goals
+
+- Retry per HTTP request, not per multi-step flow.
+- Preserve ordering by retrying only the current step.
+- Avoid duplicating non-idempotent operations.
+
+## Defaults
+
+- Attempts: 3
+- Max delay cap: 30000 ms
+- Jitter: 0.1 (10 percent)
+- Provider defaults:
+  - Telegram min delay: 400 ms
+  - Discord min delay: 500 ms
+
+## Behavior
+
+### Discord
+
+- Retries only on rate-limit errors (HTTP 429).
+- Uses Discord `retry_after` when available, otherwise exponential backoff.
+
+### Telegram
+
+- Retries on transient errors (429, timeout, connect/reset/closed, temporarily unavailable).
+- Uses `retry_after` when available, otherwise exponential backoff.
+- Markdown parse errors are not retried; they fall back to plain text.
+
+## Configuration
+
+Set retry policy per provider in `~/.milaidy/milaidy.json`:
+
+```json5
+{
+  channels: {
+    telegram: {
+      retry: {
+        attempts: 3,
+        minDelayMs: 400,
+        maxDelayMs: 30000,
+        jitter: 0.1,
+      },
+    },
+    discord: {
+      retry: {
+        attempts: 3,
+        minDelayMs: 500,
+        maxDelayMs: 30000,
+        jitter: 0.1,
+      },
+    },
+  },
+}
+```
+
+## Notes
+
+- Retries apply per request (message send, media upload, reaction, poll, sticker).
+- Composite flows do not retry completed steps.