@ggui-ai/mcp-server-handlers 0.24.0 → 0.26.0

package/dist/renders/consume.js

@@ -68,27 +68,36 @@ export function createGguiConsumeHandler(deps) {
         name: 'ggui_consume',
         title: 'Consume',
         audience: ['agent'],
-        description: 'Long-poll for buffered events on a GguiSession. CALL THIS RIGHT AFTER EVERY `ggui_render` THAT RETURNS `nextStep.tool === "ggui_consume"` — that hint is your cue to start listening for the user\'s gesture. Keyed by sessionId (global UUID); app-scoped via ctx.appId. Inline long-poll: `timeout` is an integer in [0, 25] seconds (default 0 — an instant non-blocking drain; values outside reject INVALID_PARAMS — host MCP clients abort longer tool calls; pick 5-15s typical, 25 max). Returns `{events, status}` — each event carries `{type: "action", sessionId, intent, actionData, uiContext, actionId, firedAt}`: `actionData` is WHAT the user did, `uiContext` is the iframe-local snapshot of the contract\'s contextSpec slots AT THE MOMENT they did it. Both inform your reaction without a second round trip. Returns immediately when an action event arrives OR the render completes OR the timeout elapses. On timeout with no event you may re-call once, then end your turn — a later gesture arrives as a new user message.  THE LOOP: when `events` is non-empty, REACT, then re-call `ggui_consume` for the next gesture; when `events` is empty, end your turn — a later gesture arrives as a new user message carrying its own consume directive. status:"expired" means the render is gone.  IMPORTANT — the iframe state is independent of your backend state: after you mutate via domain tools (todo_toggle, cart_add, etc.), the UI still shows the OLD props until you call `ggui_amend`. If the events caused observable state changes the user is looking at, your reaction MUST include `ggui_amend` somewhere before re-consuming; otherwise the user sees stale props (the #1 wire compliance bug). Pure-info events that don\'t change displayed state can skip it. `ggui_amend` repaints the SAME card in place (the default move in this loop); `ggui_update` instead renders the state as a NEW card and advances the history number — reserve it for milestones worth a card in the transcript.  HOSTS WITH PROGRESSIVE TOOL DISCOVERY (claude.ai-style connectors): if a call here errors with "tool not loaded yet" or "wrong parameter names," call `tool_search({query:"ggui_consume"})` once to warm the tool, then retry with the same args. DO NOT skip the consume — silent gesture drops are the worst protocol failure. IDEMPOTENCY: treat the `actionId` on each entry as an idempotency key and apply a side-effecting action AT MOST ONCE per `actionId` — the same id delivered twice is one gesture replayed, never two. This holds for EVERY action, not only those a contract marks `oneShot`: a card served mid-rollout may be running a runtime that suppresses nothing, and keying on the marker would leave a hole exactly there. Two DISTINCT ids are two distinct gestures and both are real.',
+        description: "Long-poll for buffered events on a GguiSession. CALL THIS RIGHT AFTER EVERY `ggui_render` THAT RETURNS `nextStep.tool === \"ggui_consume\"` \u2014 that hint is your cue to start listening for the user's gesture. DO NOT skip the consume \u2014 silent gesture drops are the worst protocol failure. `timeout` is an integer in [0, 25] seconds (default 0 \u2014 an instant non-blocking drain; values outside reject INVALID_PARAMS \u2014 hosts abort longer tool calls; pick 5-15s, 25 max). Returns `{events, status}`; each event is `{type: \"action\", sessionId, intent, actionData, uiContext, actionId, firedAt}` \u2014 `actionData` is WHAT the user did, `uiContext` the iframe-local snapshot of the contract's contextSpec slots AT THE MOMENT they did it. Returns immediately when an action event arrives OR the render completes OR the timeout elapses; status:\"expired\" means the render is gone. THE LOOP: when `events` is non-empty, REACT, then re-call `ggui_consume` for the next gesture; when `events` is empty, end your turn (on a timeout with no event you may re-call once first) \u2014 a later gesture arrives as a new user message carrying its own consume directive. IMPORTANT \u2014 the iframe state is independent of your backend state: after you mutate via domain tools (todo_toggle, cart_add, etc.), the UI still shows the OLD props until you call `ggui_amend`. If the events caused observable state changes the user is looking at, your reaction MUST include `ggui_amend` before re-consuming; otherwise the user sees stale props (the #1 wire compliance bug). Pure-info events that don't change displayed state can skip it. `ggui_amend` repaints the SAME card in place (the default move in this loop); `ggui_update` renders the state as a NEW card and advances the history number \u2014 reserve it for milestones worth a card in the transcript. IDEMPOTENCY: treat each entry's `actionId` as an idempotency key \u2014 apply a side-effecting action AT MOST ONCE per `actionId`; the same id delivered twice is one gesture replayed, never two; two DISTINCT ids are two real gestures. This holds for EVERY action, not only those a contract marks `oneShot`: a card served mid-rollout may be running a runtime that suppresses nothing, and keying on the marker would leave a hole exactly there. Both `actionData` and `uiContext` inform your reaction without a second round trip. Keyed by sessionId (global UUID); app-scoped via ctx.appId. HOSTS WITH PROGRESSIVE TOOL DISCOVERY (claude.ai-style connectors): if a call here errors with \"tool not loaded yet\" or \"wrong parameter names,\" call `tool_search({query:\"ggui_consume\"})` once to warm the tool, then retry with the same args. THE RESULT'S `nextStep`: when `events` is non-empty and status is active the result carries `nextStep` = ggui_amend({ sessionId, kind: 'replace', props }) with THIS sessionId filled in \u2014 the same-card repaint is the default move; absent when `events` is empty or the render has expired.",
         inputSchema,
         outputSchema,
         async handler(rawInput, ctx) {
             const { sessionId, timeout = 0 } = z.object(inputSchema).parse(rawInput);
-            // Register this long-poll on the active-consumer registry IMMEDIATELY
-            // — before the app-scope resolution awaits — so a concurrent
-            // `submit-action.ts` append observes `hasActive: true` for the
-            // earliest possible window. `exit` is paired in `finally` below so
-            // every termination path (success, timeout, error, app-scope reject)
-            // decrements the count exactly once.
+            // Resolve render FIRST (ggui#1485). Cross-app (appId) + cross-user +
+            // missing all surface uniformly as session_not_found (don't leak
+            // whether the id exists for another app / another user), and a
+            // refused call must leave no trace on the session it named. Entering
+            // the active-consumer registry before this gate let another app's
+            // consume count as the session's consumer while its store read ran
+            // (a dispatch in that moment reported a consumer present), and its
+            // `exit` stamped the session's lastExitAt, which changed the grace
+            // wait of that session's dispatches for the next minute.
+            const stored = await deps.renderStore.get(sessionId);
+            if (!isVisibleToCaller(stored, ctx)) {
+                // `stored` is narrowed to StoredGguiSession past this guard.
+                throw new GguiSessionNotFoundError(sessionId);
+            }
+            // Register this long-poll on the active-consumer registry once the
+            // caller is admitted, so a concurrent `submit-action.ts` append
+            // observes `hasActive: true`. A dispatch landing during the store
+            // read above waits its own grace (`waitForConsumer`), which this
+            // `enter` wakes; with the default policy that wait is at least
+            // 150 ms, far longer than one store read, while a deployment's
+            // `consumerGraceMs` sets its own. `exit` is paired in `finally` below
+            // so every termination path after admission (success, timeout,
+            // error, abort) decrements the count exactly once.
             deps.activeConsumerRegistry?.enter(sessionId);
             try {
-                // Resolve render. Cross-app (appId) + cross-user + missing
-                // all surface uniformly as session_not_found (don't leak whether
-                // the id exists for another app / another user).
-                const stored = await deps.renderStore.get(sessionId);
-                if (!isVisibleToCaller(stored, ctx)) {
-                    // `stored` is narrowed to StoredGguiSession past this guard.
-                    throw new GguiSessionNotFoundError(sessionId);
-                }
                 // `timeout` is schema-bounded to [0, 25] (SPEC §7.3) —
                 // out-of-range values rejected INVALID_PARAMS before this line.
                 const deadline = Date.now() + timeout * 1000;
@@ -247,6 +256,14 @@ export function createGguiConsumeHandler(deps) {
                     ...(stored.hostContext !== undefined
                         ? { client: { hostContext: projectHostContext(stored.hostContext) } }
                         : {}),
+                    // The consume → amend hint (ggui#1399, step 2 — the emit; step 1
+                    // declared it one release earlier so every host's cached schema
+                    // names it). Present iff there is something to react to AND the
+                    // render is still live: an amend on an expired render cannot
+                    // succeed, so a late drain from one carries no hint.
+                    ...(events.length > 0 && result.status === 'active'
+                        ? { nextStep: buildConsumeNextStep(sessionId) }
+                        : {}),
                 };
             }
             finally {
@@ -260,6 +277,24 @@ export function createGguiConsumeHandler(deps) {
  * immutable seam state (the protocol types it `DeepReadonly`); the wire is
  * mutable JSON, so the one array is copied and every present field carried.
  */
+/**
+ * The consume → amend hint (ggui#1399): the render → consume chain the
+ * agent follows is a hint on the result it just read, and this closes the
+ * loop from the drained gesture back to the card. `args.sessionId` is the
+ * input's session id verbatim — the literal the agent passes — and
+ * `example` carries it in copy-paste form, the same shape as the render
+ * hint. The server cannot know whether a gesture changed what the user
+ * sees, so the description carries that clause; the decision stays the
+ * agent's. Mirrors `gguiConsumeOutputSchema.nextStep` (declared in step 1).
+ */
+function buildConsumeNextStep(sessionId) {
+    return {
+        tool: 'ggui_amend',
+        description: "Repaint THIS card in place with whatever the gestures changed — kind: 'replace' with the full props, or kind: 'merge' with a patch; the user keeps looking at the same card. A new render is the exception, for a milestone worth a card in the transcript. Then re-call ggui_consume for the next gesture.",
+        example: `ggui_amend({ sessionId: '${sessionId}', kind: 'replace', props: { /* the card's props with the change applied */ } })`,
+        args: { sessionId },
+    };
+}
 function projectHostContext(h) {
     return {
         ...(h.availableDisplayModes !== undefined ? { availableDisplayModes: [...h.availableDisplayModes] } : {}),

package/dist/renders/cross-app-refused.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ggui#1479 — the one line a refused cross-app call leaves: the tool, the
+ * session, the caller's app and the session's owning app. Ids only, never
+ * the payload. Operator-side: the caller's answer never names the owner.
+ * One physical line — a fixed prefix then a JSON body — so a log query
+ * matches the event on the prefix and reads its fields from the JSON.
+ */
+export declare function logCrossAppRefused(tool: string, sessionId: string, callerAppId: string, ownerAppId: string): void;
+/**
+ * ggui#1479 — the line a refusal leaves when a session's ownership could not
+ * be read at all (the store threw): the tool, the session, the caller's app
+ * and why. The call fails closed; this line is how an outage reads apart
+ * from a probe. A caller with no logger of its own passes the store's error
+ * text, so the cause rides the same line (ggui#1514).
+ */
+export declare function logOwnershipUnverified(tool: string, sessionId: string, callerAppId: string, reason: 'read-failed', error?: string): void;
+//# sourceMappingURL=cross-app-refused.d.ts.map

package/dist/renders/cross-app-refused.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-app-refused.d.ts","sourceRoot":"","sources":["../../src/renders/cross-app-refused.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAGjH;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,KAAK,CAAC,EAAE,MAAM,GACb,IAAI,CAIN"}

package/dist/renders/cross-app-refused.js

@@ -0,0 +1,23 @@
+/**
+ * ggui#1479 — the one line a refused cross-app call leaves: the tool, the
+ * session, the caller's app and the session's owning app. Ids only, never
+ * the payload. Operator-side: the caller's answer never names the owner.
+ * One physical line — a fixed prefix then a JSON body — so a log query
+ * matches the event on the prefix and reads its fields from the JSON.
+ */
+export function logCrossAppRefused(tool, sessionId, callerAppId, ownerAppId) {
+    // eslint-disable-next-line no-console -- operator-visible structured refusal line; handlers carry no logger
+    console.warn(`[ggui] runtime_cross_app_refused ${JSON.stringify({ tool, sessionId, callerAppId, ownerAppId })}`);
+}
+/**
+ * ggui#1479 — the line a refusal leaves when a session's ownership could not
+ * be read at all (the store threw): the tool, the session, the caller's app
+ * and why. The call fails closed; this line is how an outage reads apart
+ * from a probe. A caller with no logger of its own passes the store's error
+ * text, so the cause rides the same line (ggui#1514).
+ */
+export function logOwnershipUnverified(tool, sessionId, callerAppId, reason, error) {
+    const fields = error === undefined ? { tool, sessionId, callerAppId, reason } : { tool, sessionId, callerAppId, reason, error };
+    // eslint-disable-next-line no-console -- operator-visible structured refusal line; handlers carry no logger
+    console.warn(`[ggui] runtime_ownership_unverified ${JSON.stringify(fields)}`);
+}

package/dist/renders/decide-handshake.d.ts

@@ -46,7 +46,8 @@
 import { type BlueprintSource, type BlueprintVariance, type DataContract } from '@ggui-ai/protocol';
 import { type LLMCaller } from '@ggui-ai/negotiator';
 import type { HandlerContext } from '../types.js';
-import { type BlueprintMatchResult } from './blueprint-matcher.js';
+import { type BlueprintMatchResult, type RerankPair } from './blueprint-matcher.js';
+import type { RequestFitFacts } from './fits.js';
 import type { BlueprintRegistryDeps } from './blueprint-registry.js';
 import type { HandshakeNegotiator, HandshakeNegotiatorResult } from './handshake.js';
 import type { InstalledBlueprintsProvider } from './installed-blueprints-provider.js';
@@ -94,6 +95,17 @@ export interface BlueprintLookupKeys {
     readonly variantKey: string;
     readonly exactKey: string;
 }
+/**
+ * ggui#1568 — a deployment's answer to "which rows may the semantic tier
+ * not offer for this request?" See {@link HandshakeDecisionAdapter.semanticExclusion}.
+ */
+export type SemanticExclusion = {
+    readonly kind: 'rows';
+    readonly keys: ReadonlySet<string>;
+} | {
+    readonly kind: 'all';
+    readonly reason: string;
+};
 export interface HandshakeDecisionAdapter {
     /**
      * Resolve the LLM for this request — the find-similar judge AND the
@@ -104,6 +116,13 @@ export interface HandshakeDecisionAdapter {
      * fixed caller.
      */
     resolveLlm(ctx: HandlerContext): Promise<LLMCaller | undefined> | LLMCaller | undefined;
+    /**
+     * The rerank judge as a pair with its own threshold (ggui#1235), for a
+     * deployment whose judge is not the LLM caller above — passed to the
+     * matcher as `rerank`. Absent → the matcher's default (the resolved LLM
+     * at its calibrated threshold), unchanged.
+     */
+    resolveRerank?(ctx: HandlerContext): Promise<RerankPair | undefined> | RerankPair | undefined;
     /**
      * Ordered list of blueprint pools to search. Empty / absent ⇒ the
      * find-similar probe is skipped entirely (synth-only). Searched in
@@ -123,6 +142,33 @@ export interface HandshakeDecisionAdapter {
      * Resolved once per decision, before the pool loop.
      */
     readonly reuseMode?: (ctx: HandlerContext) => Promise<'full' | 'exact-only'> | 'full' | 'exact-only';
+    /**
+     * ggui#1427 — the request's declared fit facts (the canvas it will mount
+     * on, the aesthetic preset and direction digest it is served under), for
+     * `fits()` to compare against each candidate's row before the judge ranks
+     * it. Resolved once per decision and handed to every pool probe. Absent ⇒
+     * nothing declared: only data-shape (from the draft contract) evaluates.
+     * The server this package ships declares nothing; a deployment resolves
+     * these from wherever it keeps a request's presentation facts.
+     */
+    resolveRequestFit?(ctx: HandlerContext): Promise<RequestFitFacts | undefined> | RequestFitFacts | undefined;
+    /**
+     * ggui#1568 — rows the deployment reserves from the semantic tier for this
+     * request: rows that must be reached only by their exact key, never by
+     * similarity (an A/B test's arm, served only to the traffic assigned to
+     * it, is the first such row). Resolved once per decision and applied to
+     * every pool probe. Not asked when `reuseMode` is `'exact-only'`, since
+     * the semantic tier is already off.
+     *
+     * `{ kind: 'rows', keys }` excludes each row named by
+     * {@link semanticExclusionKey}. `{ kind: 'all', reason }` turns the
+     * semantic tier off for this request: the answer when the deployment
+     * cannot say which rows are reserved. It must never answer an empty set it
+     * has not read. A hook that throws an operational error is read as
+     * `'all'` and reported through `warn`. A programmer error (TypeError and
+     * kin) is rethrown, as for every hook here. Absent ⇒ nothing is reserved.
+     */
+    readonly semanticExclusion?: (ctx: HandlerContext) => Promise<SemanticExclusion> | SemanticExclusion;
     /**
      * Optional deployment-specific pre-match, run BEFORE the find-similar
      * probe so a curated / byte-exact hit wins over everything — e.g. a

package/dist/renders/decide-handshake.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decide-handshake.d.ts","sourceRoot":"","sources":["../../src/renders/decide-handshake.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"decide-handshake.d.ts","sourceRoot":"","sources":["../../src/renders/decide-handshake.ts"],"names":[],"mappings":"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"}

package/dist/renders/decide-handshake.js

@@ -44,7 +44,7 @@
  * RangeError / SyntaxError) re-throw so real bugs surface.
  */
 import { createHash } from 'node:crypto';
-import { dataContractSchema, lintContract, summarizeContract, } from '@ggui-ai/protocol';
+import { MATCHED_INTENT_MAX_CHARS, dataContractSchema, lintContract, summarizeContract, } from '@ggui-ai/protocol';
 import { blueprintKey, variantKey } from '@ggui-ai/protocol/blueprint-key';
 import { ensureConformingContract, normalizeDraft, } from '@ggui-ai/negotiator';
 import { matchBlueprint, } from './blueprint-matcher.js';
@@ -53,6 +53,18 @@ import { composeExactKey } from './blueprint-registry.js';
 import { buildDeclined, buildSalvagedOrDeclined } from './handshake-fallbacks.js';
 import { emitAgentCaps } from './agentcaps-measurement.js';
 import { canonicalizeToolIdentity, } from './canonicalize-tool-identity.js';
+/**
+ * `blueprintMeta.matchedIntent` (#1336) for a judged hit: the stored intent,
+ * cut the way the reuse judge cuts a candidate's intent (llm-rerank.ts), so
+ * the agent reads exactly the string the judge compared. Blank → absent.
+ */
+function matchedIntentOf(intent) {
+    if (intent.trim().length === 0)
+        return undefined;
+    if (intent.length <= MATCHED_INTENT_MAX_CHARS)
+        return intent;
+    return `${intent.slice(0, MATCHED_INTENT_MAX_CHARS - 1)}…`;
+}
 /** Operational vs programmer-error classifier — bugs re-throw, ops fail open. */
 function isOperationalError(err) {
     if (err instanceof TypeError)
@@ -76,7 +88,8 @@ function coverageHasGap(gap) {
         gap.props.length > 0 ||
         gap.context.length > 0 ||
         gap.streams.length > 0 ||
-        gap.gadgets.length > 0);
+        gap.gadgets.length > 0 ||
+        gap.actionMembers.length > 0);
 }
 /**
  * Project a coverage gap into `severity:'warn'` validation findings — one
@@ -115,6 +128,19 @@ function coverageGapFindings(gap, request) {
     push('context', 'contextSpec');
     push('streams', 'streamSpec');
     push('gadgets', 'gadgets');
+    // ggui#1428 — a shared action whose stored entry lacks a load-bearing
+    // member the draft declares: the served card will not behave that way.
+    for (const entry of gap.actionMembers) {
+        const dot = entry.lastIndexOf('.');
+        const name = entry.slice(0, dot);
+        const member = entry.slice(dot + 1);
+        findings.push({
+            code: COVERAGE_GAP_CODE,
+            severity: 'warn',
+            path: `actionSpec.${entry}`,
+            message: `the proposed cached UI declares action '${name}' without the \`${member}\` your draft declares, so the served card will not carry that behaviour. Default to ACCEPT (reuse-and-refine) — override only if the user or your flow depends on it.`,
+        });
+    }
     return findings;
 }
 /** Stable code for the VARIANCE_GAP warn finding on a variance-divergent reuse. */
@@ -379,6 +405,7 @@ export async function decideHandshake(adapter, input) {
     // judge needs it at handshake time (parity with the render path), and
     // the synth/repair create path reuses it.
     const llm = await adapter.resolveLlm(ctx);
+    const rerank = adapter.resolveRerank ? await adapter.resolveRerank(ctx) : undefined;
     // Tier 1 — find-similar across pools (exact-key free + semantic
     // find+judge). Reuse the cached blueprint ATOMICALLY; a coverage gap is
     // informational (surfaced as COVERAGE_GAP warn findings, not a drop).
@@ -389,6 +416,31 @@ export async function decideHandshake(adapter, input) {
         // ggui#607 — resolve the reuse policy once; 'exact-only' threads
         // disableSemantic into every pool probe below.
         const reuseMode = adapter.reuseMode ? await adapter.reuseMode(ctx) : 'full';
+        // ggui#1568 — the reserved rows, resolved once. An operational failure
+        // reads as 'all': the tier stays off rather than offering a reserved row.
+        let exclusion;
+        if (reuseMode === 'full' && adapter.semanticExclusion) {
+            try {
+                exclusion = await adapter.semanticExclusion(ctx);
+            }
+            catch (err) {
+                if (!isOperationalError(err))
+                    throw err;
+                exclusion = { kind: 'all', reason: `semanticExclusion threw: ${errMessage(err)}` };
+            }
+            if (exclusion.kind === 'all') {
+                adapter.warn?.(`[decideHandshake] semantic tier off for this request, the reserved rows are unknown: ${exclusion.reason}`);
+            }
+        }
+        const probeOptions = reuseMode === 'exact-only'
+            ? { disableSemantic: true }
+            : exclusion?.kind === 'all'
+                ? { disableSemantic: true, disableSemanticCause: 'exclusion-unavailable' }
+                : exclusion?.kind === 'rows'
+                    ? { excludeFromSemantic: exclusion.keys }
+                    : undefined;
+        // ggui#1427 — the request's fit facts, resolved once for every pool probe.
+        const requestFit = adapter.resolveRequestFit ? await adapter.resolveRequestFit(ctx) : undefined;
         // The requesting agent's declared MCP tools (a set keyed by bare
         // toolName) — the basis for the reuse fulfillability gate. A cached
         // blueprint is only proposed for reuse when these SUPERSET the
@@ -396,6 +448,10 @@ export async function decideHandshake(adapter, input) {
         // satisfiable (see {@link isFulfillable}).
         const agentCaps = parsedDraft.data.agentCapabilities?.tools;
         const semanticHits = [];
+        // Judged hits from the requesting app's OWN pool — the only ones whose
+        // stored intent may reach this agent (`blueprintMeta.matchedIntent`,
+        // #1336). A pool shared across apps never contributes one.
+        const ownPoolHits = new Set();
         // The keys every pool probe below reads the index at — computed ONCE from the
         // same arguments `matchBlueprint` receives (its `expectedKey` is this
         // `blueprintKey(contract)`; it composes the exact key with the default kind),
@@ -413,6 +469,7 @@ export async function decideHandshake(adapter, input) {
                 const matchDeps = {
                     registry: pool.registry,
                     ...(llm ? { llm } : {}),
+                    ...(rerank ? { rerank } : {}),
                     ...(pool.installedBlueprints
                         ? { installedBlueprints: pool.installedBlueprints }
                         : {}),
@@ -421,9 +478,8 @@ export async function decideHandshake(adapter, input) {
                     intent,
                     contract: parsedDraft.data,
                     ...(variance !== undefined ? { variance } : {}),
-                }, ...(reuseMode === 'exact-only'
-                    ? [{ disableSemantic: true }]
-                    : []));
+                    ...(requestFit !== undefined ? { fit: requestFit } : {}),
+                }, ...(probeOptions !== undefined ? [probeOptions] : []));
                 // Isolated in its OWN try/catch, separate from the outer
                 // pool-probe catch below: onBlueprintMatch's contract promises
                 // non-blocking observation, so a throwing observer must never
@@ -460,6 +516,8 @@ export async function decideHandshake(adapter, input) {
                 if (matchResult.strategy === 'semantic' &&
                     isFulfillable(matchResult.blueprint.contract, agentCaps).ok) {
                     semanticHits.push(matchResult);
+                    if (scope === ctx.appId)
+                        ownPoolHits.add(matchResult);
                 }
             }
             catch (err) {
@@ -482,7 +540,17 @@ export async function decideHandshake(adapter, input) {
                     return aGap ? b : a; // empty-gap wins
                 return (b.judgeConfidence ?? 0) > (a.judgeConfidence ?? 0) ? b : a;
             });
-            const reuse = buildCacheReuseResult(best.blueprint, best.reason, best.cosine, 'match-semantic');
+            const cacheReuse = buildCacheReuseResult(best.blueprint, best.reason, best.cosine, 'match-semantic');
+            const matchedIntent = ownPoolHits.has(best) ? matchedIntentOf(best.blueprint.intent) : undefined;
+            const reuse = matchedIntent === undefined
+                ? cacheReuse
+                : {
+                    ...cacheReuse,
+                    suggestion: {
+                        ...cacheReuse.suggestion,
+                        blueprintMeta: { ...cacheReuse.suggestion.blueprintMeta, matchedIntent },
+                    },
+                };
             // A gapped reuse carries COVERAGE_GAP warn findings so the agent sees
             // what the cached UI lacks before accepting; a variance-divergent
             // reuse additionally carries a VARIANCE_GAP warn finding so the agent

package/dist/renders/declare-tool-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"declare-tool-catalog.d.ts","sourceRoot":"","sources":["../../src/renders/declare-tool-catalog.ts"],"names":[],"mappings":"AA2DA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAKjF;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,wBAAwB,CAAC;CACjD;AAED,wBAAgB,mCAAmC,CACjD,IAAI,EAAE,0BAA0B;;;;;;;;;;;GAkCjC"}
+{"version":3,"file":"declare-tool-catalog.d.ts","sourceRoot":"","sources":["../../src/renders/declare-tool-catalog.ts"],"names":[],"mappings":"AA8DA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAKjF;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,wBAAwB,CAAC;CACjD;AAED,wBAAgB,mCAAmC,CACjD,IAAI,EAAE,0BAA0B;;;;;;;;;;;GAkCjC"}

package/dist/renders/declare-tool-catalog.js

@@ -22,34 +22,37 @@
  *
  * Why `runtime` (vs `agent`) — ROUTE PLACEMENT:
  *   - `runtime`-tagged handlers ARE routed on the agent endpoint:
- *     `filterHandlersByAudience(handlers, ["agent", "runtime"])`
- *     (`@ggui-ai/mcp-server` server.ts:4621), mounted at the universal
- *     `/mcp` path (server.ts:4640-4641) with `appId` resolved from the
- *     same auth identity (server.ts:4629-4632). So the runtime library's
+ *     `filterHandlersByAudience(handlers, DATA_PLANE_AUDIENCES)`
+ *     (`@ggui-ai/mcp-server` mcp-endpoint-routes.ts), mounted at the
+ *     universal `/mcp` path with `appId` resolved from the same auth
+ *     identity. So the runtime library's
  *     call lands on the same route + resolves the same `appId` as the
  *     agent's `ggui_handshake`.
  *   - The `audience` tag controls ROUTE PLACEMENT ONLY. It does NOT
  *     hide the tool from the LLM's `tools/list`, and there is NO
- *     call-time gate rejecting any caller class (server.ts:4336-4343).
+ *     call-time gate rejecting any caller class.
  *
  * Why `_meta.ui.visibility: ['app']` IS set here — LLM-LIST HIDING:
  *   - LLM-`tools/list` hiding is done by `_meta.ui.visibility: ['app']`,
- *     NOT by the `runtime` audience tag (types.ts:219-222; the two
- *     sibling runtime handlers both carry it — submit-action.ts:237,
- *     sync-context.ts:135). Without the marker this tool would appear on
+ *     NOT by the `runtime` audience tag (the sibling runtime handlers
+ *     carry it too — submit-action.ts, sync-context.ts, runtime-pull.ts,
+ *     refresh-ws-token.ts, runtime-telemetry.ts). Without the marker this
+ *     tool would appear on
  *     the agent's `tools/list`, and an LLM could call it and poison the
  *     per-app catalog. With it, spec-compliant hosts (claude.ai, Claude
  *     Desktop) filter it out of the MODEL's list.
- *   - The marker is ADVISORY for direct callers: ggui's own canonical
+ *   - The marker is ADVISORY to the server on EVERY route: the canonical
  *     `/mcp` dispatch executes a `visibility:['app']` tool for ANY
- *     credentialed caller — it never rejects. The only server-ENFORCED
- *     visibility gate (403 `visibility_denied`,
- *     mcp-apps-inbound.ts:280-285) lives on the SEPARATE `/mcp-apps/
- *     tools-call` iframe-proxy route, which gates iframe-originated
- *     calls against a DOWNSTREAM connector's `tools/list` — never the
- *     canonical `/mcp` route. So Task 4's backend-LIBRARY direct call
- *     (its own credential, not an iframe relay) is NOT blocked by the
- *     marker. It is set purely to keep the tool off the LLM's list.
+ *     credentialed caller and never rejects, and there is no enforced
+ *     visibility gate anywhere else (the iframe-proxy route that once
+ *     carried a 403 `visibility_denied` was deleted in the orphan
+ *     campaign, 34e2c7276). A view-issued and a model-issued call are
+ *     indistinguishable on the wire, so the door is the HOST's (SPEC
+ *     §4.7 "Host obligation", ggui#1414; the kit grades it as
+ *     `M1-model-tool-set`), and a backend-library direct call with its
+ *     own credential is NOT blocked by the marker. A server-checkable
+ *     view-origin proof is ggui#1415. The marker is set purely to keep
+ *     the tool off the LLM's list on conforming hosts.
  */
 import { declareToolCatalogInputSchema, declareToolCatalogOutputSchema, } from "@ggui-ai/protocol";
 import { defineHandler } from "../types.js";

package/dist/renders/export-registry.d.ts

@@ -1,5 +1,5 @@
 import { type VectorStore } from '@ggui-ai/mcp-server-core';
-import { type BlueprintSource, type DataContract, type BlueprintVariance } from '@ggui-ai/protocol';
+import { type BlueprintSource, type DataContract, type BlueprintVariance, type GeneratorBuild } from '@ggui-ai/protocol';
 export interface ExportableBlueprint {
     readonly contract: DataContract;
     readonly componentCode: string;
@@ -19,6 +19,13 @@ export interface ExportableBlueprint {
      * artifactId fallback — useless prose for semantic matching.
      */
     readonly intent?: string;
+    /**
+     * ggui#1476 — the minting engine's build, when the row carries one, so
+     * the export codec (`toPortableBlueprint`) ships the portable
+     * blueprint's `build`. Read through the registry's one reader of the
+     * key; an unreadable stored value is absent.
+     */
+    readonly build?: GeneratorBuild;
 }
 /**
  * Enumerate every reusable TEMPLATE blueprint stored under `scope` in a

package/dist/renders/export-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"export-registry.d.ts","sourceRoot":"","sources":["../../src/renders/export-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,+BAA+B,CACnD,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CA+CzC"}
+{"version":3,"file":"export-registry.d.ts","sourceRoot":"","sources":["../../src/renders/export-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAG3B,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,+BAA+B,CACnD,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAiDzC"}

package/dist/renders/export-registry.js

@@ -1,5 +1,6 @@
 import { isEnumerableVectorStore, } from '@ggui-ai/mcp-server-core';
 import { flatToBlueprintSource, } from '@ggui-ai/protocol';
+import { readGeneratorBuild } from './blueprint-registry.js';
 /**
  * Enumerate every reusable TEMPLATE blueprint stored under `scope` in a
  * vector store, with its inline component code — the export source for a
@@ -52,6 +53,7 @@ export async function listRegistryBlueprintsForExport(vectorStore, scope) {
             }
         }
         const intentRaw = m['intent'];
+        const build = readGeneratorBuild(m, entry.key);
         out.push({
             contract,
             componentCode: codeRaw,
@@ -60,6 +62,7 @@ export async function listRegistryBlueprintsForExport(vectorStore, scope) {
             ...(typeof intentRaw === 'string' && intentRaw.length > 0
                 ? { intent: intentRaw }
                 : {}),
+            ...(build !== undefined ? { build } : {}),
         });
     }
     return out;

package/dist/renders/fits.d.ts

@@ -0,0 +1,60 @@
+import type { DataContract, JsonValue } from '@ggui-ai/protocol';
+export type FitKind = 'data-shape' | 'surface' | 'direction';
+/**
+ * Which direction a candidate's `directionDigest` hashes: `app` — the
+ * direction the app's profile carries; `request` — a direction given with
+ * the request itself. A card built for a request-given direction never
+ * matches an app-level request by construction; the scope rides the verdict
+ * so a direction miss can be read by its cause.
+ */
+export type DirectionScope = 'app' | 'request';
+export type FitCheck = 'hit' | 'miss' | 'not-evaluated';
+/** An aesthetic preset reference: the id, and the version when one is named. */
+export interface AestheticPresetRef {
+    readonly id: string;
+    readonly version?: string | null;
+}
+/** The request's declared fit facts, beside its draft contract. */
+export interface RequestFitFacts {
+    /** The canvas class the request will mount on, when the host declares one. */
+    readonly canvas?: string;
+    readonly aestheticPreset?: AestheticPresetRef;
+    readonly directionDigest?: string;
+}
+export interface FitRequest extends RequestFitFacts {
+    /** The request's draft contract. Absent = data-shape not evaluated. */
+    readonly contract?: DataContract;
+}
+export interface FitCandidate {
+    readonly contract?: DataContract;
+    /** The canvas classes the cached interface was judged on. */
+    readonly judgedCanvases?: readonly string[];
+    readonly aestheticPreset?: AestheticPresetRef;
+    readonly directionDigest?: string;
+    readonly directionScope?: DirectionScope;
+}
+export interface FitVerdict {
+    readonly fits: boolean;
+    /** The first miss in check order; absent when the candidate fits. */
+    readonly miss?: FitKind;
+    readonly checks: Readonly<Record<FitKind, FitCheck>>;
+    /** The candidate's declared direction scope, present whenever the direction check ran. */
+    readonly directionScope?: DirectionScope;
+}
+/** A candidate the pre-filter dropped, named with its first miss. */
+export interface FitDeclined {
+    readonly id: string;
+    readonly miss: FitKind;
+    /** On a direction miss, the candidate's declared scope when it had one. */
+    readonly directionScope?: DirectionScope;
+}
+/** sha256 of the direction text trimmed, whitespace-collapsed and lowercased — a stray edit to spacing or case never flips a card. */
+export declare function directionDigest(text: string): string;
+/**
+ * JSON-Schema type compatibility, not string equality: `integer` satisfies a
+ * `number` spec, type arrays are compatible when they intersect, and an
+ * absent type on either side is compatible.
+ */
+export declare function jsonSchemaTypesCompatible(candidateType: JsonValue | undefined, requestType: JsonValue | undefined): boolean;
+export declare function fits(candidate: FitCandidate, request: FitRequest): FitVerdict;
+//# sourceMappingURL=fits.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fits.d.ts","sourceRoot":"","sources":["../../src/renders/fits.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEjE,MAAM,MAAM,OAAO,GAAG,YAAY,GAAG,SAAS,GAAG,WAAW,CAAC;AAC7D;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,SAAS,CAAC;AAC/C,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,eAAe,CAAC;AAExD,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,eAAe,CAAC,EAAE,kBAAkB,CAAC;IAC9C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,UAAW,SAAQ,eAAe;IACjD,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,eAAe,CAAC,EAAE,kBAAkB,CAAC;IAC9C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;CAC1C;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;IACrD,0FAA0F;IAC1F,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;CAC1C;AAED,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;CAC1C;AAID,sIAAsI;AACtI,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AASD;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,SAAS,GAAG,SAAS,EAAE,WAAW,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAK3H;AAuDD,wBAAgB,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,GAAG,UAAU,CAY7E"}