milaidy 1.0.0

package/docs/concepts/session.md

@@ -0,0 +1,188 @@
+---
+summary: "Session management rules, keys, and persistence for chats"
+read_when:
+  - Modifying session handling or storage
+title: "Session Management"
+---
+
+# Session Management
+
+Milaidy 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)
+
+If your agent can receive DMs from **multiple people** (pairing approvals for more than one sender, a DM allowlist with multiple entries, or `dmPolicy: "open"`), enable **secure DM mode** to avoid cross-user context leakage:
+
+```json5
+// ~/.milaidy/milaidy.json
+{
+  session: {
+    // Secure DM mode: isolate DM context per channel + sender.
+    dmScope: "per-channel-peer",
+  },
+}
+```
+
+Notes:
+
+- Default is `dmScope: "main"` for continuity (all DMs share the main session).
+- 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.
+
+## Gateway is the source of truth
+
+All session state is **owned by the gateway** (the “master” Milaidy). 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: `~/.milaidy/agents/<agentId>/sessions/sessions.json` (per agent).
+- Transcripts: `~/.milaidy/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.
+- Milaidy does **not** read legacy Pi/Tau session folders.
+
+## Session pruning
+
+Milaidy 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, Milaidy 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, Milaidy stays in idle-only mode for backward compatibility.
+- Per-type overrides (optional): `resetByType` lets you override the policy for `dm`, `group`, and `thread` sessions (thread = Slack/Discord threads, Telegram topics, Matrix threads when provided by the connector).
+- 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, Milaidy 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: { channel: "discord", chatType: "group" } },
+        { action: "deny", match: { keyPrefix: "cron:" } },
+      ],
+      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
+// ~/.milaidy/milaidy.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: {
+      alice: ["telegram:123456789", "discord:987654321012345678"],
+    },
+    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 },
+      dm: { mode: "idle", idleMinutes: 240 },
+      group: { mode: "idle", idleMinutes: 120 },
+    },
+    resetByChannel: {
+      discord: { mode: "idle", idleMinutes: 10080 },
+    },
+    resetTriggers: ["/new", "/reset"],
+    store: "~/.milaidy/agents/{agentId}/sessions/sessions.json",
+    mainKey: "main",
+  },
+}
+```
+
+## Inspecting
+
+- `milaidy status` — shows store path and recent sessions.
+- `milaidy sessions --json` — dumps every entry (filter with `--active <minutes>`).
+- `milaidy 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

@@ -0,0 +1,10 @@
+---
+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/skills.md

@@ -0,0 +1,392 @@
+---
+summary: "Skills: directories, precedence, eligibility, and configuration"
+read_when:
+  - Adding or configuring skills
+  - Understanding skill loading and gating
+  - Creating custom skills
+title: "Skills"
+---
+
+# Skills
+
+Skills teach Milaidy agents how to use tools. Each skill is a directory
+containing a `SKILL.md` file with YAML frontmatter and instructions. Skills
+are [AgentSkills](https://agentskills.io)-compatible.
+
+## Skill Locations and Precedence
+
+Skills load from three locations (highest to lowest precedence):
+
+| Location | Path | Scope |
+|----------|------|-------|
+| **Workspace** | `<workspace>/skills/` | Per-agent |
+| **Managed/Local** | `~/.milaidy/skills/` | All agents |
+| **Bundled** | Shipped with install | All agents |
+
+If a skill name conflicts, the higher-precedence location wins.
+
+### Extra Directories
+
+Add additional skill folders via config:
+
+```json
+{
+  "skills": {
+    "load": {
+      "extraDirs": ["/path/to/shared/skills"]
+    }
+  }
+}
+```
+
+Extra directories have the lowest precedence.
+
+## Skill Format
+
+A minimal `SKILL.md`:
+
+```markdown
+---
+name: my-skill
+description: Does something useful
+---
+
+## Instructions
+
+Use this skill when you need to do X...
+```
+
+### Required Frontmatter
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Skill identifier |
+| `description` | string | Short description |
+
+### Optional Frontmatter
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `homepage` | string | - | Website URL |
+| `user-invocable` | boolean | `true` | Expose as slash command |
+| `disable-model-invocation` | boolean | `false` | Exclude from model prompt |
+| `command-dispatch` | string | - | Set to `tool` for direct dispatch |
+| `command-tool` | string | - | Tool to invoke |
+| `command-arg-mode` | string | `raw` | Argument handling mode |
+
+## Eligibility Gating
+
+Skills can specify requirements via `metadata`:
+
+```markdown
+---
+name: my-skill
+description: Requires specific tools
+metadata: {"milaidy": {"requires": {"bins": ["uv"], "env": ["MY_API_KEY"], "config": ["browser.enabled"]}, "primaryEnv": "MY_API_KEY"}}
+---
+```
+
+### Gating Fields
+
+| Field | Description |
+|-------|-------------|
+| `metadata.milaidy.always` | Always include (skip other gates) |
+| `metadata.milaidy.os` | Platform filter (`darwin`, `linux`, `win32`) |
+| `metadata.milaidy.requires.bins` | Required binaries on PATH |
+| `metadata.milaidy.requires.anyBins` | At least one must exist |
+| `metadata.milaidy.requires.env` | Required environment variables |
+| `metadata.milaidy.requires.config` | Required config paths (truthy) |
+| `metadata.milaidy.primaryEnv` | Associated API key name |
+| `metadata.milaidy.emoji` | Display emoji |
+| `metadata.milaidy.homepage` | Website URL |
+| `metadata.milaidy.install` | Installer specifications |
+
+### Example with Full Metadata
+
+```markdown
+---
+name: gemini-cli
+description: Use Gemini CLI for coding assistance
+metadata:
+  {
+    "milaidy":
+      {
+        "emoji": "♊️",
+        "requires": { "bins": ["gemini"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "gemini-cli",
+              "bins": ["gemini"],
+              "label": "Install Gemini CLI (brew)",
+            },
+          ],
+      },
+  }
+---
+```
+
+## Configuration
+
+### Enable/Disable Skills
+
+```json
+{
+  "skills": {
+    "entries": {
+      "my-skill": {
+        "enabled": true,
+        "apiKey": "MY_KEY_HERE",
+        "env": {
+          "MY_API_KEY": "MY_KEY_HERE"
+        },
+        "config": {
+          "endpoint": "https://api.example.com"
+        }
+      },
+      "disabled-skill": {
+        "enabled": false
+      }
+    }
+  }
+}
+```
+
+### Config Fields
+
+| Field | Description |
+|-------|-------------|
+| `enabled` | Enable/disable the skill |
+| `apiKey` | Convenience for `primaryEnv` |
+| `env` | Environment variables to inject |
+| `config` | Custom per-skill configuration |
+
+### Bundled Skills Allowlist
+
+Restrict which bundled skills load:
+
+```json
+{
+  "skills": {
+    "allowBundled": ["skill-a", "skill-b"]
+  }
+}
+```
+
+## Environment Injection
+
+When an agent run starts:
+
+1. Reads skill metadata
+2. Applies `skills.entries.<key>.env` and `apiKey` to `process.env`
+3. Builds system prompt with eligible skills
+4. Restores original environment after run
+
+This is **scoped to the agent run**, not global.
+
+## Plugin Skills
+
+Plugins can ship skills via their manifest:
+
+```json
+{
+  "id": "my-plugin",
+  "skills": ["skills/tool-a", "skills/tool-b"]
+}
+```
+
+Plugin skills:
+- Load when the plugin is enabled
+- Participate in normal precedence rules
+- Can be gated via plugin config
+
+## ClawHub
+
+Browse and install skills from [ClawHub](https://clawhub.com):
+
+```bash
+# Install a skill
+clawhub install <skill-slug>
+
+# Update all skills
+clawhub update --all
+
+# Sync (scan + publish)
+clawhub sync --all
+```
+
+Default install location: `./skills` (workspace skills).
+
+## Skills Watcher
+
+Auto-reload skills when files change:
+
+```json
+{
+  "skills": {
+    "load": {
+      "watch": true,
+      "watchDebounceMs": 250
+    }
+  }
+}
+```
+
+## Session Snapshot
+
+Skills are snapshotted when a session starts and reused for subsequent turns.
+Changes take effect on the next new session (or via hot reload when watching).
+
+## Remote Nodes
+
+If a Linux Gateway has a connected macOS node with `system.run` allowed,
+macOS-only skills become eligible. The agent executes these via `nodes.run`.
+
+## Token Impact
+
+Skills add to the system prompt:
+
+- **Base overhead:** ~195 characters (when ≥1 skill)
+- **Per skill:** ~97 characters + name + description + location
+
+Rough estimate: ~24 tokens per skill plus field content.
+
+## Dependency Installation
+
+### Install Specifications
+
+```json
+{
+  "install": [
+    {
+      "id": "brew",
+      "kind": "brew",
+      "formula": "tool-name",
+      "bins": ["tool-name"],
+      "label": "Install via Homebrew"
+    },
+    {
+      "id": "npm",
+      "kind": "node",
+      "package": "@scope/tool",
+      "bins": ["tool-name"],
+      "label": "Install via npm"
+    },
+    {
+      "id": "download",
+      "kind": "download",
+      "url": "https://example.com/tool.tar.gz",
+      "archive": "tar.gz",
+      "targetDir": "~/.milaidy/tools/tool-name"
+    }
+  ]
+}
+```
+
+### Install Kinds
+
+| Kind | Description |
+|------|-------------|
+| `brew` | Homebrew formula |
+| `node` | npm/pnpm package |
+| `go` | Go install |
+| `uv` | Python uv |
+| `download` | Direct download |
+
+### Node Manager
+
+Set the node package manager for skill installs:
+
+```json
+{
+  "skills": {
+    "install": {
+      "nodeManager": "pnpm"
+    }
+  }
+}
+```
+
+Options: `npm`, `pnpm`, `yarn`, `bun` (npm default)
+
+## Sandboxing Notes
+
+Binary requirements (`requires.bins`) are checked on the **host** at load time.
+
+For sandboxed agents, binaries must also exist **inside the container**:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "sandbox": {
+        "docker": {
+          "setupCommand": "apt-get install -y tool-name"
+        }
+      }
+    }
+  }
+}
+```
+
+## Security
+
+- **Treat third-party skills as untrusted code**
+- Skills with `env` inject into the host process
+- Use sandboxed runs for risky tools
+- Keep secrets out of prompts and logs
+
+## Creating Skills
+
+### Basic Structure
+
+```
+my-skill/
+├── SKILL.md          # Required
+├── scripts/          # Optional helper scripts
+└── templates/        # Optional templates
+```
+
+### SKILL.md Template
+
+```markdown
+---
+name: my-skill
+description: Short description of what this skill does
+metadata: {"milaidy": {"requires": {"env": ["MY_API_KEY"]}, "primaryEnv": "MY_API_KEY"}}
+---
+
+## Overview
+
+This skill enables the agent to...
+
+## Usage
+
+Use this skill when you need to...
+
+## Examples
+
+Example invocation:
+- "Do X with Y"
+- "Create Z for me"
+
+## Configuration
+
+The skill requires the following:
+- `MY_API_KEY`: API key for the service
+
+## Notes
+
+- Additional notes about behavior
+- Limitations or caveats
+```
+
+## Related Docs
+
+- [Skills Config](/tools/skills-config) - Full configuration schema
+- [ClawHub](/tools/clawhub) - Skills registry
+- [Creating Skills](/tools/creating-skills) - Development guide
+- [Plugins](/concepts/plugins) - Plugin-provided skills
+- [Security](/gateway/security) - Security considerations