happy2 0.0.12 → 0.0.14

package/packages/happy2-server/plugins/plugin-developer/skills/happy2-plugin-development/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: happy2-plugin-development
+description: Build, package, validate, install, inspect, and troubleshoot Happy2 server plugins. Use when a user asks to create a Happy2 plugin, add Agent Skills or an MCP server to one, package a plugin ZIP, install from a ZIP or HTTPS link, understand plugin permissions and containers, or diagnose plugin installation/runtime health.
+---
+
+# Happy2 plugin development
+
+Build against Happy2's server-plugin contract. Do not substitute Codex, Claude, browser-extension, or Conductor plugin formats; they are unrelated.
+
+## Start with the product boundary
+
+1. Identify the useful capability and decide whether it belongs in an Agent Skill, an MCP tool server, a persistent container command, or a combination.
+2. Keep the package focused. One plugin may contain several closely related skills or tools, but do not make it a miscellaneous bundle.
+3. Treat installation as system-wide administrator state. A chat agent may request installation, but Happy2 installs only after a human administrator approves the chat card.
+4. Never claim that MCP elicitation itself grants Happy2 authority. Happy2 owns the durable approval, audit, package snapshot, and runtime lifecycle.
+
+Read [references/package-format.md](references/package-format.md) before authoring `plugin.json` or arranging files. Read [references/installing.md](references/installing.md) before packaging, installing, updating, or uninstalling. Read [references/host-api.md](references/host-api.md) before requesting host capabilities from a local plugin container.
+
+## Choose components
+
+- Use a skill for reusable instructions, project conventions, workflows, references, scripts, and assets that an agent should load into context.
+- Use MCP for typed operations the agent should call. Keep tool schemas closed, concrete, bounded, and explicit about side effects.
+- Use a persistent container command for an indexer, watcher, worker, or daemon that must stay alive for the installation lifetime.
+- Combine a command and stdio MCP only when they genuinely share one immutable package and isolated installation container.
+- Use remote MCP only for an already-hosted public HTTPS MCP endpoint with static header-template authentication. Happy2 does not add OAuth on behalf of a plugin.
+
+## Build workflow
+
+1. Create a kebab-case package directory and make `plugin.json.shortName` match it.
+2. Add a square `plugin.png`; prefer 1024×1024.
+3. Write schema-version-1 `plugin.json` with strict SemVer, user-facing metadata, and only supported fields.
+4. Put each skill at `skills/<skill-name>/SKILL.md`; match its frontmatter `name` to the directory.
+5. For local MCP or commands, add a package-relative Dockerfile and ensure the image contains `/bin/sh`.
+6. Make stdio MCP write newline-delimited JSON-RPC only to stdout. Send logs to stderr.
+7. Declare the smallest exact host permission allowlist. Unknown permissions make the package invalid.
+8. Create a ZIP whose root is the package root, or whose only top-level directory is the package root.
+9. Install directly as an administrator, or use `happy2_plugin_install_from_link` to create a chat approval for a public HTTPS ZIP.
+10. Inspect installation health and correct the package/configuration rather than hiding a failed state.
+
+## Security invariants
+
+- Do not include symlinks, device files, traversal paths, encrypted ZIP entries, or generated dependency caches.
+- Never bake secrets into the ZIP, image, manifest, URL, arguments, or skill.
+- Declare required variables in the manifest. Happy2 encrypts `secret` values and injects both secret and text values only into configured processes.
+- Do not ask an agent to collect a plugin secret in chat. Plugins requiring variables or an administrator-selected image must use the direct administrator install flow.
+- Assume package files become immutable after the first system installation. A changed link does not silently rewrite an installed plugin.
+- Treat the package icon, display name, and description as untrusted publisher material that Happy2 validates and shows in approval UI.
+- A plugin runtime token is not a user session. It grants only manifest-declared host capabilities for one live container incarnation.
+- A contextual chat token is short-lived and bound to the originating Rig session, external-tool call, agent, human actor, and chat. Never persist or forward it.
+
+## Completion checklist
+
+- `plugin.json`, `plugin.png`, and at least one skill/container/MCP component exist.
+- Short name, directory name, skill names, referenced paths, variables, headers, permissions, and SemVer validate.
+- The ZIP stays within Happy2's package limits and contains no unsafe entry.
+- MCP initialization, ping, paginated tool listing, and representative tool calls work.
+- Side-effecting tools have bounded inputs, clear descriptions, and their own idempotency where external ambiguity matters.
+- Installation reaches `ready`, or a specific expected failure is explained.
+- The result is tested in a fresh agent turn so Rig receives the current durable tool catalog.

package/packages/happy2-server/plugins/plugin-developer/skills/happy2-plugin-development/references/host-api.md

@@ -0,0 +1,63 @@
+# Capability-scoped plugin host API
+
+## Runtime environment
+
+Local plugin processes receive:
+
+- `HAPPY2_PLUGIN_API_URL`: the dedicated capability-only host listener.
+- `HAPPY2_PLUGIN_API_TOKEN`: an RS256 token for one installed plugin and live container incarnation.
+
+Send `Authorization: Bearer <token>`. Do not persist, log, return, or forward either value.
+
+## List plugins
+
+Manifest permission: `plugins:list`
+
+```http
+GET /plugins
+Authorization: Bearer …
+```
+
+The response includes the calling installation ID and non-secret installation identity, short name, version, and status. It does not expose variables, users, filesystem paths, package internals, or administrator APIs.
+
+## Request linked installation
+
+Manifest permission: `plugins:request-install`
+
+```http
+POST /plugin-install-requests
+Authorization: Bearer …
+Content-Type: application/json
+
+{
+  "sourceUrl": "https://downloads.example.com/plugin.zip",
+  "reason": "Adds the formatter requested in this chat."
+}
+```
+
+This endpoint additionally requires a short-lived contextual token issued only while Happy2 executes an MCP tool for a running Rig turn. The token binds the request to the external-tool call, session, agent, human actor, and chat. A persistent plugin command or a non-contextual health probe receives 403 even if its base manifest declares the permission.
+
+The endpoint downloads, extracts, fully validates, and snapshots the package before it creates the approval. It returns HTTP 202 and an approval summary. It does not install synchronously.
+
+## Request uninstall
+
+Manifest permission: `plugins:request-uninstall`
+
+```http
+POST /plugin-uninstall-requests
+Authorization: Bearer …
+Content-Type: application/json
+
+{
+  "installationId": "the installation ID from GET /plugins",
+  "reason": "The user no longer needs this integration."
+}
+```
+
+This endpoint has the same contextual-call requirement. It snapshots the installed plugin's validated name, description, and icon into a pending chat card. Removal begins only after a chat-member server administrator approves it.
+
+## Trust model
+
+Manifest permissions are exact capabilities, not descriptive labels. Happy2 verifies the token signature, installation, container-incarnation ID, database health, and matching live OCI container on every host request. Stopping, replacing, failing, or uninstalling that incarnation invalidates the token without a process-local revocation list.
+
+The host listener is deliberately separate from `/v0`. A plugin cannot exchange its capability for a human session, choose a different chat for approval, or call arbitrary product APIs.

package/packages/happy2-server/plugins/plugin-developer/skills/happy2-plugin-development/references/installing.md

@@ -0,0 +1,86 @@
+# Packaging, installation, and removal
+
+## Contents
+
+1. Create the ZIP
+2. Direct ZIP install
+3. Direct HTTPS-link install
+4. Chat approval install
+5. Health and listing
+6. Uninstall
+7. Version changes
+
+## Create the ZIP
+
+From the parent of `my-plugin/`:
+
+```sh
+zip -r my-plugin.zip my-plugin \
+  -x '*/node_modules/*' '*/.git/*' '*/.DS_Store'
+```
+
+Happy2 accepts either package files at the archive root or exactly one top-level directory containing `plugin.json`. Do not include symlinks, secrets, build caches, sockets, device nodes, or unrelated project files.
+
+## Direct ZIP install
+
+An authenticated server administrator posts multipart form data:
+
+```sh
+curl -X POST "$HAPPY2_URL/v0/admin/plugins/installPlugin" \
+  -H "Authorization: Bearer $HAPPY2_TOKEN" \
+  -F "archive=@my-plugin.zip;type=application/zip" \
+  -F 'variables={}'
+```
+
+For declared variables, supply one JSON object. For a plugin without a bundled local image, also supply `containerImageId` as a multipart field.
+
+## Direct HTTPS-link install
+
+```sh
+curl -X POST "$HAPPY2_URL/v0/admin/plugins/installPlugin" \
+  -H "Authorization: Bearer $HAPPY2_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "sourceUrl": "https://downloads.example.com/my-plugin.zip",
+    "variables": {}
+  }'
+```
+
+Happy2 accepts public HTTPS on approved ports, rejects credentials/fragments/private destinations, revalidates redirects, pins DNS, caps the response at 20 MiB, validates the ZIP, and snapshots the exact package.
+
+## Chat approval install
+
+Use the `happy2_plugin_install_from_link` MCP tool when the user wants the agent to install a public linked package. Provide the URL and a concise reason. Happy2 downloads and validates first, then records the validated icon, name, description, source, digest, requesting plugin, agent, originating human, Rig call, and chat.
+
+The tool returns after posting a pending request. It does not wait and does not install. A chat-member server administrator approves or denies the durable card. Approval installs the staged immutable bytes with a predetermined installation ID; denial leaves no running plugin.
+
+Chat installation rejects packages needing variables or an administrator-selected image. Direct the user to the administrator form for those packages; never solicit secrets in chat.
+
+## Health and listing
+
+An accepted install returns HTTP 202 with an installation. Runtime work continues asynchronously through `preparing`, `starting`, and `ready`, or ends in `broken_configuration` or `failed` with bounded details.
+
+Use the `happy2_plugins_list` tool from the developer plugin, or call:
+
+```sh
+curl "$HAPPY2_URL/v0/admin/systemPlugins" \
+  -H "Authorization: Bearer $HAPPY2_TOKEN"
+```
+
+One durable system plugin may have multiple independent installations. Use installation IDs—not short names—when inspecting health or removing an instance.
+
+## Uninstall
+
+```sh
+curl -X POST \
+  "$HAPPY2_URL/v0/admin/pluginInstallations/INSTALLATION_ID/uninstallPlugin" \
+  -H "Authorization: Bearer $HAPPY2_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{}'
+```
+
+Uninstall stops and removes that installation's runtime, encrypted variables, cached MCP tools, and durable installation. When it was the final installation, Happy2 also removes the system-plugin row and private package/image snapshot. Other installations remain intact.
+
+## Version changes
+
+Installed bytes are immutable. Reusing the same source installs another instance of the stored system package. A built-in catalog digest change is reported as `updateAvailable`; it does not silently mutate existing installations. If a different source tries to claim an installed short name, Happy2 rejects the collision. Publish intentional version changes as explicit package/update work, not by replacing bytes behind a stable URL and assuming they will be adopted.

package/packages/happy2-server/plugins/plugin-developer/skills/happy2-plugin-development/references/package-format.md

@@ -0,0 +1,137 @@
+# Happy2 package format
+
+## Contents
+
+1. Package tree
+2. Manifest fields
+3. Skills
+4. Local containers and stdio MCP
+5. Remote MCP
+6. Variables and permissions
+7. Validation limits
+
+## Package tree
+
+```text
+my-plugin/
+├── plugin.json
+├── plugin.png
+├── server.mjs                 # optional
+├── container/
+│   └── Dockerfile             # optional
+└── skills/
+    └── my-plugin-workflow/
+        ├── SKILL.md
+        ├── references/        # optional
+        ├── scripts/           # optional
+        └── assets/            # optional
+```
+
+`plugin.png` is required, must be PNG, must be square, and may be at most 4096×4096. Happy2 records its dimensions, bytes, SHA-256 checksum, and thumbhash, then keeps the exact image in the immutable installed snapshot.
+
+The entire package may contain at most 1,000 files and 20 MiB uncompressed. One file may be at most 5 MiB. Symlinks and non-files are rejected.
+
+## Manifest fields
+
+```json
+{
+    "schemaVersion": 1,
+    "version": "1.2.3",
+    "displayName": "Project Search",
+    "shortName": "project-search",
+    "description": "Searches project source and documentation.",
+    "variables": []
+}
+```
+
+- `schemaVersion` must be `1`.
+- `version` must be strict SemVer.
+- `shortName` is lower-case kebab-case and at most 64 characters. It must match a built-in package directory; an uploaded/downloaded ZIP may use any enclosing folder name.
+- `displayName` is at most 100 characters.
+- `description` is at most 1,000 characters.
+- `variables` defaults conceptually to none, but write the explicit array.
+- A package must contain at least one discovered skill, `container`, or `mcp`.
+- Unknown manifest fields are rejected.
+
+## Skills
+
+Every direct child of `skills/` is one Agent Skill. It must contain `SKILL.md` with YAML frontmatter:
+
+```markdown
+---
+name: project-search
+description: Search this project's indexed source and docs. Use when an agent needs to locate code, symbols, or design documentation.
+---
+```
+
+The name matches the skill directory and uses lower-case kebab-case. Put detailed material in one-level `references/` files and deterministic reusable helpers in `scripts/`. Do not make the core skill a dump of material the agent rarely needs.
+
+## Local containers and stdio MCP
+
+Bundled runtime:
+
+```json
+{
+    "container": {
+        "dockerfile": "container/Dockerfile",
+        "command": "/plugin/bin/indexer",
+        "args": ["--watch"],
+        "permissions": ["plugins:list"]
+    },
+    "mcp": {
+        "type": "stdio",
+        "command": "node",
+        "args": ["/plugin/server.mjs"]
+    }
+}
+```
+
+The optional persistent `container.command` and each stdio MCP process run in the same dedicated installation container. The image root is read-only at runtime. `/tmp` and `/run` are ephemeral and writable. `HOME`, `TMPDIR`, and the working directory are `/tmp`.
+
+If a stdio MCP is the only local component, older manifests may put a bundled Dockerfile under `mcp.container`; new packages should use `container.dockerfile` so one container definition owns permissions and both processes.
+
+Without `container.dockerfile`, direct installation must provide a ready Happy2 agent-image ID. Chat-requested installation intentionally rejects that package because an administrator must make the image choice.
+
+## Remote MCP
+
+```json
+{
+    "variables": [
+        {
+            "key": "PROJECT_TOKEN",
+            "displayName": "API token",
+            "description": "Token sent to the project MCP server.",
+            "kind": "secret"
+        }
+    ],
+    "mcp": {
+        "type": "remote",
+        "url": "https://mcp.example.com/mcp",
+        "headers": {
+            "Authorization": "Bearer ${PROJECT_TOKEN}"
+        }
+    }
+}
+```
+
+Remote URLs are public HTTPS URLs without embedded credentials or fragments. Happy2 resolves and pins public addresses to prevent DNS rebinding. Header templates may reference only declared variables; every remote variable must be used. Hop-by-hop, proxy, host, content, MCP protocol, and other Happy-managed headers are reserved.
+
+Remote MCP cannot share a local plugin container. OAuth is not part of schema version 1.
+
+## Variables and permissions
+
+Variable keys use environment-variable syntax. Each installation must provide every declared variable and no extra keys. Use `secret` for credentials and `text` for non-secret configuration. Values must be non-empty and no larger than 64 KiB.
+
+Supported local host permissions:
+
+- `plugins:list`: read non-secret installed-plugin identity and health.
+- `plugins:request-install`: during a contextual agent tool call, stage a linked ZIP and create a durable approval in that exact chat.
+- `plugins:request-uninstall`: during a contextual agent tool call, create a durable approval to remove one exact installation.
+
+The host API is capability-only and separate from the product API. It exposes neither user sessions nor arbitrary server routes.
+
+## Validation limits
+
+Happy2 rejects unsafe relative paths, missing referenced Dockerfiles, malformed skill frontmatter, duplicate skill names, invalid SemVer, duplicate variables/permissions, unsupported fields, non-square icons, oversized packages, and packages with no functional component.
+
+The installed package digest covers every relative filename, byte length, and byte. Container image tags are content-addressed from that digest. Mutating source files later does not mutate a durable installation.