@ggui-ai/mcp-server-handlers 0.6.3 → 0.8.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/ops-apps/delete-app.d.ts

@@ -1,23 +1,38 @@
 /**
- * `ggui_ops_delete_app` — hard-delete a `GguiApp` row owned by the
+ * `ggui_ops_delete_app` — hard-delete an app record owned by the
  * caller.
  *
  * Tenancy: cross-tenant probes return the success shape WITHOUT
  * touching the row (uniform shape; no existence leak). Idempotent —
  * a second delete of the same id resolves cleanly.
  *
- * What the cloud adapter additionally does on top of this seam (NOT
- * the responsibility of the handler):
- *   - Cascade-revoke per-app `GguiUserApiKey` rows
- *   - Cascade-clean per-app provider keys, blueprints, renders
- * The handler stays narrow; the adapter's `delete()` implementation
- * orchestrates the cascade.
+ * Default-app lock: REJECTED when the target is the caller's default
+ * app. `defaultAppId` is what the universal route resolves on every
+ * request, so deleting the app it names strands that route.
  *
- * Pure over the {@link AppsSource} seam.
+ * The check runs AFTER the ownership read. `getDefault(ownerSub)`
+ * only ever reads the caller's own row, so ordering is not what keeps
+ * another tenant's default secret — nothing here could read it under
+ * any ordering. What ordering buys is SHAPE UNIFORMITY in the one
+ * state where the two branches disagree: the caller's own default
+ * naming an app the caller does not own. Ownership first answers that
+ * with the same `{deleted: true}` every other foreign id gets;
+ * lock-first would answer with a distinguishable error, and the
+ * difference is itself the signal.
+ *
+ * Scope: this handler removes the APP RECORD, through
+ * {@link AppsSource.delete}, and claims nothing beyond it. Whether
+ * data other stores hold for the same app disappears with it is the
+ * bound implementation's business, spelled out in that method's
+ * contract. `{deleted: true}` means the app record is gone — read no
+ * cascade into it.
+ *
+ * Pure over the {@link AppsSource} + {@link UserDefaultAppSource}
+ * seams.
  */
 import { z } from 'zod';
 import type { SharedHandler } from '../types.js';
-import type { AppsSource } from './types.js';
+import type { AppsSource, UserDefaultAppSource } from './types.js';
 declare const inputSchema: {
     readonly appId: z.ZodString;
 };
@@ -29,6 +44,8 @@ export interface DeleteAppOutput {
 }
 export interface DeleteAppDeps {
     readonly apps: AppsSource;
+    /** Read side only — the default-app lock reads `defaultAppId`, never writes it. */
+    readonly userDefaultApp: UserDefaultAppSource;
 }
 export declare function createDeleteAppHandler(deps: DeleteAppDeps): SharedHandler<typeof inputSchema, typeof outputSchema, DeleteAppOutput>;
 export {};

package/dist/ops-apps/delete-app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delete-app.d.ts","sourceRoot":"","sources":["../../src/ops-apps/delete-app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAkB,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,QAAA,MAAM,WAAW;;CAOP,CAAC;AAEX,QAAA,MAAM,YAAY;;CAER,CAAC;AAEX,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,aAAa,GAClB,aAAa,CAAC,OAAO,WAAW,EAAE,OAAO,YAAY,EAAE,eAAe,CAAC,CA8BzE"}
+{"version":3,"file":"delete-app.d.ts","sourceRoot":"","sources":["../../src/ops-apps/delete-app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAkB,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjE,OAAO,KAAK,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEnE,QAAA,MAAM,WAAW;;CAOP,CAAC;AAEX,QAAA,MAAM,YAAY;;CAER,CAAC;AAEX,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,cAAc,EAAE,oBAAoB,CAAC;CAC/C;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,aAAa,GAClB,aAAa,CAAC,OAAO,WAAW,EAAE,OAAO,YAAY,EAAE,eAAe,CAAC,CAqCzE"}

package/dist/ops-apps/delete-app.js

@@ -1,22 +1,38 @@
 /**
- * `ggui_ops_delete_app` — hard-delete a `GguiApp` row owned by the
+ * `ggui_ops_delete_app` — hard-delete an app record owned by the
  * caller.
  *
  * Tenancy: cross-tenant probes return the success shape WITHOUT
  * touching the row (uniform shape; no existence leak). Idempotent —
  * a second delete of the same id resolves cleanly.
  *
- * What the cloud adapter additionally does on top of this seam (NOT
- * the responsibility of the handler):
- *   - Cascade-revoke per-app `GguiUserApiKey` rows
- *   - Cascade-clean per-app provider keys, blueprints, renders
- * The handler stays narrow; the adapter's `delete()` implementation
- * orchestrates the cascade.
+ * Default-app lock: REJECTED when the target is the caller's default
+ * app. `defaultAppId` is what the universal route resolves on every
+ * request, so deleting the app it names strands that route.
  *
- * Pure over the {@link AppsSource} seam.
+ * The check runs AFTER the ownership read. `getDefault(ownerSub)`
+ * only ever reads the caller's own row, so ordering is not what keeps
+ * another tenant's default secret — nothing here could read it under
+ * any ordering. What ordering buys is SHAPE UNIFORMITY in the one
+ * state where the two branches disagree: the caller's own default
+ * naming an app the caller does not own. Ownership first answers that
+ * with the same `{deleted: true}` every other foreign id gets;
+ * lock-first would answer with a distinguishable error, and the
+ * difference is itself the signal.
+ *
+ * Scope: this handler removes the APP RECORD, through
+ * {@link AppsSource.delete}, and claims nothing beyond it. Whether
+ * data other stores hold for the same app disappears with it is the
+ * bound implementation's business, spelled out in that method's
+ * contract. `{deleted: true}` means the app record is gone — read no
+ * cascade into it.
+ *
+ * Pure over the {@link AppsSource} + {@link UserDefaultAppSource}
+ * seams.
  */
 import { z } from 'zod';
 import { resolveOwnerSub } from './identity.js';
+import { DefaultAppDeleteBlockedError } from './types.js';
 const inputSchema = {
     appId: z
         .string()
@@ -31,7 +47,7 @@ export function createDeleteAppHandler(deps) {
         name: 'ggui_ops_delete_app',
         title: 'Delete app',
         audience: ['ops'],
-        description: "Hard-delete an app owned by the calling user. Idempotent — a second delete returns `{deleted: true}`. Cross-tenant probes return the same shape without touching foreign rows (no existence leak). Cascades per-app keys / blueprints / renders at the cloud adapter layer.",
+        description: "Hard-delete an app owned by the calling user. Removes the APP RECORD only — data other stores hold for that app (saved blueprints, per-app provider keys, marketplace installs, issued keys) is not removed by this call, and whether the deployment cleans it up separately is the deployment's own policy. Idempotent — a second delete returns `{deleted: true}`. Cross-tenant probes return the same shape without touching foreign rows (no existence leak). Throws `default_app_delete_blocked` when the target is the caller's default app — set a different default first.",
         inputSchema,
         outputSchema,
         async handler(rawInput, ctx) {
@@ -44,10 +60,17 @@ export function createDeleteAppHandler(deps) {
             if (!existing) {
                 // Either the row doesn't exist or it lives under a different
                 // owner. Either way: return the success shape without
-                // touching DDB. Uniform across "missing" and "cross-tenant"
-                // prevents id-existence leak.
+                // touching the store. Uniform across "missing" and
+                // "cross-tenant" prevents id-existence leak.
                 return { deleted: true };
             }
+            // AFTER the ownership read, so a caller whose own default names
+            // a foreign app gets the same uniform shape as any other foreign
+            // id rather than a distinguishable lock error.
+            const currentDefault = await deps.userDefaultApp.getDefault(ownerSub);
+            if (currentDefault === parsed.appId) {
+                throw new DefaultAppDeleteBlockedError(parsed.appId);
+            }
             await deps.apps.delete({ appId: parsed.appId, ownerSub });
             return { deleted: true };
         },

package/dist/ops-apps/index.d.ts

@@ -14,7 +14,7 @@
  *   - `createSetDefaultAppHandler` → `ggui_ops_set_default_app`
  */
 export type { AppRecord, AppsSource, AppUpdatePatch, UserDefaultAppSource, } from './types.js';
-export { AppNotFoundError, OpsAppsAccessDeniedError } from './types.js';
+export { AppNotFoundError, DefaultAppDeleteBlockedError, OpsAppsAccessDeniedError, } from './types.js';
 export { createListAppsHandler } from './list-apps.js';
 export type { ListAppsDeps, ListAppsOutput } from './list-apps.js';
 export { createCreateAppHandler } from './create-app.js';

package/dist/ops-apps/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ops-apps/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EACV,SAAS,EACT,UAAU,EACV,cAAc,EACd,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAExE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EACV,eAAe,EACf,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,YAAY,EACV,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ops-apps/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EACV,SAAS,EACT,UAAU,EACV,cAAc,EACd,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EACV,eAAe,EACf,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,YAAY,EACV,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC"}

package/dist/ops-apps/index.js

@@ -13,7 +13,7 @@
  *   - `createDeleteAppHandler` → `ggui_ops_delete_app`
  *   - `createSetDefaultAppHandler` → `ggui_ops_set_default_app`
  */
-export { AppNotFoundError, OpsAppsAccessDeniedError } from './types.js';
+export { AppNotFoundError, DefaultAppDeleteBlockedError, OpsAppsAccessDeniedError, } from './types.js';
 export { createListAppsHandler } from './list-apps.js';
 export { createCreateAppHandler } from './create-app.js';
 export { createUpdateAppHandler } from './update-app.js';

package/dist/ops-apps/types.d.ts

@@ -99,7 +99,25 @@ export interface AppsSource {
         ownerSub: string;
         patch: AppUpdatePatch;
     }): Promise<AppRecord>;
-    /** Hard delete. No-throw idempotent — second delete of the same id resolves. */
+    /**
+     * Hard delete. No-throw idempotent — a second delete of the same id
+     * resolves. Rejects cross-tenant.
+     *
+     * Scope of the obligation, stated because a caller cannot see it:
+     * this seam owns the APP RECORD and nothing else. Whatever other
+     * stores hold keyed by the same `appId` — saved blueprints, per-app
+     * provider keys, marketplace installs, issued keys — is outside it.
+     *
+     * An implementation MAY cascade those away inside its own `delete`,
+     * and MAY complete that cascade asynchronously after resolving. One
+     * that leaves rows behind — permanently or until an asynchronous
+     * sweep lands — MUST make that observable: a named, structured event
+     * naming the row classes left in place, emitted on the delete that
+     * orphaned them, carrying an indication of whether asynchronous
+     * completion was arranged. Returning silently is the contract
+     * violation — not the orphaning itself. Orphaned rows an operator
+     * can enumerate are debt; orphaned rows nobody can find are loss.
+     */
     delete(args: {
         appId: string;
         ownerSub: string;
@@ -143,6 +161,19 @@ export declare class AppNotFoundError extends Error {
     readonly code: "app_not_found";
     constructor(appId: string);
 }
+/**
+ * Thrown when the delete target IS the caller's default app.
+ *
+ * `defaultAppId` is what the universal route resolves on every
+ * request; deleting the app it names would leave that route pointing
+ * at a row that no longer exists. Same lock the console's Delete
+ * enforces — the operator picks a different default first, then
+ * deletes.
+ */
+export declare class DefaultAppDeleteBlockedError extends Error {
+    readonly code: "default_app_delete_blocked";
+    constructor(appId: string);
+}
 /**
  * Thrown by adapters that prefer surfacing access denial over the
  * "treat as not-found" privacy posture. Handlers translate to the