@noodleseed/agent-kit 0.82.0 → 0.84.0

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

@@ -80,6 +80,13 @@ describe('food-ordering example', () => {
     expect(JSON.stringify(tools.get('open_ordering'))).toContain('${context.ambient.serviceArea}');
     expect(JSON.stringify(tools.get('open_ordering'))).toContain('${context.location.latitude}');
     expect(JSON.stringify(tools.get('open_ordering'))).toContain('${context.location.longitude}');
+    expect(tools.get('open_ordering')?.annotations).toMatchObject({
+      'x-noodleseed-model-latest-message-includes-any': expect.arrayContaining([
+        'order',
+        'menu',
+        'checkout',
+      ]),
+    });
     expect(JSON.stringify(tools.get('sync_cart'))).toContain('revision');
     expect(tools.get('sync_cart')?.annotations?.confirm).toBe(false);
     expect(tools.get('prepare_checkout')?.annotations?.confirm).toBe(false);

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.82.0 hash:6a9f132ddb79352e -->
+<!-- noodle-skill version:0.84.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.82.0 hash:efffbf82007f935d -->
+<!-- noodle-skill version:0.84.0 hash:efffbf82007f935d -->
 
 # publishing-mcp-integrations
 

package/skills/codex/references/authoring-workflow.md

@@ -23,7 +23,8 @@
 
 1. **Website scrape** — if the user gives a URL, scrape it for surface hints (products, services, hours, contact, pricing). Stop there: the URL does not reveal CRM, booking systems, custom APIs, auth model, eligibility rules, quoting logic, or approval flows. Those live in the business systems and the owner’s head — ask.
 2. **OpenAPI import** — `noodle import openapi <file>` emits a starter `server.ts` from a spec. Use it when the user provides an OpenAPI document.
-3. **User interview** — Noodle does not interview; you do. Cover custom APIs/integrations, eligibility rules, quoting/approval logic, and private schemas (SQL DDL or JSON samples for custom `connector` declarations). Ask for concrete examples and sample payloads; do not guess a schema from a URL or invent endpoints.
+3. **Upstream MCP import** — `noodle import mcp <url> --name <slug> --output <dir>` discovers `tools/list` once, validates and freezes tool schemas into TypeScript, and writes a secret-free drift snapshot. Upstream annotations are untrusted, so generated tools remain destructive confirmed actions until an author verifies and narrows them. Use `--header-env <header>=<ENV_NAME>` for import-only auth and `--check` for classified, non-mutating drift detection. Runtime never performs discovery.
+4. **User interview** — Noodle does not interview; you do. Cover custom APIs/integrations, eligibility rules, quoting/approval logic, and private schemas (SQL DDL or JSON samples for custom `connector` declarations). Ask for concrete examples and sample payloads; do not guess a schema from a URL or invent endpoints.
 
 ## Fit check
 
@@ -42,10 +43,18 @@ Author in `server.ts`, then `noodle validate` → fix cited errors (see `compile
 Declare connectors as data, not imperative code:
 
 - **HTTP**: `connector("id").version("1.0.0").http({ baseUrl, allowedOrigins, auth, operations })` with per-operation `request`/`response` mapping using `${args...}` / `${response...}` expressions.
+- **MCP**: `connector("id").version("1.0.0").mcp({ endpoint, allowedOrigins, auth?, operations })` where each operation freezes the separate upstream `tool` wire name plus input/output schema. Import with `noodle import mcp`; do not hand-copy a live surface or call `tools/list` at runtime.
 - **Compute**: `connector("id").version("1.0.0").compute(name, { input, output, calls?, run })` — a self-contained, sandboxed function (no imports/closure capture) that may call allowlisted operations via `callOperation`.
 
 Tools record connector calls into a flow; recording is not execution. Do not branch on runtime outputs with native `if` — use declarative `when(...)` conditions.
 
+MCP connectors are curated backing operations, never transparent proxies. Publish ordinary Noodle tools
+with stable intent-shaped names, descriptions, annotations, authored schemas, confirmation, visibility,
+and optional React `view`. Normalize a text-only upstream result through compute before rendering when the
+view needs a richer stable output. Upstream resources, prompts, `_meta`, annotations, widgets, and CSP are
+not imported or forwarded. The runtime opens one guarded session for one operation, uses only a broker-minted
+credential, and closes it; it does not act as an agent for upstream sampling, roots, or elicitation.
+
 HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `clientCredentials`, `delegatedOAuth`, `delegatedSessionCookie`, and `delegatedTokenExchange` (per-user calls to your own API — see "Delegated downstream auth" below). Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
 
 When one connector needs independently selectable accounts, declare catalog `credentialProfiles` plus each operation’s accepted `credentials.profiles`, then bind each `server.use` alias with `bind(connector, { profile, connection: connection("logical_id", managedSecret(secret("NAME"), { scopes, audience })) })`. The alias is the stable account boundary; never put provider account ids, labels, or credential values in it. `gmailConnector()` is the curated Gmail catalog helper; reuse it under independent aliases and accept canonical `accounts` arrays in tools (one account for writes, or an explicitly ordered supported combination for reads). See the bundled `gmail-multi-account` flagship. Bound managed secrets are supported by hosted execution. For deployed-server access to Google APIs, use `googleWorkloadIdentity({ provider: variable("GOOGLE_WIF_PROVIDER"), access: { kind: "direct" } })`, or add `serviceAccountImpersonation` with a managed service-account email. This is keyless Google Workload Identity Federation: exact Google scopes/audience come from the catalog operation, while `noodle auth google prepare|status|doctor|revoke` owns operator lifecycle. See the bundled `google-bigquery` flagship. `externalExchange()` is runnable only when the deployment operator injects an exact HTTPS provider endpoint/origin/audience and durable shared subject-pin store through service ports; Noodle sends a short-lived platform-signed deployment workload assertion and accepts only a bounded bearer response. Provider implementations must consume assertion replay ids through durable shared atomic storage across instances and restarts. There is intentionally no hosted enrollment or provider CRUD surface yet. The provider wire contract is public, but its conformance kit is workspace/source-only and is not an installable npm package. Bound `clientCredentials(...)` remains fail-closed until its provider slice lands.

package/skills/codex/references/connect-an-api.md

@@ -11,6 +11,7 @@ Connect a real API to a focused MCP product using managed credentials, mappings
 - Secure the key first
 - Probe the live API
 - Model the connector from the observed shape
+- Import and curate an upstream MCP server
 - Return a list
 - Create, update, delete
 - Design intent tools
@@ -22,7 +23,7 @@ Connect a real API to a focused MCP product using managed credentials, mappings
 
 ## Use when
 
-- The user provides credentials, a reachable API, or an OpenAPI document and wants real MCP behavior backed by it.
+- The user provides credentials, a reachable API, an OpenAPI document, or an upstream MCP endpoint and wants real MCP behavior backed by it.
 - Existing connector behavior compiles but still needs proof against the actual service and data shape.
 
 ## Do not use when
@@ -80,6 +81,35 @@ Encode the API as an HTTP connector, mapping only the fields you actually saw in
 The full connector shape, every `auth.kind`, and compute connectors are in
 `references/authoring-workflow.md`.
 
+### Import and curate an upstream MCP server
+
+Use an explicit import to discover the upstream tool surface once and generate TypeScript:
+
+```sh
+noodle import mcp https://store.example/api/mcp --name store --output store-app
+# When import discovery needs a credential, read it only from the environment:
+noodle import mcp https://store.example/api/mcp --name store \
+  --header-env Authorization=STORE_MCP_TOKEN
+```
+
+The importer freezes upstream tool names and normalized schemas into `.mcp({ operations })`; it never
+persists the import credential. Runtime calls only those declared operations and never runs `tools/list`.
+MCP annotations are untrusted hints, so every generated tool starts as a destructive confirmed action.
+Verify real behavior and deliberately narrow proven reads before accepting the generated source. Use
+`noodle import mcp <url> --output <dir> --check` in CI to detect upstream additions, removals, or schema
+changes without mutating source; its review labels drift additive, breaking, or metadata-only.
+
+Treat the imported connector operation as a backing-system contract, not the public tool design. Publish
+ordinary intent-shaped `tool(...)` capabilities with stable names and narrower schemas, normalize text or
+large upstream output through compute, and attach a normal Noodle React `view` when UI helps. Upstream
+`_meta`, resources, prompts, annotations, widgets, and CSP are never forwarded. A Noodle-owned widget may
+therefore enrich a headless upstream tool without trusting upstream executable UI.
+
+Managed endpoints require an exact managed origin allowlist. Configure each deployment with
+`variable(...)` and `secret(...)`; inbound MCP/OAuth bearer tokens are never reusable upstream credentials.
+The first release supports no auth, bearer, API key, and client credentials through the broker. Do not
+invent a delegated-user OAuth shortcut for an upstream MCP server.
+
 ### Return a list
 
 Most real tools return a variable-length list (search results, a user’s tasks). Bind the **whole array** — a single `${response.path}` returns the referenced value verbatim, arrays included:

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

@@ -29,7 +29,8 @@ Keep every credential and identity layer separate:
 | Owner | Values | Destination |
 | --- | --- | --- |
 | Noodle operator | Login, selected org/app/env | Plugin-managed CLI profile and explicit target; never the SaaS runtime |
-| Noodle deployment | `ASSISTANT_MODEL_BASE_URL`, `ASSISTANT_MODEL`, `ASSISTANT_MODEL_API_KEY` | `noodle variables set` / `noodle secrets set`; never the SaaS environment |
+| Noodle-managed model | No authored provider, model id, URL, or key | Hosted operator state; available only when Noodle has enrolled the exact org/app/env |
+| Operator-provided model | `ASSISTANT_MODEL_BASE_URL`, `ASSISTANT_MODEL`, `ASSISTANT_MODEL_API_KEY` | `noodle variables set` / `noodle secrets set`; never the SaaS environment |
 | Connector/delegated exchange | Connector credentials and any customer-owned token-exchange client | Noodle managed configuration plus the matching customer backend secret manager |
 | SaaS backend | `NOODLE_SERVICE_URL`, `NOODLE_ASSISTANT_CLIENT_ID`, `NOODLE_ASSISTANT_CLIENT_SECRET`, `PUBLIC_APP_ORIGIN` | Backend-only environment or secret manager; never browser code or public-prefixed variables |
 | Browser | Short-lived assistant session only | In memory; never a client secret, model key, connector credential, or raw application session |
@@ -48,11 +49,7 @@ Use the same server tools in the embed; do not create a second tool set. Declare
 branding: { name: "Acme", accent: "#3157D5" },
 context: { defaults: { locale: "en-GB", timeZone: "Europe/London" } },
 assistant: embeddedAssistant({
-  model: openAICompatible({
-    baseUrl: variable("ASSISTANT_MODEL_BASE_URL"),
-    model: variable("ASSISTANT_MODEL"),
-    apiKey: secret("ASSISTANT_MODEL_API_KEY"),
-  }),
+  model: noodleManaged(),
   access: authenticatedWebsite({
     origins: ["http://localhost:3000", "https://app.example.com"],
   }),
@@ -60,6 +57,8 @@ assistant: embeddedAssistant({
 }),
 ```
 
+`noodleManaged()` is the zero-configuration Cloud path: the public artifact contains only `{ kind: "noodle-managed" }`. It never exposes a provider or model identifier, and it fails closed unless Noodle has enrolled that exact deployment target. For a customer- or self-hosted model, replace it with `openAICompatible({ baseUrl: variable("ASSISTANT_MODEL_BASE_URL"), model: variable("ASSISTANT_MODEL"), apiKey: secret("ASSISTANT_MODEL_API_KEY") })`; that remains the portable BYO path.
+
 Origins are exact: scheme, host, and optional port, with no path, trailing slash, or wildcard. Production origins must be HTTPS; plain HTTP is accepted only for loopback development origins (`http://localhost:<port>`, `http://127.0.0.1:<port>`). `noodle dev` serves the MCP project, not the embedding SaaS. For a public surface it also prints a process-local Embed ID and script; mount that script on the separately running loopback website to test anonymous mint, chat, widgets, and confirmation. The local ID is ephemeral, while a hosted deploy provisions the stable ID behind durable admission counters.
 
 ## Product workflow guidance
@@ -166,7 +165,7 @@ Local MCP authoring and tests need no account, but an external browser embed nee
 noodle deploy --org <org> --app <app> --env <env>
 ```
 
-Deploy preflights the complete target before upload. In an interactive terminal it collects all missing model variables and secrets, then continues. In a non-interactive run it reports every missing name and safe `noodle variables set ... --from-env` / `noodle secrets set ... --from-env` action; perform every action and repeat the same deploy command. Values never appear in the preflight report or resume state. Do not put these model values in the embedding SaaS environment. A production deployment may omit a local origin; include a loopback origin only when local browser integration is required.
+Deploy preflights the complete target before upload. `noodleManaged()` has no customer model variables or secrets; enrollment is hosted operator state and an unenrolled target fails closed at serving time. `openAICompatible()` preflight collects or reports every missing model variable and secret with safe `noodle variables set ... --from-env` / `noodle secrets set ... --from-env` actions. Values never appear in the preflight report or resume state. Do not put BYO model values in the embedding SaaS environment. A production deployment may omit a local origin; include a loopback origin only when local browser integration is required.
 
 ## Access modes and customer auth
 

package/skills/codex/references/sdk-surface.md

@@ -65,6 +65,7 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 - `knowledge`
 - `managedSecret`
 - `meilisearch`
+- `noodleManaged`
 - `openAICompatible`
 - `publicWebsite`
 - `site`
@@ -73,7 +74,7 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 ## Authoring signatures
 
 - `server(name, options, definitions)` — `options` commonly includes `title`, `version`, `instructions`, `agentGuide`, `distribution`, `branding`, `auth`, `use`, `provides`, `state`, and `handoff`; `definitions` is the array of tools/resources/prompts.
-- `tool(name, { description, input, output, annotations?, visibility?, view?, fulfil })` — `input`/`output` are Zod schemas; `fulfil({ input, connectors, user })` returns data matching `output`. Add `view: { component, entry }` for a React widget; use `visibility: ["app"]` for an app-only helper.
+- `tool(name, { description, input, output, annotations?, visibility?, modelVisibility?, view?, fulfil })` — `input`/`output` are Zod schemas; `fulfil({ input, connectors, user })` returns data matching `output`. Add `view: { component, entry }` for a React widget; use `visibility: ["app"]` for an app-only helper. Use `modelVisibility.latestMessageIncludesAny` only for normalized literal explicit-intent discovery; it does not authorize execution.
 - Keep tool input names application-owned and meaningful; `__noodleIntent` is reserved for an optional serve-time operator analytics adapter and never reaches `fulfil`.
 - `resource(name, { uri, description?, mimeType?, fulfil })` and `prompt(name, { description?, arguments?, fulfil })` expose MCP resources/prompts.
 - View metadata (`viewTitle`, `viewDescription`, `csp`, `domain`, `permissions`) belongs on the tool that renders it; `asset("./path")` packages local files.
@@ -145,7 +146,7 @@ prompt('summarize_ticket', {
 
 ### Non-trivial tool: ctx connectors, annotations, visibility, async
 
-`ctx` is `{ input, user, connectors }`. Bind connectors with `use` on the server, then call one inside `fulfil` to record a step. `annotations.readOnly()` declares a closed-world safe read. TypeScript action helpers enforce confirmation only with `{ confirm: true }`; omitted or `false` executes directly, and action/destructive/open-world hints alone never enable the gate. For stateless hosts that cannot present Noodle confirmation, set `interactions: { confirmationFallback: 'host' }` in the `server` options to explicitly trust native host write approval; omission remains fail-closed and the fallback never supplies missing `ctx.elicit` input. `visibility` defaults to `['model', 'app']` — set `['app']` to hide a helper from the model. `fulfil` may be `async` (the compiler awaits it while recording).
+`ctx` is `{ input, user, connectors }`. Bind connectors with `use` on the server, then call one inside `fulfil` to record a step. `annotations.readOnly()` declares a closed-world safe read. TypeScript action helpers enforce confirmation only with `{ confirm: true }`; omitted or `false` executes directly, and action/destructive/open-world hints alone never enable the gate. For stateless hosts that cannot present Noodle confirmation, set `interactions: { confirmationFallback: 'host' }` in the `server` options to explicitly trust native host write approval; omission remains fail-closed and the fallback never supplies missing `ctx.elicit` input. `visibility` defaults to `['model', 'app']` — set `['app']` to hide a helper from the model. For a narrow explicit-intent tool, `modelVisibility: { latestMessageIncludesAny: [...] }` deterministically limits model discovery to a latest user message containing one of the normalized literal phrases; it is not authorization. `fulfil` may be `async` (the compiler awaits it while recording).
 
 ```ts
 import { annotations, connector, server, tool, z } from '@noodleseed/one';
@@ -176,6 +177,7 @@ export default server('support', { title: 'Support', version: '1.0.0', use: { cr
     output: z.object({ subject: z.string(), status: z.string() }),
     annotations: annotations.readOnly(), // read-only hint for hosts
     visibility: ['model', 'app'], // default; use ['app'] to hide the tool from the model
+    modelVisibility: { latestMessageIncludesAny: ['show ticket', 'open ticket'] },
     // ctx is { input, user, connectors }. A connector call records one flow step (a Ref) —
     // recording is not execution, so never branch on the result with native if (use when).
     fulfil: ({ input, connectors }) => {

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

@@ -12,7 +12,7 @@
 
 ## Tools and views
 
-Use `tool(name, { description, input, output, fulfil, view })` for a model-visible tool that renders a widget, and the same `tool(name, { ..., visibility: ["app"] })` for an app-only helper hidden from the model. A `view` is `{ component: "name", entry: "./views/name.tsx" }` — a React component the compiler bundles at validate/deploy time.
+Use `tool(name, { description, input, output, fulfil, view })` for a model-visible tool that renders a widget, and the same `tool(name, { ..., visibility: ["app"] })` for an app-only helper hidden from the model. When a view is valid only for narrow explicit intent, add `modelVisibility: { latestMessageIncludesAny: ["open the form", ...] }`; Noodle normalizes and matches those literal phrases against the latest user message before model discovery and fails closed on malformed data. This is relevance filtering, never authorization. A `view` is `{ component: "name", entry: "./views/name.tsx" }` — a React component the compiler bundles at validate/deploy time.
 
 ## Noodle Design default
 

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.82.0 hash:0f404109f4845683 -->
+<!-- noodle-skill version:0.84.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.82.0 hash:6ef6ef551e26b78e -->
+<!-- noodle-skill version:0.84.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.82.0 hash:eccc3c158dcafba8 -->
+<!-- noodle-skill version:0.84.0 hash:eccc3c158dcafba8 -->
 
 # wrapping-existing-applications