@noodleseed/agent-kit 0.62.0 → 0.63.0

package/skills/codex/examples/acme-tasks/test/server.test.ts

@@ -24,8 +24,37 @@ describe('acme-tasks example', () => {
     const manifest = await app.toManifest();
     const completeTask = manifest.tools.find((candidate) => candidate.name === 'complete_task');
     const addTask = manifest.tools.find((candidate) => candidate.name === 'add_task');
+    const setPriority = manifest.tools.find((candidate) => candidate.name === 'set_priority');
 
     expect(completeTask?.annotations?.confirm).toBe(true);
     expect(addTask?.annotations).not.toHaveProperty('confirm');
+    expect(setPriority?.visibility).toEqual(['app']);
+  });
+
+  it('teaches its three product workflows through one host-neutral agent guide', async () => {
+    const manifest = await app.toManifest();
+    const guide = manifest.server.agentGuide;
+
+    expect(guide?.workflows.map((workflow) => workflow.id)).toEqual([
+      'review_tasks',
+      'capture_task',
+      'complete_task',
+    ]);
+    expect(
+      guide?.workflows.flatMap((workflow) => workflow.steps.map((step) => step.capability.name)),
+    ).toEqual(expect.arrayContaining(['list_today', 'set_priority', 'add_task', 'complete_task']));
+    expect(
+      guide?.workflows
+        .find((workflow) => workflow.id === 'review_tasks')
+        ?.steps.map((step) => step.capability.name),
+    ).toContain('set_priority');
+    expect(
+      guide?.examples.every((example) =>
+        guide.workflows.some((workflow) => workflow.id === example.workflow),
+      ),
+    ).toBe(true);
+    expect(guide?.boundaries.some((boundary) => boundary.toLowerCase().includes('confirm'))).toBe(
+      true,
+    );
   });
 });

package/skills/codex/examples/food-ordering/src/helpers.ts

@@ -10,6 +10,7 @@ export {
   DataList,
   Feedback,
   Field,
+  Form,
   HandoffButton,
   QuantityStepper,
   ShellNav,

package/skills/codex/examples/food-ordering/src/views/ordering-flow.tsx

@@ -9,6 +9,7 @@ import {
   DataList,
   Feedback,
   Field,
+  Form,
   HandoffButton,
   QuantityStepper,
   ShellNav,
@@ -340,53 +341,55 @@ export default function OrderingFlow() {
       <div className="nw-body">
         <ViewStack flow={flow}>
           <View name="stores">
-            <div className="nw-field-grid">
-              <Field className="nw-field" label="Customer">
-                <input
-                  className="nw-input"
-                  value={customer}
-                  onChange={(event) => setCustomer(event.currentTarget.value)}
-                />
-              </Field>
-              <Field className="nw-field" label="Search">
-                <input
-                  className="nw-input"
-                  value={query}
-                  placeholder="Noodles"
-                  onChange={(event) => setQuery(event.currentTarget.value)}
-                />
-              </Field>
-            </div>
-            <ActionBar className="nw-actions">
-              <SubmitButton
-                type="button"
-                className="nw-button nw-button-primary"
-                pending={searchStores.isPending}
-                pendingLabel="Searching..."
-                onClick={() => searchStores.callTool({ query, openOnly: false })}
-              >
-                <SearchIcon />
-                Search stores
-              </SubmitButton>
-              <SubmitButton
-                type="button"
-                className="nw-button"
-                pending={readCart.isPending}
-                pendingLabel="Loading..."
-                onClick={async () => {
-                  const result = await readCart.callTool({});
-                  const stored = structured<{
-                    readonly value?: CartState;
-                    readonly revision?: number;
-                  }>(result);
-                  if (stored?.value?.lines) setCart(stored.value);
-                  setRevision(stored?.revision ?? revision);
-                }}
-              >
-                <RefreshIcon />
-                Load cart
-              </SubmitButton>
-            </ActionBar>
+            <Form onSubmit={() => void searchStores.callTool({ query, openOnly: false })}>
+              <div className="nw-field-grid">
+                <Field className="nw-field" label="Customer">
+                  <input
+                    className="nw-input"
+                    value={customer}
+                    onChange={(event) => setCustomer(event.currentTarget.value)}
+                  />
+                </Field>
+                <Field className="nw-field" label="Search">
+                  <input
+                    className="nw-input"
+                    value={query}
+                    placeholder="Noodles"
+                    onChange={(event) => setQuery(event.currentTarget.value)}
+                  />
+                </Field>
+              </div>
+              <ActionBar className="nw-actions">
+                <SubmitButton
+                  type="submit"
+                  className="nw-button nw-button-primary"
+                  disabled={!ready}
+                  pending={searchStores.isPending}
+                  pendingLabel="Searching..."
+                >
+                  <SearchIcon />
+                  Search stores
+                </SubmitButton>
+                <SubmitButton
+                  type="button"
+                  className="nw-button"
+                  pending={readCart.isPending}
+                  pendingLabel="Loading..."
+                  onClick={async () => {
+                    const result = await readCart.callTool({});
+                    const stored = structured<{
+                      readonly value?: CartState;
+                      readonly revision?: number;
+                    }>(result);
+                    if (stored?.value?.lines) setCart(stored.value);
+                    setRevision(stored?.revision ?? revision);
+                  }}
+                >
+                  <RefreshIcon />
+                  Load cart
+                </SubmitButton>
+              </ActionBar>
+            </Form>
             <AsyncBoundary
               state={searchStores}
               isEmpty={displayedStores.length === 0}

package/skills/codex/examples/food-ordering/test/ordering-flow.test.ts

@@ -38,6 +38,7 @@ vi.mock('../src/helpers.js', async () => {
     Feedback: ({ children, status }: { readonly children?: unknown; readonly status?: string }) =>
       createElement('div', { 'data-status': status }, children),
     Field: container,
+    Form: ({ children }: { readonly children?: unknown }) => createElement('form', null, children),
     HandoffButton: button,
     QuantityStepper: container,
     ShellNav: container,
@@ -71,6 +72,7 @@ vi.mock('../src/helpers.js', async () => {
     useUpdateModelContext: () => () => Promise.resolve(),
     useViewState: <T>(_key: string, initial: T) => [initial, () => undefined] as const,
     useWidgetLifecycle: () => () => Promise.resolve(),
+    useWidgetReady: () => true,
     View: container,
     ViewStack: container,
   };
@@ -183,5 +185,6 @@ describe('food-ordering invoking result states', () => {
     });
     expect(text).toContain('Search stores');
     expect(text).toContain('Harbor Noodles');
+    expect(document.querySelector('form')).not.toBeNull();
   });
 });

package/skills/codex/executing-noodle-plans/SKILL.md

@@ -3,7 +3,7 @@ name: executing-noodle-plans
 description: "Use when the user asks to execute an approved, decision-complete implementation plan for a Noodle Seed project task by task with test-first changes, review, recovery, and final verification."
 ---
 
-<!-- noodle-skill version:0.62.0 hash:6a9f132ddb79352e -->
+<!-- noodle-skill version:0.63.0 hash:6a9f132ddb79352e -->
 
 # Execute a Noodle Seed implementation plan
 

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

@@ -3,7 +3,7 @@ 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.62.0 hash:efffbf82007f935d -->
+<!-- noodle-skill version:0.63.0 hash:efffbf82007f935d -->
 
 # publishing-mcp-integrations
 

package/skills/codex/references/compile-errors.md

@@ -73,4 +73,11 @@ Run `noodle validate` (add `--json` for the machine-readable envelope, `--fix-pr
 | `customer_endpoint_policy_conflict` | Give every reachable declaration of this endpoint key one identical policy, or rename keys whose allowed origins differ. |
 | `customer_endpoint_routing_inconsistent` | Regenerate the connector catalog so every action route includes all of its ordinary customer endpoint dependencies. |
 | `unused_connector_alias` | A declared connector alias is never called; remove the unused `use` entry or wire it into a tool. |
-| `arg_mismatch` | A connector call is missing or adds arguments; match the operation signature under `expected`/`got`. |
+| `arg_mismatch` | A connector call is missing or adds arguments; match the operation signature under `expected`/`got`. |
+| `agent_guide_invalid` | Correct the product guide shape in `server(..., { agentGuide })` using non-empty bounded prose and symbolic references. |
+| `agent_guide_duplicate_workflow` | Give every `agentGuide.workflows` entry a unique lowercase underscore id. |
+| `agent_guide_duplicate_example` | Keep each agent-guide prompt and workflow pairing unique. |
+| `agent_guide_example_workflow_missing` | Point the example workflow at an existing `agentGuide.workflows` id. |
+| `agent_guide_capability_missing` | Correct the capability kind/name in `server(..., { agentGuide })` to a declared MCP capability. |
+| `agent_guide_capability_kind` | Correct the capability kind/name in `server(..., { agentGuide })` to match its declared MCP capability. |
+| `app_package_sensitive_content` | Remove the credential value; reference managed config by name only. |

package/skills/codex/references/product-agent-guides.md

@@ -0,0 +1,11 @@
+# Product agent guides
+
+Author one optional `agentGuide` in `server(name, { agentGuide, ... }, definitions)` when an agent needs product-level workflow guidance beyond individual MCP capability descriptions. It is host-neutral and TypeScript-only.
+
+The guide contains `description`, `useWhen`, named `workflows`, optional `boundaries`, and optional example prompt-to-workflow mappings. Each workflow step references a declared `tool`, `resource`, or `prompt` by symbolic `{ kind, name }`; do not duplicate schemas, connector bindings, URLs, credentials, or raw runtime data.
+
+Keep identifiers within 200 characters and prose within 4,000 characters. A guide has at most 32 `useWhen` entries, 32 workflows, 64 steps per workflow, 64 boundaries, and 64 examples. The compiler rejects an App Package whose bounded derived MCP surface would still exceed its artifact ceiling.
+
+Use `server.instructions` for a concise live MCP-session primer. Noodle-owned workflow skills teach how to build and operate Noodle projects; a product guide teaches agents how to use this one deployed product. Compilation validates references and produces an App Package sibling while the RuntimeArtifact deliberately omits guide prose.
+
+Recover `agent_guide_*` errors by correcting the guide shape, workflow IDs, and capability kind/name. Remove any credential-shaped value: managed config is referenced by name only.

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

@@ -48,7 +48,7 @@ Author views as React components. `generateHelpers<ServerDefinition>()` (from `@
 | `useAppFlow` | Manage named widget views with persisted params and back-stack state: `const flow = useAppFlow({ initialView, views })`. |
 | `useHandoff` | Open server-created HTTP(S) handoff URLs through the host with status/error state; domain policy still comes from `handoff.allowedDomains`. |
 
-Bind interactive elements to tools (`useCallTool("place_order")`), keep bridge-backed controls disabled until `useWidgetReady()` is true, drive named views with `useAppFlow(...)`, open server-created handoffs with `useHandoff()`, and publish one compact, safe, cohesive snapshot with `useUpdateModelContext()` when `useLayout().supports?.modelContext` is true. Generated form workflows use the portable `<Form onSubmit={...}>` component with a submit button; never add browser-navigation `action`, `method`, or `target` attributes. Existing intrinsic React forms are valid when their `onSubmit` handler calls `preventDefault()` before the explicit tool call and omits those navigation attributes. Standalone actions use an explicit `type="button"` and call the tool from their click handler. In every case the widget calls the standard MCP Apps tool bridge itself — never rely on a host to translate native form submission into a tool call, and never branch on a host name. Every model-context or lifecycle publication replaces the prior snapshot rather than merging fields, so include everything the model should still know. Calling `useWidgetLifecycle("name")` automatically publishes `mounted`, listens for host `cancelled` and `dismissed`, and returns a publisher for author-owned `submitted` or app-specific milestones; `mounted` is not proof that the host presented pixels. Both hooks use the standard MCP Apps model-context channel, not a host-specific API. These updates affect future model context but do not start a model turn. When an explicit user submit/cancel should receive an immediate reply, also call `useSendFollowUpMessage()` from that user action. `data-llm` may remain a DOM inspection hint, but it is not the bidirectional model-state contract. Use `createViewStore("key", initial)` for multi-component widget state such as carts, filters, or drafts. Use the domain-neutral React components from `@noodleseed/one/react` (`AppShell`, `ShellNav`, `ViewStack`, `AsyncBoundary`, `ActionBar`, `Form`, `Field`, `QuantityStepper`, `ChoiceGroup`, `HandoffButton`, and related state components) for rich apps before inventing local shell/control scaffolding. Adapt to the host with `useLayout()` — style for both `theme` values, and keep the inline `displayMode` compact (content fits the space; no internal scrolling). Trigger `useOpenExternal()`, `useHandoff()`, and `useSendFollowUpMessage()` only from explicit user actions. A raw `html` escape hatch exists for self-contained widgets (declarative `data-bind`/`data-action`; no inline `<script>`); raw markup must cancel native form navigation explicitly.
+Bind interactive elements to tools (`useCallTool("place_order")`), keep bridge-backed controls disabled until `useWidgetReady()` is true, drive named views with `useAppFlow(...)`, open server-created handoffs with `useHandoff()`, and publish one compact, safe, cohesive snapshot with `useUpdateModelContext()` when `useLayout().supports?.modelContext` is true. Generated form workflows use the portable `<Form onSubmit={() => void submit()}>` component with a submit button; never use an intrinsic React `<form>` or add browser-navigation `action`, `method`, or `target` attributes. A sandbox can block native activation before React receives `onSubmit`, so `preventDefault()` inside an intrinsic handler is not a portability fix. Standalone actions use an explicit `type="button"` and call the tool from their click handler. In every case the widget calls the standard MCP Apps tool bridge itself — never rely on a host to translate native form submission into a tool call, and never branch on a host name. Every model-context or lifecycle publication replaces the prior snapshot rather than merging fields, so include everything the model should still know. Calling `useWidgetLifecycle("name")` automatically publishes `mounted`, listens for host `cancelled` and `dismissed`, and returns a publisher for author-owned `submitted` or app-specific milestones; `mounted` is not proof that the host presented pixels. Both hooks use the standard MCP Apps model-context channel, not a host-specific API. These updates affect future model context but do not start a model turn. When an explicit user submit/cancel should receive an immediate reply, also call `useSendFollowUpMessage()` from that user action. `data-llm` may remain a DOM inspection hint, but it is not the bidirectional model-state contract. Use `createViewStore("key", initial)` for multi-component widget state such as carts, filters, or drafts. Use the domain-neutral React components from `@noodleseed/one/react` (`AppShell`, `ShellNav`, `ViewStack`, `AsyncBoundary`, `ActionBar`, `Form`, `Field`, `QuantityStepper`, `ChoiceGroup`, `HandoffButton`, and related state components) for rich apps before inventing local shell/control scaffolding. Adapt to the host with `useLayout()` — style for both `theme` values, and keep the inline `displayMode` compact (content fits the space; no internal scrolling). Trigger `useOpenExternal()`, `useHandoff()`, and `useSendFollowUpMessage()` only from explicit user actions. A raw `html` escape hatch exists for self-contained widgets (declarative `data-bind`/`data-action`; no inline `<script>`); use a `data-action` button with `type="button"` instead of native form submission.
 
 ## Worked widget recipe
 

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.62.0 hash:0f404109f4845683 -->
+<!-- noodle-skill version:0.63.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.62.0 hash:6ef6ef551e26b78e -->
+<!-- noodle-skill version:0.63.0 hash:6ef6ef551e26b78e -->
 
 # verifying-mcp-delivery
 

package/skills/codex/wrapping-existing-applications/SKILL.md

@@ -3,7 +3,7 @@ name: wrapping-existing-applications
 description: "Use when an existing application has no stable usable API and needs a read-only, identity-first Noodle Seed integration plan before implementation."
 ---
 
-<!-- noodle-skill version:0.62.0 hash:eccc3c158dcafba8 -->
+<!-- noodle-skill version:0.63.0 hash:eccc3c158dcafba8 -->
 
 # wrapping-existing-applications