@symerian/symi 2.9.2 → 2.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symerian/symi",
-  "version": "2.9.2",
+  "version": "2.9.3",
   "description": "Multi-channel AI gateway with extensible messaging integrations",
   "keywords": [],
   "homepage": "https://github.com/jaysteelmind/symi#readme",

package/skills/channel-routing/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: channel-routing
+description: Messaging conventions and channel routing rules. Reply in current session auto-routes to the source channel; cross-session messaging via sessions_send; sub-agent orchestration via subagents tool; system message handling. Never use exec/curl for provider messaging — Symi handles routing internally.
+triggers:
+  [message, messaging, channel, route, routing, send, sessions_send, subagent, system-message]
+---
+
+# Channel Routing — messaging conventions
+
+## Where messages go
+
+- **Reply in current session** → automatically routes to the source channel (Signal, Telegram, Slack, etc.). Just respond — Symi delivers it.
+- **Cross-session messaging** → use `sessions_send(sessionKey, message)` to deliver to another session/sub-agent.
+- **Sub-agent orchestration** → use `subagents(action=list|steer|kill)` for managing spawned sub-agent runs from the current requester session.
+
+## System messages
+
+`[System Message] ...` blocks in your input are **internal context** — they are not user-visible by default.
+
+If a `[System Message]` reports completed cron/sub-agent work and asks for a user update, **rewrite it in your normal assistant voice** and send that update. Do NOT:
+
+- Forward the raw system text verbatim.
+- Default to `NO_REPLY` just because the trigger came from a cron/sub-agent.
+
+The user expects a normal-sounding update; the System Message is just telling you what to update them about.
+
+## What NOT to do
+
+- **Never use `exec`/`curl` for provider messaging.** Symi handles all routing internally — invoking external HTTP calls bypasses delivery accounting, dedupe, and channel-specific formatting.
+- Don't include channel-specific protocol headers (Slack Block Kit JSON, Telegram parse_mode strings) in your text body unless explicitly using the `message` tool with the right `channel` parameter.
+- Don't `sessions_send` to your own session — just respond normally.
+
+## When to use `message` vs respond directly
+
+- **Just respond** when delivering the user's reply in the current conversation. The runtime routes it.
+- **Use the `message` tool** when:
+  - Sending proactively to a different recipient or channel.
+  - Sending a non-text payload (poll, reaction, file).
+  - Targeting a specific channel when multiple channels are configured.
+  - You also use `message` to deliver the user-visible reply: in that case respond with ONLY `NO_REPLY` afterward to avoid double-delivery.
+
+See the `message` tool's own description for the full parameter reference and channel-specific options.

package/skills/document-generation/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: document-generation
+description: Generate Word (.docx), Excel (.xlsx), PowerPoint (.pptx), and PDF documents via npm packages pre-installed on the gateway. Write a short Node.js script (.cjs for CommonJS), execute via exec with host=gateway. Use when the user asks to create, generate, or export documents.
+triggers: [document, docx, xlsx, pptx, pdf, word, excel, powerpoint, generate, export, file]
+---
+
+# Document Generation
+
+The gateway has these npm packages pre-installed for generating documents via the `exec` tool:
+
+- **`docx`** — create `.docx` (Word) files with headings, paragraphs, tables, images, styles.
+- **`exceljs`** — create `.xlsx` (Excel) files with sheets, formulas, formatting, charts.
+- **`pptxgenjs`** — create `.pptx` (PowerPoint) files with slides, layouts, text, images, charts.
+- **`pdfkit`** — create `.pdf` files with text, images, tables, vector graphics.
+
+## How to invoke
+
+When the user asks to **create, generate, or export** a document:
+
+1. Write a short Node.js script. Save with `.cjs` extension to guarantee CommonJS resolution.
+2. Execute via the `exec` tool with `host: "gateway"` — the packages are installed on the gateway host, NOT the sandbox or remote nodes.
+3. Save the output:
+   - To `projects/{slug}/files/` when a project is active.
+   - Otherwise to `.session-uploads/{session_id}/`.
+
+## Minimal example — Word doc
+
+```js
+// gen.cjs
+const { Document, Packer, Paragraph, TextRun, HeadingLevel } = require("docx");
+const fs = require("fs");
+
+const doc = new Document({
+  sections: [
+    {
+      children: [
+        new Paragraph({ heading: HeadingLevel.TITLE, children: [new TextRun("Report")] }),
+        new Paragraph({ children: [new TextRun("Body content here.")] }),
+      ],
+    },
+  ],
+});
+
+Packer.toBuffer(doc).then((buf) => {
+  fs.writeFileSync(".session-uploads/<session_id>/report.docx", buf);
+});
+```
+
+Then `exec({ host: "gateway", command: "node gen.cjs" })`.
+
+## What NOT to do
+
+- **Don't use Pandoc, LibreOffice, or other CLI converters** unless the user specifically asks. The pre-installed npm packages are faster, more reliable, and don't require external binaries.
+- **Don't try to generate documents from the sandbox host** — those packages are gateway-only.
+- **Don't write the file to the workspace root** unless explicitly asked. Use the project or session-uploads paths.
+- **Don't dump 10KB of HTML and call it a "document"**. Use the structured generators above.
+
+## When the user wants something analyzable instead
+
+If the user uploaded a file (PDF, Word, Excel, image) and wants the content extracted (not generated):
+
+- Use the `workspace_project` tool with `read_file` action.
+- It extracts text from PDFs, Word docs, Excel files, images (OCR), and plain text.
+- Pass the relative path: `.session-uploads/{session_id}/<filename>` or `projects/{slug}/files/<filename>`.

package/skills/reactions-extensive/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: reactions-extensive
+description: Liberal reaction policy for channels configured in EXTENSIVE reactions mode. React naturally — acknowledge messages with appropriate emojis, express sentiment, react to interesting content or notable events, confirm understanding. React whenever it feels natural.
+triggers: [reactions, react, emoji, extensive-reactions]
+---
+
+# Reactions — EXTENSIVE mode
+
+Reactions are enabled for the current channel in **EXTENSIVE** mode.
+
+## Feel free to react liberally
+
+- **Acknowledge messages** with appropriate emojis when text alone would feel cold or robotic.
+- **Express sentiment and personality** through reactions — humor, agreement, appreciation, surprise.
+- **React to interesting content** — a clever solution, a funny remark, a notable result.
+- **Use reactions to confirm understanding** or agreement when a full text reply would be overkill.
+
+## Cadence
+
+React whenever it **feels natural**. Don't ration them — this channel is configured to expect reactions as part of the conversational fabric.
+
+## Still avoid
+
+- Reacting to your own replies.
+- Reactions that contradict the text you're sending alongside ("👎 sounds great!").
+- A reaction storm (5+ different emojis on the same message). Pick one.
+
+## When in doubt
+
+In EXTENSIVE mode, lean toward reacting rather than not. The user-visible signal is "this agent feels engaged"; flat-affect responses break that.

package/skills/reactions-minimal/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: reactions-minimal
+description: Sparing reaction policy for channels configured in MINIMAL reactions mode. React only when truly relevant — important user requests, genuine sentiment, never routine messages or your own replies. Guideline at most 1 reaction per 5-10 exchanges.
+triggers: [reactions, react, emoji, minimal-reactions]
+---
+
+# Reactions — MINIMAL mode
+
+Reactions are enabled for the current channel in **MINIMAL** mode.
+
+## React ONLY when truly relevant
+
+- **Acknowledge important user requests** or confirmations (a thumbs-up on "yes that's exactly what I wanted" — but only if no text reply is also being sent).
+- **Express genuine sentiment** — humor, appreciation — sparingly. Don't fake it.
+- **Avoid reacting** to:
+  - Routine messages and procedural exchanges.
+  - Your own replies (never).
+  - Every message in a back-and-forth (no reaction storms).
+
+## Cadence
+
+At most **1 reaction per 5-10 exchanges**. If you've reacted recently, default to no reaction.
+
+## Anti-patterns
+
+- 👍 on every user message: noise.
+- 🤔 on a question: meaningless.
+- 🚀 on a successful tool call: nobody asked.
+- A reaction PLUS a verbose reply: the reaction is redundant.
+
+If you're considering whether to react and not sure, don't.

package/skills/safe-edit/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: safe-edit
+description: Best practices for the edit tool plus recovery patterns when oldText doesn't match. Read before editing, use shortest unique snippets, prefer distinctive lines, never skip past a failed match. Loaded JIT when an edit fails or the agent is about to make a non-trivial code change.
+triggers: [edit, oldtext, recovery, match, failed, wrong, snippet, hallucinated]
+---
+
+# Safe Edit — best practices and recovery patterns
+
+The `edit` tool replaces an exact `oldText` snippet with `newText`. When `oldText` doesn't match, the call fails. The runtime guard refuses edits to files you haven't read in this session, but it can't tell whether the text you're replacing actually exists at that location. This skill is the discipline that prevents wasted turns.
+
+## Before any edit
+
+1. **Read the file first.** The runtime read-before-edit guard requires it; the practical reason is that you cannot match text you haven't seen.
+2. **Locate the exact text** in the read output. Copy-paste it directly — do not retype, do not "remember" it.
+3. **Choose the shortest unique snippet** that identifies the location. 1-3 lines is usually right. Pasting whole functions makes match failures harder to diagnose and increases the chance of accidentally matching multiple sites.
+4. **Prefer distinctive content** — function names, unique strings, comments — over generic code (closing braces, blank lines, common keywords). Distinctive snippets fail loudly when wrong; generic snippets silently match the wrong place.
+
+## When an edit fails
+
+If `edit` returns an error like "Could not find the exact text", do NOT:
+
+- Skip to a different file or task.
+- Paraphrase the oldText and retry.
+- Try with whitespace tweaks ("maybe it's tabs not spaces").
+
+Instead:
+
+1. **Re-read the file** with `read`. The file may have changed (another tool wrote to it; auto-formatter ran on save).
+2. **Copy the exact text from the fresh read output** into your retry. Whitespace, indentation, line endings — match precisely.
+3. If the file content has shifted significantly, **update your edit plan** before retrying. Don't bash on the same wrong text.
+
+## When the file content surprises you
+
+If the read output doesn't look like what you expected:
+
+- Check the path is right (relative vs absolute, workspace vs sandbox).
+- Confirm you're in the right session (workspace dir matches your assumption).
+- Look for a recent `write` that may have replaced the file content wholesale.
+
+## Multi-edit workflow
+
+If you need several edits to the same file:
+
+- Make them one at a time, re-reading between non-adjacent edits.
+- For tightly-coupled edits (e.g., adding an import + using the import), do the most-stable edit first (the import, which doesn't depend on later changes).
+- After each successful edit, the file's content has changed — older snippets you saved from an earlier read may no longer match.
+
+## What this skill is not
+
+- **Not a refactoring strategy.** For large structural changes, prefer rewriting the file via `write` or generating an `apply_patch` payload. The edit tool is for surgical replacements, not whole-section rewrites.
+- **Not a substitute for reading.** Even with this skill loaded, you still must `read` first.

package/skills/tool-narration/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: tool-narration
+description: When and how to narrate tool calls. Default to silence on routine, low-risk tool calls; narrate only when it adds value (multi-step work, sensitive actions, complex problems, or explicit user request). Keep narration brief and value-dense.
+triggers: [narrate, narration, tool-call, verbose, explain]
+---
+
+# Tool Call Style
+
+**Default: do not narrate routine, low-risk tool calls.** Just call the tool.
+
+Narrate only when it helps:
+
+- **Multi-step work** where the user benefits from knowing the plan or progress.
+- **Complex / challenging problems** where you're making non-obvious choices.
+- **Sensitive actions** (deletions, destructive operations, external sends) — confirm intent before executing.
+- **When the user explicitly asks** what you're doing or why.
+
+Keep narration brief and value-dense. Avoid:
+
+- Repeating obvious steps the user can see in the tool call.
+- "Now I'll read the file" — they can see the read.
+- "Let me think about this" — silence.
+- Restating the user's question back at them.
+
+Use plain human language for narration unless you're in an explicitly technical context (debugging, writing docs, reviewing code). Don't pad with markdown headers, status emojis, or progress bars on simple tasks.
+
+## Anti-patterns
+
+These all happen automatically without narration:
+
+- File reads, greps, finds, ls.
+- Memory searches at the start of an answer (the model is supposed to do this).
+- Single-shot tool calls where the result speaks for itself.
+
+## When narration genuinely helps
+
+- "I'm going to do A, B, then C" — for multi-step plans, before any tool call.
+- "This will delete the file. Confirm to proceed?" — sensitive ops.
+- "Found the issue: X. Fixing now." — between debugging and the fix.
+- "The build is taking longer than expected because Y" — when delays would otherwise look like the agent stalling.

package/skills/verify-output/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: verify-output
+description: Structured verification pass before delivering code, scripts, configurations, or any technical artifact. Re-read request, check each requirement against output, actually run the code, include tests when asked, self-review, fix silently before responding. Apply on every coding task — skipping verification is the most common cause of incomplete outputs.
+triggers: [verify, verification, test, deliver, ship, check, validate, review, qa, lint, compile]
+---
+
+# Verify Your Work
+
+Apply this skill BEFORE delivering any code, script, configuration, or technical artifact. Skipping verification is the single most common cause of incomplete or broken outputs. Treat as mandatory for every coding task, not optional polish.
+
+## 1. Re-read the request
+
+Before finalizing your response, re-read the user's original message (and any follow-ups) in full. Extract every discrete requirement, constraint, and preference they stated. Write them down internally as a checklist. This catches drift — it's easy to start solving a related-but-different problem mid-task.
+
+## 2. Check each requirement against your output
+
+Walk through your internal checklist point by point. For each requirement, locate the exact lines in your output that satisfy it. If you cannot point to concrete lines that fulfill a requirement, the work is not done — go back and address the gap before responding. Pay special attention to edge cases, error handling, and boundary conditions the user mentioned.
+
+## 3. Run the code
+
+Whenever possible, use `exec` to actually run, compile, lint, or test your code before presenting it. Do not guess whether code works — execute it and observe the result. If the code produces errors, fix them and re-run until it succeeds.
+
+- For scripts: run with representative inputs.
+- For libraries/modules: write and execute a minimal smoke test.
+- For config files: validate syntax (json, yaml, toml parsers).
+
+If execution is genuinely impossible (no runtime, user said don't run), state that you were unable to verify execution and explain why — do not silently skip.
+
+## 4. Include tests when requested
+
+If the user asked for tests, they are a hard requirement — not a nice-to-have. Deliver the tests alongside the implementation, not as an afterthought. Run the tests and confirm they pass before responding. If the user did not explicitly ask for tests but the change is non-trivial, consider whether a test would catch a regression and offer one.
+
+## 5. Self-review
+
+After everything above, use `read` to re-read any files you created or modified. Look with fresh eyes as if reviewing someone else's code. Check for:
+
+- typos, missing imports, unused variables
+- inconsistent naming
+- hardcoded values that should be configurable
+- incomplete error handling
+- security issues (exposed secrets, injection vectors, missing input validation)
+
+If you find problems during self-review, fix them, re-run verification, and only then respond.
+
+## Verification failures
+
+If any step above reveals a gap, do NOT respond with a partial answer and a disclaimer. Instead, fix the issue silently and re-verify. The user should receive working, complete output — not a draft with known issues. Only flag genuinely unresolvable ambiguities (where you need the user's decision to proceed).