@noodleseed/agent-kit 0.44.0 → 0.45.0

package/skills/codex/references/embedded-assistant.md

@@ -254,6 +254,7 @@ For a customer-owned React renderer, use the renderer-free hook. It owns client
 "use client";
 
 import { useState } from "react";
+import { NoodleAppView } from "@noodleseed/assistant/react";
 import { useNoodleAssistant } from "@noodleseed/assistant/react/client";
 
 export function CustomAssistant({ principalKey }: { principalKey: string }) {
@@ -327,9 +328,11 @@ export function CustomAssistant({ principalKey }: { principalKey: string }) {
             }
             if (part.type === "data-view") {
               return (
-                <p key={part.data.id}>
-                  Trusted app view available: {part.data.title ?? part.data.resourceUri}
-                </p>
+                <NoodleAppView
+                  key={`${part.data.id}:${part.data.resourceUri}`}
+                  client={client}
+                  view={part.data}
+                />
               );
             }
             return <p key={index}>Unsupported assistant content.</p>;
@@ -364,7 +367,9 @@ export function CustomAssistant({ principalKey }: { principalKey: string }) {
 
 `principalKey` is a browser-local identity for the authenticated user/tenant and is never sent to Noodle. Change it whenever that principal changes; the hook then aborts and clears the previous session and transcript. The hook does not register `<noodle-assistant>` or render Noodle markup.
 
-The sample fails closed on input requests until you replace that branch with a form generated from `requestedSchema`. A custom renderer must show the complete confirmation review and both decisions, handle every part it supports, and surface an explicit unsupported state for the rest. For `data-view`, map `resourceUri` or `tool` plus the bounded/redacted `result` to a component already trusted by the application. Never inject `part.data.html`, assign it to `srcdoc`, or fetch a `ui://` URI; the managed element alone supplies Noodle’s sandbox host. Do not wrap this client in another chat transport or invent user messages for interaction continuations.
+The sample fails closed on input requests until you replace that branch with a form generated from `requestedSchema`. A custom renderer must show the complete confirmation review and both decisions, handle every part it supports, and surface an explicit unsupported state for the rest. For `data-view`, use `NoodleAppView` to render the linked App or deliberately map `resourceUri`/tool plus the bounded redacted `result` to an application-trusted native component. JSON result data is not the linked App UI. Never inject `part.data.html`, assign it to `srcdoc`, fetch a `ui://` URI, or reproduce the bridge with a direct Ext Apps dependency. Do not wrap this client in another chat transport or invent user messages for interaction continuations.
+
+`NoodleAppView` owns one bridge for the semantic view identity: client + `view.id` + `view.resourceUri`. It retains the iframe across fresh payload/callback objects from parent rerenders, reads current payloads through refs, and sends standard App teardown only when that semantic identity changes or the component unmounts. Do not key an ancestor by a view object or callback. If the embedding page sets Content-Security-Policy, include the Noodle service origin in both `connect-src` and `frame-src`.
 
 Outside React, use the same DOM-free client directly. It keeps the session token in memory, exposes a React-free `UIMessage` transcript with typed parts, and never registers a custom element:
 
@@ -416,7 +421,7 @@ if (pending) {
 
 `subscribeChat` immediately emits a detached `{ messages, status, error? }` snapshot and then emits as `UIMessage.parts` change. Text uses `text`; Noodle confirmations, input requests, tool results, and linked views use `data-confirmation`, `data-input-request`, `data-tool-result`, and `data-view`. Interaction data moves through pending/submitting/accepted/declined/cancelled. Use raw `subscribe(...)` only for transport/session lifecycle events that are not transcript content.
 
-`data-view` means a completed tool has a linked MCP App view. It carries the call/interaction id, tool, `ui://` identity, optional title, bounded/redacted public result, and—on current services—the self-contained bridged document. The standard element is an MCP Apps host and mounts that document behind a double iframe; a customer renderer ignores it and maps the identity/result to an application-trusted component. The standard element supports lifecycle, app tool/resource calls, ui/message, ui/update-model-context, links, resize, and inline/fullscreen; sampling, tasks, downloads, and remote DOM are not advertised. It also dispatches `assistant-view-available` for a customer-owned renderer.
+`data-view` means a completed tool has a linked MCP App view. In a customer-owned React renderer, pass that typed part and the existing client to `NoodleAppView`; it retains one bridge for client + `view.id` + `view.resourceUri` and requests standard App teardown on semantic replacement or unmount. Deliberately map the bounded result to an application-trusted native component only when replacing the linked App UI.
 
 `clientContext` and typed `pageContext` are recomputed for each turn. `updateContext(...)` remains the legacy session-exchange context; `updatePageContext(...)` replaces the fresh per-turn application hint. `updateModelContext({ content, structuredContent })` publishes one cohesive renderer snapshot for later message turns without starting a turn; every call replaces the prior snapshot rather than merging fields. These are untrusted data, not conversation history or authorization input, and the boundaries reject credential-shaped or unbounded updates. A message may re-exchange once after a pre-execution `401`; the client never auto-retries interaction decisions. `tool_proposed.arguments` is a complete schema-aware review projection and, for connector-backed tools, names the sole exact connector version/operation/resolved arguments. Sensitive/write-only fields are redacted; truncating or omitting any non-sensitive action field fails closed. Accept is bound to the server-held action and claims at most one execution attempt—clients cannot replace it. Normal terminal outcomes scrub private arguments and continuations immediately; only an accepted action still executing retains them for the one-hour unknown-outcome recovery window, after which it records `interaction_outcome_unknown` and scrubs. Without downstream idempotency this is not an exactly-once business-effect guarantee. To reconcile a lost response, explicitly repeat the same id and decision: the service returns its durable stored outcome without re-execution.
 

package/skills/codex/references/widgets-and-apps.md

@@ -26,13 +26,15 @@ Treat 1 MiB of uncompressed UTF-8 HTML as the recommended initial React-widget b
 
 Every production widget handles loading, empty, partial, stale, error, retry, and success states. Prefill fields from known tool results and choose safe, reversible defaults; preserve the user’s work across rerenders, and never preselect a consequential action. Use public React primitives and branding tokens. Never author against `ns-*`, `nsr-*`, or example-local `--nw-*` classes/tokens; those are implementation details, not alternate design systems.
 
+Keep the complete `useToolInfo()` result. An empty result envelope is pending, `isError` is an explicit tool error, and any non-pending success must validate every required field and identifier before it becomes UI data. Render a malformed-result error when validation fails, and render dependent actions only after validation succeeds. Safe local input defaults may follow valid hydration; they must never fabricate a loaded business record.
+
 ## React hook surface
 
 Author views as React components. `generateHelpers<ServerDefinition>()` (from `@noodleseed/one/react`) returns the typed host hooks:
 
 | Hook | Use for |
 | :-- | :-- |
-| `useToolInfo` | Read the invoking tool result; `structuredContent` is the widget’s typed data payload. |
+| `useToolInfo` | Read the complete invoking tool result: treat `{}` as pending, handle `isError`, validate every required `structuredContent` field and identifier, reject malformed success data, and render dependent actions only after validation succeeds. |
 | `useCallTool` | Call a tool from the widget — returns `{ status, callTool, callToolAsync, data, structuredContent, error, reset }`; target a model-visible tool or a hidden `tool` helper. |
 | `useViewState` | Persist per-widget UI state across re-renders and restores: `const [value, setValue] = useViewState("key", initial)`. |
 | `useLayout` | Read host layout: `{ theme, displayMode, locale?, host?, supports? }` (`displayMode` is `"inline"`/`"pip"`/`"fullscreen"`) — adapt styling to the host theme and mode. |
@@ -65,14 +67,27 @@ const { useToolInfo, useCallTool, useViewState, useLayout, useOpenExternal, useS
   generateHelpers<ServerDefinition>();
 
 type OrderResult = {
-  readonly customer?: string;
-  readonly item?: string;
-  readonly total?: number;
-  readonly checkoutUrl?: string;
+  readonly customer: string;
+  readonly item: string;
+  readonly total: number;
+  readonly checkoutUrl: string;
 };
 
+function isOrderResult(value: unknown): value is OrderResult {
+  if (value === null || typeof value !== 'object') return false;
+  const result = value as Partial<OrderResult>;
+  return (
+    typeof result.customer === 'string' && result.customer.length > 0 &&
+    typeof result.item === 'string' && result.item.length > 0 &&
+    typeof result.total === 'number' && Number.isFinite(result.total) &&
+    typeof result.checkoutUrl === 'string' && result.checkoutUrl.startsWith('https://')
+  );
+}
+
 export default function OrderStatus() {
-  const shown = useToolInfo('show_order').structuredContent as OrderResult | undefined;
+  const toolInfo = useToolInfo('show_order');
+  const isPending = Object.keys(toolInfo).length === 0;
+  const shown = isOrderResult(toolInfo.structuredContent) ? toolInfo.structuredContent : undefined;
   const placeOrder = useCallTool('place_order'); // calls the widget-only helper tool
   const { supports } = useLayout();
   const openExternal = useOpenExternal();
@@ -85,15 +100,16 @@ export default function OrderStatus() {
   const checkoutUrl = shown?.checkoutUrl ?? '';
 
   useEffect(() => {
-    if (!supports?.modelContext) return;
+    if (!shown || !supports?.modelContext) return;
     void updateModelContext({
       content: [{ type: 'text', text: `Pickup order: ${item}, total ${total}` }],
       structuredContent: { widget: { name: 'pickup-order', lifecycle: 'active' }, order: { item, total } },
     });
-  }, [item, supports?.modelContext, total, updateModelContext]);
+  }, [item, shown, supports?.modelContext, total, updateModelContext]);
 
   async function submitOrder() {
-    await placeOrder.callTool({ customer: shown?.customer ?? 'Guest', item });
+    if (!shown) return;
+    await placeOrder.callTool({ customer: shown.customer, item });
     if (supports?.modelContext) {
       await publishLifecycle('submitted', { surface: 'order', item, total, status: 'submitted' });
     }
@@ -102,9 +118,13 @@ export default function OrderStatus() {
     }
   }
 
+  if (isPending) return <Feedback status="loading">Loading the order…</Feedback>;
+  if (toolInfo.isError) return <Feedback status="error">Could not load the order.</Feedback>;
+  if (!shown) return <Feedback status="error">The order result was incomplete.</Feedback>;
+
   return (
     // data-llm is an inspection hint; useUpdateModelContext above is the model-visible channel.
-    <Frame title="Pickup order" displayMode="auto" data-llm={`Pickup order for ${shown?.customer ?? 'Guest'}: ${item}, total ${total}`}>
+    <Frame title="Pickup order" displayMode="auto" data-llm={`Pickup order for ${shown.customer}: ${item}, total ${total}`}>
       <Flow variant="stack">
       <AsyncBoundary state={placeOrder} loading="Placing order…" error={(error) => error.message}>
       <Region title="Order" description="Choose one item for pickup.">

package/skills/codex/reporting-noodle-feedback/SKILL.md

@@ -3,7 +3,7 @@ name: reporting-noodle-feedback
 description: "Use when a Noodle Seed bug, misleading instruction, missing capability, or concrete product improvement should be proposed to the user."
 ---
 
-<!-- noodle-skill version:0.44.0 hash:0f404109f4845683 -->
+<!-- noodle-skill version:0.45.0 hash:0f404109f4845683 -->
 
 # reporting-noodle-feedback
 

package/skills/codex/verifying-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: verifying-mcp-delivery
 description: "Use when proving a Noodle Seed MCP project works at a named compile, local, connector, App, host, deployment, or production evidence level."
 ---
 
-<!-- noodle-skill version:0.44.0 hash:6ef6ef551e26b78e -->
+<!-- noodle-skill version:0.45.0 hash:6ef6ef551e26b78e -->
 
 # verifying-mcp-delivery