happy2 0.0.12 → 0.0.14

package/packages/happy2-server/drizzle/0025_plugin_skills.sql

@@ -0,0 +1,8 @@
+CREATE TABLE `plugin_skills` (
+	`plugin_id` text NOT NULL,
+	`name` text NOT NULL,
+	`description` text NOT NULL,
+	`directory` text NOT NULL,
+	PRIMARY KEY(`plugin_id`, `name`),
+	FOREIGN KEY (`plugin_id`) REFERENCES `plugins`(`id`) ON UPDATE no action ON DELETE cascade
+);

package/packages/happy2-server/drizzle/0026_agent_turn_traces.sql

@@ -0,0 +1,35 @@
+ALTER TABLE `agent_turns` ADD `trace_latest_kind` text;
+--> statement-breakpoint
+ALTER TABLE `agent_turns` ADD `trace_latest_title` text;
+--> statement-breakpoint
+ALTER TABLE `agent_turns` ADD `trace_latest_detail` text;
+--> statement-breakpoint
+ALTER TABLE `agent_turns` ADD `trace_latest_at` integer;
+--> statement-breakpoint
+ALTER TABLE `agent_turns` ADD `trace_entry_count` integer DEFAULT 0 NOT NULL;
+--> statement-breakpoint
+ALTER TABLE `agent_turns` ADD `trace_subagents_json` text DEFAULT '[]' NOT NULL;
+--> statement-breakpoint
+ALTER TABLE `agent_turns` ADD `trace_background_terminals_json` text DEFAULT '[]' NOT NULL;
+--> statement-breakpoint
+CREATE TABLE `agent_turn_trace_entries` (
+	`id` text PRIMARY KEY NOT NULL,
+	`user_message_id` text NOT NULL,
+	`agent_user_id` text NOT NULL,
+	`trace_key` text NOT NULL,
+	`session_event_id` text NOT NULL,
+	`kind` text NOT NULL,
+	`title` text NOT NULL,
+	`detail` text,
+	`status` text NOT NULL,
+	`occurred_at` integer NOT NULL,
+	`completed_at` integer,
+	`created_at` text DEFAULT CURRENT_TIMESTAMP NOT NULL,
+	`updated_at` text DEFAULT CURRENT_TIMESTAMP NOT NULL,
+	FOREIGN KEY (`user_message_id`) REFERENCES `messages`(`id`) ON UPDATE no action ON DELETE cascade,
+	FOREIGN KEY (`agent_user_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `agent_turn_trace_entries_turn_key_unique` ON `agent_turn_trace_entries` (`user_message_id`,`agent_user_id`,`trace_key`);
+--> statement-breakpoint
+CREATE INDEX `agent_turn_trace_entries_turn_time_index` ON `agent_turn_trace_entries` (`user_message_id`,`agent_user_id`,`occurred_at`);

package/packages/happy2-server/drizzle/0027_chat_agent_effort.sql

@@ -0,0 +1,9 @@
+ALTER TABLE `agent_rig_bindings` ADD COLUMN `effort` TEXT;
+--> statement-breakpoint
+UPDATE `agent_rig_bindings`
+SET `effort` = (
+    SELECT `users`.`agent_effort`
+    FROM `users`
+    WHERE `users`.`id` = `agent_rig_bindings`.`user_id`
+)
+WHERE `effort` IS NULL;

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

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

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

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

@@ -162,6 +162,55 @@
             "when": 1784420000000,
             "tag": "0022_plugin_container_runtime_tools",
             "breakpoints": true
+        },
+        {
+            "idx": 23,
+            "version": "6",
+            "when": 1784421000000,
+            "tag": "0023_roles_and_permissions",
+            "breakpoints": true
+        },
+        {
+            "idx": 24,
+            "version": "6",
+            "when": 1784422000000,
+            "tag": "0024_session_bound_dev_tokens",
+            "breakpoints": true
+        },
+        {
+            "idx": 25,
+            "version": "6",
+            "when": 1784425000000,
+            "tag": "0025_plugin_skills",
+            "breakpoints": true
+        },
+        {
+            "idx": 26,
+            "version": "6",
+            "when": 1784426000000,
+            "tag": "0026_agent_turn_traces",
+            "breakpoints": true
+        },
+        {
+            "idx": 27,
+            "version": "6",
+            "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/happy2.example.toml

@@ -90,6 +90,12 @@ expiry_days = 30
 [auth.password]
 enabled = true
 
+# Allows an authenticated Settings session to create an opaque bearer token for
+# local web development. Every token inherits its backing session's expiry and
+# revocation; leave disabled on servers that do not need remote UI development.
+[auth.dev_tokens]
+enabled = false
+
 [auth.magic_link]
 enabled = false
 from = "Happy (2) <noreply@happy2.example.com>"

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

@@ -4,4 +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. 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/container/Dockerfile

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

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

@@ -0,0 +1,17 @@
+{
+    "schemaVersion": 1,
+    "version": "1.1.0",
+    "displayName": "Chat Management",
+    "shortName": "chat-management",
+    "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", "channels:manage"]
+    },
+    "mcp": {
+        "type": "stdio",
+        "command": "node",
+        "args": ["/plugin/server.mjs"]
+    }
+}

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

@@ -0,0 +1,280 @@
+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) {
+    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 : "The chat could not be updated.",
+                },
+            ],
+        },
+    }));
+    process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: request.id, ...response })}\n`);
+}
+
+async function handle(request) {
+    if (request.method === "initialize") {
+        return {
+            result: {
+                protocolVersion: request.params?.protocolVersion ?? "2025-06-18",
+                capabilities: { tools: {} },
+                serverInfo: { name: "happy2-chat-management", version: "1.1.0" },
+            },
+        };
+    }
+    if (request.method === "ping") return { result: {} };
+    if (request.method === "tools/list") {
+        return {
+            result: {
+                tools: [
+                    {
+                        name: "chat_update",
+                        title: "Update current chat",
+                        description:
+                            "Changes the title or description of the current chat. Omit a field to leave it unchanged; pass null or an empty string to clear the description.",
+                        inputSchema: {
+                            type: "object",
+                            properties: {
+                                title: {
+                                    type: "string",
+                                    minLength: 1,
+                                    maxLength: 100,
+                                    description: "The new title for the current chat.",
+                                },
+                                description: {
+                                    type: ["string", "null"],
+                                    maxLength: 500,
+                                    description:
+                                        "The new description, or null to clear the current description.",
+                                },
+                            },
+                            anyOf: [{ required: ["title"] }, { required: ["description"] }],
+                            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 response = await fetch(`${apiUrl}${path}`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${runtimeToken}`,
+            "content-type": "application/json",
+            "x-happy2-chat-token": chatToken,
+        },
+        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 action failed.",
+        );
+    return result;
+}

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

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

@@ -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/server.mjs

@@ -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);
+}