@moxxy/cli 0.0.0

package/dist/skills/self-update.md

@@ -0,0 +1,137 @@
+---
+name: self-update
+description: Extend or repair moxxy's OWN capabilities — add a tool/skill the user asks for, or fix a recurring failure — by authoring a plugin or skill through a guardrailed, verified, auto-rollback transaction.
+triggers:
+  - "add a tool"
+  - "add a capability"
+  - "teach yourself"
+  - "update yourself"
+  - "extend yourself"
+  - "give yourself"
+  - "self-update"
+  - "self update"
+  - "modify your code"
+  - "change your code"
+  - "you should be able to"
+  - "can you learn to"
+---
+
+# Self-update — author or repair a capability, safely
+
+Use this when the user asks you to **add a capability** ("add a tool that…",
+"you should be able to…") or to **fix a recurring failure** in your own
+behavior, and the change requires editing code/skills rather than just doing
+the task. Every code write goes through a `prompt` permission gate and every
+change is verified before it counts — there is no silent self-modification.
+
+Pick the **lowest-risk tier** that satisfies the request:
+
+| Tier | When | Mechanism | Reversible by |
+|------|------|-----------|---------------|
+| **A — Skill** | A recurring *procedure* expressible with tools that already exist ("always run X before Y") | a `.md` skill in `~/.moxxy/skills` (no code) | delete one file |
+| **B — Plugin** | A new *action* (call an API, run a script) or a *behavior override* of an existing tool | a plugin in `~/.moxxy/plugins`, hot-reloaded | unload + restore |
+| **C — Core** | Genuinely needs to edit `@moxxy/core` (new event type, registry, the loop itself) | provision source → build + test → overlay → restart | snapshot restore + restart |
+
+Prefer A, then B. **Most "core fixes" should still be a plugin *override*** (wrap
+a tool, swap a mode) — that's hot-reloadable and reversible. Only use Tier C
+when the change genuinely cannot be expressed as a plugin. Tier C is heavy
+(provisions a source clone, builds, then needs a process restart) and every
+step is approval-gated.
+
+## Loop
+
+1. **Classify.** Call `self_update_classify` with the request text (or
+   `trigger: "error"` after a failure). It reads recent errors + the live tool
+   set and recommends a tier. The recommendation is *advisory* — apply the
+   table above. If a published plugin already does it, prefer `install_plugin`
+   over authoring from scratch.
+
+2. **State the smallest change** in one sentence. A new plugin should add the
+   one tool/hook needed — no "while I'm here" extras.
+
+3. **Open a transaction.** `self_update_begin({ kind, name })` snapshots the
+   target so it can be rolled back. For a brand-new plugin, scaffold first with
+   `moxxy plugins new <name>` (zero-build `.mjs` that hot-reloads), or write a
+   `src/index.ts` (loaded via jiti).
+
+4. **Surface the change BEFORE writing.** Tell the user the diagnosis/goal and
+   the exact file contents you're about to write. Then write with `Write` /
+   `Edit` — the user approves each at the permission prompt. Never bundle edits
+   into a `bash` heredoc to dodge the prompts.
+
+5. **Verify.** `self_update_verify({ txnId })` builds (if the plugin has a
+   build script), runs its tests, hot-reloads it into the session, and confirms
+   it registered. If it fails on a *modified* plugin, the previous working
+   version is auto-restored. Read the returned `stages` to see what broke.
+
+6. **Apply or roll back.** If verify passes, show the user what registered and
+   call `self_update_apply({ txnId })` to keep it. If runtime behavior is wrong,
+   `self_update_rollback({ txnId })`.
+
+7. **Stop after 2 failed verify cycles.** `self_update_verify` refuses a 3rd
+   attempt, rolls back to a clean state, and returns `escalate: true`. When that
+   happens, stop editing and report to the user: the original goal, what you
+   tried, and the captured errors. Don't loop.
+
+## Tier C — core patch (heavy, restart-required)
+
+Only when a plugin override genuinely can't do it. Confirm with the user first.
+
+1. `self_update_core_preflight` — checks git/pnpm + that the install has pinned
+   source provenance (`gitHead` + repo url). If any check fails, STOP and tell
+   the user (e.g. set `options.repoUrl` in config, or update via npm instead).
+2. `self_update_core_begin({ packages })` — provisions a source clone at the
+   exact installed commit (slow). Returns a `coreTxnId` + repo path.
+3. Edit with `self_update_core_write` / `self_update_core_edit` (paths relative
+   to the repo). Show the diff first.
+4. `self_update_core_verify({ coreTxnId })` — builds/typechecks/tests the
+   affected packages + dependents, and rejects any change that adds a new
+   runtime dependency.
+5. `self_update_core_apply({ coreTxnId })` — overlays the build into the live
+   install (snapshotting the old dist) and stages a restart. **Tell the user a
+   restart is required.** It auto-commits on the next clean boot.
+6. If a patch is bad, `self_update_core_rollback({ coreTxnId })` (or
+   `moxxy self-update rollback <coreTxnId>` from a shell) + restart.
+
+## Expressing a fix as a plugin override (Tier B templates)
+
+A plugin can change core behavior without touching core, via lifecycle hooks:
+
+- **Wrap a misbehaving tool's output** — `onToolResult(ctx)`: if
+  `ctx.result.toolName === 'X'`, return a repaired/truncated result.
+- **Block or rewrite a bad call** — `onToolCall(ctx)`: return
+  `{ action: 'deny', reason }` or `{ action: 'rewrite', input }`.
+- **Add a capability** — a new `defineTool({...})` in the plugin's `tools`.
+- **Augment the system prompt** — `onBeforeProviderCall(req)`: return
+  `{ ...req, system: req.system + extra }`.
+- **Swap the loop/compaction strategy** — register a mode/compactor and
+  activate it from the plugin's `onInit`.
+
+Minimal plugin entry (`~/.moxxy/plugins/<name>/index.mjs`):
+```js
+import { definePlugin, defineTool, z } from '@moxxy/sdk';
+
+export default definePlugin({
+  name: 'my-capability',
+  version: '0.0.0',
+  tools: [
+    defineTool({
+      name: 'my_tool',
+      description: 'One sentence, lead with a verb.',
+      inputSchema: z.object({ arg: z.string() }),
+      permission: { action: 'prompt' },
+      handler: async ({ arg }) => ({ result: arg }),
+    }),
+  ],
+});
+```
+
+## Don't
+
+- **Don't skip the transaction.** Always `self_update_begin` before editing so
+  there's a snapshot to roll back to.
+- **Don't edit `@moxxy/core` or other framework packages here.** That's Tier C —
+  escalate. Reach for a plugin override first.
+- **Don't keep retrying a failing change.** Two failed verifies is the wall.
+- **Don't self-update silently.** This responds to an explicit request or a
+  reported failure — not proactive tinkering.

package/dist/skills/synthesize-skill.md

@@ -0,0 +1,20 @@
+---
+name: synthesize-skill
+description: When the user request doesn't match any existing skill, draft a new one and persist it for next time.
+triggers: ["create skill", "new skill", "save this as a skill"]
+allowed-tools: [Write, Read]
+---
+# Synthesize a new skill
+
+The user has asked for something for which no existing skill matches. Your job is to:
+
+1. Identify the intent (one sentence).
+2. Draft a Markdown skill file with YAML frontmatter:
+   - `name`: kebab-case slug, no more than 60 chars
+   - `description`: one sentence, < 120 chars
+   - `triggers`: 2–5 short phrases a user might say
+   - `allowed-tools`: only the tools you need
+3. The body is the instructions for future invocations: numbered steps, the minimum needed to execute reliably.
+4. Save to `~/.moxxy/skills/<slug>.md` unless the user redirects to project scope.
+
+Keep skill bodies short — under 30 lines. Long context belongs in code/files the skill reads at runtime, not in the skill itself.

package/dist/skills/telegram-setup.md

@@ -0,0 +1,40 @@
+---
+name: telegram-setup
+description: Walk the user through creating a Telegram bot via BotFather and pairing their chat.
+triggers: ["set up telegram", "configure telegram", "connect telegram", "telegram bot"]
+allowed-tools: [telegram_set_token, telegram_status, vault_status, vault_list]
+---
+# Telegram setup
+
+The user wants to connect a Telegram bot to moxxy. Walk them through these steps in order. Be terse — one step at a time.
+
+## 1. Create a bot with BotFather
+
+Tell the user:
+> Open Telegram and message **@BotFather**. Send `/newbot`, then follow its prompts to choose a display name and a username (must end in `bot`). BotFather will reply with a token that looks like `1234567890:ABCdefGhIjKl...`. Paste it here.
+
+Wait for the user to provide the token.
+
+## 2. Store the token
+
+Once they paste the token, call `telegram_set_token` with it. The token will be encrypted into the vault.
+
+This will trigger the vault permission prompt + (on first use) the master-key prompt (keychain or passphrase). If the vault has never been initialized, mention that briefly so the prompt isn't confusing.
+
+## 3. Verify
+
+Call `telegram_status` and report what came back. Expected:
+```
+{ "tokenConfigured": true, "authorizedChatId": null }
+```
+
+## 4. Tell them how to pair
+
+> Run **`moxxy telegram pair`** in your terminal. It will print a 6-digit code. In Telegram, find your new bot, send `/start`, then type the code. That chat is now the only authorized chat for this bot.
+
+## Don't
+
+- Don't ask for the token before step 1 (the user may not have created a bot yet).
+- Don't try to start the bot from this skill — it's a long-running process; the CLI subcommand is the right entry point.
+- Don't store the token in plaintext anywhere. The `telegram_set_token` tool persists to the encrypted vault.
+- If the user already has `telegram_status.tokenConfigured = true`, ask if they want to replace the existing token before overwriting.

package/dist/skills/vault-setup.md

@@ -0,0 +1,48 @@
+---
+name: vault-setup
+description: Help the user store secrets in the encrypted vault via the /vault command, without the secret ever reaching the model.
+triggers: ["set up vault", "initialize vault", "store a secret", "save api key", "need an api key", "provide your key"]
+allowed-tools: [vault_status, vault_list]
+---
+# Vault setup
+
+The user wants to store secrets (API keys, tokens, webhook URLs) in moxxy's encrypted vault.
+
+## The golden rule: never handle the plaintext yourself
+
+**Never ask the user to paste a secret into the chat, and never call a tool with a secret value the user gave you.** Anything the user types to you, and any tool argument you send, is visible to you (the model) and is recorded in the conversation. Secrets must not flow through there.
+
+Instead, **the user stores the secret themselves** with the `/vault` slash command. Its argument is intercepted by the channel and never sent to you — you only ever learn the *reference*.
+
+## How to get a secret stored
+
+When you need a secret from the user (e.g. an API key for a platform), tell them to run:
+
+```
+/vault set <NAME> <value>
+```
+
+For example: "I need your OpenAI API key. Please run `/vault set OPENAI_API_KEY <your-key>` — the value stays local and I'll only get a reference to it." Then **stop and wait** for the user; don't keep working until they confirm.
+
+After they run it, you'll receive a short note confirming the secret was stored and giving you the reference `${vault:<NAME>}`. Use that reference — you will never see the value.
+
+Naming: use slug-style names like `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `slack_webhook_url` (letters, digits, `_`, `.`, `-`).
+
+## Using a stored secret
+
+- In `moxxy.config.ts` / `moxxy.config.yaml`: write `${vault:OPENAI_API_KEY}` anywhere a string is expected. The CLI resolves it on session start.
+- For a tool/integration that needs the value at call time: pass the `${vault:NAME}` reference where supported, or let the integration resolve it — do not fetch and inline the plaintext.
+
+## Where things live
+
+`~/.moxxy/vault.json` — AES-256-GCM ciphertext per entry. The master key comes from the OS keychain (macOS Keychain / libsecret / Windows Credential Manager) when available, otherwise a passphrase prompt; on headless systems set `MOXXY_VAULT_PASSPHRASE`. The first vault use triggers the unlock.
+
+## Verify
+
+Call `vault_list` (names + metadata only, never plaintext) or have the user run `/vault list` to confirm the entry is present.
+
+## Don't
+
+- Don't ask the user to type or paste a secret value into the chat — direct them to `/vault set` instead.
+- Don't print the plaintext of an existing secret. If the user wants to verify, suggest they run `/vault list`.
+- Don't reuse a name for two different secrets — storing overwrites silently.

package/dist/skills/web-research.md

@@ -0,0 +1,53 @@
+---
+name: web-research
+description: Research a topic on the web — pick the lightest browser tier that gets the answer.
+triggers: ["look up", "research", "find on the web", "browse to", "open page", "scrape", "fetch url"]
+allowed-tools: [web_fetch, browser_session]
+---
+
+# Web research
+
+Pick the lightest tier that still answers the question.
+
+## Tier 1 — `web_fetch` (default)
+
+Use for: single static page, public docs, RSS, JSON endpoints, well-known cached pages, anything where the answer is in the initial HTML server response.
+
+```
+web_fetch({ url, format: "markdown" })
+```
+
+`format: "text"` is fine for prose, `"markdown"` keeps headings + links + lists, `"raw"` returns the body untouched (for JSON or HTML you need to parse). Pass `selector: "main"` or `selector: "#content"` to extract a single block from a noisy page.
+
+Heuristic: try `web_fetch` first. If the result is empty, looks like a JS shell ("loading...", "you need to enable javascript"), or the page clearly needs interaction (login, cookies, modals, infinite scroll), escalate to Tier 2.
+
+## Tier 2 — `browser_session` (Playwright)
+
+Use for: JS-heavy SPAs, pages that require clicks/fills, pages with anti-bot detection that browser fingerprinting bypasses, screenshots, anything stateful across multiple actions.
+
+```
+browser_session({ action: { kind: "goto", url, waitUntil: "networkidle" } })
+browser_session({ action: { kind: "text", selector: "main" } })   // or no selector for whole body
+browser_session({ action: { kind: "click", selector: "button.show-more" } })
+browser_session({ action: { kind: "fill", selector: "input[name=q]", value: "query" } })
+browser_session({ action: { kind: "screenshot", fullPage: true } })
+```
+
+Calls within a turn share the same page — `goto` then `click` then `text` is the common pattern.
+
+`browser_session` requires Playwright installed in the moxxy install dir. If you get an "init" error mentioning playwright, instruct the user to:
+```
+npm i playwright && npx playwright install
+```
+Then retry, or fall back to `web_fetch` if the page works without JS.
+
+## Don't
+
+- Don't loop `web_fetch` calls scraping a paginated site — for that you want a small script or `browser_session` with explicit `click`s.
+- Don't `eval` arbitrary user JS via `browser_session.eval` for "convenience." Use `text` / `click` / `fill` instead; `eval` should be the last resort when you genuinely need to read computed state.
+- Don't fetch the same URL repeatedly within a turn — cache the result mentally and re-quote it.
+- Don't request `screenshot` unless the user explicitly asked for one. Image bytes inflate the context.
+
+## Report back
+
+After the research is done, summarize concisely. Quote source URLs inline (the response already includes the resolved URL from `web_fetch` and `browser_session.url`). If multiple sources contradicted, say so.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@moxxy/cli",
+  "version": "0.0.0",
+  "description": "moxxy command-line binary. Subcommand dispatcher consuming the moxxy SDK.",
+  "type": "module",
+  "main": "./dist/bin.js",
+  "bin": {
+    "moxxy": "./dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsx scripts/gen-requirements.mts && tsup",
+    "prepack": "node scripts/prepack.mjs",
+    "postpack": "node scripts/postpack.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo",
+    "start": "node ./dist/bin.js"
+  },
+  "dependencies": {
+    "@moxxy/sdk": "workspace:*",
+    "zod": "catalog:"
+  },
+  "optionalDependencies": {
+    "@huggingface/transformers": "^3.0.0",
+    "keytar": "^7.9.0",
+    "playwright": "^1.40.0"
+  },
+  "devDependencies": {
+    "@clack/prompts": "catalog:",
+    "@types/node": "catalog:",
+    "@types/react": "catalog:",
+    "ink": "catalog:",
+    "punycode": "^2.3.1",
+    "react": "catalog:",
+    "tsup": "catalog:",
+    "tsx": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}