npm - happy2 - Versions diffs - 0.0.13 → 0.0.14 - Mend

happy2 0.0.13 → 0.0.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (213) hide show

package/packages/happy2-server/dist/web/index.html CHANGED Viewed

@@ -13,8 +13,8 @@
                 background: #131217;
             }
         </style>
-      <script type="module" crossorigin src="/assets/index-BnhFxR3U.js"></script>
-      <link rel="stylesheet" crossorigin href="/assets/index-BaPUPGPe.css">
+      <script type="module" crossorigin src="/assets/index-Dn5SZu3y.js"></script>
+      <link rel="stylesheet" crossorigin href="/assets/index-Dys3sWv8.css">
     </head>
     <body>
         <div id="root"></div>

package/packages/happy2-server/drizzle/0028_plugin_api_permissions.sql ADDED Viewed

	@@ -0,0 +1 @@
1	+ ALTER TABLE `plugin_installations` ADD `granted_permissions_json` text DEFAULT '[]' NOT NULL;

package/packages/happy2-server/drizzle/0029_plugin_management_requests.sql ADDED Viewed

@@ -0,0 +1,35 @@
+CREATE TABLE `plugin_management_requests` (
+	`id` text PRIMARY KEY NOT NULL,
+	`action` text NOT NULL,
+	`status` text DEFAULT 'pending' NOT NULL,
+	`chat_id` text NOT NULL,
+	`actor_user_id` text,
+	`agent_user_id` text,
+	`requester_installation_id` text,
+	`call_id` text NOT NULL,
+	`display_name` text NOT NULL,
+	`short_name` text NOT NULL,
+	`description` text NOT NULL,
+	`reason` text,
+	`source_kind` text,
+	`source_reference` text,
+	`package_digest` text,
+	`package_directory` text,
+	`target_installation_id` text,
+	`installation_id` text,
+	`resolved_by_user_id` text,
+	`resolved_at` text,
+	`last_error` text,
+	`sync_sequence` integer DEFAULT 0 NOT NULL,
+	`created_at` text DEFAULT CURRENT_TIMESTAMP NOT NULL,
+	`updated_at` text DEFAULT CURRENT_TIMESTAMP NOT NULL,
+	FOREIGN KEY (`chat_id`) REFERENCES `chats`(`id`) ON UPDATE no action ON DELETE cascade,
+	FOREIGN KEY (`actor_user_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE set null,
+	FOREIGN KEY (`agent_user_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE set null,
+	FOREIGN KEY (`requester_installation_id`) REFERENCES `plugin_installations`(`id`) ON UPDATE no action ON DELETE set null,
+	FOREIGN KEY (`resolved_by_user_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE set null
+);
+--> statement-breakpoint
+CREATE INDEX `plugin_management_requests_chat_index` ON `plugin_management_requests` (`chat_id`,`created_at`);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `plugin_management_requests_call_unique` ON `plugin_management_requests` (`requester_installation_id`,`call_id`,`action`);

package/packages/happy2-server/drizzle/meta/_journal.json CHANGED Viewed

@@ -197,6 +197,20 @@
             "when": 1784427000000,
             "tag": "0027_chat_agent_effort",
             "breakpoints": true
+        },
+        {
+            "idx": 28,
+            "version": "6",
+            "when": 1784430000000,
+            "tag": "0028_plugin_api_permissions",
+            "breakpoints": true
+        },
+        {
+            "idx": 29,
+            "version": "6",
+            "when": 1784433600000,
+            "tag": "0029_plugin_management_requests",
+            "breakpoints": true
         }
     ]
 }

package/packages/happy2-server/plugins/README.md CHANGED Viewed

@@ -4,6 +4,10 @@ Each child directory is one immutable, built-in plugin package. See
 [`../PLUGINS.md`](../PLUGINS.md) for the manifest and package contract.
 `hello` is the minimal built-in example with both a skill and a bundled stdio MCP
-tool. `chat-management` demonstrates a chat-scoped Plugin API capability without
-accepting a chat identifier from tool arguments. Product plugins should be added
-here as separate, reviewable changes.
+tool. `chat-management` demonstrates installation-bound chat and referenced-user
+capabilities: it updates the current chat, manages channel membership, and creates
+private channels with either an informational opening message or an agent-triggering
+prompt. `plugin-developer` provides Happy2 plugin authoring/install documentation
+and chat-scoped MCP tools that request administrator approval for linked install
+or uninstall actions. Product plugins should be added here as separate,
+reviewable changes.

package/packages/happy2-server/plugins/chat-management/plugin.json CHANGED Viewed

@@ -1,13 +1,13 @@
 {
     "schemaVersion": 1,
-    "version": "1.0.0",
+    "version": "1.1.0",
     "displayName": "Chat Management",
     "shortName": "chat-management",
-    "description": "Lets an agent update the title and description of its current chat.",
+    "description": "Lets an agent update its current chat, manage channel members, and create new channels with an initial people or agent message.",
     "variables": [],
     "container": {
         "dockerfile": "container/Dockerfile",
-        "permissions": ["chats:update"]
+        "permissions": ["chats:update", "channels:manage"]
     },
     "mcp": {
         "type": "stdio",

package/packages/happy2-server/plugins/chat-management/server.mjs CHANGED Viewed

@@ -1,6 +1,8 @@
 import { createInterface } from "node:readline";
+import { randomUUID } from "node:crypto";
 const CHAT_META_KEY = "happy2/chat";
+const USERS_META_KEY = "happy2/users";
 const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
 for await (const line of lines) {
@@ -32,7 +34,7 @@ async function handle(request) {
             result: {
                 protocolVersion: request.params?.protocolVersion ?? "2025-06-18",
                 capabilities: { tools: {} },
-                serverInfo: { name: "happy2-chat-management", version: "1.0.0" },
+                serverInfo: { name: "happy2-chat-management", version: "1.1.0" },
             },
         };
     }
@@ -66,48 +68,213 @@ async function handle(request) {
                             additionalProperties: false,
                         },
                     },
+                    {
+                        name: "channel_members_update",
+                        title: "Add or remove channel members",
+                        description:
+                            "Adds or removes users from the current channel. This never changes direct-message membership. Identify users by the @username shown in the triggering conversation; only users supplied in Happy's signed metadata are available.",
+                        inputSchema: {
+                            type: "object",
+                            properties: {
+                                addUsers: {
+                                    type: "array",
+                                    maxItems: 100,
+                                    uniqueItems: true,
+                                    items: { type: "string", minLength: 1 },
+                                    description: "Usernames (with or without @) to add.",
+                                },
+                                removeUsers: {
+                                    type: "array",
+                                    maxItems: 100,
+                                    uniqueItems: true,
+                                    items: { type: "string", minLength: 1 },
+                                    description: "Usernames (with or without @) to remove.",
+                                },
+                            },
+                            anyOf: [{ required: ["addUsers"] }, { required: ["removeUsers"] }],
+                            additionalProperties: false,
+                        },
+                    },
+                    {
+                        name: "channel_create",
+                        title: "Create a channel",
+                        description:
+                            "Creates a private channel owned by the user who triggered this turn, adds selected referenced users, and optionally posts an initial message. An agents message starts the current agent working; a people message only shares context and does not trigger inference.",
+                        inputSchema: {
+                            type: "object",
+                            properties: {
+                                name: {
+                                    type: "string",
+                                    minLength: 1,
+                                    maxLength: 100,
+                                    description: "Channel title.",
+                                },
+                                description: {
+                                    type: "string",
+                                    minLength: 1,
+                                    maxLength: 500,
+                                    description: "Optional channel description.",
+                                },
+                                members: {
+                                    type: "array",
+                                    maxItems: 100,
+                                    uniqueItems: true,
+                                    items: { type: "string", minLength: 1 },
+                                    description:
+                                        "Referenced usernames (with or without @) to add. The triggering user is already the owner.",
+                                },
+                                initialMessage: {
+                                    type: "object",
+                                    properties: {
+                                        text: {
+                                            type: "string",
+                                            minLength: 1,
+                                            maxLength: 40000,
+                                            description:
+                                                "A copied or rephrased opening prompt or informational message.",
+                                        },
+                                        audience: {
+                                            type: "string",
+                                            enum: ["agents", "people"],
+                                            description:
+                                                "agents starts the current agent; people posts without inference.",
+                                        },
+                                    },
+                                    required: ["text", "audience"],
+                                    additionalProperties: false,
+                                },
+                            },
+                            required: ["name"],
+                            additionalProperties: false,
+                        },
+                    },
                 ],
             },
         };
     }
     if (request.method === "tools/call" && request.params?.name === "chat_update")
         return { result: await updateChat(request.params) };
+    if (request.method === "tools/call" && request.params?.name === "channel_members_update")
+        return { result: await updateChannelMembers(request.params) };
+    if (request.method === "tools/call" && request.params?.name === "channel_create")
+        return { result: await createChannel(request.params) };
     return {
         error: { code: -32601, message: `Method not found: ${String(request.method)}` },
     };
 }
 async function updateChat(params) {
+    const { chat } = capabilityContext(params);
+    const input = params.arguments;
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new Error("A chat update is required.");
+    const result = await callHost("/chats/updateChat", chat.token, input);
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Updated chat ${result.chat.id}.`,
+            },
+        ],
+        structuredContent: { chat: result.chat },
+    };
+}
+async function updateChannelMembers(params) {
+    const { chat, users } = capabilityContext(params);
+    const input = params.arguments;
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new Error("A channel membership update is required.");
+    const add = resolveUsers(input.addUsers ?? [], users, "addUsers");
+    const remove = resolveUsers(input.removeUsers ?? [], users, "removeUsers");
+    if (!add.length && !remove.length)
+        throw new Error("At least one user must be added or removed.");
+    const result = await callHost("/channels/updateMembers", chat.token, { add, remove });
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Updated members of channel ${result.chatId}: added ${result.addedUserIds.length}, removed ${result.removedUserIds.length}.`,
+            },
+        ],
+        structuredContent: result,
+    };
+}
+async function createChannel(params) {
+    const { chat, users } = capabilityContext(params);
+    const input = params.arguments;
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new Error("A channel definition is required.");
+    const members = resolveUsers(input.members ?? [], users, "members");
+    const result = await callHost("/channels/createChannel", chat.token, {
+        ...input,
+        members,
+        idempotencyKey: randomUUID(),
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Created channel ${result.chat.id}${result.initialMessage ? " and posted its initial message" : ""}.`,
+            },
+        ],
+        structuredContent: result,
+    };
+}
+function capabilityContext(params) {
     const chat = params?._meta?.[CHAT_META_KEY];
     if (!chat || typeof chat.id !== "string" || typeof chat.token !== "string")
         throw new Error("This tool must be called from an active Happy chat.");
+    const users = params?._meta?.[USERS_META_KEY];
+    if (!Array.isArray(users)) throw new Error("Happy did not provide referenced-user metadata.");
+    return { chat, users };
+}
+function resolveUsers(selectors, users, name) {
+    if (!Array.isArray(selectors)) throw new Error(`${name} must be an array.`);
+    const resolved = selectors.map((selector) => {
+        if (typeof selector !== "string" || !selector.trim())
+            throw new Error(`${name} must contain usernames.`);
+        const normalized = selector.trim().replace(/^@/, "").toLowerCase();
+        const matches = users.filter(
+            (user) =>
+                user &&
+                typeof user === "object" &&
+                (user.id === selector.trim() ||
+                    (typeof user.username === "string" &&
+                        user.username.toLowerCase() === normalized)),
+        );
+        if (matches.length !== 1)
+            throw new Error(`User ${selector} is not uniquely available in this turn.`);
+        const user = matches[0];
+        if (typeof user.id !== "string" || typeof user.token !== "string")
+            throw new Error(`User ${selector} has malformed capability metadata.`);
+        return { id: user.id, token: user.token };
+    });
+    if (new Set(resolved.map(({ id }) => id)).size !== resolved.length)
+        throw new Error(`${name} contains a duplicate user.`);
+    return resolved;
+}
+async function callHost(path, chatToken, body) {
     const apiUrl = process.env.HAPPY2_PLUGIN_API_URL;
     const runtimeToken = process.env.HAPPY2_PLUGIN_API_TOKEN;
     if (!apiUrl || !runtimeToken) throw new Error("The Happy Plugin API is unavailable.");
-    const input = params.arguments;
-    if (!input || typeof input !== "object" || Array.isArray(input))
-        throw new Error("A chat update is required.");
-    const response = await fetch(`${apiUrl}/chats/updateChat`, {
+    const response = await fetch(`${apiUrl}${path}`, {
         method: "POST",
         headers: {
             authorization: `Bearer ${runtimeToken}`,
             "content-type": "application/json",
-            "x-happy2-chat-token": chat.token,
+            "x-happy2-chat-token": chatToken,
         },
-        body: JSON.stringify(input),
+        body: JSON.stringify(body),
     });
     const result = await response.json().catch(() => undefined);
     if (!response.ok)
         throw new Error(
-            typeof result?.message === "string" ? result.message : "The chat could not be updated.",
+            typeof result?.message === "string" ? result.message : "The chat action failed.",
         );
-    return {
-        content: [
-            {
-                type: "text",
-                text: `Updated chat ${result.chat.id}.`,
-            },
-        ],
-        structuredContent: { chat: result.chat },
-    };
+    return result;
 }

package/packages/happy2-server/plugins/plugin-developer/container/Dockerfile ADDED Viewed

@@ -0,0 +1,6 @@
+FROM node:22-alpine
+WORKDIR /plugin
+COPY server.mjs /plugin/server.mjs
+CMD ["sleep", "infinity"]

package/packages/happy2-server/plugins/plugin-developer/plugin.json ADDED Viewed

@@ -0,0 +1,17 @@
+{
+    "schemaVersion": 1,
+    "version": "1.0.0",
+    "displayName": "Plugin Developer",
+    "shortName": "plugin-developer",
+    "description": "Helps agents design, validate, inspect, and request installation of Happy2 plugins.",
+    "variables": [],
+    "container": {
+        "dockerfile": "container/Dockerfile",
+        "permissions": ["plugins:list", "plugins:request-install", "plugins:request-uninstall"]
+    },
+    "mcp": {
+        "type": "stdio",
+        "command": "node",
+        "args": ["/plugin/server.mjs"]
+    }
+}

package/packages/happy2-server/plugins/plugin-developer/plugin.png ADDED Viewed

Binary file

package/packages/happy2-server/plugins/plugin-developer/server.mjs ADDED Viewed

@@ -0,0 +1,155 @@
+import { createInterface } from "node:readline";
+async function handle(request) {
+    if (request.method === "initialize") {
+        return {
+            result: {
+                protocolVersion: request.params?.protocolVersion ?? "2025-06-18",
+                capabilities: { tools: {} },
+                serverInfo: { name: "happy2-plugin-developer", version: "1.0.0" },
+            },
+        };
+    }
+    if (request.method === "ping") return { result: {} };
+    if (request.method === "tools/list") return { result: { tools } };
+    if (request.method === "tools/call") return callTool(request.params);
+    return { error: { code: -32601, message: `Method not found: ${String(request.method)}` } };
+}
+const tools = [
+    {
+        name: "happy2_plugins_list",
+        title: "List installed Happy2 plugins",
+        description:
+            "Lists installed Happy2 plugin identities, versions, installation IDs, and health.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "happy2_plugin_install_from_link",
+        title: "Request Happy2 plugin installation",
+        description:
+            "Downloads and validates a Happy2 plugin ZIP link, then posts a human approval request in the current chat. It never installs without approval.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sourceUrl: {
+                    type: "string",
+                    description: "Public HTTPS URL of a Happy2 plugin ZIP package.",
+                },
+                reason: {
+                    type: "string",
+                    description: "Short explanation of why this chat needs the plugin.",
+                },
+            },
+            required: ["sourceUrl"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "happy2_plugin_uninstall",
+        title: "Request Happy2 plugin uninstall",
+        description:
+            "Posts a human approval request in the current chat to uninstall one Happy2 plugin installation. It never uninstalls without approval.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                installationId: {
+                    type: "string",
+                    description: "Installation ID returned by happy2_plugins_list.",
+                },
+                reason: {
+                    type: "string",
+                    description: "Short explanation of why this installation should be removed.",
+                },
+            },
+            required: ["installationId"],
+            additionalProperties: false,
+        },
+    },
+];
+const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+for await (const line of lines) {
+    if (!line.trim()) continue;
+    let request;
+    try {
+        request = JSON.parse(line);
+    } catch {
+        continue;
+    }
+    if (request.id === undefined) continue;
+    const response = await handle(request).catch((error) => ({
+        result: {
+            isError: true,
+            content: [
+                { type: "text", text: error instanceof Error ? error.message : String(error) },
+            ],
+        },
+    }));
+    process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: request.id, ...response })}\n`);
+}
+async function callTool(params) {
+    if (params?.name === "happy2_plugins_list") {
+        const result = await hostRequest("GET", "/plugins");
+        return textResult(JSON.stringify(result, null, 2));
+    }
+    if (params?.name === "happy2_plugin_install_from_link") {
+        const sourceUrl = text(params.arguments?.sourceUrl, "sourceUrl", 4_096);
+        const reason = optionalText(params.arguments?.reason, "reason", 1_000);
+        const result = await hostRequest("POST", "/plugin-install-requests", {
+            sourceUrl,
+            ...(reason ? { reason } : {}),
+        });
+        return textResult(
+            `Happy2 posted an installation approval in this chat. Request: ${JSON.stringify(result.approval)}`,
+        );
+    }
+    if (params?.name === "happy2_plugin_uninstall") {
+        const installationId = text(params.arguments?.installationId, "installationId", 128);
+        const reason = optionalText(params.arguments?.reason, "reason", 1_000);
+        const result = await hostRequest("POST", "/plugin-uninstall-requests", {
+            installationId,
+            ...(reason ? { reason } : {}),
+        });
+        return textResult(
+            `Happy2 posted an uninstall approval in this chat. Request: ${JSON.stringify(result.approval)}`,
+        );
+    }
+    return { result: { isError: true, content: [{ type: "text", text: "Unknown tool" }] } };
+}
+async function hostRequest(method, path, body) {
+    const base = process.env.HAPPY2_PLUGIN_API_URL;
+    const token = process.env.HAPPY2_PLUGIN_API_TOKEN;
+    if (!base || !token) throw new Error("Happy2 plugin host API is unavailable");
+    const response = await fetch(new URL(path, base), {
+        method,
+        headers: {
+            authorization: `Bearer ${token}`,
+            ...(body ? { "content-type": "application/json" } : {}),
+        },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    const result = await response.json().catch(() => undefined);
+    if (!response.ok)
+        throw new Error(
+            result?.message ?? `Happy2 plugin host API returned HTTP ${response.status}`,
+        );
+    return result;
+}
+function textResult(text) {
+    return { result: { content: [{ type: "text", text }] } };
+}
+function text(value, name, maximum) {
+    if (typeof value !== "string" || !value.trim() || value.length > maximum)
+        throw new Error(`${name} must contain between 1 and ${maximum} characters`);
+    return value.trim();
+}
+function optionalText(value, name, maximum) {
+    return value === undefined ? undefined : text(value, name, maximum);
+}

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

@@ -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 ADDED Viewed

@@ -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.