@prismer/runtime 2.2.55 → 2.2.63

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

@@ -0,0 +1,219 @@
+# Webhook Subscriptions
+
+> 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.
+
+Create dynamic webhook subscriptions so external services (GitHub, GitLab, Stripe, CI/CD, IoT sensors, monitoring tools) can trigger Hermes agent runs by POSTing events to a URL.
+
+## Setup (Required First)
+
+The webhook platform must be enabled before subscriptions can be created. Check with:
+```bash
+hermes webhook list
+```
+
+If it says "Webhook platform is not enabled", set it up:
+
+### Option 1: Setup wizard
+```bash
+hermes gateway setup
+```
+Follow the prompts to enable webhooks, set the port, and set a global HMAC secret.
+
+### Option 2: Manual config
+Add to `~/.hermes/config.yaml`:
+```yaml
+platforms:
+  webhook:
+    enabled: true
+    extra:
+      port: 8644
+      secret: "your-webhook-secret-here"
+```
+
+Omitting `host` uses the dual-stack default and listens on both IPv4 and IPv6.
+Set a specific address only when you intentionally want to restrict the bind.
+
+### Option 3: Environment variables
+Add to `${HERMES_HOME:-~/.hermes}/.env`:
+```bash
+WEBHOOK_ENABLED=true
+WEBHOOK_PORT=8644
+WEBHOOK_SECRET=your-webhook-secret-here
+```
+
+After configuration, start (or restart) the gateway:
+```bash
+hermes gateway run
+# Or if using systemd:
+systemctl --user restart hermes-gateway
+```
+
+Verify it's running:
+```bash
+curl http://localhost:8644/health
+```
+
+## Commands
+
+All management is via the `hermes webhook` CLI command:
+
+### Create a subscription
+```bash
+hermes webhook subscribe <name> \
+  --prompt "Prompt template with {payload.fields}" \
+  --events "event1,event2" \
+  --description "What this does" \
+  --skills "skill1,skill2" \
+  --deliver telegram \
+  --deliver-chat-id "12345" \
+  --secret "optional-custom-secret"
+```
+
+Returns the webhook URL and HMAC secret. The user configures their service to POST to that URL.
+
+### Filter or transform payloads before the agent runs
+
+Two mechanisms narrow broad event streams (e.g. Todoist/GitHub fire on every update) so only relevant payloads wake the agent:
+
+- **Declarative `filters`** (config.yaml routes only): list of conditions on payload fields, event type, or headers — operators `equals`, `not_equals`, `contains`, `exists`, `missing`, `in`, `in_file`, `regex`, with `all`/`any`/`not` grouping. Non-matching events are ignored with HTTP 200.
+- **Route scripts** (`--script` on subscribe, or `script:` on a config route): a script under `~/.hermes/scripts/` receives the payload as JSON on stdin. JSON stdout replaces the payload before prompt templating; empty stdout, `[SILENT]`, or a nonzero exit ignores the webhook. `.sh`/`.bash` run with bash, everything else with Python. Scripts cannot live outside `~/.hermes/scripts/` (path traversal is blocked).
+
+```bash
+hermes webhook subscribe todoist-hermes \
+  --prompt "Task changed: {payload.content}" \
+  --script "todoist-hermes-label.py" \
+  --deliver telegram --deliver-chat-id "12345"
+```
+
+Full filter syntax: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/webhooks#payload-filters
+
+### List subscriptions
+```bash
+hermes webhook list
+```
+
+### Remove a subscription
+```bash
+hermes webhook remove <name>
+```
+
+### Test a subscription
+```bash
+hermes webhook test <name>
+hermes webhook test <name> --payload '{"key": "value"}'
+```
+
+## Prompt Templates
+
+Prompts support `{dot.notation}` for accessing nested payload fields:
+
+- `{issue.title}` — GitHub issue title
+- `{pull_request.user.login}` — PR author
+- `{data.object.amount}` — Stripe payment amount
+- `{sensor.temperature}` — IoT sensor reading
+
+If no prompt is specified, the full JSON payload is dumped into the agent prompt.
+
+## Common Patterns
+
+### GitHub: new issues
+```bash
+hermes webhook subscribe github-issues \
+  --events "issues" \
+  --prompt "New GitHub issue #{issue.number}: {issue.title}\n\nAction: {action}\nAuthor: {issue.user.login}\nBody:\n{issue.body}\n\nPlease triage this issue." \
+  --deliver telegram \
+  --deliver-chat-id "-100123456789"
+```
+
+Then in GitHub repo Settings → Webhooks → Add webhook:
+- Payload URL: the returned webhook_url
+- Content type: application/json
+- Secret: the returned secret
+- Events: "Issues"
+
+### GitHub: PR reviews
+```bash
+hermes webhook subscribe github-prs \
+  --events "pull_request" \
+  --prompt "PR #{pull_request.number} {action}: {pull_request.title}\nBy: {pull_request.user.login}\nBranch: {pull_request.head.ref}\n\n{pull_request.body}" \
+  --skills "github-code-review" \
+  --deliver github_comment
+```
+
+### Stripe: payment events
+```bash
+hermes webhook subscribe stripe-payments \
+  --events "payment_intent.succeeded,payment_intent.payment_failed" \
+  --prompt "Payment {data.object.status}: {data.object.amount} cents from {data.object.receipt_email}" \
+  --deliver telegram \
+  --deliver-chat-id "-100123456789"
+```
+
+### CI/CD: build notifications
+```bash
+hermes webhook subscribe ci-builds \
+  --events "pipeline" \
+  --prompt "Build {object_attributes.status} on {project.name} branch {object_attributes.ref}\nCommit: {commit.message}" \
+  --deliver discord \
+  --deliver-chat-id "1234567890"
+```
+
+### Generic monitoring alert
+```bash
+hermes webhook subscribe alerts \
+  --prompt "Alert: {alert.name}\nSeverity: {alert.severity}\nMessage: {alert.message}\n\nPlease investigate and suggest remediation." \
+  --deliver origin
+```
+
+### Direct delivery (no agent, zero LLM cost)
+
+For use cases where you just want to push a notification through to a user's chat — no reasoning, no agent loop — add `--deliver-only`. The rendered `--prompt` template becomes the literal message body and is dispatched directly to the target adapter.
+
+Use this for:
+- External service push notifications (Supabase/Firebase webhooks → Telegram)
+- Monitoring alerts that should forward verbatim
+- Inter-agent pings where one agent is telling another agent's user something
+- Any webhook where an LLM round trip would be wasted effort
+
+```bash
+hermes webhook subscribe antenna-matches \
+  --deliver telegram \
+  --deliver-chat-id "123456789" \
+  --deliver-only \
+  --prompt "🎉 New match: {match.user_name} matched with you!" \
+  --description "Antenna match notifications"
+```
+
+The POST returns `200 OK` on successful delivery, `502` on target failure — so upstream services can retry intelligently. HMAC auth, rate limits, and idempotency still apply.
+
+Requires `--deliver` to be a real target (telegram, discord, slack, github_comment, etc.) — `--deliver log` is rejected because log-only direct delivery is pointless.
+
+## Security
+
+- Each subscription gets an auto-generated HMAC-SHA256 secret (or provide your own with `--secret`)
+- The webhook adapter validates signatures on every incoming POST
+- Static routes from config.yaml cannot be overwritten by dynamic subscriptions
+- Subscriptions persist to `~/.hermes/webhook_subscriptions.json`
+
+## How It Works
+
+1. `hermes webhook subscribe` writes to `~/.hermes/webhook_subscriptions.json`
+2. The webhook adapter hot-reloads this file on each incoming request (mtime-gated, negligible overhead)
+3. When a POST arrives matching a route, the adapter formats the prompt and triggers an agent run
+4. The agent's response is delivered to the configured target (Telegram, Discord, GitHub comment, etc.)
+
+## Troubleshooting
+
+If webhooks aren't working:
+
+1. **Is the gateway running?** Check with `systemctl --user status hermes-gateway` or `ps aux | grep gateway`
+2. **Is the webhook server listening?** `curl http://localhost:8644/health` should return `{"status": "ok"}`
+3. **Check gateway logs:** `grep webhook ~/.hermes/logs/gateway.log | tail -20`
+4. **Signature mismatch?** Verify the secret in your service matches the one from `hermes webhook list`. GitHub sends `X-Hub-Signature-256`, GitLab sends `X-Gitlab-Token`.
+5. **Firewall/NAT?** The webhook URL must be reachable from the service. For local development, use a tunnel (ngrok, cloudflared).
+6. **Wrong event type?** Check `--events` filter matches what the service sends. Use `hermes webhook test <name>` to verify the route works.

package/built-in-skills/prismer-hermes-agent/references/windows-quirks.md

@@ -0,0 +1,64 @@
+# Windows-Specific Quirks
+
+> 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.
+
+Hermes runs natively on Windows (PowerShell, cmd, Windows Terminal, git-bash
+mintty, VS Code integrated terminal). Most of it just works, but a handful
+of differences between Win32 and POSIX have bitten us — document new ones
+here as you hit them so the next person (or the next session) doesn't
+rediscover them from scratch.
+
+### Input / Keybindings
+
+**Alt+Enter doesn't insert a newline** — Windows Terminal (and mintty) grab it
+for fullscreen before prompt_toolkit sees it. Use **Ctrl+Enter** instead (the
+CLI binds it to newline on Windows; raw Ctrl+J does the same, harmlessly).
+To inspect how your terminal reports a keystroke, run
+`python scripts/keystroke_diagnostic.py` from the repo root.
+
+### Config / Files
+
+**HTTP 400 "No models provided" on first run** — `config.yaml` was saved with
+a UTF-8 BOM (Notepad does this). Re-save as UTF-8 without BOM;
+`hermes config edit` writes correctly.
+
+### `execute_code` / Sandbox
+
+**WinError 10106** from the sandbox child process — it can't create an
+`AF_INET` socket. Root cause is usually Hermes's env scrubber dropping
+`SYSTEMROOT`/`WINDIR`/`COMSPEC` (Python's `socket` needs `SYSTEMROOT` to find
+`mswsock.dll`), not a broken Winsock LSP. The `_WINDOWS_ESSENTIAL_ENV_VARS`
+allowlist in `tools/code_execution_env.py` covers it; if you still hit it,
+echo `os.environ` inside an `execute_code` block to confirm `SYSTEMROOT` is set.
+
+### Testing on Windows
+
+`scripts/run_tests.sh` is POSIX-only (expects `.venv/bin/activate`); the
+Hermes-installed `venv/Scripts/` has no pip/pytest (stripped for size).
+Install pytest into a system Python and run directly (the repo no longer
+uses pytest-xdist; the canonical runner does per-file subprocess isolation,
+which the POSIX-only wrapper handles):
+
+```bash
+"/c/Program Files/Python311/python" -m pip install --user pytest pyyaml
+export PYTHONPATH="$(pwd)"
+"/c/Program Files/Python311/python" -m pytest tests/foo/test_bar.py -v --tb=short
+```
+
+(POSIX-only tests need skip guards — see the cross-platform guard list in
+`references/contributor-guide.md`.)
+
+### Path / Filesystem
+
+**Line endings.** Git may warn `LF will be replaced by CRLF`. Cosmetic — the
+repo's `.gitattributes` normalizes. Don't let editors auto-convert committed
+POSIX-newline files to CRLF.
+
+**Forward slashes work almost everywhere.** `C:/Users/...` is accepted by
+every Hermes tool and most Windows APIs. Prefer forward slashes in code
+and logs — avoids shell-escaping backslashes in bash.

package/built-in-skills/prismer-hermes-agent/templates/clock.mjs

@@ -0,0 +1,51 @@
+/**
+ * Reference user widget: a live clock docked above the status bar.
+ * Copy to ~/.hermes/tui-widgets/clock.mjs, then `/widgets-reload` and `/clock`.
+ */
+export default function register(sdk) {
+  const { Box, Dialog, React, Text, defineWidgetApp, h } = sdk
+
+  function Face({ label, t }) {
+    const [now, setNow] = React.useState(() => new Date())
+
+    React.useEffect(() => {
+      const id = setInterval(() => setNow(new Date()), 1000)
+
+      return () => clearInterval(id)
+    }, [])
+
+    return h(
+      Box,
+      { columnGap: 1, flexDirection: 'row' },
+      h(Text, { bold: true, color: t.color.label }, label),
+      h(Text, { color: t.color.text }, now.toLocaleTimeString('en-GB', { hour12: false, timeZone: label === 'local' ? undefined : label }))
+    )
+  }
+
+  defineWidgetApp({
+    id: 'clock',
+    help: 'live clock in the dock (arg: IANA timezone)',
+    mode: 'ambient',
+    usage: 'usage: /clock [timezone]   e.g. /clock UTC · /clock Asia/Tokyo',
+
+    init(arg) {
+      const label = arg.trim() || 'local'
+
+      try {
+        new Date().toLocaleTimeString('en-GB', { timeZone: label === 'local' ? undefined : label })
+      } catch {
+        return null
+      }
+
+      return { label }
+    },
+
+    reduce(state, { ch, key }) {
+      return key.escape || ch === 'q' ? null : state
+    },
+
+    render({ state, t }) {
+      return h(Dialog, { width: 30 }, h(Face, { label: state.label, t }))
+    }
+  })
+}

package/built-in-skills/prismer-hermes-agent/templates/plugin.js

@@ -0,0 +1,97 @@
+/**
+ * Hermes desktop plugin template. Save as:
+ *   <hermes home>/desktop-plugins/<id>/plugin.js   (folder name == id)
+ * where <hermes home> is ~/.hermes by default, or ~/.hermes/profiles/<name>
+ * when running a named profile (`hermes -p <name>`). Run `hermes doctor` (or
+ * check the app's Settings → Plugins folder path) if unsure which is active.
+ * Then run "Reload desktop plugins" from ⌘K in the desktop app.
+ *
+ * Plain ESM, loaded uncompiled — UI is jsx() calls, not JSX syntax.
+ * Only these imports resolve: @hermes/plugin-sdk, react, react/jsx-runtime.
+ */
+
+import { cn, haptic, host, Tip, usePluginI18n, useValue } from '@hermes/plugin-sdk'
+import { jsx, jsxs } from 'react/jsx-runtime'
+
+// Ship your OWN strings (never edit core en.ts). `usePluginI18n` resolves them
+// against the app's active locale, falling back to `en`, then the raw key.
+const ID = 'my-plugin'
+
+function MyPane() {
+  const t = usePluginI18n(ID)
+  const gateway = useValue(host.state.gateway)
+
+  return jsxs('div', {
+    className: 'flex h-full flex-col gap-2 p-3 text-sm',
+    children: [
+      jsx('div', { className: 'font-medium', children: t('paneTitle') }),
+      jsx('div', {
+        className: 'text-(--ui-text-tertiary)',
+        children: t('gateway', gateway)
+      })
+    ]
+  })
+}
+
+function MyChip() {
+  const t = usePluginI18n(ID)
+
+  return jsx(Tip, {
+    label: t('chipTip'),
+    children: jsx('button', {
+      className: cn(
+        'inline-flex h-full items-center gap-1 px-1.5 text-[0.6875rem] transition-colors',
+        'text-(--ui-text-tertiary) hover:bg-(--chrome-action-hover) hover:text-foreground'
+      ),
+      type: 'button',
+      onClick: () => {
+        haptic('tap')
+        host.notify({ kind: 'info', message: t('hello') })
+      },
+      children: 'my-plugin'
+    })
+  })
+}
+
+export default {
+  id: ID, // must match the folder name
+  name: 'My Plugin',
+  register(ctx) {
+    // Register locale bundles — scoped to this plugin, torn down on reload.
+    // Values are literals or interpolators (`arg => `…${arg}…``).
+    ctx.i18n.register({
+      en: {
+        paneTitle: 'My Plugin Pane',
+        gateway: state => `gateway: ${state}`,
+        chipTip: 'My plugin — click me',
+        hello: 'Hello from my plugin!'
+      },
+      ja: {
+        paneTitle: 'マイプラグイン',
+        gateway: state => `ゲートウェイ: ${state}`,
+        chipTip: 'マイプラグイン — クリック',
+        hello: 'マイプラグインからこんにちは！'
+      }
+    })
+
+    // A layout pane — auto-placed by the placement hint; user can drag it.
+    // To land on a specific edge instead of stacking, add a dock gesture,
+    // e.g. below the conversation:
+    //   data: { placement: 'bottom', dock: { pane: 'workspace', pos: 'bottom' }, height: '200px' }
+    ctx.register({
+      id: 'pane',
+      area: 'panes',
+      title: 'my plugin',
+      data: { placement: 'right', width: '237px' },
+      render: () => jsx(MyPane, {})
+    })
+
+    // A statusbar chip.
+    ctx.register({
+      id: 'chip',
+      area: 'statusBar.right',
+      order: 130,
+      render: () => jsx(MyChip, {})
+    })
+  }
+}

package/built-in-skills/prismer-hermes-agent/templates/skin.yaml

@@ -0,0 +1,49 @@
+# Hermes skin template — themes the CLI, TUI, and desktop GUI from one file.
+# Copy to <hermes-home>/skins/<name>.yaml, edit the palette, then set
+# `display.skin: <name>` in config.yaml. Missing keys inherit the default skin.
+
+name: synthwave
+description: Neon dusk — magenta and cyan on deep indigo
+
+colors:
+  # Base surface — set this. The GUI derives its palette from it; the TUI
+  # status bar and CLI chrome seed from it too.
+  background: "#1a1030"
+
+  # Brand accent — buttons, focus rings, GUI primary. Keep it legible (~4.5:1)
+  # against `background`.
+  ui_accent: "#ff5fd2"
+  banner_accent: "#ff5fd2"
+
+  # Text hierarchy.
+  banner_title: "#7ef9ff"   # headings / primary
+  banner_text: "#e6e0ff"    # body foreground
+  ui_text: "#e6e0ff"
+  banner_dim: "#8a7fb5"     # muted / secondary
+  banner_border: "#3a2a63"
+  ui_border: "#3a2a63"
+
+  # Semantic status.
+  ui_ok: "#5af7b0"
+  ui_warn: "#ffcf5f"
+  ui_error: "#ff6b7d"
+
+  # CLI / TUI chrome.
+  prompt: "#e6e0ff"
+  input_rule: "#ff5fd2"
+  response_border: "#7ef9ff"
+  status_bar_bg: "#120a24"
+  status_bar_text: "#e6e0ff"
+  status_bar_good: "#5af7b0"
+  status_bar_warn: "#ffcf5f"
+  status_bar_critical: "#ff6b7d"
+  session_label: "#7ef9ff"
+  session_border: "#3a2a63"
+
+# Optional flavor — safe to delete.
+branding:
+  agent_name: Hermes Agent
+  prompt_symbol: "❯"
+  help_header: "(^_^)? Commands"
+
+tool_prefix: "┊"

package/built-in-skills/prismer-himalaya/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-himalaya/NOTICE.md

@@ -0,0 +1,11 @@
+# Source and modifications
+
+Derived from Hermes Agent skills/email/himalaya, commit
+1a1f4a59e252e1dc0137e7b2e7bcc8b0381d19c4. Upstream authors remain credited
+in SKILL.md. The MIT license is included in LICENSE.
+
+Prismer adaptation: unique slug/native replacement, scoped execution and
+authorization, corrected resource/API instructions and local safety helpers.
+See docs/bugfix223/implementation-productivity.md in the source repository
+for offline evidence and untested live integrations. Dependencies and service
+data retain their own licenses; this notice does not relicense them.