happy2 0.0.13 → 0.0.14

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.

package/packages/happy2-server/dist/modules/agent/agentChatGetIdBySession.d.ts

@@ -1,7 +0,0 @@
-import type { DrizzleExecutor } from "../drizzle.js";
-/**
- * Resolves the one current chat bound to a Rig session so agent-originated capabilities cannot be detached from their durable conversation.
- * Returning no ID for missing or ambiguous bindings prevents an external tool call from receiving authority over an inferred chat.
- */
-export declare function agentChatGetIdBySession(executor: DrizzleExecutor, sessionId: string): Promise<string | undefined>;
-//# sourceMappingURL=agentChatGetIdBySession.d.ts.map

package/packages/happy2-server/dist/modules/agent/agentChatGetIdBySession.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"agentChatGetIdBySession.d.ts","sourceRoot":"","sources":["../../../sources/modules/agent/agentChatGetIdBySession.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGrD;;;GAGG;AACH,wBAAsB,uBAAuB,CACzC,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO7B"}

package/packages/happy2-server/dist/modules/agent/agentChatGetIdBySession.js

@@ -1,15 +0,0 @@
-import { eq } from "drizzle-orm";
-import { agentRigBindings } from "../schema.js";
-/**
- * Resolves the one current chat bound to a Rig session so agent-originated capabilities cannot be detached from their durable conversation.
- * Returning no ID for missing or ambiguous bindings prevents an external tool call from receiving authority over an inferred chat.
- */
-export async function agentChatGetIdBySession(executor, sessionId) {
-    const rows = await executor
-        .select({ chatId: agentRigBindings.chatId })
-        .from(agentRigBindings)
-        .where(eq(agentRigBindings.sessionId, sessionId))
-        .limit(2);
-    return rows.length === 1 ? rows[0].chatId : undefined;
-}
-//# sourceMappingURL=agentChatGetIdBySession.js.map

package/packages/happy2-server/dist/modules/agent/agentChatGetIdBySession.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"agentChatGetIdBySession.js","sourceRoot":"","sources":["../../../sources/modules/agent/agentChatGetIdBySession.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CACzC,QAAyB,EACzB,SAAiB;IAEjB,MAAM,IAAI,GAAG,MAAM,QAAQ;SACtB,MAAM,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,MAAM,EAAE,CAAC;SAC3C,IAAI,CAAC,gBAAgB,CAAC;SACtB,KAAK,CAAC,EAAE,CAAC,gBAAgB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;SAChD,KAAK,CAAC,CAAC,CAAC,CAAC;IACd,OAAO,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3D,CAAC"}