@homespunapps/mcp 1.0.0

package/dist/tools.js

@@ -0,0 +1,1029 @@
+// Tool definitions for the Homespun MCP server.
+//
+// Each tool wraps one or more @homespunapps/core HomespunClient operations. The
+// descriptions are written for the LLM consumer — they ARE the docs the model
+// reads to decide when and how to call each tool. Keep them concrete and
+// action-oriented.
+//
+// Surface design (v2-only — the v1 homespun-lifecycle/events/records/
+// participant/share/query tools were removed along with the rest of the v1
+// app API, and the v1 Template subsystem's template/template_records/trash
+// tools were removed in PR 2c-1; see git history for the prior surfaces):
+//   - v2 app lifecycle + data are DISCRETE tools: deploy_app, list_rows,
+//     get_row, upsert_row, update_row, delete_row, get_feed_events.
+//   - Multi-verb MANAGEMENT nouns each collapse into ONE tool with a required
+//     `action` enum and per-action fields: apps, members, attachments, taste,
+//     key, feedback, agent.
+//   - skill → get_skill (no API key).
+//
+// MCP is request/response: there is no streaming.
+//
+// Schema validation uses Zod raw shapes (the shape McpServer.registerTool
+// expects); the SDK validates arguments before the handler runs. For
+// consolidated tools the per-action required fields are documented in the tool
+// description and re-checked in the handler (a Zod raw shape can't express a
+// discriminated union across a flat field set, so the handler asserts the
+// action-specific requirements and returns a tight invalid_args error).
+import { z } from "zod";
+import { HomespunApiError } from "@homespunapps/core";
+import { readFileSync, writeFileSync } from "node:fs";
+import { basename } from "node:path";
+import { resolveUrl, describeActiveConfig, clearActiveProfile, } from "./config.js";
+import { fetchSkill } from "./skill.js";
+/** Wrap a JSON-able value as a single text-content tool result. */
+function jsonResult(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    };
+}
+/** Plain text result (used by get_skill for raw markdown). */
+function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+/**
+ * Turn any thrown error into a structured `isError` tool result. HomespunApiError
+ * carries the relay's `code`, HTTP `status`, and an optional remediation
+ * `hint`; surface all of it so the model can self-correct (e.g. fix an event
+ * type the schema rejected) instead of getting an opaque failure.
+ */
+function errorResult(e) {
+    if (e instanceof HomespunApiError) {
+        const payload = {
+            error: e.code,
+            status: e.status,
+            message: e.message,
+        };
+        if (e.hint)
+            payload["hint"] = e.hint;
+        if (e.details !== undefined)
+            payload["details"] = e.details;
+        if (e.retryable !== undefined)
+            payload["retryable"] = e.retryable;
+        return {
+            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+            isError: true,
+        };
+    }
+    const message = e instanceof Error ? e.message : String(e);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ error: "internal", message }, null, 2),
+            },
+        ],
+        isError: true,
+    };
+}
+/**
+ * Structured invalid_args error for the per-action validation inside
+ * consolidated tools. Mirrors the relay's envelope so the model self-corrects.
+ */
+function invalidArgs(message) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ error: "invalid_args", message }, null, 2),
+            },
+        ],
+        isError: true,
+    };
+}
+/** Read a required string arg; returns undefined when absent/empty. */
+function str(args, key) {
+    const v = args[key];
+    return typeof v === "string" && v !== "" ? v : undefined;
+}
+/** True for a non-null, non-array plain object (`{"type":"object"}` land). */
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Defense in depth for a client harness that serializes an object-valued
+ * argument as a JSON *string* instead of a JSON object (the reported bug). If
+ * `value` is a string that JSON-parses to an object, return the parsed object;
+ * if it is a string that does NOT parse as JSON at all, return a tight
+ * invalid_args error naming the field. Anything else (already an object /
+ * array / number / boolean / null, or a string that parses to a non-object
+ * JSON value) is passed through unchanged - we never silently coerce.
+ */
+function parseMaybeStringifiedObject(value, field) {
+    if (typeof value !== "string")
+        return { value };
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return {
+            error: invalidArgs(`\`${field}\` must be a JSON object, not a string; received a string that is not valid JSON`),
+        };
+    }
+    if (isPlainObject(parsed))
+        return { value: parsed };
+    return { value };
+}
+/**
+ * A JSON object schema (`{"type":"object"}` in the emitted tool schema). Using
+ * z.record here - rather than z.unknown, which emits NO type keyword - is what
+ * signals harnesses that an OBJECT is expected so they stop stringifying it.
+ */
+const jsonObjectSchema = z.record(z.string(), z.unknown());
+/**
+ * A permissive "any JSON value" schema that STILL advertises what is allowed:
+ * it serializes to an `anyOf` of typed branches (object|array|string|number|
+ * boolean|null) rather than a bare, type-less `{}`. Matches what the relay
+ * actually accepts for a row body (any JSON value valid against the
+ * collection's row schema, if any).
+ */
+const jsonValueSchema = z.union([
+    jsonObjectSchema,
+    z.array(z.unknown()),
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+]);
+// ===========================================================================
+// v2 app lifecycle + data (discrete, hot-path)
+// ===========================================================================
+const deployAppShape = {
+    app_id: z
+        .string()
+        .optional()
+        .describe("Omit to CREATE a new app; pass an existing app's id to REDEPLOY it (a new version, compat-gated unless force:true)."),
+    html: z
+        .string()
+        .min(1)
+        .describe("The app's UI as a complete HTML document (single file, up to the relay's size cap)."),
+    manifest: jsonObjectSchema.describe("The x-homespun-manifest capability document (a JSON object): app metadata, declared collections (+ per-collection write/delete role lists), external fetch hosts, CDN flag. Call get_skill for the full grammar before authoring one from scratch."),
+    visibility: z
+        .enum(["private", "link", "public"])
+        .optional()
+        .describe("CREATE only. Default 'private' (owner plus invited members, sign-in gated). 'link' shares with anyone holding the URL and always gets a server-generated unguessable slug; 'private' and 'public' accept an owner-chosen `slug`."),
+    slug: z
+        .string()
+        .optional()
+        .describe("CREATE only. Accepted with visibility private or public, including the private default; rejected with explicit visibility 'link', where the slug is always server-generated."),
+    force: z
+        .boolean()
+        .optional()
+        .describe("REDEPLOY only. Bypass the compat gate on a narrowing manifest change (a removed/narrowed collection is detached, never deleted)."),
+};
+const listRowsShape = {
+    app_id: z.string().min(1).describe("The app id."),
+    collection: z
+        .string()
+        .min(1)
+        .describe("The collection name declared in the app's manifest."),
+    since: z
+        .string()
+        .optional()
+        .describe("Opaque cursor from a previous call's next_cursor. Also the POLL handle: pass it back to fetch only newer/changed rows."),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(1000)
+        .optional()
+        .describe("Page size."),
+};
+const getRowShape = {
+    app_id: z.string().min(1).describe("The app id."),
+    collection: z.string().min(1).describe("The collection name."),
+    key: z.string().min(1).describe("The key of the row to fetch."),
+};
+const upsertRowShape = {
+    app_id: z.string().min(1).describe("The app id."),
+    collection: z.string().min(1).describe("The collection name."),
+    key: z
+        .string()
+        .optional()
+        .describe("Optional stable key. Reusing an existing key returns the existing row (deduped:true)."),
+    data: jsonValueSchema.describe("The row body - any JSON value valid against the collection's row schema (an object, or any JSON value for a schemaless collection)."),
+};
+const updateRowShape = {
+    app_id: z.string().min(1).describe("The app id."),
+    collection: z.string().min(1).describe("The collection name."),
+    key: z.string().min(1).describe("The key of the row to update."),
+    data: jsonValueSchema.describe("The new row body (replaces the row's data) - any JSON value valid against the collection's row schema."),
+    if_match: z
+        .number()
+        .int()
+        .optional()
+        .describe("Optional optimistic-lock version. On mismatch the update is rejected with the current row in details.current."),
+};
+const deleteRowShape = {
+    app_id: z.string().min(1).describe("The app id."),
+    collection: z.string().min(1).describe("The collection name."),
+    key: z.string().min(1).describe("The key of the row to delete."),
+    if_match: z
+        .number()
+        .int()
+        .optional()
+        .describe("Optional optimistic-lock version."),
+};
+const getFeedEventsShape = {
+    app_id: z.string().min(1).describe("The app id."),
+    since: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("Opaque numeric cursor from a previous call's cursor. Omit (or 0) to read from the beginning."),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Max entries per page (capped server-side by FEED_PAGE_MAX)."),
+    wait: z
+        .number()
+        .int()
+        .min(0)
+        .max(30)
+        .optional()
+        .describe("Optional long-poll: how long the relay holds the request open waiting for a new entry (0-30s). Use ~25 when waiting for activity, then call again with the same cursor."),
+};
+const appsShape = {
+    action: z
+        .enum(["list", "show", "update", "delete", "wake"])
+        .describe("list: YOUR owning human's apps. show/update/delete/wake: act on one app (app_id)."),
+    app_id: z
+        .string()
+        .optional()
+        .describe("Required for show/update/delete/wake."),
+    status: z
+        .enum(["active", "dormant", "archived", "all"])
+        .optional()
+        .describe("list only. Default: active."),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(200)
+        .optional()
+        .describe("list only. Page size."),
+    cursor: z
+        .string()
+        .optional()
+        .describe("list only. Opaque cursor from a previous next_cursor."),
+    slug: z.string().optional().describe("list only. Exact-match slug filter."),
+    visibility: z
+        .enum(["private", "link", "public"])
+        .optional()
+        .describe("update only. The new visibility (slug is immutable)."),
+};
+const membersShape = {
+    action: z
+        .enum(["add", "list", "remove"])
+        .describe("add: invite-or-attach a member by email (app_id+email). list: the app's owner + members (app_id). remove: drop a member (app_id+human_id)."),
+    app_id: z.string().min(1).describe("The app id."),
+    email: z
+        .string()
+        .optional()
+        .describe("add only. The email to invite/attach. If a Human already exists for it, the member row is attached immediately; otherwise the relay emails a magic-link invite."),
+    role: z
+        .enum(["member"])
+        .optional()
+        .describe("add only. Defaults to 'member' server-side — no other role is assignable via this API (ownership transfer is not available here)."),
+    human_id: z
+        .string()
+        .optional()
+        .describe("remove only. The Human id to remove — see list's `humanId` field. The app owner cannot be removed."),
+};
+// ===========================================================================
+// Consolidated management tools
+// ===========================================================================
+const attachmentsShape = {
+    action: z
+        .enum([
+        "upload",
+        "download",
+        "show",
+        "list",
+        "delete",
+        "mint_token",
+        "revoke_token",
+        "list_tokens",
+    ])
+        .describe("Binary attachment operations. upload: read a local file (file_path) and upload it; scope agent|app. download: fetch bytes by attachment_id to out_path (absolute) or return base64. show: metadata only. list: the agent's attachments. delete: soft-delete. mint_token: mint a /b/<token> capability URL (returned ONCE). revoke_token / list_tokens: manage those tokens."),
+    attachment_id: z
+        .string()
+        .optional()
+        .describe("Attachment id. Required for download/show/delete/mint_token/revoke_token/list_tokens."),
+    file_path: z
+        .string()
+        .optional()
+        .describe("upload: ABSOLUTE path to the local file to upload."),
+    scope: z
+        .enum(["agent", "app"])
+        .optional()
+        .describe("upload scope (default agent)."),
+    app_id: z.string().optional().describe("Required when scope=app."),
+    filename: z
+        .string()
+        .optional()
+        .describe("upload: display filename (defaults to the file's basename)."),
+    mime: z
+        .string()
+        .optional()
+        .describe("upload: advisory Content-Type (the relay sniffs the bytes regardless)."),
+    out_path: z
+        .string()
+        .optional()
+        .describe("download: ABSOLUTE path to write the bytes to. If omitted, the bytes are returned base64-encoded in the result."),
+    cursor: z.string().optional().describe("list pagination cursor."),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(100)
+        .optional()
+        .describe("list page size (1..100)."),
+    ttl_seconds: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("mint_token: per-token TTL (clamped by scope default)."),
+    once: z
+        .boolean()
+        .optional()
+        .describe("mint_token: token self-deletes on first GET."),
+    token_id: z
+        .string()
+        .optional()
+        .describe("revoke_token: the token id to revoke."),
+};
+const tasteShape = {
+    action: z
+        .enum(["get", "set", "clear"])
+        .describe("The agent's freeform UI taste notes (markdown) — presentation preferences learned from human feedback. get: read them before generating an app. set: whole-document replace (taste, non-empty). clear: delete them."),
+    taste: z
+        .string()
+        .optional()
+        .describe("The full markdown notes (required for set; whole-document replace, not append)."),
+};
+const keyShape = {
+    action: z
+        .enum(["list", "revoke"])
+        .describe("The calling agent's API key. list: key info (agent_id, key_prefix, timestamps). revoke: self-destruct the agent's OWN key — it stops working immediately and is irreversible (requires confirm:true)."),
+    confirm: z.boolean().optional().describe("Required (true) for revoke."),
+};
+const feedbackShape = {
+    action: z
+        .enum(["create", "list"])
+        .describe("Feedback to the relay operator. create: submit a bug|feature|note with a message (optional app_id). list: the agent's own submissions, newest first."),
+    type: z
+        .enum(["bug", "feature", "note"])
+        .optional()
+        .describe("Feedback category (required for create)."),
+    message: z
+        .string()
+        .optional()
+        .describe("Message body (required for create)."),
+    app_id: z
+        .string()
+        .optional()
+        .describe("Optional app this feedback relates to (create)."),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(100)
+        .optional()
+        .describe("list page size (default 50, max 100)."),
+    before: z
+        .string()
+        .optional()
+        .describe("list cursor from a prior page's next_before."),
+};
+const agentShape = {
+    action: z
+        .enum(["whoami", "claim", "logout"])
+        .describe("Agent identity. whoami: show the resolved relay URL, active profile, and whether a key is configured (no network, no secrets). claim: bind this agent to a human via a one-shot claim code the human generated in their Settings UI (one-way). logout: clear the locally-saved key/profile (does NOT revoke it on the relay — use the key tool's revoke for that)."),
+    code: z
+        .string()
+        .optional()
+        .describe("The one-shot claim code (required for claim)."),
+};
+const getSkillShape = {
+    version_only: z
+        .boolean()
+        .optional()
+        .describe("If true, return only the relay's current skill version string instead of the full SKILL.md markdown."),
+};
+// ===========================================================================
+// Tool definitions
+// ===========================================================================
+export const TOOLS = [
+    // ----- v2 app lifecycle + data (discrete, hot-path) -----------------------
+    {
+        name: "deploy_app",
+        description: "Deploy a v2 app: an HTML document + a capability manifest (declared collections, external hosts, CDN flag), hosted at its own URL. Pass EITHER no `app_id` (create — mints a slug + URL) OR `app_id` (redeploy an existing app with new content). A redeploy that NARROWS the manifest (drops a collection, tightens a schema, revokes a role) is refused with manifest_incompatible_redeploy unless force:true; a narrowed collection is then detached, never deleted. BEFORE authoring: call get_skill for the manifest grammar. Returns { app_id, slug, url, version, visibility, created } (create) or { app_id, version, compat, breaks? } (redeploy).",
+        inputSchema: deployAppShape,
+        annotations: {
+            title: "Deploy App",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        handler: async (client, args) => {
+            try {
+                const manifest = parseMaybeStringifiedObject(args["manifest"], "manifest");
+                if ("error" in manifest)
+                    return manifest.error;
+                const appId = str(args, "app_id");
+                if (appId === undefined) {
+                    if (str(args, "html") === undefined) {
+                        return invalidArgs("create requires `html`");
+                    }
+                    const slug = str(args, "slug");
+                    const visibility = args["visibility"];
+                    if (slug !== undefined && visibility === "link") {
+                        return invalidArgs("a `slug` is not allowed with visibility 'link' (link slugs are server-generated); drop visibility 'link', or omit slug");
+                    }
+                    return jsonResult(await client.deployApp({
+                        html: String(args["html"]),
+                        manifest: manifest.value,
+                        visibility,
+                        slug,
+                    }));
+                }
+                if (str(args, "html") === undefined) {
+                    return invalidArgs("redeploy requires `html`");
+                }
+                if (args["slug"] !== undefined || args["visibility"] !== undefined) {
+                    return invalidArgs("slug/visibility cannot change on redeploy — slug is immutable, visibility changes via the `apps` tool (action: update)");
+                }
+                const redeployed = await client.redeployApp(appId, {
+                    html: String(args["html"]),
+                    manifest: manifest.value,
+                    force: args["force"],
+                });
+                return jsonResult(redeployed);
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "list_rows",
+        description: "List rows in a v2 app's mutable collection. This also doubles as the POLL for a collection's current state (no streaming in MCP): pass the prior next_cursor as `since` to fetch only newer/changed rows. Returns { rows, next_cursor, has_more }.",
+        inputSchema: listRowsShape,
+        annotations: {
+            title: "List Rows",
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
+        handler: async (client, args) => {
+            try {
+                return jsonResult(await client.listAppRows(String(args["app_id"]), String(args["collection"]), {
+                    since: args["since"],
+                    limit: args["limit"],
+                }));
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "get_row",
+        description: "Fetch a single row by its key from a v2 app collection (a dedicated relay route — not a client-side scan). Returns { row } or an isError row_not_found.",
+        inputSchema: getRowShape,
+        annotations: {
+            title: "Get Row",
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
+        handler: async (client, args) => {
+            try {
+                return jsonResult(await client.getAppRow(String(args["app_id"]), String(args["collection"]), String(args["key"])));
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "upsert_row",
+        description: "Create a row in a v2 app's collection, or return the existing row if `key` is already present (deduped:true) — the ONLY create-shaped verb for app rows (no separate strict create). Omit `key` to add a new row (server-generates one); pass `key` to ensure a row exists at that key. The collection must be declared in the app's manifest with 'agent' allowed to write. Returns { row, deduped? }.",
+        inputSchema: upsertRowShape,
+        annotations: {
+            title: "Upsert Row",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        handler: async (client, args) => {
+            try {
+                const data = parseMaybeStringifiedObject(args["data"], "data");
+                if ("error" in data)
+                    return data.error;
+                const body = { data: data.value };
+                if (args["key"] !== undefined)
+                    body.key = String(args["key"]);
+                return jsonResult(await client.upsertAppRow(String(args["app_id"]), String(args["collection"]), body));
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "update_row",
+        description: "Update an existing row in a v2 app's collection (replaces its data). Pass if_match with the row's current version for an optimistic-locked update — on a version mismatch the relay returns the current row so you can retry. Returns { row }.",
+        inputSchema: updateRowShape,
+        annotations: {
+            title: "Update Row",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        handler: async (client, args) => {
+            try {
+                const data = parseMaybeStringifiedObject(args["data"], "data");
+                if ("error" in data)
+                    return data.error;
+                const body = {
+                    data: data.value,
+                };
+                if (args["if_match"] !== undefined)
+                    body.if_match = args["if_match"];
+                return jsonResult(await client.updateAppRow(String(args["app_id"]), String(args["collection"]), String(args["key"]), body));
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "delete_row",
+        description: "Soft-delete a row from a v2 app's collection. A watcher sees the deletion live (op:delete on the change feed). Pass if_match for an optimistic-locked delete. Returns { deleted: true }.",
+        inputSchema: deleteRowShape,
+        annotations: {
+            title: "Delete Row",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        handler: async (client, args) => {
+            try {
+                await client.deleteAppRow(String(args["app_id"]), String(args["collection"]), String(args["key"]), args["if_match"] !== undefined
+                    ? { ifMatch: args["if_match"] }
+                    : {});
+                return jsonResult({ deleted: true, key: args["key"] });
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "get_feed_events",
+        description: "Poll a v2 app's change feed for what happened (row creates/updates/deletes, from any writer — agent or human). This is the long-poll analogue of `homespun apps watch` — there is no streaming in MCP. Poll loop: call with no `since` first; process the returned entries; remember cursor; call again passing it as `since` to get only newer entries. To WAIT for activity, pass wait (~25) so the relay holds the request open until an entry arrives or it times out. A `since` older than the retention floor returns resync_required — re-list the collection(s) with list_rows instead. Returns { entries, cursor, truncated }.",
+        inputSchema: getFeedEventsShape,
+        annotations: {
+            title: "Get App Feed Events",
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
+        handler: async (client, args) => {
+            try {
+                return jsonResult(await client.getAppFeed(String(args["app_id"]), {
+                    since: args["since"] ?? 0,
+                    limit: args["limit"],
+                    wait: args["wait"],
+                }));
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "apps",
+        description: "Manage v2 app lifecycle (deploy_app creates/redeploys; this tool covers the rest). ONE tool with an `action` enum: list (YOUR owning human's apps) | show (full detail incl. manifest) | update (visibility only — slug is immutable) | delete (soft-delete, idempotent) | wake (a dormant app; a no-op reporting the actual status otherwise).",
+        inputSchema: appsShape,
+        // Consolidated tool: read actions (list/show) + mutating ones (update/
+        // delete/wake). Hint reflects delete, the most-privileged action.
+        annotations: {
+            title: "Manage Apps",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        handler: async (client, args) => {
+            const action = String(args["action"]);
+            try {
+                switch (action) {
+                    case "list": {
+                        const opts = {};
+                        if (args["status"] !== undefined)
+                            opts["status"] = args["status"];
+                        if (args["limit"] !== undefined)
+                            opts["limit"] = args["limit"];
+                        if (args["cursor"] !== undefined)
+                            opts["cursor"] = args["cursor"];
+                        if (args["slug"] !== undefined)
+                            opts["slug"] = args["slug"];
+                        return jsonResult(await client.listApps(opts));
+                    }
+                    case "show":
+                        if (str(args, "app_id") === undefined) {
+                            return invalidArgs("show requires `app_id`");
+                        }
+                        return jsonResult(await client.getApp(String(args["app_id"])));
+                    case "update":
+                        if (str(args, "app_id") === undefined) {
+                            return invalidArgs("update requires `app_id`");
+                        }
+                        if (str(args, "visibility") === undefined) {
+                            return invalidArgs("update requires `visibility`");
+                        }
+                        return jsonResult(await client.updateApp(String(args["app_id"]), args["visibility"]));
+                    case "delete":
+                        if (str(args, "app_id") === undefined) {
+                            return invalidArgs("delete requires `app_id`");
+                        }
+                        await client.deleteApp(String(args["app_id"]));
+                        return jsonResult({ app_id: args["app_id"], deleted: true });
+                    case "wake":
+                        if (str(args, "app_id") === undefined) {
+                            return invalidArgs("wake requires `app_id`");
+                        }
+                        return jsonResult(await client.wakeApp(String(args["app_id"])));
+                    default:
+                        return invalidArgs(`unknown apps action '${action}'`);
+                }
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "members",
+        description: "Manage a v2 app's membership (auth spec §6) — who besides the app's owner can sign in to a private app / write to member-scoped collections. ONE tool with an `action` enum: add (invite-or-attach a member by email — attaches immediately if the email already has a Human, otherwise the relay emails a magic-link invite) | list (the app's owner + members) | remove (idempotent; also revokes the human's live sessions on this app — the app owner cannot be removed).",
+        inputSchema: membersShape,
+        // Consolidated tool: read action (list) + mutating ones (add/remove).
+        // Hint reflects remove, the most-privileged action.
+        annotations: {
+            title: "Manage App Members",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        handler: async (client, args) => {
+            const action = String(args["action"]);
+            if (str(args, "app_id") === undefined) {
+                return invalidArgs(`${action} requires \`app_id\``);
+            }
+            const appId = String(args["app_id"]);
+            try {
+                switch (action) {
+                    case "add": {
+                        if (str(args, "email") === undefined) {
+                            return invalidArgs("add requires `email`");
+                        }
+                        return jsonResult(await client.addAppMember(appId, {
+                            email: String(args["email"]),
+                            ...(args["role"] !== undefined
+                                ? { role: args["role"] }
+                                : {}),
+                        }));
+                    }
+                    case "list":
+                        return jsonResult(await client.listAppMembers(appId));
+                    case "remove": {
+                        if (str(args, "human_id") === undefined) {
+                            return invalidArgs("remove requires `human_id`");
+                        }
+                        await client.removeAppMember(appId, String(args["human_id"]));
+                        return jsonResult({
+                            app_id: appId,
+                            human_id: args["human_id"],
+                            removed: true,
+                        });
+                    }
+                    default:
+                        return invalidArgs(`unknown members action '${action}'`);
+                }
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    // ----- consolidated management tools --------------------------------------
+    {
+        name: "attachments",
+        description: "Binary attachments (images, PDFs, audio, video) referenced from event payloads / input_data via `format: homespun-attachment-id`. ONE tool with an `action` enum: upload | download | show | list | delete | mint_token | revoke_token | list_tokens. upload reads an ABSOLUTE file_path; download writes to an ABSOLUTE out_path (or returns base64). Scope an upload to agent (default, reusable) or app. mint_token returns a /b/<token> capability URL (ONCE) a browser can GET without your API key.",
+        inputSchema: attachmentsShape,
+        // Consolidated tool: read actions (download/show/list/list_tokens) +
+        // mutating ones (upload/delete/mint_token/revoke_token). openWorld:true
+        // because upload pushes bytes into external relay storage + mint_token
+        // produces a publicly-fetchable capability URL.
+        annotations: {
+            title: "Manage Attachments",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        handler: async (client, args) => {
+            const action = String(args["action"]);
+            try {
+                switch (action) {
+                    case "upload": {
+                        const filePath = str(args, "file_path");
+                        if (filePath === undefined)
+                            return invalidArgs("upload requires `file_path` (absolute)");
+                        const scope = (str(args, "scope") ?? "agent");
+                        if (scope === "app" && str(args, "app_id") === undefined)
+                            return invalidArgs("scope=app requires `app_id`");
+                        let bytes;
+                        try {
+                            bytes = readFileSync(filePath);
+                        }
+                        catch (e) {
+                            return invalidArgs(`failed to read file_path '${filePath}': ${e instanceof Error ? e.message : String(e)}`);
+                        }
+                        const ref = await client.uploadBlob(bytes, {
+                            scope,
+                            appId: str(args, "app_id"),
+                            filename: str(args, "filename") ?? basename(filePath),
+                            mime: str(args, "mime"),
+                        });
+                        return jsonResult(ref);
+                    }
+                    case "download": {
+                        if (str(args, "attachment_id") === undefined)
+                            return invalidArgs("download requires `attachment_id`");
+                        const buf = await client.downloadBlob(String(args["attachment_id"]));
+                        const outPath = str(args, "out_path");
+                        if (outPath !== undefined) {
+                            try {
+                                writeFileSync(outPath, Buffer.from(buf));
+                            }
+                            catch (e) {
+                                return invalidArgs(`failed to write out_path '${outPath}': ${e instanceof Error ? e.message : String(e)}`);
+                            }
+                            return jsonResult({
+                                attachment_id: args["attachment_id"],
+                                written: outPath,
+                                bytes: buf.byteLength,
+                            });
+                        }
+                        return jsonResult({
+                            attachment_id: args["attachment_id"],
+                            bytes: buf.byteLength,
+                            base64: Buffer.from(buf).toString("base64"),
+                        });
+                    }
+                    case "show":
+                        if (str(args, "attachment_id") === undefined)
+                            return invalidArgs("show requires `attachment_id`");
+                        return jsonResult(await client.getBlob(String(args["attachment_id"])));
+                    case "list": {
+                        const opts = {};
+                        if (str(args, "cursor") !== undefined)
+                            opts.cursor = String(args["cursor"]);
+                        if (args["limit"] !== undefined)
+                            opts.limit = args["limit"];
+                        return jsonResult(await client.listBlobs(opts));
+                    }
+                    case "delete":
+                        if (str(args, "attachment_id") === undefined)
+                            return invalidArgs("delete requires `attachment_id`");
+                        return jsonResult(await client.deleteBlob(String(args["attachment_id"])));
+                    case "mint_token": {
+                        if (str(args, "attachment_id") === undefined)
+                            return invalidArgs("mint_token requires `attachment_id`");
+                        return jsonResult(await client.mintBlobToken(String(args["attachment_id"]), {
+                            ttlSeconds: args["ttl_seconds"],
+                            once: args["once"] === true,
+                        }));
+                    }
+                    case "revoke_token":
+                        if (str(args, "attachment_id") === undefined ||
+                            str(args, "token_id") === undefined)
+                            return invalidArgs("revoke_token requires `attachment_id` and `token_id`");
+                        return jsonResult(await client.revokeBlobToken(String(args["attachment_id"]), String(args["token_id"])));
+                    case "list_tokens":
+                        if (str(args, "attachment_id") === undefined)
+                            return invalidArgs("list_tokens requires `attachment_id`");
+                        return jsonResult(await client.listBlobTokens(String(args["attachment_id"])));
+                    default:
+                        return invalidArgs(`unknown attachments action '${action}'`);
+                }
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "taste",
+        description: "Read / write / clear the agent's freeform UI taste notes (a small markdown document of presentation preferences learned from human feedback — 'denser layout', 'no rounded corners'). ONE tool with an `action` enum: get | set | clear. Call `get` BEFORE generating an app so prior feedback shapes the output; `set` does a whole-document replace (not append). Keep entries about UI/presentation only.",
+        inputSchema: tasteShape,
+        // Consolidated tool: read action (get) + mutating ones (set replaces the
+        // doc, clear deletes it). Hint reflects the destructive action.
+        annotations: {
+            title: "Manage UI Taste Notes",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        handler: async (client, args) => {
+            const action = String(args["action"]);
+            try {
+                switch (action) {
+                    case "get":
+                        return jsonResult(await client.getTaste());
+                    case "set": {
+                        const taste = str(args, "taste");
+                        if (taste === undefined || taste.trim() === "")
+                            return invalidArgs("set requires non-empty `taste` (use clear to delete the notes)");
+                        return jsonResult(await client.setTaste(taste));
+                    }
+                    case "clear":
+                        await client.clearTaste();
+                        return jsonResult({ cleared: true });
+                    default:
+                        return invalidArgs(`unknown taste action '${action}'`);
+                }
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "key",
+        description: "Inspect or revoke the calling agent's API key. ONE tool with an `action` enum: list (key info — agent_id, key_prefix, timestamps) | revoke (self-destruct the agent's OWN key; it stops working immediately and is irreversible — pass confirm:true). The relay scopes keys to the caller, so both act only on your own key.",
+        inputSchema: keyShape,
+        // Consolidated tool: read action (list) + a mutating one (revoke
+        // self-destructs the agent's own key). Hint reflects the destructive
+        // action.
+        annotations: {
+            title: "Manage API Key",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        handler: async (client, args) => {
+            const action = String(args["action"]);
+            try {
+                switch (action) {
+                    case "list":
+                        return jsonResult(await client.listKeys());
+                    case "revoke": {
+                        if (args["confirm"] !== true) {
+                            return invalidArgs("revoke is irreversible and stops your key working immediately — pass confirm:true");
+                        }
+                        const id = (await client.listKeys()).agent_id;
+                        await client.revokeKey(id);
+                        return jsonResult({ revoked: true, agent_id: id });
+                    }
+                    default:
+                        return invalidArgs(`unknown key action '${action}'`);
+                }
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "feedback",
+        description: "Send or list feedback to the relay operator. ONE tool with an `action` enum: create (a bug|feature|note with a message, optional app_id) | list (the agent's own submissions, newest first, paginated by before).",
+        inputSchema: feedbackShape,
+        // Consolidated tool: read action (list) + a side-effecting one (create
+        // submits feedback to the relay operator). Hint reflects the write action.
+        annotations: {
+            title: "Manage Feedback",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        handler: async (client, args) => {
+            const action = String(args["action"]);
+            try {
+                switch (action) {
+                    case "create": {
+                        if (str(args, "type") === undefined ||
+                            str(args, "message") === undefined)
+                            return invalidArgs("create requires `type` and `message`");
+                        return jsonResult(await client.submitFeedback({
+                            type: args["type"],
+                            message: String(args["message"]),
+                            ...(str(args, "app_id") !== undefined
+                                ? { appId: String(args["app_id"]) }
+                                : {}),
+                        }));
+                    }
+                    case "list": {
+                        const opts = {};
+                        if (args["limit"] !== undefined)
+                            opts.limit = args["limit"];
+                        if (str(args, "before") !== undefined)
+                            opts.before = String(args["before"]);
+                        return jsonResult(await client.listFeedback(opts));
+                    }
+                    default:
+                        return invalidArgs(`unknown feedback action '${action}'`);
+                }
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "agent",
+        description: "Agent identity + binding. ONE tool with an `action` enum: whoami (the resolved relay URL, active profile, whether a key is configured — no network, no secrets) | claim (bind this agent to a human via a one-shot claim code from their Settings UI; one-way) | logout (clear the locally-saved key/profile; does NOT revoke it on the relay — use the `key` tool's revoke for that).",
+        inputSchema: agentShape,
+        // Consolidated tool: read action (whoami) + mutating ones (claim binds
+        // this agent to a human, logout clears the local profile). Hint reflects
+        // the state-changing action.
+        annotations: {
+            title: "Manage Agent Identity",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        handler: async (client, args, env) => {
+            const action = String(args["action"]);
+            try {
+                switch (action) {
+                    case "whoami":
+                        // No network — pure local config introspection. The relay's HTTP
+                        // server injects describeConfig (active token's agent identity);
+                        // the stdio server reads the CLI config store.
+                        return jsonResult((env?.describeConfig ?? describeActiveConfig)());
+                    case "claim":
+                        if (str(args, "code") === undefined)
+                            return invalidArgs("claim requires `code`");
+                        return jsonResult(await client.claimAgent(String(args["code"])));
+                    case "logout":
+                        return jsonResult((env?.clearProfile ?? clearActiveProfile)());
+                    default:
+                        return invalidArgs(`unknown agent action '${action}'`);
+                }
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "get_skill",
+        description: "Fetch the relay's auto-updating SKILL.md (the full Homespun usage guide) — UNAUTHENTICATED, needs no API key. Call this to self-teach the Homespun workflow (events vs records, schema grammars, the poll loop) before driving the other tools. Pass version_only:true to get just the relay's skill version string (to check if a cached copy is stale).",
+        inputSchema: getSkillShape,
+        annotations: {
+            title: "Get Skill Guide",
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
+        handler: async (_client, args, env) => {
+            try {
+                const versionOnly = args["version_only"] === true;
+                // The relay's HTTP server injects getSkill so MCP consumers receive
+                // the MCP-invocation rendering of the skill (tool-call grammar, not
+                // `homespun ...` commands) straight from the relay image. The stdio server
+                // falls back to fetching SKILL.md over HTTP from its configured relay.
+                if (env?.getSkill) {
+                    const { markdown, version } = await env.getSkill(versionOnly);
+                    if (versionOnly)
+                        return jsonResult({ version });
+                    return textResult(markdown ?? "");
+                }
+                const url = resolveUrl();
+                if (versionOnly) {
+                    const { version } = await fetchSkill(url, { version: true });
+                    return jsonResult({ version });
+                }
+                const { markdown } = await fetchSkill(url);
+                return textResult(markdown ?? "");
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+];