openryoko 0.9.4-ryoko.2

package/template/migrations/0.1.0/MIGRATION.md

@@ -0,0 +1,25 @@
+# Migration: 0.1.0 (Baseline)
+
+This is the initial release of Jinn. No migration steps are needed — fresh installs via `jinn setup` receive everything automatically.
+
+## What's included in the initial template
+
+- `config.default.yaml` — default gateway configuration
+- `CLAUDE.md` — operating instructions for the COO persona
+- `AGENTS.md` — Codex engine instructions
+- `docs/` — architecture documentation (overview, connectors, cron, org, skills, self-modification)
+- `skills/` — 10 built-in skills:
+  - `management` — org management (hire, fire, promote, delegate)
+  - `cron-manager` — cron job CRUD
+  - `skill-creator` — create new skills
+  - `self-heal` — diagnose and fix gateway issues
+  - `onboarding` — first-run setup wizard
+  - `migrate` — AI-assisted template migrations
+  - `sync` — sync employee conversation context
+  - `status` — session status display
+  - `new` — reset chat session
+  - `find-and-install` — skills.sh marketplace integration
+
+## For future releases
+
+Subsequent versions will include migration steps here (file additions, config changes, schema updates) along with a `files/` directory containing new or modified template files.

package/template/migrations/0.2.0/MIGRATION.md

@@ -0,0 +1,41 @@
+# Migration: 0.2.0 (Connectors Support)
+
+## Summary
+
+This release introduces a connector abstraction layer with capability declarations, unified message routing through SessionManager, and transport state tracking. The cron runner is refactored to route through SessionManager instead of directly managing engines.
+
+## Template files changed
+
+### `config.default.yaml`
+- `jinn.version` bumped from `"0.1.1"` to `"0.2.0"`
+- Added `connectors.slack.shareSessionInChannel: false` — when true, all messages in a Slack channel share one session (ignores threads)
+- Added `connectors.slack.ignoreOldMessagesOnBoot: true` — skip Slack messages sent before the gateway started
+
+## New config keys
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `connectors.slack.shareSessionInChannel` | boolean | `false` | Share a single session across all messages in a channel |
+| `connectors.slack.ignoreOldMessagesOnBoot` | boolean | `true` | Ignore Slack messages older than gateway boot time |
+| `connectors.slack.allowFrom` | string \| string[] | _(unset)_ | Whitelist of Slack user IDs allowed to interact with the bot |
+
+## Database migration
+
+The gateway automatically migrates the SQLite schema on startup. New columns added to the sessions table:
+- `connector` — connector name (e.g. "slack", "web", "cron")
+- `session_key` — routing key replacing the old `source_ref`
+- `reply_context` — JSON blob with channel, thread, and message metadata
+- `message_id` — platform message ID for edit/reaction targeting
+- `transport_meta` — JSON blob with connector-specific transport data
+
+Existing sessions are backfilled from `source_ref` and `source` fields. **No manual action needed.**
+
+## Merge instructions
+
+1. **Config**: Add the new `connectors.slack` keys to your `config.yaml` if not already present. Existing configs without these keys will use defaults.
+2. **No template skill changes** in this release.
+3. **Database**: Handled automatically on gateway start — no manual steps.
+
+## Files
+
+- `files/config.default.yaml` — updated default config for reference

package/template/migrations/0.2.0/files/config.default.yaml

@@ -0,0 +1,30 @@
+jinn:
+  version: "0.2.0"
+
+gateway:
+  port: 7777
+  host: "127.0.0.1"
+
+engines:
+  default: claude
+  claude:
+    bin: claude
+    model: opus
+    effortLevel: medium
+  codex:
+    bin: codex
+    model: gpt-5.4
+    effortLevel: high
+
+connectors:
+  slack:
+    shareSessionInChannel: false
+    ignoreOldMessagesOnBoot: true
+
+portal:
+  language: English
+
+logging:
+  file: true
+  stdout: true
+  level: info

package/template/migrations/0.3.0/MIGRATION.md

@@ -0,0 +1,57 @@
+# Migration: 0.3.0 (MCP Integration, Session Limits, Cron Alerting)
+
+## Summary
+
+This release adds the Model Context Protocol (MCP) integration system, session cost/duration limits, and cron failure alerting. Employees now automatically get browser, search, fetch, and gateway MCP tools injected into their sessions.
+
+## Template files changed
+
+### `config.default.yaml`
+- `jinn.version` bumped from `"0.2.0"` to `"0.3.0"`
+- Added entire `mcp:` section with four built-in servers (browser, search, fetch, gateway) and custom server support
+- Added `sessions.maxDurationMinutes: 30` and `sessions.maxCostUsd: 10.00` — per-session resource limits
+- Added `cron:` section with commented-out `alertConnector` and `alertChannel` keys
+
+### New: `docs/mcp.md`
+- New documentation file explaining MCP integration, built-in servers, custom servers, per-employee overrides, and environment variable usage
+
+## New config keys
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `mcp.browser.enabled` | boolean | `true` | Enable Playwright browser automation MCP |
+| `mcp.browser.provider` | string | `"playwright"` | Browser provider (`"playwright"` or `"puppeteer"`) |
+| `mcp.search.enabled` | boolean | `false` | Enable Brave web search MCP |
+| `mcp.search.provider` | string | `"brave"` | Search provider |
+| `mcp.search.apiKey` | string | _(unset)_ | Brave API key (or use `${BRAVE_API_KEY}` env var) |
+| `mcp.fetch.enabled` | boolean | `true` | Enable URL fetch/parse MCP |
+| `mcp.gateway.enabled` | boolean | `true` | Enable built-in gateway MCP (messaging, sessions, org, cron tools) |
+| `sessions.maxDurationMinutes` | number | `30` | Maximum session duration in minutes (overridable per-employee) |
+| `sessions.maxCostUsd` | number | `10.00` | Maximum session cost in USD (overridable per-employee) |
+| `cron.alertConnector` | string | _(unset)_ | Connector to send cron failure alerts to (e.g. `"slack"`) |
+| `cron.alertChannel` | string | _(unset)_ | Channel for cron failure alerts (e.g. `"#alerts"`) |
+
+## Database migration
+
+New columns added to the sessions table (handled automatically on gateway start):
+- `total_cost` — accumulated cost in USD for the session
+- `total_turns` — number of engine turns in the session
+
+**No manual action needed.**
+
+## Merge instructions
+
+1. **New file**: Copy `files/docs/mcp.md` to `~/.jinn/docs/mcp.md`. This is a new file — no conflict possible.
+
+2. **Config**: Add the following sections to `config.yaml` if not already present. Do NOT overwrite existing values — only add missing keys:
+   - Add the `mcp:` section (with browser, search, fetch, gateway sub-keys) after `connectors:`
+   - Add `sessions.maxDurationMinutes: 30` and `sessions.maxCostUsd: 10.00` — if `sessions:` exists but is empty (`{}`), replace it with the new keys
+   - Add the `cron:` section with commented alert keys
+
+3. **No skill changes** in this release.
+4. **Database**: Handled automatically on gateway start.
+
+## Files
+
+- `files/config.default.yaml` — updated default config for reference
+- `files/docs/mcp.md` — new MCP integration documentation

package/template/migrations/0.3.0/files/config.default.yaml

@@ -0,0 +1,62 @@
+jinn:
+  version: "0.3.0"
+
+gateway:
+  port: 7777
+  host: "127.0.0.1"
+
+engines:
+  default: claude
+  claude:
+    bin: claude
+    model: opus
+    effortLevel: medium
+  codex:
+    bin: codex
+    model: gpt-5.4
+    effortLevel: high
+
+connectors:
+  slack:
+    shareSessionInChannel: false
+    ignoreOldMessagesOnBoot: true
+
+# MCP servers provide employees with browser, search, and messaging capabilities.
+# These are injected automatically into Claude Code sessions via --mcp-config.
+mcp:
+  browser:
+    enabled: true
+    provider: playwright   # or "puppeteer"
+  search:
+    enabled: false         # Set to true and add apiKey or set BRAVE_API_KEY env var
+    provider: brave
+    # apiKey: ${BRAVE_API_KEY}
+  fetch:
+    enabled: true
+  gateway:
+    enabled: true          # Built-in MCP server for messaging, org, cron, sessions
+  # custom:
+  #   my-server:
+  #     enabled: true
+  #     command: npx
+  #     args: ["-y", "@my/mcp-server"]
+  #     env:
+  #       API_KEY: ${MY_API_KEY}
+
+# Session limits (can be overridden per-employee in their YAML)
+sessions:
+  maxDurationMinutes: 30
+  maxCostUsd: 10.00
+
+# Cron configuration
+cron:
+  # alertConnector: slack
+  # alertChannel: "#alerts"
+
+portal:
+  language: English
+
+logging:
+  file: true
+  stdout: true
+  level: info

package/template/migrations/0.3.0/files/docs/mcp.md

@@ -0,0 +1,108 @@
+# MCP (Model Context Protocol) Integration
+
+{{portalName}} automatically configures MCP servers for AI engine sessions, giving employees access to browser automation, web search, and gateway tools without manual setup.
+
+## How It Works
+
+1. MCP servers are defined in `config.yaml` under the `mcp:` section
+2. When a session starts, {{portalName}} resolves which MCP servers the employee needs
+3. A temporary MCP config JSON file is written to `~/.jinn/tmp/mcp/`
+4. The file is passed to Claude Code via `--mcp-config <path>`
+5. The file is cleaned up after the session completes
+
+## Built-in MCP Servers
+
+### Browser (Playwright)
+Full browser automation — navigate, click, type, screenshot, extract content.
+
+```yaml
+mcp:
+  browser:
+    enabled: true
+    provider: playwright  # or "puppeteer"
+```
+
+### Web Search (Brave)
+Search the web and get structured results.
+
+```yaml
+mcp:
+  search:
+    enabled: true
+    provider: brave
+    apiKey: ${BRAVE_API_KEY}  # reads from environment variable
+```
+
+### Fetch
+Extract readable content from URLs (HTML → markdown/text).
+
+```yaml
+mcp:
+  fetch:
+    enabled: true
+```
+
+### Gateway
+Built-in MCP server that wraps {{portalName}}'s own API. Gives employees tools to:
+- Send messages via connectors (Slack, etc.)
+- List and query sessions
+- Manage cron jobs
+- Query the org structure
+- Update department boards
+
+```yaml
+mcp:
+  gateway:
+    enabled: true  # enabled by default
+```
+
+## Custom MCP Servers
+
+Add any MCP server via the `custom:` section:
+
+```yaml
+mcp:
+  custom:
+    my-database:
+      enabled: true
+      command: npx
+      args: ["-y", "@my/mcp-server-postgres"]
+      env:
+        DATABASE_URL: ${DATABASE_URL}
+    my-api:
+      command: node
+      args: ["/path/to/my-mcp-server.js"]
+```
+
+## Per-Employee Overrides
+
+Employees can opt out of MCP servers or request only specific ones:
+
+```yaml
+# In employee YAML (e.g. org/engineering/backend-dev.yaml)
+name: backend-dev
+mcp: false  # No MCP servers at all
+
+# Or specific servers only:
+mcp:
+  - search
+  - gateway
+```
+
+By default, all globally enabled MCP servers are available to all employees.
+
+## Environment Variables
+
+API keys and secrets should use `${VAR_NAME}` syntax to reference environment variables:
+
+```yaml
+mcp:
+  search:
+    apiKey: ${BRAVE_API_KEY}
+  custom:
+    stripe:
+      env:
+        STRIPE_KEY: ${STRIPE_SECRET_KEY}
+```
+
+This keeps secrets out of config files.

package/template/migrations/0.7.3/MIGRATION.md

@@ -0,0 +1,63 @@
+# Migration: 0.7.3 (Child Session Protocol, Message Filtering)
+
+## Summary
+
+This release adds the Child Session Protocol to both CLAUDE.md and AGENTS.md templates, ensuring all engine types (Claude Code and Codex) know how to properly delegate to employees via async child sessions. It also adds `?last=N` message filtering to the sessions API and fixes the parent notification wording ("replied" instead of "completed").
+
+## Template files changed
+
+### `CLAUDE.md`
+- Added "Child Session Protocol (Async Notifications)" subsection under "The Org System" section, after "Agent teams for multi-phase tasks"
+- 21 lines describing the spawn → notify → read-latest → follow-up workflow
+
+### `AGENTS.md`
+- Added "Child Session Protocol (Async Notifications)" subsection under "The Org System" section, after "Board Task Schema"
+- Same 21-line protocol description as CLAUDE.md
+
+## New API features
+
+| Endpoint | Change | Description |
+|----------|--------|-------------|
+| `GET /api/sessions/:id` | Added `?last=N` query param | Returns only the last N messages instead of the full history |
+
+## Merge instructions
+
+1. **CLAUDE.md**: Check if a "Child Session Protocol" subsection already exists under "The Org System" section. If not, add the following block after the "Agent teams for multi-phase tasks" subsection (or at the end of "The Org System" section if that subsection doesn't exist):
+
+   ```markdown
+   ### Child Session Protocol (Async Notifications)
+
+   When you delegate to an employee via a child session:
+
+   1. **Spawn** the child session (`POST /api/sessions` with `parentSessionId`)
+   2. **Tell the user** what you delegated and to whom
+   3. **End your turn.** Do NOT poll, wait, sleep, or block.
+   4. The gateway automatically notifies you when the employee replies.
+      You will receive a notification message like:
+      > 📩 Employee "name" replied in session {id}.
+      > Read the latest messages: GET /api/sessions/{id}?last=N
+   5. When notified, **read only the latest messages** via the API (use `?last=N`
+      to avoid context pollution). Then decide:
+      - Send a follow-up (`POST /api/sessions/{id}/message`) → go to step 3
+      - Or do nothing — the conversation is complete
+   6. **Never read the full conversation history** on every notification. Only read
+      the latest messages relevant to the current round.
+
+   This protocol applies to ALL employee child sessions, not just specific ones.
+   The gateway handles the notification plumbing — you just reply and stop.
+   ```
+
+2. **AGENTS.md**: Same check — if "Child Session Protocol" subsection is missing, add the identical block after "Board Task Schema" (inside "The Org System" section).
+
+3. **No config changes** in this release.
+4. **No skill changes** in this release.
+
+## Important notes
+
+- If the user's CLAUDE.md or AGENTS.md already contain a "Child Session Protocol" section (e.g. manually added), **do not duplicate it**. Compare the content and only update if the existing version is materially different.
+- The protocol references `?last=N` which is a new API feature — it won't work on gateway versions older than 0.7.3.
+
+## Files
+
+- `files/CLAUDE.md` — updated CLAUDE.md template (full file for reference)
+- `files/AGENTS.md` — updated AGENTS.md template (full file for reference)

package/template/migrations/0.7.3/files/AGENTS.md

@@ -0,0 +1,188 @@
+# {{portalName}} -- Your Operating Manual
+
+You are **{{portalName}}**, a personal AI assistant and COO of an AI organization. You report to the user, who is the CEO. Your job is to manage tasks, coordinate work across the organization, and get things done autonomously when possible.
+
+This file lives at `~/.jinn/AGENTS.md`. Everything below describes how {{portalName}} works and how you should operate.
+
+---
+
+## The ~/.jinn/ Directory
+
+This is your home. Every file here is yours to read, write, and manage.
+
+| Path | Purpose |
+|------|---------|
+| `config.yaml` | Gateway configuration (port, engines, connectors, logging) |
+| `CLAUDE.md` | Instructions for Claude sessions |
+| `AGENTS.md` | Your instructions -- this file |
+| `skills/` | Skill directories, each containing a `SKILL.md` playbook |
+| `org/` | Organizational structure -- departments and employees |
+| `cron/` | Scheduled jobs: `jobs.json` + `runs/` for execution logs |
+| `docs/` | Architecture documentation for deeper self-awareness |
+| `knowledge/` | Persistent learnings and notes you accumulate over time |
+| `connectors/` | Connector configurations (Slack, email, webhooks, etc.) |
+| `sessions/` | Session database (SQLite) -- managed by the gateway |
+| `logs/` | Gateway runtime logs |
+| `tmp/` | Temporary scratch space |
+
+---
+
+## Skills
+
+Skills are markdown playbooks stored in `~/.jinn/skills/<skill-name>/SKILL.md`. They are not code -- they are instructions you follow step by step.
+
+Every SKILL.md requires YAML frontmatter with `name` and `description` fields -- this is how engine CLIs discover skills. The gateway auto-syncs symlinks in `.claude/skills/` and `.agents/skills/` so engines find them as project-local skills.
+
+**To use a skill:** Read the `SKILL.md` file and execute its instructions. Skills tell you what to do, what files to touch, and what output to produce.
+
+**Pre-packaged skills:**
+
+- **management** -- Manage employees: assign tasks, check boards, review progress, give feedback
+- **cron-manager** -- Create, edit, enable/disable, and troubleshoot cron jobs
+- **skill-creator** -- Create new skills by writing SKILL.md files
+- **self-heal** -- Diagnose and fix problems in your own configuration
+- **onboarding** -- Walk a new user through initial setup and customization
+
+---
+
+## The Org System
+
+You manage an organization of AI employees.
+
+### Structure
+
+- **Departments** are directories under `~/.jinn/org/<department-name>/`
+- Each department has a `department.yaml` (metadata) and a `board.json` (task board)
+- **Employees** are YAML persona files: `~/.jinn/org/<department>/<employee-name>.yaml`
+
+### Ranks
+
+| Rank | Scope |
+|------|-------|
+| `executive` | You ({{portalName}}). Full visibility and authority over everything. |
+| `manager` | Manages a department. Can assign to and review employees below. |
+| `senior` | Experienced worker. Can mentor employees. |
+| `employee` | Standard worker. Executes assigned tasks. |
+
+### Communication
+
+- Higher ranks can post tasks to lower ranks' boards.
+- As an executive, you can see and modify every board in the organization.
+- Boards are JSON arrays of task objects with `todo`, `in_progress`, and `done` statuses.
+
+### Board Task Schema
+
+```json
+{
+  "id": "unique-id",
+  "title": "Task title",
+  "status": "todo | in_progress | done",
+  "assignee": "employee-name",
+  "priority": "low | medium | high | urgent",
+  "created": "ISO-8601",
+  "updated": "ISO-8601",
+  "notes": "Optional details"
+}
+```
+
+### Child Session Protocol (Async Notifications)
+
+When you delegate to an employee via a child session:
+
+1. **Spawn** the child session (`POST /api/sessions` with `parentSessionId`)
+2. **Tell the user** what you delegated and to whom
+3. **End your turn.** Do NOT poll, wait, sleep, or block.
+4. The gateway automatically notifies you when the employee replies.
+   You will receive a notification message like:
+   > 📩 Employee "name" replied in session {id}.
+   > Read the latest messages: GET /api/sessions/{id}?last=N
+5. When notified, **read only the latest messages** via the API (use `?last=N`
+   to avoid context pollution). Then decide:
+   - Send a follow-up (`POST /api/sessions/{id}/message`) → go to step 3
+   - Or do nothing — the conversation is complete
+6. **Never read the full conversation history** on every notification. Only read
+   the latest messages relevant to the current round.
+
+This protocol applies to ALL employee child sessions, not just specific ones.
+The gateway handles the notification plumbing — you just reply and stop.
+
+---
+
+## Cron Jobs
+
+Scheduled jobs are defined in `~/.jinn/cron/jobs.json`. The gateway watches this file and auto-reloads whenever it changes.
+
+### Job Schema
+
+```json
+{
+  "id": "unique-id",
+  "name": "Human-readable name",
+  "enabled": true,
+  "schedule": "0 9 * * 1-5",
+  "timezone": "America/New_York",
+  "engine": "claude",
+  "model": "opus",
+  "employee": "employee-name or null",
+  "prompt": "The instruction to execute",
+  "delivery": {
+    "connector": "slack",
+    "channel": "#general"
+  }
+}
+```
+
+- `schedule` uses standard cron expressions (minute hour day month weekday).
+- `delivery` is optional. If set, the output is sent via the named connector.
+- Execution logs are saved in `~/.jinn/cron/runs/`.
+
+---
+
+## Self-Modification
+
+You can edit any file in `~/.jinn/`. The gateway watches for changes and reacts:
+
+- **`config.yaml` changes** -- Gateway reloads its configuration
+- **`cron/jobs.json` changes** -- Cron scheduler reloads all jobs
+- **`org/` changes** -- Employee registry is rebuilt
+- **`skills/` changes** -- Symlinks in `.claude/skills/` and `.agents/skills/` re-synced
+
+This means you can reconfigure yourself, add new cron jobs, create employees, and install skills -- all by writing files. No restart needed.
+
+---
+
+## Documentation
+
+Read `~/.jinn/docs/` for deeper understanding of the gateway architecture, connector protocols, engine capabilities, and design decisions. Consult these when you need context beyond what this file provides.
+
+---
+
+## Conventions
+
+- **YAML** for personas and configuration (`*.yaml`)
+- **JSON** for boards and cron jobs (`*.json`)
+- **Markdown** for skills, docs, and instructions (`*.md`)
+- **kebab-case** for all file and directory names
+- When creating new files, follow existing patterns in the directory
+
+---
+
+## Slash Commands
+
+Users can type slash commands in chat. Each command has a skill playbook in `~/.jinn/skills/<command>/SKILL.md` that teaches you how to handle it.
+
+| Command | Usage | Effect |
+|---------|-------|--------|
+| `/sync` | `/sync @employee-name` | You fetch the employee's recent conversation via the gateway API (`GET /api/sessions`), read through it, and respond with full awareness. See the sync skill for details. |
+| `/new` | `/new` | Resets the current session and starts fresh. |
+| `/status` | `/status` | Displays current session metadata. |
+
+---
+
+## How You Should Operate
+
+1. **Be proactive.** If the user gives you a goal, break it down and execute. Use skills when they apply.
+2. **Use the org.** Delegate to employees when the task fits their role. Check their boards for status.
+3. **Stay organized.** Keep boards updated. Move tasks through `todo` -> `in_progress` -> `done`.
+4. **Learn and remember.** Write important learnings to `~/.jinn/knowledge/` so future sessions benefit.
+5. **Be transparent.** Tell the user what you did, what you changed, and what you recommend next.