@noodleseed/agent-kit 0.39.0 → 0.41.0

package/skills/codex/embedding-mcp-assistants/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: embedding-mcp-assistants
+description: "Use when embedding a Noodle assistant into an existing SaaS or web application with browser, identity, session, and credential boundaries."
+---
+
+<!-- noodle-skill version:0.41.0 hash:5d8f40f904d6ab4b -->
+
+# embedding-mcp-assistants
+
+Deliver the requested assistant embed with identity and credential separation proven at the tested level.
+
+## Use when
+
+- Embed the Noodle assistant in an existing web app.
+- Wire browser mounting and session exchange.
+
+## Do not use when
+
+- Do not use to build a standalone MCP App.
+- Do not use when the request is only server authoring or deployment.
+
+## Required inputs
+
+- Application origin and mounting point.
+- Identity/session boundary.
+- Requested local or hosted evidence level.
+
+## Workflow
+
+Read and follow the canonical playbook `references/embedded-assistant.md` at `../noodle-seed/references/embedded-assistant.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+Load `references/authoring-workflow.md` at `../noodle-seed/references/authoring-workflow.md` only when the playbook or observed evidence names that concern.
+
+## Verification evidence
+
+The embed works at the requested boundary without forwarding inbound credentials to business backends.
+
+## Recovery paths
+
+Localize failures to origin, session exchange, browser mount, MCP surface, or hosted configuration.
+
+## Stop conditions
+
+Stop when unavailable identity, origin, or hosted authority blocks the next evidence layer.
+
+## Handoff contract
+
+Pass the selected outcome, explicit target, changed files, commands run, passing evidence, first unproven evidence layer, sanitized failure, remaining authority, and exact next action. The receiving skill continues from that layer; do not restart discovery or discard prior proof.

package/skills/codex/examples/customer-auth/README.md

@@ -169,7 +169,7 @@ customer backend. The model URL, model name, and model API key remain managed by
 
 The customer's authenticated backend calls `createAssistantSession(...)` from
 `@noodleseed/assistant/server`, passing the already-verified user and browser origin. The browser then uses
-the returned short-lived session through the Web Component or React wrapper:
+the returned short-lived session through the managed Web Component/React renderer or a customer-owned UI:
 
 ```bash
 pnpm add @noodleseed/assistant
@@ -185,6 +185,148 @@ import { NoodleAssistant } from '@noodleseed/assistant/react';
 />;
 ```
 
+For an entirely application-owned React renderer, use the renderer-free hook. It creates no custom element
+and returns the AI SDK transcript plus the canonical client commands:
+
+```tsx
+'use client';
+
+import { useState } from 'react';
+import { useNoodleAssistant } from '@noodleseed/assistant/react/client';
+
+export function CustomerAssistant({ principalKey }: { principalKey: string }) {
+  const [draft, setDraft] = useState('');
+  const { client, messages, status, error } = useNoodleAssistant({
+    sessionEndpoint: '/api/noodle-assistant/session',
+    principalKey,
+  });
+  const busy = status === 'submitted' || status === 'streaming';
+  const settle = (operation: Promise<void>) => {
+    void operation.catch(() => {
+      // The hook exposes this same structured failure through `error`.
+    });
+  };
+
+  return (
+    <section aria-label="Assistant" aria-busy={busy}>
+      {messages.map((message) => (
+        <article key={message.id} data-role={message.role}>
+          {message.parts.map((part, index) => {
+            if (part.type === 'text') return <p key={index}>{part.text}</p>;
+            if (part.type === 'data-confirmation') {
+              const review = part.data;
+              return (
+                <section key={review.id} aria-label="Review proposed action">
+                  <h3>{review.title ?? 'Review proposed action'}</h3>
+                  {review.description ? <p>{review.description}</p> : null}
+                  <pre aria-label="Proposed action arguments">
+                    {JSON.stringify(review.arguments ?? {}, null, 2)}
+                  </pre>
+                  <button
+                    disabled={busy || review.status !== 'pending'}
+                    onClick={() => settle(client.respond(review.id, { action: 'accept' }))}
+                  >
+                    Confirm
+                  </button>
+                  <button
+                    disabled={busy || review.status !== 'pending'}
+                    onClick={() => settle(client.respond(review.id, { action: 'decline' }))}
+                  >
+                    Don't proceed
+                  </button>
+                </section>
+              );
+            }
+            if (part.type === 'data-input-request') {
+              const request = part.data;
+              return (
+                <section key={request.id} aria-label="Assistant needs input">
+                  <p>{request.message}</p>
+                  <p>This renderer has not implemented the requested form.</p>
+                  <button
+                    disabled={busy || request.status !== 'pending'}
+                    onClick={() => settle(client.respond(request.id, { action: 'decline' }))}
+                  >
+                    Cancel request
+                  </button>
+                </section>
+              );
+            }
+            if (part.type === 'data-tool-result') {
+              return (
+                <pre key={part.data.id} aria-label={`${part.data.tool} result`}>
+                  {JSON.stringify(part.data.result, null, 2)}
+                </pre>
+              );
+            }
+            if (part.type === 'data-view') {
+              return (
+                <p key={part.data.id}>
+                  Trusted app view available: {part.data.title ?? part.data.resourceUri}
+                </p>
+              );
+            }
+            return <p key={index}>Unsupported assistant content.</p>;
+          })}
+        </article>
+      ))}
+      {error ? <p role="alert">{error.message}</p> : null}
+      <form
+        onSubmit={(event) => {
+          event.preventDefault();
+          const message = draft.trim();
+          if (!message) return;
+          setDraft('');
+          settle(client.sendMessage(message));
+        }}
+      >
+        <input
+          aria-label="Message"
+          value={draft}
+          onChange={(event) => setDraft(event.currentTarget.value)}
+        />
+        {busy ? (
+          <button type="button" onClick={() => client.abort()}>
+            Stop
+          </button>
+        ) : (
+          <button type="submit">Send</button>
+        )}
+      </form>
+    </section>
+  );
+}
+```
+
+`principalKey` stays in the browser. Change it whenever the authenticated user or tenant changes; the hook
+then aborts and clears the prior session and transcript. The sample fails closed on input requests until its
+fallback is replaced with a form generated from `requestedSchema`. A production renderer must show the
+complete confirmation review and both decisions. For `data-view`, map `resourceUri` or `tool` and the
+bounded/redacted result to a component already trusted by this application. Never inject `part.data.html`,
+assign it to `srcdoc`, or fetch a `ui://` URI.
+
+Outside React, subscribe to the DOM-free client directly. It exposes the same conversation as headless AI
+SDK `UIMessage` state, including typed confirmation, input, tool-result, and linked-view parts:
+
+```ts
+import { createAssistantClient } from '@noodleseed/assistant/client';
+
+const assistant = createAssistantClient({
+  sessionEndpoint: '/api/noodle-assistant/session',
+});
+
+assistant.subscribeChat((state) => {
+  renderUIMessageState(state);
+  for (const message of state.messages) {
+    for (const part of message.parts) {
+      if (part.type === 'data-confirmation' && part.data.status === 'pending') {
+        renderConfirmation(part.data, (response) => assistant.respond(part.data.id, response));
+      }
+    }
+  }
+});
+```
+
 `theme="auto"` follows the SaaS application. The server-level `branding` block is inherited by both MCP App
 widgets and the assistant; documented `--ns-assistant-*` semantic CSS variables remain the final integration
 escape hatch. There is no second assistant branding declaration.

package/skills/codex/publishing-mcp-integrations/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: publishing-mcp-integrations
+description: "Use when preparing, reviewing, or submitting a Noodle Seed MCP integration to a host or app directory."
+---
+
+<!-- noodle-skill version:0.41.0 hash:efffbf82007f935d -->
+
+# publishing-mcp-integrations
+
+Produce complete submission evidence with host-review uncertainty stated explicitly.
+
+## Use when
+
+- Prepare this MCP integration for a directory.
+- Review or submit the host listing.
+
+## Do not use when
+
+- Do not use for ordinary deployment.
+- Do not submit when the user requested preparation or review only.
+
+## Required inputs
+
+- Target directory.
+- Current deployment and verification evidence.
+- Requested review, preparation, or submission boundary.
+
+## Workflow
+
+Read and follow the canonical playbook `references/publishing.md` at `../noodle-seed/references/publishing.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+Load `references/app-directory-compliance.md` at `../noodle-seed/references/app-directory-compliance.md` only when the playbook or observed evidence names that concern.
+
+## Verification evidence
+
+Required product, policy, deployment, media, and test evidence is present or explicitly missing.
+
+## Recovery paths
+
+Return missing implementation or evidence to its owning skill without restarting discovery.
+
+## Stop conditions
+
+Stop before external submission without explicit user authorization.
+
+## Handoff contract
+
+Pass the selected outcome, explicit target, changed files, commands run, passing evidence, first unproven evidence layer, sanitized failure, remaining authority, and exact next action. The receiving skill continues from that layer; do not restart discovery or discard prior proof.

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

@@ -248,7 +248,125 @@ Or import the package root once and mount `<noodle-assistant session-endpoint="/
 
 The component renders a custom element and must mount client-side. In a Next.js App Router tree, put the mount in a `"use client"` component; from a server component or the Pages Router, load it with `next/dynamic` and `ssr: false`.
 
-For a customer-owned renderer, use the DOM-free client. It keeps the session token in memory, streams the same typed events, and never registers a custom element:
+For a customer-owned React renderer, use the renderer-free hook. It owns client lifetime and React subscription while `client` remains the one command surface:
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { useNoodleAssistant } from "@noodleseed/assistant/react/client";
+
+export function CustomAssistant({ principalKey }: { principalKey: string }) {
+  const [draft, setDraft] = useState("");
+  const { client, messages, status, error } = useNoodleAssistant({
+    sessionEndpoint: "/api/assistant/session",
+    principalKey,
+    clientContext: () => ({
+      locale: navigator.language,
+      timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    }),
+  });
+  const busy = status === "submitted" || status === "streaming";
+  const settle = (operation: Promise<void>) => {
+    void operation.catch(() => {
+      // The hook exposes this same structured failure through `error`.
+    });
+  };
+
+  return (
+    <section aria-label="Assistant" aria-busy={busy}>
+      {messages.map((message) => (
+        <article key={message.id} data-role={message.role}>
+          {message.parts.map((part, index) => {
+            if (part.type === "text") return <p key={index}>{part.text}</p>;
+            if (part.type === "data-confirmation") {
+              const review = part.data;
+              return (
+                <section key={review.id} aria-label="Review proposed action">
+                  <h3>{review.title ?? "Review proposed action"}</h3>
+                  {review.description ? <p>{review.description}</p> : null}
+                  <pre aria-label="Proposed action arguments">
+                    {JSON.stringify(review.arguments ?? {}, null, 2)}
+                  </pre>
+                  <button
+                    disabled={busy || review.status !== "pending"}
+                    onClick={() => settle(client.respond(review.id, { action: "accept" }))}
+                  >
+                    Confirm
+                  </button>
+                  <button
+                    disabled={busy || review.status !== "pending"}
+                    onClick={() => settle(client.respond(review.id, { action: "decline" }))}
+                  >
+                    Don't proceed
+                  </button>
+                </section>
+              );
+            }
+            if (part.type === "data-input-request") {
+              const request = part.data;
+              return (
+                <section key={request.id} aria-label="Assistant needs input">
+                  <p>{request.message}</p>
+                  <p>This renderer has not implemented the requested form.</p>
+                  <button
+                    disabled={busy || request.status !== "pending"}
+                    onClick={() => settle(client.respond(request.id, { action: "decline" }))}
+                  >
+                    Cancel request
+                  </button>
+                </section>
+              );
+            }
+            if (part.type === "data-tool-result") {
+              return (
+                <pre key={part.data.id} aria-label={`${part.data.tool} result`}>
+                  {JSON.stringify(part.data.result, null, 2)}
+                </pre>
+              );
+            }
+            if (part.type === "data-view") {
+              return (
+                <p key={part.data.id}>
+                  Trusted app view available: {part.data.title ?? part.data.resourceUri}
+                </p>
+              );
+            }
+            return <p key={index}>Unsupported assistant content.</p>;
+          })}
+        </article>
+      ))}
+      {error ? <p role="alert">{error.message}</p> : null}
+      <form
+        onSubmit={(event) => {
+          event.preventDefault();
+          const message = draft.trim();
+          if (!message) return;
+          setDraft("");
+          settle(client.sendMessage(message));
+        }}
+      >
+        <input
+          aria-label="Message"
+          value={draft}
+          onChange={(event) => setDraft(event.currentTarget.value)}
+        />
+        {busy ? (
+          <button type="button" onClick={() => client.abort()}>Stop</button>
+        ) : (
+          <button type="submit">Send</button>
+        )}
+      </form>
+    </section>
+  );
+}
+```
+
+`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.
+
+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:
 
 ```ts
 import { createAssistantClient } from "@noodleseed/assistant/client";
@@ -266,30 +384,39 @@ assistant.updateModelContext({
   structuredContent: { widget: { name: 'time-off', lifecycle: 'mounted' } },
 });
 
-let pendingId: string | undefined;
-let requestedSchema: unknown;
-assistant.subscribe((event) => {
-  renderAssistantEvent(event);
-  if (event.event === 'view_available') {
-    renderRegisteredView(event.data.resourceUri, event.data.result);
-  }
-  if ((event.event === 'tool_proposed' || event.event === 'input_requested') && typeof event.data.id === 'string') {
-    pendingId = event.data.id;
-    requestedSchema = event.event === 'input_requested' ? event.data.requestedSchema : undefined;
+let pending: { id: string; requestedSchema?: Readonly<Record<string, unknown>> } | undefined;
+assistant.subscribeChat((state) => {
+  renderUIMessageState(state);
+  pending = undefined;
+  for (const message of state.messages) {
+    for (const part of message.parts) {
+      if (part.type === 'data-confirmation' && part.data.status === 'pending') {
+        pending = { id: part.data.id };
+      }
+      if (part.type === 'data-input-request' && part.data.status === 'pending') {
+        pending = { id: part.data.id, requestedSchema: part.data.requestedSchema };
+      }
+      if (part.type === 'data-view') {
+        renderRegisteredView(part.data.resourceUri, part.data.result);
+      }
+    }
   }
 });
 
 await assistant.sendMessage("Book next Thursday and Friday off");
-if (pendingId) {
+if (pending) {
+  const requestedSchema = pending.requestedSchema;
   const resolution = requestedSchema
     ? { action: 'accept' as const, content: await renderPortableForm(requestedSchema) }
     : { action: 'accept' as const };
-  await assistant.respond(pendingId, resolution);
+  await assistant.respond(pending.id, resolution);
 }
 // The same pending id also accepts { action: 'decline' } or { action: 'cancel' }.
 ```
 
-`view_available` 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. It 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.
+`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.
 
 `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.
 
@@ -297,7 +424,7 @@ if (pendingId) {
 
 - Node.js 20+ for `@noodleseed/assistant/server`.
 - The package ships ESM and CommonJS with full export conditions; no bundler aliases, `transpilePackages`, or ambient type shims are needed. If resolution fails, the installed package version is outdated: update `@noodleseed/assistant` instead of adding workarounds.
-- TypeScript `moduleResolution` `bundler` or `node16` recommended; classic `node` also resolves the `/client`, `/react`, and `/server` subpaths.
+- TypeScript `moduleResolution` `bundler` or `node16` recommended; classic `node` also resolves the `/client`, `/react`, `/react/client`, and `/server` subpaths.
 
 ## Verify the boundary
 

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

@@ -0,0 +1,46 @@
+---
+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.41.0 hash:1e23938b39956ef8 -->
+
+# reporting-noodle-feedback
+
+Offer one sanitized feedback command and submit it only after informed explicit approval.
+
+## Use when
+
+- Report a Noodle Seed bug or documentation gap.
+- Propose a concrete Noodle product improvement.
+
+## Do not use when
+
+- Do not use for generic project bugs.
+- Do not send customer code, identifiers, logs, or secrets.
+
+## Required inputs
+
+- One distinct finding.
+- Sanitized observed and expected behavior.
+- User approval for the exact command.
+
+## Workflow
+
+Read and follow the canonical playbook `references/feedback.md` at `../noodle-seed/references/feedback.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+
+## Verification evidence
+
+The user saw the exact sanitized command; only a returned reference proves submission.
+
+## Recovery paths
+
+If login or rate limits block submission, report that nothing was sent and do not retry-loop.
+
+## Stop conditions
+
+Stop before running the command until the user explicitly approves it.
+
+## Handoff contract
+
+Pass the selected outcome, explicit target, changed files, commands run, passing evidence, first unproven evidence layer, sanitized failure, remaining authority, and exact next action. The receiving skill continues from that layer; do not restart discovery or discard prior proof.

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

@@ -0,0 +1,47 @@
+---
+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.41.0 hash:6ef6ef551e26b78e -->
+
+# verifying-mcp-delivery
+
+Report the highest evidence level actually rerun without upgrading weaker proof.
+
+## Use when
+
+- Verify this MCP delivery before handoff.
+- Prove which delivery layers currently pass.
+
+## Do not use when
+
+- Do not use as a substitute for fixing a known failure.
+- Do not infer hosted health from local success.
+
+## Required inputs
+
+- Requested evidence level.
+- Current target.
+- Existing evidence and its freshness.
+
+## Workflow
+
+Read and follow the canonical playbook `references/verify-and-recover.md` at `../noodle-seed/references/verify-and-recover.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+Load `references/test-in-hosts.md` at `../noodle-seed/references/test-in-hosts.md` only when the playbook or observed evidence names that concern.
+
+## Verification evidence
+
+Every dependency below the requested level passes now, or the first unproven layer is explicit.
+
+## Recovery paths
+
+Hand a concrete failing layer to debugging-mcp-delivery with all passing evidence preserved.
+
+## Stop conditions
+
+Stop after the requested level passes or the first bounded failure is isolated.
+
+## Handoff contract
+
+Pass the selected outcome, explicit target, changed files, commands run, passing evidence, first unproven evidence layer, sanitized failure, remaining authority, and exact next action. The receiving skill continues from that layer; do not restart discovery or discard prior proof.