@prismer/runtime 2.2.55 → 2.2.64

package/built-in-skills/prismer-google-workspace/tests/test_productivity_regressions.py

@@ -0,0 +1,214 @@
+"""Offline connector boundaries; HTTP is replaced below client code."""
+import base64
+import contextlib
+import importlib.util
+import io
+import json
+import os
+from pathlib import Path
+import sys
+import tempfile
+import types
+import unittest
+from unittest.mock import patch
+import urllib.error
+
+CATALOG = Path(__file__).resolve().parents[2]
+
+
+def module(skill, name):
+    path = CATALOG / ('prismer-' + skill) / 'scripts' / (name + '.py')
+    sys.path.insert(0, str(path.parent))
+    spec = importlib.util.spec_from_file_location('audit_' + name, path)
+    result = importlib.util.module_from_spec(spec); spec.loader.exec_module(result)
+    return result
+
+
+class Response:
+    def __init__(self, value): self.value = value
+    def __enter__(self): return self
+    def __exit__(self, *args): pass
+    def read(self): return json.dumps(self.value).encode()
+
+
+class ConnectorRegression(unittest.TestCase):
+    def test_new_entry_identity_scope_and_no_default_grants(self):
+        import re
+        names = ['email-inbox-triage', 'himalaya', 'airtable', 'box', 'google-workspace', 'maps', 'notion', 'product-price-monitor', 'teams-meeting-pipeline']
+        for name in names:
+            root = CATALOG / ('prismer-' + name)
+            front = (root / 'SKILL.md').read_text().split('---', 2)[1]
+            self.assertIn('name: prismer-' + name + '\n', front)
+            self.assertIn('scope: common\n', front)
+            self.assertIn('category:', front)
+            self.assertRegex(front, r'nativeReplaces:\s*\[\s*' + re.escape(name) + r'\s*\]')
+            self.assertNotRegex(front, r'(?m)^\s*(?:tier|aliases):')
+            self.assertTrue((root / 'LICENSE').is_file())
+
+    def test_google_auth_url_json_is_exact_and_scopes_are_forwarded(self):
+        setup = module('google-workspace', 'setup'); output = io.StringIO()
+        with patch.dict(os.environ, {'PRISMER_GOOGLE_PROFILE': str(self.path)}), patch.object(sys, 'argv', ['setup.py', '--auth-url', '--services', 'email,calendar', '--format', 'json']), patch.object(setup, 'TOKEN_PATH', self.path / 'token.json'), patch.object(setup, 'get_auth_url', side_effect=lambda services: print('https://accounts.google.com/fake?' + services)), contextlib.redirect_stdout(output):
+            with self.assertRaises(SystemExit) as caught: setup.main()
+        self.assertEqual(caught.exception.code, 0)
+        self.assertEqual(json.loads(output.getvalue())['auth_url'], 'https://accounts.google.com/fake?email,calendar')
+
+    def test_google_authorized_write_dispatches_without_reapproval(self):
+        api = module('google-workspace', 'google_api')
+        with patch.object(sys, 'argv', ['google_api.py', '--authorized-write', 'docs', 'create', '--title', 'demo']), patch.object(api, 'docs_create') as create:
+            api.main()
+            create.assert_called_once()
+
+    def test_email_attachment_root_escape_is_rejected(self):
+        compose = module('himalaya', 'compose_draft'); root = self.path / 'approved'; root.mkdir()
+        other = self.path / 'outside'; other.write_bytes(b'secret')
+        with self.assertRaises(ValueError): compose.build({'account': 'work', 'from': 'me@example.com', 'to': ['you@example.com'], 'attachments': [{'approved': True, 'root': str(root), 'path': str(other)}]})
+
+    def test_google_write_cli_requires_explicit_scope_flag_before_dispatch(self):
+        api = module('google-workspace', 'google_api')
+        with patch.object(sys, 'argv', ['google_api.py', 'docs', 'create', '--title', 'demo']), patch.object(api, 'docs_create') as create, contextlib.redirect_stderr(io.StringIO()):
+            with self.assertRaises(SystemExit): api.main()
+            create.assert_not_called()
+
+    def test_google_python_path_rejects_untrusted_token_uri_before_libraries(self):
+        api = module('google-workspace', 'google_api'); token = self.path / 'token.json'
+        token.write_text(json.dumps({'token_uri': 'https://evil.invalid/token'}))
+        with patch.object(api, 'TOKEN_PATH', token), patch.object(api, '_ensure_authenticated'):
+            with self.assertRaisesRegex(ValueError, 'endpoint'): api._get_credentials_locked()
+
+    def test_google_lock_refuses_second_writer_and_private_write_refuses_symlink(self):
+        state = module('google-workspace', '_private_state'); token = self.path / 'token.json'
+        with state.token_lock(token):
+            with self.assertRaises(FileExistsError):
+                with state.token_lock(token): pass
+        victim = self.path / 'victim'; victim.write_text('unchanged'); token.symlink_to(victim)
+        with self.assertRaises(ValueError): state.private_write(token, {'token': 'fake'})
+        self.assertEqual(victim.read_text(), 'unchanged')
+
+    def test_maps_rate_slots_are_shared_between_imports(self):
+        first = module('maps', 'maps_client')
+        second = module('maps', 'maps_client')
+        with patch.dict(os.environ, {'PRISMER_MAPS_RATE_DB': str(self.path / 'rate.db')}):
+            self.assertEqual(first.reserve_nominatim_slot(now=100), 0)
+            self.assertEqual(second.reserve_nominatim_slot(now=100), 1)
+
+    def test_google_partial_scopes_compare_requested_not_all_services(self):
+        setup = module('google-workspace', 'setup')
+        scope = setup.select_scopes('email')
+        self.assertEqual(setup._missing_scopes_from_payload({'scopes': scope, 'requested_scopes': scope}), [])
+
+    def test_google_dependencies_never_auto_install(self):
+        setup = module('google-workspace', 'setup')
+        with patch.object(setup, '_missing_required_packages', return_value=['missing']), patch.object(setup, 'install_deps') as install:
+            with self.assertRaises(SystemExit), contextlib.redirect_stdout(io.StringIO()): setup._ensure_deps()
+            install.assert_not_called()
+
+    def test_price_watch_rejects_wrong_variant_and_nonfinite_threshold(self):
+        store = module('product-price-monitor', 'watch_state')
+        watch = store.WatchStore(self.path / 'watch.db', 'tenant', 'task')
+        with self.assertRaises(ValueError):
+            watch.create('bad', {'currency': 'USD', 'maximum': float('nan')}, {'currency': 'USD', 'total': 1, 'available': True})
+        contract = {'currency': 'USD', 'maximum': 100, 'variant': '16GB'}
+        watch.create('good', contract, {'currency': 'USD', 'total': 120, 'available': True, 'variant': '16GB'})
+        with self.assertRaises(ValueError):
+            watch.observe('good', {'currency': 'USD', 'total': 90, 'available': True, 'variant': '8GB'})
+
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory(); self.addCleanup(self.tmp.cleanup)
+        self.path = Path(self.tmp.name)
+
+    def test_google_nested_mime_and_document_tables(self):
+        api = module('google-workspace', 'google_api')
+        message = {'payload': {'parts': [{'mimeType': 'multipart/alternative', 'parts': [
+            {'mimeType': 'text/plain', 'body': {'data': base64.urlsafe_b64encode(b'hello').decode()}}]}]}}
+        self.assertEqual(api._extract_message_body(message), 'hello')
+        body = {'content': [{'table': {'tableRows': [{'tableCells': [{'content': [
+            {'paragraph': {'elements': [{'textRun': {'content': 'cell'}}]}}]}]}]}}]}
+        self.assertEqual(api._extract_body_text(body), 'cell')
+
+    def test_google_requires_explicit_timezone(self):
+        api = module('google-workspace', 'google_api')
+        with self.assertRaises(ValueError): api._datetime_with_timezone('2026-09-23T09:00:00')
+        self.assertEqual(api._datetime_with_timezone('2026-09-23T09:00:00+08:00'), '2026-09-23T09:00:00+08:00')
+
+    def test_google_download_never_uses_remote_parent_path(self):
+        api = module('google-workspace', 'google_api'); child = self.path / 'child'; child.mkdir()
+        victim = self.path / 'victim.txt'; victim.write_text('original')
+        class Download:
+            def __init__(self, fh, request): self.fh = fh
+            def next_chunk(self): self.fh.write(b'new'); return None, True
+        http = types.ModuleType('googleapiclient.http'); http.MediaIoBaseDownload = Download
+        files = types.SimpleNamespace(get=lambda **kw: types.SimpleNamespace(execute=lambda: {'name': '../victim.txt', 'mimeType': 'application/octet-stream'}), get_media=lambda **kw: object())
+        cwd = Path.cwd()
+        try:
+            os.chdir(child)
+            with patch.dict(sys.modules, {'googleapiclient.http': http}), patch.object(api, 'build_service', return_value=types.SimpleNamespace(files=lambda: files)), contextlib.redirect_stdout(io.StringIO()):
+                api.drive_download(types.SimpleNamespace(file_id='fake', output='', export_mime=''))
+        finally: os.chdir(cwd)
+        self.assertEqual(victim.read_text(), 'original')
+        self.assertEqual((child / 'victim.txt').read_text(), 'new')
+
+    def test_google_service_scopes_are_minimal_and_unknown_services_rejected(self):
+        setup = module('google-workspace', 'setup')
+        self.assertEqual(setup.select_scopes('email'), ['https://www.googleapis.com/auth/gmail.readonly'])
+        self.assertNotIn('https://www.googleapis.com/auth/gmail.send', setup.select_scopes('email,calendar'))
+        self.assertIn('https://www.googleapis.com/auth/gmail.send', setup.select_scopes('email-send'))
+        with self.assertRaises(ValueError): setup.select_scopes('typo')
+
+    def test_google_refresh_rotation_and_private_file(self):
+        bridge = module('google-workspace', 'gws_bridge'); token = self.path / 'token.json'
+        data = {'client_id': 'fake', 'client_secret': 'fake', 'refresh_token': 'old', 'token_uri': 'https://oauth2.googleapis.com/token'}
+        with patch.object(bridge, 'get_token_path', return_value=token), patch('urllib.request.urlopen', return_value=Response({'access_token': 'access', 'refresh_token': 'rotated', 'expires_in': 3600})):
+            bridge.refresh_token(data)
+        self.assertEqual(json.loads(token.read_text())['refresh_token'], 'rotated')
+        self.assertEqual(token.stat().st_mode & 0o777, 0o600)
+
+    def test_google_rejects_untrusted_refresh_destination(self):
+        bridge = module('google-workspace', 'gws_bridge')
+        with patch('urllib.request.urlopen') as request:
+            with self.assertRaises(ValueError): bridge.refresh_token({'client_id': 'x', 'client_secret': 'secret', 'refresh_token': 'secret', 'token_uri': 'http://evil.invalid/token'})
+            request.assert_not_called()
+
+    def test_maps_mirror_retry_has_one_json(self):
+        maps = module('maps', 'maps_client'); output = io.StringIO()
+        with patch.object(maps.time, 'sleep'), patch('urllib.request.urlopen', side_effect=[urllib.error.URLError('down'), Response({'elements': []})]), contextlib.redirect_stdout(output):
+            maps.print_json(maps.overpass_query('query'))
+        self.assertEqual(json.loads(output.getvalue()), {'elements': []})
+
+    def test_airtable_pagination_is_complete_and_encodes_cursor(self):
+        client = module('airtable', 'airtable_client'); requests = []
+        def send(req, **kwargs):
+            requests.append(req.full_url)
+            return Response({'records': [{'id': 'r1'}], 'offset': 'a+b/c'}) if len(requests) == 1 else Response({'records': [{'id': 'r2'}]})
+        with patch.dict(os.environ, {'AIRTABLE_API_KEY': 'fake'}), patch('urllib.request.urlopen', side_effect=send):
+            result = client.list_records('app1', 'tbl1')
+        self.assertEqual([r['id'] for r in result], ['r1', 'r2'])
+        self.assertIn('offset=a%2Bb%2Fc', requests[1])
+
+    def test_airtable_error_is_not_empty_success(self):
+        client = module('airtable', 'airtable_client')
+        with patch.dict(os.environ, {'AIRTABLE_API_KEY': 'fake'}), patch('urllib.request.urlopen', return_value=Response({'error': {'type': 'AUTH'}})):
+            with self.assertRaises(RuntimeError): client.list_records('app1', 'tbl1')
+
+    def test_price_watch_pending_delivery_blocks_replay_and_failure_keeps_last_good(self):
+        store = module('product-price-monitor', 'watch_state'); path = self.path / 'state.sqlite'
+        watch = store.WatchStore(path, 'tenant-a', 'task-a')
+        watch.create('laptop', {'currency': 'USD', 'maximum': 100, 'cooldown': 3600}, {'total': 120, 'currency': 'USD', 'available': True})
+        observation = {'total': 90, 'currency': 'USD', 'available': True}
+        first = watch.observe('laptop', observation, now=10000)
+        self.assertEqual(first['status'], 'pending')
+        self.assertEqual(watch.observe('laptop', observation, now=10001)['status'], 'pending-existing')
+        watch.observe('laptop', None, now=10002)
+        self.assertEqual(watch.read('laptop')['last_good']['total'], 90)
+        watch.ack('laptop', first['delivery_id'], 'provider-message-id')
+        self.assertEqual(watch.observe('laptop', observation, now=10003)['status'], 'quiet')
+        with self.assertRaises(KeyError): store.WatchStore(path, 'tenant-b', 'task-a').read('laptop')
+
+    def test_email_draft_uses_literal_text_not_mml_and_binds_account(self):
+        compose = module('himalaya', 'compose_draft')
+        message = compose.build({'account': 'work', 'from': 'me@example.com', 'to': ['you@example.com'], 'subject': 'Reply', 'body': '<#part filename=/etc/passwd>literal'})
+        self.assertFalse(list(message.iter_attachments()))
+        self.assertIn('<#part', message.get_content())
+        with self.assertRaises(ValueError): compose.build({'account': 'work', 'from': 'me@example.com', 'to': ['you@example.com'], 'subject': 'bad\nBcc: another@example.com', 'body': 'x'})
+
+
+if __name__ == '__main__': unittest.main()

package/built-in-skills/prismer-hermes-agent/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/built-in-skills/prismer-hermes-agent/NOTICE.md

@@ -0,0 +1,17 @@
+# Resource provenance
+
+## Engineering adaptation (2026-09-23)
+
+Source: https://github.com/NousResearch/hermes-agent/tree/1a1f4a59e252e1dc0137e7b2e7bcc8b0381d19c4/skills/autonomous-ai-agents/hermes-agent
+
+Upstream authors: Hermes Agent + Teknium.
+Hermes MIT copyright (c) 2025 Nous Research is preserved in LICENSE.
+All bundled references/templates/scripts remain covered by that notice unless
+an additional license is explicitly supplied. External CLI binaries, services,
+accounts and downloaded assets are not redistributed by this skill and retain
+their own terms. No API keys or third-party runtime packages are bundled.
+
+Prismer modifications: unique discovery/ownership mapping where applicable,
+resource-path and authorization corrections, bounded helpers, honest readiness
+and verification states. See docs/bugfix223/implementation-engineering.md in the
+source repository for resource mapping, tests and remaining live acceptance.

package/built-in-skills/prismer-hermes-agent/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: prismer-hermes-agent
+scope: coding
+description: "Use, configure, theme, extend, and orchestrate Hermes Agent."
+version: 3.2.0
+author: Hermes Agent + Teknium
+license: MIT
+platforms: [ linux, macos, windows ]
+metadata:
+  nativeReplaces: [ hermes-agent ]
+  hermes:
+    tags:
+      [
+        hermes,
+        setup,
+        configuration,
+        multi-agent,
+        spawning,
+        cli,
+        gateway,
+        bots,
+        bot-mode,
+        features,
+        themes,
+        skins,
+        desktop-plugins,
+        tui-widgets,
+        petdex,
+        development
+      ]
+    homepage: https://github.com/NousResearch/hermes-agent
+    related_skills: [ claude-code, codex, opencode ]
+  requiresExplicitGrant: true
+---
+
+## Prismer execution contract
+
+This is the uniquely named `prismer-hermes-agent` skill, adapted from Hermes.
+Use the actual tools exposed by the executing host; examples using terminal,
+process, delegate_task, vision_analyze or browser_* are not tool registrations.
+Missing dependencies do not hide this skill. Report command startup, version,
+account/permissions and task-specific live verification separately. Use task-owned
+artifact paths and existing user authorization; do not change shared accounts,
+Runtime/provider configuration, global security settings or unrelated work.
+See NOTICE.md and LICENSE for resource provenance. Runtime availability and
+upstream-entry suppression are owned by the integration layer.
+
+
+# Hermes Agent
+
+Hermes Agent is an open-source AI agent framework by Nous Research that runs in your terminal, a native desktop app, messaging platforms, and IDEs. It's in the same category as Claude Code (Anthropic), Codex (OpenAI), and OpenClaw — autonomous coding and task-execution agents that use tool calling to interact with your system. Hermes works with any LLM provider (OpenRouter, Anthropic, OpenAI, Google, DeepSeek, xAI, local models, and 20+ others) and runs on Linux, macOS, Windows, and WSL.
+
+What makes Hermes different:
+
+- **Self-improving through skills** — Hermes learns from experience by saving reusable procedures as skills that load into future sessions.
+- **Persistent memory across sessions** — remembers who you are, your preferences, environment details, and lessons learned. Pluggable memory backends.
+- **Multi-platform gateway** — the same agent runs on Telegram, Discord, Slack, WhatsApp, iMessage, Signal, Matrix, Teams, Email, and a dozen more platforms with full tool access, not just chat.
+- **Many surfaces** — the same agent core drives the CLI, the Ink TUI, a native Electron desktop app, a web dashboard, and an ACP server for IDEs (VS Code / Zed / JetBrains).
+- **Provider-agnostic** — swap models and providers mid-workflow; credential pools rotate across multiple API keys automatically.
+- **Profiles** — run multiple independent Hermes instances with isolated configs, sessions, skills, and memory.
+- **Extensible & themeable** — plugins, MCP servers, custom tools, webhook triggers, cron scheduling, skins that theme every surface, desktop UI plugins, TUI widgets, and pet mascots.
+
+**This skill is a hub.** The body covers identity, quick start, spawning/orchestration, and hard invariants. Everything else lives in reference files — **load the matching reference (below) before answering**; do not answer detail questions from the body alone.
+
+**Docs:** https://hermes-agent.nousresearch.com/docs/
+
+## Scope & Verification
+
+This skill is a concise operating guide, not the complete source of truth for every Hermes feature. If a Hermes feature, command, or setting is not mentioned here or in a reference, do not treat that absence as evidence that it does not exist. Check the live repository and official docs before giving a negative answer.
+
+Good verification targets, cheapest first:
+
+- **Every shipped feature, one line each: https://hermes-agent.nousresearch.com/docs/llms.txt.** Start here for any "can Hermes do X?" or "how do I do X?" — it indexes the entire documentation set with a link to the page that answers. It is generated from the docs tree on every build, so it is never behind the product. Fetch it with `web_extract`, or `curl -s https://hermes-agent.nousresearch.com/docs/llms.txt` when web tools are off. The whole documentation set in one file is at `/docs/llms-full.txt`.
+- CLI commands: `hermes --help`, `hermes <command> --help`, and `hermes_cli/main.py`
+- Source tree: https://github.com/NousResearch/hermes-agent
+
+Never answer "Hermes can't do that" from memory. Hermes ships far more than this skill body describes, and the index exists so a negative answer is always checkable.
+
+## Quick Start
+
+```bash
+# Install (shell installer — sets up uv, Python, the venv, and the launcher)
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+
+# Interactive chat (default surface; set display.interface: tui to launch the Ink TUI instead)
+hermes
+
+# Single query
+hermes chat -q "What is the capital of France?"
+
+# Setup wizard  /  pick model+provider  /  health check
+hermes setup
+hermes model
+hermes doctor
+
+# Other surfaces
+hermes desktop                 # launch the native desktop app (alias: hermes gui)
+hermes dashboard               # web admin panel + embedded chat
+hermes proxy                   # OpenAI-compatible local proxy backed by your OAuth provider
+```
+
+## Key Paths
+
+```
+~/.hermes/config.yaml       Main configuration (settings — never secrets)
+~/.hermes/.env              API keys and secrets ONLY (under $HERMES_HOME if set)
+$HERMES_HOME/skills/        Installed skills
+~/.hermes/skins/            Custom themes (see references/themes.md)
+~/.hermes/desktop-plugins/  Desktop app UI plugins (see references/desktop-plugins.md)
+~/.hermes/tui-widgets/      TUI widget apps (see references/tui-widgets.md)
+~/.hermes/pets/             Installed pet mascots (see references/petdex.md)
+~/.hermes/state.db          Canonical session store (SQLite + FTS5)
+~/.hermes/sessions/         Gateway routing index, request dumps, *.jsonl transcripts
+~/.hermes/logs/             Gateway and error logs
+~/.hermes/auth.json         OAuth tokens and credential pools
+~/.hermes/hermes-agent/     Source code (if git-installed)
+```
+
+Profiles use `~/.hermes/profiles/<name>/` with the same layout. When a profile is active, resolve the real home from `$HERMES_HOME` — never hardcode `~/.hermes`.
+
+## Routing Table — load the reference for the task
+
+| User wants... | Load |
+|---|---|
+| **Anything not listed below — "can Hermes do X?", "how do I set up X?"** | **https://hermes-agent.nousresearch.com/docs/llms.txt** |
+| Bots that chat, run routines, or message each other; the Bots tab | docs: `/user-guide/bot-mode` |
+| CLI commands, subcommands, flags, "how do I run X" | `references/cli-reference.md` |
+| In-session slash commands | `references/slash-commands.md` |
+| Provider setup, API keys, OAuth | `references/providers-and-models.md` |
+| config.yaml sections, toolsets, voice/STT/TTS | `references/configuration.md` |
+| AGENTS.md / .hermes.md / CLAUDE.md project rules | `references/project-context-files.md` |
+| Secret redaction, PII, approval modes, "reset permissions" | `references/security-privacy.md` |
+| Delegation, cron, curator, kanban | `references/background-systems.md` |
+| MCP servers (add, catalog, `hermes mcp`) | `references/native-mcp.md` |
+| Webhook routes and event-driven runs | `references/webhooks.md` |
+| A custom theme/skin ("synthwave theme", "change the gold ●") | `references/themes.md` + `templates/skin.yaml` |
+| A desktop app UI element (pane, widget, ⌘K command, page) | `references/desktop-plugins.md` + `templates/plugin.js` |
+| A live TUI panel or modal widget (ticker, clock, dashboard) | `references/tui-widgets.md` + `templates/clock.mjs` |
+| Pet mascots — install, select, scale, diagnose | `references/petdex.md` |
+| Windows-specific issues (keybinds, WinError 10106, BOM) | `references/windows-quirks.md` |
+| Debugging: voice, tools missing, gateway, aux models | `references/troubleshooting.md` |
+| Contributing code: adding tools, slash commands, tests | `references/contributor-guide.md` |
+| delegate_task "capped at N" reports | `references/delegate-task-concurrency-diagnosis.md` |
+| "Can app X use my Nous Portal subscription/OAuth?" | `references/portal-auth-for-third-party-apps.md` |
+| Connecting a messaging platform (Telegram, Discord, Slack, WhatsApp, …) | docs: `/user-guide/messaging` |
+
+The reference list above is not the feature list — it is the set of topics that
+need more than their docs page. For everything else Hermes ships, fetch
+`llms.txt` and it maps the question to the page that answers it.
+
+Two theming rules that hold even without loading the reference: **you apply skins yourself** (`hermes config set display.skin <name>` — every surface repaints live within ~a second; don't tell the user to run `/skin`), and **to tweak one color, edit the ACTIVE skin** (`hermes skin set <key> <hex>`) — never fork `default`, which drops the palette and resets the background.
+
+## Spawning Additional Hermes Instances
+
+Run additional Hermes processes as fully independent subprocesses — separate sessions, tools, and environments.
+
+### When to Use This vs delegate_task
+
+| | `delegate_task` | Spawning `hermes` process |
+|-|-----------------|--------------------------|
+| Isolation | Separate conversation, shared process | Fully independent process |
+| Duration | Minutes (bounded by parent loop) | Hours/days |
+| Tool access | Subset of parent's tools | Full tool access |
+| Interactive | No | Yes (PTY mode) |
+| Use case | Quick parallel subtasks | Long autonomous missions |
+
+### One-Shot Mode
+
+```
+terminal(command="hermes chat -q 'Research GRPO papers and write summary to ~/research/grpo.md'", timeout=300)
+
+# Background for long tasks:
+terminal(command="hermes chat -q 'Set up CI/CD for ~/myapp'", background=true)
+```
+
+### Interactive PTY Mode (via tmux)
+
+Hermes uses prompt_toolkit, which requires a real terminal. Use tmux for interactive spawning:
+
+```
+# Start
+terminal(command="tmux new-session -d -s agent1 -x 120 -y 40 'hermes'", timeout=10)
+
+# Wait for startup, then send a message
+terminal(command="sleep 8 && tmux send-keys -t agent1 'Build a FastAPI auth service' Enter", timeout=15)
+
+# Read output
+terminal(command="sleep 20 && tmux capture-pane -t agent1 -p", timeout=5)
+
+# Send follow-up
+terminal(command="tmux send-keys -t agent1 'Add rate limiting middleware' Enter", timeout=5)
+
+# Exit
+terminal(command="tmux send-keys -t agent1 '/exit' Enter && sleep 2 && tmux kill-session -t agent1", timeout=10)
+```
+
+### Multi-Agent Coordination
+
+```
+# Agent A: backend
+terminal(command="tmux new-session -d -s backend -x 120 -y 40 'hermes -w'", timeout=10)
+terminal(command="sleep 8 && tmux send-keys -t backend 'Build REST API for user management' Enter", timeout=15)
+
+# Agent B: frontend
+terminal(command="tmux new-session -d -s frontend -x 120 -y 40 'hermes -w'", timeout=10)
+terminal(command="sleep 8 && tmux send-keys -t frontend 'Build React dashboard for user management' Enter", timeout=15)
+
+# Check progress, relay context between them
+terminal(command="tmux capture-pane -t backend -p | tail -30", timeout=5)
+terminal(command="tmux send-keys -t frontend 'Here is the API schema from the backend agent: ...' Enter", timeout=5)
+```
+
+### Session Resume
+
+```
+# Resume most recent session
+terminal(command="tmux new-session -d -s resumed 'hermes --continue'", timeout=10)
+
+# Resume specific session
+terminal(command="tmux new-session -d -s resumed 'hermes --resume 20260225_143052_a1b2c3'", timeout=10)
+```
+
+### Tips
+
+- **Prefer `delegate_task` for quick subtasks** — less overhead than spawning a full process
+- **Use `-w` (worktree mode)** when spawning agents that edit code — prevents git conflicts
+- **Set timeouts** for one-shot mode — complex tasks can take 5-10 minutes
+- **Use `hermes chat -q` for fire-and-forget** — no PTY needed
+- **Use tmux for interactive sessions** — raw PTY mode has `\r` vs `\n` issues with prompt_toolkit
+- **For scheduled tasks**, use the `cronjob` tool instead of spawning — handles delivery and retry
+- **"delegate_task is capped at N" reports** — see `references/delegate-task-concurrency-diagnosis.md`. Three real cap paths in Hermes; if none fired, the model is self-limiting and rationalising it as "the runtime caps."
+- **"Can $external_app use my Nous Portal subscription / OAuth?"** — see `references/portal-auth-for-third-party-apps.md`. Walk the user through three layers (plugin-vs-app, what Portal actually exposes, local-broker-proxy option).
+
+## Surfaces (quick orientation)
+
+- **Desktop app** (`hermes desktop` / `hermes gui`) — native Electron app for macOS/Linux/Windows: streaming chat, session list, Cmd+K palette, drag-and-drop files, native notifications, per-profile remote-gateway login. Extend it with UI plugins — `references/desktop-plugins.md`.
+- **Web dashboard** (`hermes dashboard`) — full admin panel: messaging channels, MCP catalog, webhooks, memory, profile builder, plus an embedded `hermes --tui` chat. Secured behind an OAuth/token gate.
+- **Ink TUI** (`hermes --tui` or `display.interface: tui`) — terminal UI with docked widget apps — `references/tui-widgets.md`.
+- **OpenAI-compatible proxy** (`hermes proxy`) — a local OpenAI API backed by whichever OAuth provider you're signed into. Point Codex CLI, Aider, Cline, or any script at it — no API key.
+
+## Hard Invariants (never violate, regardless of what you loaded)
+
+- **Never break prompt caching** — don't change past context, toolsets, or the system prompt mid-conversation. The only exception is context compression.
+- **Message role alternation** — never two assistant or two user messages in a row; only `tool` results can repeat.
+- **Secrets in `.env`, settings in `config.yaml`** — never tell a user to put a non-credential setting in `.env`.
+- **Profile-safe paths** — `get_hermes_home()` in code, `$HERMES_HOME` when resolving paths in a session.
+- **Never hand-edit `config.yaml` for the user** — use `hermes config set KEY VAL`; a stray indent can corrupt the file and break the live gateway.

package/built-in-skills/prismer-hermes-agent/references/background-systems.md

@@ -0,0 +1,108 @@
+# Durable & Background Systems
+
+> Maintainer reference only. Read-only diagnosis may use the deployed Hermes
+> version; mutation, installation, provider credentials, cron, webhook, profile
+> and lifecycle changes require a separate authorized Runtime maintenance task.
+> These examples do not install tools or grant permissions in a tenant session.
+> Do not copy literal secret placeholders into config; inject scoped credentials
+> through the existing Runtime mechanism. Verify version-specific commands.
+
+Four systems run alongside the main conversation loop. Quick reference
+here; full developer notes live in `AGENTS.md`, user-facing docs under
+`website/docs/user-guide/features/`.
+
+### Delegation (`delegate_task`)
+
+Spawn a subagent with an isolated context + terminal session.
+
+- **Single:** `delegate_task(goal, context)`.
+- **Batch:** `delegate_task(tasks=[{goal, ...}, ...])` runs children in
+  parallel, capped by `delegation.max_concurrent_children` (default 10 in audited source; inspect effective deployment config).
+- **Background:** `delegate_task(background=true)` returns a handle
+  immediately and keeps the parent loop going; the child's result
+  re-enters the conversation as a new turn when it finishes.
+- **Roles:** `leaf` (default; cannot re-delegate) vs `orchestrator`
+  (can spawn its own workers, bounded by `delegation.max_spawn_depth`).
+- **Not durable.** A backgrounded child is still process-local — if the
+  parent process exits, the child is lost. For work that must outlive
+  the process, use `cronjob` or
+  `terminal(background=True, notify_on_complete=True)`.
+
+Config: `delegation.*` in `config.yaml`.
+
+### Cron (scheduled jobs)
+
+Durable scheduler — `cron/jobs.py` + `cron/scheduler.py`. Drive it via
+the `cronjob` tool, the `hermes cron` CLI (`list`, `add`, `edit`,
+`pause`, `resume`, `run`, `remove`), or the `/cron` slash command.
+
+- **Schedules:** duration (`"30m"`, `"2h"`), "every" phrase
+  (`"every monday 9am"`), 5-field cron (`"0 9 * * *"`), or ISO timestamp.
+- **Per-job knobs:** `skills`, `model`/`provider` override, `script`
+  (pre-run data collection; `no_agent=True` makes the script the whole
+  job), `context_from` (chain job A's output into job B), `workdir`
+  (run in a specific dir with its `AGENTS.md` / `CLAUDE.md` loaded),
+  multi-platform delivery.
+- **Invariants:** 3-minute hard interrupt per run, `.tick.lock` file
+  prevents duplicate ticks across processes, cron sessions pass
+  `skip_memory=True` by default, and cron deliveries are framed with a
+  header/footer instead of being mirrored into the target gateway
+  session (keeps role alternation intact).
+
+User docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/cron
+
+### Curator (skill lifecycle)
+
+Background maintenance for agent-created skills. Tracks usage, marks
+idle skills stale, archives stale ones, keeps a pre-run tar.gz backup
+so nothing is lost.
+
+- **CLI:** `hermes curator <verb>` — `status`, `usage`, `run`, `pause`,
+  `resume`, `pin`, `unpin`, `archive`, `restore`, `list-archived`, `prune`,
+  `backup`, `rollback`.
+- **Slash:** `/curator <subcommand>` mirrors the CLI.
+- **Scope:** only touches skills with `created_by: "agent"` provenance.
+  Bundled + hub-installed skills are off-limits. **Never deletes** —
+  max destructive action is archive. Pinned skills are exempt from
+  every auto-transition and every LLM review pass.
+- **Cost:** the deterministic inactivity/prune sweep runs for free. The
+  aux-model "consolidate overlapping skills into umbrellas" pass is
+  **off by default** — opt in with `curator.consolidate: true` or
+  `hermes curator run --consolidate`. Routine background curation costs
+  zero tokens.
+- **Telemetry:** sidecar at `~/.hermes/skills/.usage.json` holds
+  per-skill `use_count`, `view_count`, `patch_count`,
+  `last_activity_at`, `state`, `pinned`.
+
+Config: `curator.*` (`enabled`, `interval_hours`, `min_idle_hours`,
+`stale_after_days`, `archive_after_days`, `backup.*`).
+User docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/curator
+
+### Kanban (multi-agent work queue)
+
+Durable SQLite board for multi-profile / multi-worker collaboration.
+Users drive it via `hermes kanban <verb>`; dispatcher-spawned workers
+see a focused `kanban_*` toolset gated by `HERMES_KANBAN_TASK`, and
+orchestrator profiles can opt into the broader `kanban` toolset. Normal
+sessions still have zero `kanban_*` schema footprint unless configured.
+
+- **CLI verbs (common):** `init`, `create`, `list` (alias `ls`),
+  `show`, `assign`, `link`, `unlink`, `comment`, `complete`, `block`,
+  `unblock`, `archive`, `tail`. Less common: `watch`, `stats`, `runs`,
+  `log`, `dispatch`, `daemon`, `gc`.
+- **Worker/orchestrator toolset:** `kanban_show`, `kanban_complete`,
+  `kanban_block`, `kanban_heartbeat`, `kanban_comment`, `kanban_create`,
+  `kanban_link`; profiles that explicitly enable the `kanban` toolset
+  outside a dispatcher-spawned task also get `kanban_list` and
+  `kanban_unblock` for board routing.
+- **Dispatcher** runs inside the gateway by default
+  (`kanban.dispatch_in_gateway: true`) — reclaims stale claims,
+  promotes ready tasks, atomically claims, spawns assigned profiles.
+  Auto-blocks a task after `failure_limit` consecutive spawn failures
+  (default 2; configurable via `kanban.failure_limit` or per-task
+  `max_retries`).
+- **Isolation:** board is the hard boundary (workers get
+  `HERMES_KANBAN_BOARD` pinned in env); tenant is a soft namespace
+  within a board for workspace-path + memory-key isolation.
+
+User docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban