@ggui-ai/mcp-server-handlers 0.7.0 → 0.9.0

package/dist/blueprints/index.d.ts

@@ -23,8 +23,8 @@
  * on top when wrapping these into its tool-handler shape (a wider
  * `SharedHandler<ToolContext>` re-export).
  */
-export { createSearchBlueprintsHandler, MIN_SIMILARITY_SCORE, MANIFEST_EXACT_NAME_SCORE, MANIFEST_SUBSTRING_SCORE, } from './search-blueprints.js';
-export type { SearchBlueprintsDeps } from './search-blueprints.js';
+export { createSearchBlueprintsHandler, DEFAULT_REGISTRY_SEARCH_TIMEOUT_MS, MIN_SIMILARITY_SCORE, MANIFEST_EXACT_NAME_SCORE, MANIFEST_SUBSTRING_SCORE, } from './search-blueprints.js';
+export type { SearchBlueprintsDeps, SearchBlueprintsRegistrySource, } from './search-blueprints.js';
 export { createListFeaturedBlueprintsHandler } from './list-featured-blueprints.js';
 export type { ListFeaturedBlueprintsDeps, ListFeaturedBlueprintsOutput, } from './list-featured-blueprints.js';
 export { createRenderBlueprintHandler } from './render-blueprint.js';

package/dist/blueprints/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/blueprints/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EACL,6BAA6B,EAC7B,oBAAoB,EACpB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,EAAE,mCAAmC,EAAE,MAAM,+BAA+B,CAAC;AACpF,YAAY,EACV,0BAA0B,EAC1B,4BAA4B,GAC7B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACrE,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,8BAA8B,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,EAAE,oCAAoC,EAAE,MAAM,gCAAgC,CAAC;AACtF,OAAO,EAAE,oCAAoC,EAAE,MAAM,gCAAgC,CAAC;AACtF,OAAO,EAAE,oCAAoC,EAAE,MAAM,gCAAgC,CAAC;AACtF,OAAO,EAAE,uCAAuC,EAAE,MAAM,oCAAoC,CAAC;AAC7F,OAAO,EAAE,iCAAiC,EAAE,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/blueprints/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EACL,6BAA6B,EAC7B,kCAAkC,EAClC,oBAAoB,EACpB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,oBAAoB,EACpB,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,mCAAmC,EAAE,MAAM,+BAA+B,CAAC;AACpF,YAAY,EACV,0BAA0B,EAC1B,4BAA4B,GAC7B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACrE,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,8BAA8B,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,EAAE,oCAAoC,EAAE,MAAM,gCAAgC,CAAC;AACtF,OAAO,EAAE,oCAAoC,EAAE,MAAM,gCAAgC,CAAC;AACtF,OAAO,EAAE,oCAAoC,EAAE,MAAM,gCAAgC,CAAC;AACtF,OAAO,EAAE,uCAAuC,EAAE,MAAM,oCAAoC,CAAC;AAC7F,OAAO,EAAE,iCAAiC,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/blueprints/index.js

@@ -23,7 +23,7 @@
  * on top when wrapping these into its tool-handler shape (a wider
  * `SharedHandler<ToolContext>` re-export).
  */
-export { createSearchBlueprintsHandler, MIN_SIMILARITY_SCORE, MANIFEST_EXACT_NAME_SCORE, MANIFEST_SUBSTRING_SCORE, } from './search-blueprints.js';
+export { createSearchBlueprintsHandler, DEFAULT_REGISTRY_SEARCH_TIMEOUT_MS, MIN_SIMILARITY_SCORE, MANIFEST_EXACT_NAME_SCORE, MANIFEST_SUBSTRING_SCORE, } from './search-blueprints.js';
 export { createListFeaturedBlueprintsHandler } from './list-featured-blueprints.js';
 export { createRenderBlueprintHandler } from './render-blueprint.js';
 export { createValidateBlueprintHandler } from './validate-blueprint.js';

package/dist/blueprints/search-blueprints.d.ts

@@ -2,8 +2,8 @@
  * ggui_search_blueprints — search across every discoverable blueprint
  * on this server.
  *
- * Two sources are consulted in parallel, then merged + de-duplicated
- * by id:
+ * Up to three sources are consulted in parallel, then merged +
+ * de-duplicated by id:
  *
  *   1. **Manifest source** (optional `BlueprintProvider`) — authored
  *      UIs declared in `ggui.json#blueprints.include`. Matched by
@@ -19,6 +19,11 @@
  *      producer that has written into the scope. Continues to honor
  *      `MIN_SIMILARITY_SCORE`.
  *
+ *   3. **Registry source** (optional, opt-in via deps.registry) —
+ *      bounded public /search call for published blueprint
+ *      candidates; appended after local hits, degrades typed on
+ *      failure.
+ *
  * When both sources return the same id (a manifest blueprint that
  * also has a cached generation), the manifest entry wins — its
  * metadata is the source of truth and its name/description don't
@@ -26,8 +31,12 @@
  * max of the two so a lexical OR semantic hit keeps the entry in
  * the top band.
  *
- * The merge stays under the `limit` request by taking the top-N
- * after sort. `total` reflects pre-trim matches.
+ * The local merge (manifest + semantic) is trimmed to the top-N
+ * after sort, so it stays within `limit`. Registry candidates are
+ * bounded by the same `limit` on their own request and append AFTER
+ * that trim rather than sharing its budget, so the final `results`
+ * count can reach up to 2×`limit`. `total` reflects the pre-trim
+ * local match count plus the appended registry count.
  *
  * ## Why merge vs. a dedicated tool
  *
@@ -38,8 +47,8 @@
  * the split the server already knows how to make.
  *
  * Pure over `@ggui-ai/mcp-server-core`'s seams. No AWS imports. No
- * config loading. The hosted server's logger wrapper decorates this
- * when composing.
+ * config loading. A composing host may wrap this with its own
+ * logging when assembling the server.
  */
 import { z } from 'zod';
 import type { BlueprintProvider, EmbeddingProvider, VectorStore } from '@ggui-ai/mcp-server-core';
@@ -65,6 +74,30 @@ export declare const MANIFEST_EXACT_NAME_SCORE = 1;
  * stronger signal.
  */
 export declare const MANIFEST_SUBSTRING_SCORE = 0.7;
+/**
+ * Default budget for the registry `/search` round-trip. The registry
+ * source is advisory — a slow registry must never stall the local
+ * sources past this bound. Operator-overridable per-deps.
+ */
+export declare const DEFAULT_REGISTRY_SEARCH_TIMEOUT_MS = 3000;
+/**
+ * Registry-backed discovery source configuration. Presence of this
+ * object on `SearchBlueprintsDeps` ACTIVATES the source (opt-in —
+ * a zero-config server never makes an outbound registry request).
+ */
+export interface SearchBlueprintsRegistrySource {
+    /**
+     * Registry host (`host[:port]`). Absent = `DEFAULT_BUNDLE_HOST`.
+     * Scheme derives via `bundleHostScheme` — http for loopback,
+     * https otherwise (the same resolution the gadget bundleHost
+     * uses).
+     */
+    readonly host?: string;
+    /** Fetch budget in ms. Default `DEFAULT_REGISTRY_SEARCH_TIMEOUT_MS`. */
+    readonly timeoutMs?: number;
+    /** Injectable fetch for tests. Defaults to the global fetch. */
+    readonly fetch?: typeof fetch;
+}
 export interface SearchBlueprintsDeps {
     readonly embedding: EmbeddingProvider;
     readonly vectors: VectorStore;
@@ -74,29 +107,48 @@ export interface SearchBlueprintsDeps {
      * included in the search results alongside the semantic
      * `VectorStore` matches.
      *
-     * Omitted = semantic-only behavior (the pre-merge default). The
-     * hosted server historically ran without a manifest provider on
-     * this handler; OSS `createGguiServer` constructs a
-     * `ManifestBlueprintProvider` at boot and threads it through.
+     * Omitted = semantic-only behavior (the pre-merge default) — a
+     * composing host can run without a manifest provider bound to this
+     * handler. This package's own `createGguiServer` constructs a
+     * `ManifestBlueprintProvider` at boot and threads it through by
+     * default.
      */
     readonly blueprints?: BlueprintProvider;
+    /**
+     * Optional registry discovery source. When bound, the handler
+     * queries the registry's public `/search` for published blueprint
+     * candidates and appends them after the local sources. Omitted =
+     * no outbound registry traffic (the zero-config default).
+     */
+    readonly registry?: SearchBlueprintsRegistrySource;
 }
 declare const inputSchema: {
     readonly query: z.ZodString;
     readonly limit: z.ZodOptional<z.ZodNumber>;
+    readonly tool: z.ZodOptional<z.ZodString>;
+    readonly server: z.ZodOptional<z.ZodString>;
 };
 declare const outputSchema: {
     results: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     total: z.ZodNumber;
     query: z.ZodString;
+    degradedSources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        source: z.ZodLiteral<"registry">;
+        reason: z.ZodEnum<{
+            unreachable: "unreachable";
+            timeout: "timeout";
+            invalid_response: "invalid_response";
+        }>;
+    }, z.core.$strip>>>;
 };
 /**
  * Build a search-blueprints handler bound to concrete `embedding` +
  * `vectors` implementations (required) + an optional manifest
  * `BlueprintProvider`. Tests inject in-memory fakes from
  * `@ggui-ai/mcp-server-core/in-memory`; production hosts bind to
- * AWS Bedrock + S3 Vectors for the semantic source and a
- * `ManifestBlueprintProvider` for the manifest source.
+ * their own operator-configured embedding + vector-store providers
+ * for the semantic source and a `ManifestBlueprintProvider` for the
+ * manifest source.
  */
 export declare function createSearchBlueprintsHandler(deps: SearchBlueprintsDeps): SharedHandler<typeof inputSchema, typeof outputSchema, GguiSearchBlueprintsOutput>;
 export {};

package/dist/blueprints/search-blueprints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-blueprints.d.ts","sourceRoot":"","sources":["../../src/blueprints/search-blueprints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAEV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAGL,KAAK,0BAA0B,EAChC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAkB,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,IAAM,CAAC;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC;CACzC;AAID,QAAA,MAAM,WAAW;;;CAA6B,CAAC;AAE/C,QAAA,MAAM,YAAY;;;;CAUjB,CAAC;AAKF;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,oBAAoB,GACzB,aAAa,CAAC,OAAO,WAAW,EAAE,OAAO,YAAY,EAAE,0BAA0B,CAAC,CA4CpF"}
+{"version":3,"file":"search-blueprints.d.ts","sourceRoot":"","sources":["../../src/blueprints/search-blueprints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAEV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAKL,KAAK,0BAA0B,EAChC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAkB,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,IAAM,CAAC;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,OAAO,CAAC;AAEvD;;;;GAIG;AACH,MAAM,WAAW,8BAA8B;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,8BAA8B,CAAC;CACpD;AAID,QAAA,MAAM,WAAW;;;;;CAA6B,CAAC;AAE/C,QAAA,MAAM,YAAY;;;;;;;;;;;;CAkBjB,CAAC;AAKF;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,oBAAoB,GACzB,aAAa,CAAC,OAAO,WAAW,EAAE,OAAO,YAAY,EAAE,0BAA0B,CAAC,CAyDpF"}

package/dist/blueprints/search-blueprints.js

@@ -2,8 +2,8 @@
  * ggui_search_blueprints — search across every discoverable blueprint
  * on this server.
  *
- * Two sources are consulted in parallel, then merged + de-duplicated
- * by id:
+ * Up to three sources are consulted in parallel, then merged +
+ * de-duplicated by id:
  *
  *   1. **Manifest source** (optional `BlueprintProvider`) — authored
  *      UIs declared in `ggui.json#blueprints.include`. Matched by
@@ -19,6 +19,11 @@
  *      producer that has written into the scope. Continues to honor
  *      `MIN_SIMILARITY_SCORE`.
  *
+ *   3. **Registry source** (optional, opt-in via deps.registry) —
+ *      bounded public /search call for published blueprint
+ *      candidates; appended after local hits, degrades typed on
+ *      failure.
+ *
  * When both sources return the same id (a manifest blueprint that
  * also has a cached generation), the manifest entry wins — its
  * metadata is the source of truth and its name/description don't
@@ -26,8 +31,12 @@
  * max of the two so a lexical OR semantic hit keeps the entry in
  * the top band.
  *
- * The merge stays under the `limit` request by taking the top-N
- * after sort. `total` reflects pre-trim matches.
+ * The local merge (manifest + semantic) is trimmed to the top-N
+ * after sort, so it stays within `limit`. Registry candidates are
+ * bounded by the same `limit` on their own request and append AFTER
+ * that trim rather than sharing its budget, so the final `results`
+ * count can reach up to 2×`limit`. `total` reflects the pre-trim
+ * local match count plus the appended registry count.
  *
  * ## Why merge vs. a dedicated tool
  *
@@ -38,11 +47,11 @@
  * the split the server already knows how to make.
  *
  * Pure over `@ggui-ai/mcp-server-core`'s seams. No AWS imports. No
- * config loading. The hosted server's logger wrapper decorates this
- * when composing.
+ * config loading. A composing host may wrap this with its own
+ * logging when assembling the server.
  */
 import { z } from 'zod';
-import { flatToBlueprintSource, searchBlueprintsInputShape, } from '@ggui-ai/protocol';
+import { bundleHostScheme, DEFAULT_BUNDLE_HOST, flatToBlueprintSource, searchBlueprintsInputShape, } from '@ggui-ai/protocol';
 /**
  * Matches the hosted `MIN_SIMILARITY_SCORE`. Below this is noise —
  * callers that want stricter matching post-filter by `score`.
@@ -63,6 +72,12 @@ export const MANIFEST_EXACT_NAME_SCORE = 1.0;
  * stronger signal.
  */
 export const MANIFEST_SUBSTRING_SCORE = 0.7;
+/**
+ * Default budget for the registry `/search` round-trip. The registry
+ * source is advisory — a slow registry must never stall the local
+ * sources past this bound. Operator-overridable per-deps.
+ */
+export const DEFAULT_REGISTRY_SEARCH_TIMEOUT_MS = 3000;
 // Canonical SSoT shape — authored once in `@ggui-ai/protocol`
 // (`schemas/mcp.ts`).
 const inputSchema = searchBlueprintsInputShape;
@@ -76,32 +91,42 @@ const outputSchema = {
     results: z.array(z.record(z.string(), z.unknown())),
     total: z.number().int().nonnegative(),
     query: z.string(),
+    degradedSources: z
+        .array(z.object({
+        source: z.literal('registry'),
+        reason: z.enum(['unreachable', 'timeout', 'invalid_response']),
+    }))
+        .optional(),
 };
 /**
  * Build a search-blueprints handler bound to concrete `embedding` +
  * `vectors` implementations (required) + an optional manifest
  * `BlueprintProvider`. Tests inject in-memory fakes from
  * `@ggui-ai/mcp-server-core/in-memory`; production hosts bind to
- * AWS Bedrock + S3 Vectors for the semantic source and a
- * `ManifestBlueprintProvider` for the manifest source.
+ * their own operator-configured embedding + vector-store providers
+ * for the semantic source and a `ManifestBlueprintProvider` for the
+ * manifest source.
  */
 export function createSearchBlueprintsHandler(deps) {
     return {
         name: 'ggui_search_blueprints',
         title: 'Search blueprints',
         audience: ['agent'],
-        description: "Search this app's blueprints — both manifest-declared UIs (ggui.json#blueprints.include) and any previously cached generations. Matches by name/description against the manifest source and by cosine similarity against the semantic vector index. Returns entries ordered by score (descending). The agent can decide to reuse a match or generate from scratch.",
+        description: "Search this app's blueprints — manifest-declared UIs (ggui.json#blueprints.include), previously cached generations, and, when a registry is configured, published blueprint candidates from the artifact registry. Local sources match by name/description and cosine similarity; registry candidates are advisory matches appended after local results, labeled origin 'registry'. Optional tool/server filters narrow registry candidates to artifacts declaring those MCP tool bindings. The agent can decide to reuse a match or generate from scratch; installing a registry candidate remains a human/operator act.",
         inputSchema,
         outputSchema,
         async handler(rawInput, ctx) {
-            const { query, limit = 10 } = z.object(inputSchema).parse(rawInput);
-            // Fan out both sources in parallel. The manifest source is a
+            const { query, limit = 10, tool, server } = z
+                .object(inputSchema)
+                .parse(rawInput);
+            // Fan out all sources in parallel. The manifest source is a
             // pure metadata read (cheap); the semantic source is one
-            // `embed` + one `query` round-trip. Running them concurrently
-            // keeps handler latency close to the slower of the two.
-            const [semantic, manifest] = await Promise.all([
+            // `embed` + one `query` round-trip; the registry source is a
+            // bounded HTTP call that degrades typed instead of throwing.
+            const [semantic, manifest, registry] = await Promise.all([
                 searchSemantic(deps, ctx.appId, query, limit),
                 searchManifest(deps.blueprints, query, limit),
+                searchRegistry(deps.registry, { query, tool, server, limit }, ctx.signal),
             ]);
             // Merge + dedupe by id. Manifest entries win on collision —
             // their metadata is author-curated and cannot drift against a
@@ -117,7 +142,15 @@ export function createSearchBlueprintsHandler(deps) {
             }
             const merged = Array.from(byId.values()).sort((a, b) => b.score - a.score);
             const trimmed = merged.slice(0, limit);
-            return { results: trimmed, total: merged.length, query };
+            // Registry candidates append AFTER the local sources (advisory
+            // per the discovery design §3) and never displace a local id.
+            const registryHits = registry.hits.filter((hit) => !byId.has(hit.id));
+            return {
+                results: [...trimmed, ...registryHits],
+                total: merged.length + registryHits.length,
+                query,
+                ...(registry.degraded ? { degradedSources: [registry.degraded] } : {}),
+            };
         },
     };
 }
@@ -222,3 +255,120 @@ function toManifestHit(entry, queryLower) {
 function asString(value) {
     return typeof value === 'string' ? value : '';
 }
+/**
+ * Wire subset of the registry `GET /search` response this handler
+ * consumes. Local on purpose: this package does not depend on the
+ * registry server implementation, and zod's default strip semantics
+ * keep the guard forward-compatible with response additions.
+ */
+const registrySearchEntrySchema = z.object({
+    artifactId: z.string().min(1),
+    latestVersion: z.string().min(1),
+    kind: z.string(),
+    description: z.string().optional(),
+    mcpTools: z.array(z.object({ server: z.string().optional(), tool: z.string() })).optional(),
+    scopeVerification: z.enum(['verified', 'unverified']).optional(),
+});
+const registrySearchResponseSchema = z.object({
+    results: z.array(registrySearchEntrySchema),
+});
+/**
+ * Registry-source branch: bounded public `/search` call. Inactive
+ * (empty hits, no degradation) when no registry source is
+ * configured. Never throws — every failure mode maps onto the typed
+ * `degraded` indication so the merged tool result always succeeds.
+ */
+async function searchRegistry(registry, filters, signal) {
+    if (!registry)
+        return { hits: [] };
+    // Operator-override-then-default host resolution — the same
+    // precedence + scheme rule as gadget bundleHost (`DEFAULT_BUNDLE_HOST`
+    // + `bundleHostScheme` from `@ggui-ai/protocol`).
+    const host = typeof registry.host === 'string' && registry.host.length > 0
+        ? registry.host
+        : DEFAULT_BUNDLE_HOST;
+    const params = new URLSearchParams();
+    params.set('q', filters.query);
+    // This tool's kind scope is blueprints; gadget discovery is served
+    // by the registry HTTP surface directly.
+    params.set('kind', 'blueprint');
+    if (filters.tool !== undefined)
+        params.set('tool', filters.tool);
+    if (filters.server !== undefined)
+        params.set('server', filters.server);
+    params.set('limit', String(filters.limit));
+    const url = `${bundleHostScheme(host)}://${host}/search?${params.toString()}`;
+    const timeoutMs = registry.timeoutMs ?? DEFAULT_REGISTRY_SEARCH_TIMEOUT_MS;
+    const signals = [AbortSignal.timeout(timeoutMs)];
+    if (signal)
+        signals.push(signal);
+    const fetchImpl = registry.fetch ?? fetch;
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: 'GET',
+            headers: { accept: 'application/json' },
+            signal: AbortSignal.any(signals),
+        });
+    }
+    catch (err) {
+        const reason = err instanceof Error && err.name === 'TimeoutError' ? 'timeout' : 'unreachable';
+        return { hits: [], degraded: { source: 'registry', reason } };
+    }
+    if (!res.ok) {
+        // Undici doesn't return the socket to the pool until the body is
+        // consumed or canceled. We never read this body (non-2xx), so
+        // cancel it explicitly — a rejecting cancel() must still surface
+        // the already-typed degradation, not throw past this branch.
+        try {
+            await res.body?.cancel();
+        }
+        catch {
+            // Deliberately swallowed — see comment above.
+        }
+        return {
+            hits: [],
+            degraded: { source: 'registry', reason: 'invalid_response' },
+        };
+    }
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        return {
+            hits: [],
+            degraded: { source: 'registry', reason: 'invalid_response' },
+        };
+    }
+    const parsed = registrySearchResponseSchema.safeParse(body);
+    if (!parsed.success) {
+        return {
+            hits: [],
+            degraded: { source: 'registry', reason: 'invalid_response' },
+        };
+    }
+    return { hits: parsed.data.results.map(toRegistryHit) };
+}
+function toRegistryHit(entry) {
+    return {
+        id: `${entry.artifactId}@${entry.latestVersion}`,
+        name: entry.artifactId,
+        description: entry.description ?? '',
+        category: entry.kind,
+        // Registry search rows carry no contract details — honest empties.
+        props: [],
+        callbacks: [],
+        featured: false,
+        relevance: 'match',
+        // The registry source computes no similarity. Entries always
+        // append AFTER the score-sorted local sources, so this value
+        // carries no ranking weight; 0 is the honest "not measured".
+        score: 0,
+        origin: 'registry',
+        artifactId: entry.artifactId,
+        version: entry.latestVersion,
+        ...(entry.mcpTools ? { mcpTools: entry.mcpTools } : {}),
+        ...(entry.scopeVerification ? { scopeVerification: entry.scopeVerification } : {}),
+    };
+}

package/dist/renders/amend.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `ggui_amend` — in-place props mutation on the ALREADY-MOUNTED card
+ * (#483 tool split). Same wire grammar as `ggui_update`
+ * (replace/merge via the shared {@link runPropsMutation} core), the
+ * opposite mount identity:
+ *
+ *   - NO history record: the head epoch is untouched by construction
+ *     (the core advances it only for `ggui_update`).
+ *   - NO `_meta.ui` on the tool DECLARATION and NO `resultMeta` — this
+ *     is a plain data tool. Hosts never reserve a per-result view for
+ *     it (hosts mint views from `_meta` on UI-bound success results —
+ *     live-proven 2026-08-12), so nothing new appears in the
+ *     conversation. The mounted card receives the new props over the
+ *     live-channel ladder (WS / SSE / polling / bridge-pull); the
+ *     spec tool-result forwarding path is deliberately not part of
+ *     this tool's contract.
+ *
+ * Git reading: `ggui_update` = commit (new history entry);
+ * `ggui_amend` = commit --amend (fix up the current one).
+ */
+import { z } from 'zod';
+import type { SharedHandler } from '../types.js';
+import { mutationInputSchema } from './props-mutation-core.js';
+import type { GguiUpdateHandlerDeps } from './update.js';
+/**
+ * Same seam set as `ggui_update` on purpose — the two tools share ONE
+ * mutation core, so composers wire ONE deps object for both. The
+ * slice-meta options (`mintWsToken` / `runtimeUrl` / theme plumbing)
+ * are simply never read on the amend path (no result meta exists to
+ * emit them into).
+ */
+export type GguiAmendHandlerDeps = GguiUpdateHandlerDeps;
+declare const outputSchema: {
+    readonly sessionId: z.ZodString;
+    readonly updated: z.ZodBoolean;
+    /**
+     * The BARE live-head URI — amend targets the mounted card and never
+     * mints a record, so there is no pinned URI to return and no epoch
+     * field (the history number is untouched by construction).
+     */
+    readonly resourceUri: z.ZodString;
+    /** No-op feedback channel — same semantics as ggui_update's. */
+    readonly warning: z.ZodOptional<z.ZodString>;
+};
+interface AmendOutput {
+    sessionId: string;
+    updated: boolean;
+    resourceUri: string;
+    warning?: string;
+}
+/**
+ * Build the OSS `ggui_amend` handler. Additive, like `update:` — server
+ * composers opt in via the dedicated `amend:` slot.
+ */
+export declare function createGguiAmendHandler(deps: GguiAmendHandlerDeps): SharedHandler<typeof mutationInputSchema, typeof outputSchema, AmendOutput>;
+export {};
+//# sourceMappingURL=amend.d.ts.map

package/dist/renders/amend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amend.d.ts","sourceRoot":"","sources":["../../src/renders/amend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAkB,aAAa,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EACL,mBAAmB,EAEpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AAEzD,QAAA,MAAM,YAAY;;;IAGhB;;;;OAIG;;IAEH,gEAAgE;;CAExD,CAAC;AAEX,UAAU,WAAW;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,oBAAoB,GACzB,aAAa,CAAC,OAAO,mBAAmB,EAAE,OAAO,YAAY,EAAE,WAAW,CAAC,CA0B7E"}

package/dist/renders/amend.js

@@ -0,0 +1,64 @@
+/**
+ * `ggui_amend` — in-place props mutation on the ALREADY-MOUNTED card
+ * (#483 tool split). Same wire grammar as `ggui_update`
+ * (replace/merge via the shared {@link runPropsMutation} core), the
+ * opposite mount identity:
+ *
+ *   - NO history record: the head epoch is untouched by construction
+ *     (the core advances it only for `ggui_update`).
+ *   - NO `_meta.ui` on the tool DECLARATION and NO `resultMeta` — this
+ *     is a plain data tool. Hosts never reserve a per-result view for
+ *     it (hosts mint views from `_meta` on UI-bound success results —
+ *     live-proven 2026-08-12), so nothing new appears in the
+ *     conversation. The mounted card receives the new props over the
+ *     live-channel ladder (WS / SSE / polling / bridge-pull); the
+ *     spec tool-result forwarding path is deliberately not part of
+ *     this tool's contract.
+ *
+ * Git reading: `ggui_update` = commit (new history entry);
+ * `ggui_amend` = commit --amend (fix up the current one).
+ */
+import { z } from 'zod';
+import { mutationInputSchema, runPropsMutation, } from './props-mutation-core.js';
+const outputSchema = {
+    sessionId: z.string(),
+    updated: z.boolean(),
+    /**
+     * The BARE live-head URI — amend targets the mounted card and never
+     * mints a record, so there is no pinned URI to return and no epoch
+     * field (the history number is untouched by construction).
+     */
+    resourceUri: z.string(),
+    /** No-op feedback channel — same semantics as ggui_update's. */
+    warning: z.string().optional(),
+};
+/**
+ * Build the OSS `ggui_amend` handler. Additive, like `update:` — server
+ * composers opt in via the dedicated `amend:` slot.
+ */
+export function createGguiAmendHandler(deps) {
+    return {
+        name: 'ggui_amend',
+        title: 'Amend',
+        // Deliberately NO `_meta` — see the module docstring. Declaring
+        // the UI binding here would make hosts treat amend results as
+        // renderable views, which is exactly what this tool exists to
+        // avoid.
+        audience: ['agent'],
+        description: deps.description ??
+            "Update the rendered UI's props IN PLACE — repaint the currently mounted card without adding a new card to the conversation; the history number does not advance. This is the DEFAULT mutation of the render/update family for reacting to user gestures (see ggui_update for the new-card variant). USE THIS AFTER ANY DOMAIN-TOOL CALL THAT CHANGED DATA THE UI SHOWS — e.g. you handled a `todo_toggle`/`cart_add`/`note_save` event from `ggui_consume`, mutated backend state, and the user is staring at stale props. Skipping this leaves the card frozen on the old state and is the #1 wire bug. Pattern: `consume → domain-tool → ggui_amend → loop`. The card repaints WITHOUT losing scroll position, focus, or uncommitted input.  Two mutation modes:  (1) `{sessionId, kind:'replace', props}` — full props replacement.  (2) `{sessionId, kind:'merge', patch}` — RFC 7396 JSON Merge Patch; send ONLY the delta (null deletes a key; arrays fully replace). Prefer `merge` after a single domain-tool mutation.  Both modes validate the FINAL props against the GguiSession's `propsSpec` (when declared) and reject on violation.  For a state MILESTONE that deserves its own new card in the conversation — or when the original card is no longer visible or usable — use ggui_update instead (it renders the state as a new card and advances the history number).",
+        inputSchema: mutationInputSchema,
+        outputSchema,
+        async handler(input, ctx) {
+            const r = await runPropsMutation(deps, 'ggui_amend', input, ctx);
+            return {
+                sessionId: r.sessionId,
+                updated: r.updated,
+                resourceUri: r.mountResourceUri,
+                ...(r.warning !== undefined ? { warning: r.warning } : {}),
+            };
+        },
+        // NO resultMeta — a `_meta`-carrying success result would make
+        // hosts mint a per-result view (live-proven), defeating the tool.
+    };
+}

package/dist/renders/apply-ggui-session-patch.d.ts

@@ -45,10 +45,14 @@ export type ApplyGguiSessionPatchInput<T extends GguiSessionTarget> = {
     readonly render: T;
     readonly mode: 'replace';
     readonly props: JsonObject;
+    /** Error attribution for propsSpec violations (#483). Default `'ggui_update'`. */
+    readonly tool?: 'ggui_update' | 'ggui_amend';
 } | {
     readonly render: T;
     readonly mode: 'merge';
     readonly patch: JsonObject;
+    /** Error attribution for propsSpec violations (#483). Default `'ggui_update'`. */
+    readonly tool?: 'ggui_amend' | 'ggui_update';
 };
 export interface ApplyGguiSessionPatchResult<T extends GguiSessionTarget> {
     /** The updated render (post-patch). Safe to persist. */

package/dist/renders/apply-ggui-session-patch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply-ggui-session-patch.d.ts","sourceRoot":"","sources":["../../src/renders/apply-ggui-session-patch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,UAAU,EAAa,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAG1E;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;CAC7B;AAED,MAAM,MAAM,0BAA0B,CAAC,CAAC,SAAS,iBAAiB,IAC9D;IACE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B,CAAC;AAEN,MAAM,WAAW,2BAA2B,CAAC,CAAC,SAAS,iBAAiB;IACtE,wDAAwD;IACxD,QAAQ,CAAC,cAAc,EAAE,CAAC,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,UAAU,GAChB,UAAU,CAwBZ;AAED,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,iBAAiB,EAC/D,KAAK,EAAE,0BAA0B,CAAC,CAAC,CAAC,GACnC,2BAA2B,CAAC,CAAC,CAAC,CAyBhC"}
+{"version":3,"file":"apply-ggui-session-patch.d.ts","sourceRoot":"","sources":["../../src/renders/apply-ggui-session-patch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,UAAU,EAAa,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAG1E;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;CAC7B;AAED,MAAM,MAAM,0BAA0B,CAAC,CAAC,SAAS,iBAAiB,IAC9D;IACE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,YAAY,CAAC;CAC9C,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,aAAa,CAAC;CAC9C,CAAC;AAEN,MAAM,WAAW,2BAA2B,CAAC,CAAC,SAAS,iBAAiB;IACtE,wDAAwD;IACxD,QAAQ,CAAC,cAAc,EAAE,CAAC,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,UAAU,GAChB,UAAU,CAwBZ;AAED,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,iBAAiB,EAC/D,KAAK,EAAE,0BAA0B,CAAC,CAAC,CAAC,GACnC,2BAA2B,CAAC,CAAC,CAAC,CAyBhC"}

package/dist/renders/apply-ggui-session-patch.js

@@ -49,7 +49,7 @@ export function applyGguiSessionPatch(input) {
     // unknown-key strictness. For merge mode, this catches the case
     // where the patch's null-delete would orphan a required field, or
     // a recursive merge would introduce an undeclared key.
-    assertPropsContract(existing.propsSpec, finalProps);
+    assertPropsContract(existing.propsSpec, finalProps, input.tool ?? 'ggui_update');
     // Spread preserves T's other fields; the `props` override lands on
     // top. The spread infers `T & { props: JsonObject }`, which is
     // assignable to `T` — no cast needed.

package/dist/renders/assert-props-contract.d.ts

@@ -5,9 +5,10 @@
  * Contract:
  *   - `spec === undefined` → no-op (matches legacy ggui_update: missing
  *     propsSpec is permissive, no validation runs).
- *   - Otherwise validate; on failure throw `ContractViolationError` with
- *     tool=`'ggui_update'` so error shape matches the existing protocol
- *     response envelope.
+ *   - Otherwise validate; on failure throw `ContractViolationError`
+ *     attributed to the calling tool (`ggui_update` by default —
+ *     `ggui_amend` threads its own name, #483) so the error envelope
+ *     names the tool the agent actually called.
  *
  * This helper is the centralized enforcement point for props contracts —
  * every mutation path that applies new props to a render SHOULD go
@@ -15,5 +16,5 @@
  * bypass validation entirely.
  */
 import { type PropsSpec } from '@ggui-ai/protocol';
-export declare function assertPropsContract(spec: PropsSpec | undefined, patch: Record<string, unknown>): void;
+export declare function assertPropsContract(spec: PropsSpec | undefined, patch: Record<string, unknown>, tool?: 'ggui_update' | 'ggui_amend'): void;
 //# sourceMappingURL=assert-props-contract.d.ts.map

package/dist/renders/assert-props-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assert-props-contract.d.ts","sourceRoot":"","sources":["../../src/renders/assert-props-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,mBAAmB,CAAC;AAE3B,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CASN"}
+{"version":3,"file":"assert-props-contract.d.ts","sourceRoot":"","sources":["../../src/renders/assert-props-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,mBAAmB,CAAC;AAE3B,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,GAAE,aAAa,GAAG,YAA4B,GACjD,IAAI,CASN"}

package/dist/renders/assert-props-contract.js

@@ -5,9 +5,10 @@
  * Contract:
  *   - `spec === undefined` → no-op (matches legacy ggui_update: missing
  *     propsSpec is permissive, no validation runs).
- *   - Otherwise validate; on failure throw `ContractViolationError` with
- *     tool=`'ggui_update'` so error shape matches the existing protocol
- *     response envelope.
+ *   - Otherwise validate; on failure throw `ContractViolationError`
+ *     attributed to the calling tool (`ggui_update` by default —
+ *     `ggui_amend` threads its own name, #483) so the error envelope
+ *     names the tool the agent actually called.
  *
  * This helper is the centralized enforcement point for props contracts —
  * every mutation path that applies new props to a render SHOULD go
@@ -15,13 +16,13 @@
  * bypass validation entirely.
  */
 import { ContractViolationError, validatePropsData, } from '@ggui-ai/protocol';
-export function assertPropsContract(spec, patch) {
+export function assertPropsContract(spec, patch, tool = 'ggui_update') {
     if (!spec)
         return;
     const result = validatePropsData(patch, spec);
     if (!result.valid) {
         throw new ContractViolationError({
-            tool: 'ggui_update',
+            tool,
             violations: result.violations,
         });
     }