@noodleseed/agent-kit 0.41.0 → 0.43.0

package/skills/codex/examples/weather/src/server.ts

@@ -189,6 +189,7 @@ export default server(
   },
   [
     tool('weather_briefing', {
+      title: 'Weather briefing',
       description:
         'Look up a city, fetch its current weather, and return a human-readable briefing. Runs a ' +
         'three-step flow: geocode the city, fetch the forecast, then derive the briefing in a sandboxed compute step.',
@@ -233,14 +234,21 @@ export default server(
     // the whole array; the compute connector narrows each element to the two fields the model speaks
     // from. Append new tools AFTER existing ones so `tools[0]` stays stable for host harnesses.
     tool('search_places', {
+      title: 'Search places',
       description:
         'Search a place name and return the matching locations as a list of { id, label } options.',
-      input: z.object({ query: z.string() }),
+      // Bound the list at the source: `limit` is capped in the schema and passed through to the
+      // upstream `count` parameter, so the model can never pull an unbounded page into its context.
+      // `noodle check` reports an unbounded array output as `tool_design_output_bounds`.
+      input: z.object({
+        query: z.string(),
+        limit: z.number().int().min(1).max(10).default(5),
+      }),
       output: z.object({
         places: z.array(z.object({ id: z.string(), label: z.string() })),
       }),
       fulfil: ({ input, connectors }) => {
-        const found = connectors.geo.search_list({ name: input.query });
+        const found = connectors.geo.search_list({ name: input.query, count: input.limit });
         const narrowed = connectors.places.narrow({ results: found.results });
         return { places: narrowed.places };
       },

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.41.0 hash:efffbf82007f935d -->
+<!-- noodle-skill version:0.43.0 hash:efffbf82007f935d -->
 
 # publishing-mcp-integrations
 

package/skills/codex/references/agent-contract.md

@@ -1,6 +1,6 @@
 # Agent contract: --json, exit codes, output modes
 
-The cold-agent-path commands (`init`, `validate`, `test`, `check`, `tools`/`resources`/`prompts`, `deploy`, `metrics`, `events`, `agents`) are agent-native and return the envelope below; hosted admin/ops commands (`status`, `inspect`, `smoke`, `logs`, `update`) are still being normalized. Decide what to do next by parsing machine state — do not scrape human prose.
+Every `--json` command returns the canonical envelope below on stdout and keeps stderr empty. Decide what to do next by parsing machine state — do not scrape human prose.
 
 ## Contents
 
@@ -11,12 +11,13 @@ The cold-agent-path commands (`init`, `validate`, `test`, `check`, `tools`/`reso
 
 ## Response envelope
 
-A `--json` command returns exactly one JSON object:
+A one-shot `--json` command returns exactly one JSON object on stdout; stderr stays empty:
 
 - **Success**: `{ ok: true, data, warnings? }` — `data` is the command payload; `warnings?` is an optional array of non-fatal notes.
-- **Failure**: `{ ok: false, error: { code, message, cause?, fix, next, requestId? } }` — `code` is the stable machine code to branch on, `message` is human text, `cause?` is the underlying error, `fix` states the correction, `next` names the command to run next, `requestId?` correlates a hosted call.
+- **Failure**: `{ ok: false, error: { code, message, cause?, fix, next, requestId?, retryable?, retryAfterSeconds? } }` — `code` is the stable machine code to branch on, `message` is human text, `cause?` is the underlying error, `fix` states the correction, `next` names the command to run next, `requestId?` correlates a hosted call, and retry metadata tells automation whether and when to retry.
 - **Field errors** carry a dotted `path`: multi-error commands (e.g. `noodle validate`) nest them under `error.errors[]`, each `{ code, path, message }`. The top-level `error` still carries `code`/`message`/`fix`/`next`; the per-field `path`s live in `error.errors[]`.
 - **Repair prose is isolated**: ready-to-apply repair text appears only under `error.fixPrompt` (surfaced by `--fix-prompt`), never mixed into `message` or `data`.
+- **Streams are NDJSON envelopes**: the initial snapshot is `{ ok: true, data: { kind: "snapshot", snapshot } }`, subsequent records are `{ ok: true, data: { kind: "event", event } }`, and a terminal failure is the ordinary `{ ok: false, error }` envelope on its own line. Parse each line independently.
 
 ## Exit codes
 

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

@@ -8,7 +8,6 @@
 - Connectors
 - HTTP connector example (full server)
 - Delegated downstream auth (call your API as the signed-in user)
-- Design tools for the model
 - Invocation context
 - Compute connector example
 - Tests
@@ -173,65 +172,7 @@ Diagnose statically with `noodle auth doctor`; set a short-lived real customer t
 
 ## Design tools for the model
 
-Design tools around what a user says, not 1:1 around API endpoints. A raw wrapper per endpoint (`get_task`, `list_tasks`, `close_task`) forces the model to orchestrate low-level calls and to know identifiers the user never sees — an MCP connector, but not a usable product. Instead:
-
-- **Shape by intent.** Name and scope tools for the job to be done — "find my overdue tasks", "complete the task matching this text" — combining multiple backing calls in one recorded flow (`when(...)`) where it helps.
-- **Prefer names/text over raw IDs.** When an action needs an id the user does not know, pair the id-taking operation with a find/search operation that returns model-friendly summaries (id + a human label), so the model resolves text → id itself. Write descriptions that tell the model when to use each tool and how they chain.
-- **Return only what the model needs.** Map the response to a small, typed `output` (a few labelled fields), not the raw API payload.
-
-This example pairs a name resolver with an id-taking action: the model calls `find_tasks` to turn the user’s words into an id, then `complete_task`. It is compile-verified on every `pnpm test`.
-
-```ts
-import { connector, secret, server, tool, z } from '@noodleseed/one';
-
-const tasks = connector('tasks').version('1.0.0').http({
-  baseUrl: 'https://api.tasks.example',
-  allowedOrigins: ['https://api.tasks.example'],
-  auth: { kind: 'bearer', secret: secret('TASKS_TOKEN') },
-  operations: {
-    search_tasks: {
-      type: 'read',
-      method: 'GET',
-      path: '/tasks',
-      query: ['query'],
-      input: z.object({ query: z.string() }),
-      output: z.object({ matches: z.array(z.unknown()) }),
-      response: { matches: '${response.results}' },
-    },
-    close_task: {
-      type: 'action',
-      method: 'POST',
-      path: '/tasks/{id}/close',
-      input: z.object({ id: z.string() }),
-      output: z.object({ ok: z.boolean() }),
-      response: { ok: '${response.ok}' },
-    },
-  },
-});
-
-export default server('todo', { title: 'Tasks', version: '1.0.0', use: { tasks } }, [
-  tool('find_tasks', {
-    description: 'Find tasks whose text matches a query — call this first to resolve a task the user names by text into its id, then pass that id to complete_task.',
-    input: z.object({ query: z.string() }),
-    output: z.object({ matches: z.array(z.object({ id: z.string(), title: z.string() })) }),
-    fulfil: ({ input, connectors }) => {
-      const found = connectors.tasks.search_tasks({ query: input.query });
-      return { matches: found.matches };
-    },
-  }),
-  tool('complete_task', {
-    description: 'Mark a task complete by its id (get the id from find_tasks).',
-    input: z.object({ id: z.string() }),
-    output: z.object({ ok: z.boolean() }),
-    fulfil: ({ input, connectors }) => {
-      const result = connectors.tasks.close_task({ id: input.id });
-      return { ok: result.ok };
-    },
-  }),
-]);
-```
-
-The model never sees a task id from the user; `find_tasks` returns `{ id, title }` summaries it can pick from, then `complete_task` acts by id. Keep write actions (`complete_task`) separate and explicitly described so the host can gate them.
+Shape tools around what a user says, not 1:1 around API endpoints. `references/tool-design.md` owns the doctrine: intent-shaped tools, titles and annotations, bounded outputs, a small tool surface, and deliberate context.
 
 ## Invocation context
 

package/skills/codex/references/build-an-mcp-server.md

@@ -22,7 +22,7 @@ Establish only the inputs needed for the requested stopping point. Follow `refer
 1. **Confirm conversational fit.** Name one to three focused jobs where saying the request is easier than navigating the underlying system, and identify the data or action the model cannot provide by itself.
 2. **Define the product contract.** For each job, write the user phrase, the intent-shaped tool or resource, its minimal typed input, the useful output, read/write effect, and backing operation. Design for user intent, not a 1:1 API endpoint wrapper.
 3. **Choose the smallest implementation.** Use native tools, resources, or prompts for local/static behavior; add a connector only when external data or actions are required. Keep response output small and model-readable.
-4. **Author in TypeScript.** Follow `references/authoring-workflow.md` for connector and flow patterns and `references/sdk-surface.md` for exact builders. These are this route’s complete canonical support set; use the router lookup catalog only when observed evidence names a different concern.
+4. **Author in TypeScript.** Follow `references/authoring-workflow.md` for connector and flow patterns, `references/tool-design.md` for the model-facing tool surface, and `references/sdk-surface.md` for exact builders. These are this route’s complete canonical support set; use the router lookup catalog only when observed evidence names a different concern.
 5. **Validate and repair.** Run `noodle validate --json`. Parse `error.errors[]`, repair the cited `path`, and rerun validation. Consult the lookup catalog only for the specific reported error code; do not open another reference speculatively.
 6. **Run the local smoke.** After validation succeeds, run `noodle test --json` and repair any failure at that evidence layer.
 7. **Prove external behavior.** For connector-backed reads, set credentials through the effective local target and run a safe representative `noodle tools call`. Confirm populated mapped fields from real output, not merely successful registration.

package/skills/codex/references/cli-commands.md

@@ -27,7 +27,7 @@ Developer-facing `noodle` commands, grouped by area. Local authoring commands (`
 | `noodle import` | Import an OpenAPI spec into a starter `server.ts`. |
 | `noodle export` | Compile locally and write the portable manifest JSON (no service). |
 | `noodle validate` | Author-time compile/schema/connector check; no service (`--json`, `--fix-prompt`). |
-| `noodle check` | Check MCP Apps/widget readiness; no service. |
+| `noodle check` | Check tool design (`tool_design_*`) and MCP Apps/widget readiness; no service. `--min-severity warn` shows only what needs fixing. |
 | `noodle test` | Local compile plus a loopback MCP smoke. |
 
 ## Local run & inspect

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

@@ -157,8 +157,12 @@ Local `dev`, smoke commands, secrets, and variables resolve one effective target
 noodle secrets set SOME_API_KEY --runtime local --from-env SOME_API_KEY
 # Explicit flags remain available when intentionally testing a different local target:
 noodle secrets set SOME_API_KEY --runtime local --scope env --org <org> --app <app> --env <env> --from-env SOME_API_KEY
+# Configuring a deployed environment is a different store — say so:
+noodle secrets set SOME_API_KEY --runtime cloud --scope env --org <org> --app <app> --env <env> --from-env SOME_API_KEY
 ```
 
+`--runtime` is required whenever `--org`, `--app`, and `--env` together name a complete hosted target: a command that looks remote must never fall back to writing `.env.noodle`. Omitting it fails with `runtime_required` before anything is written.
+
 Local secrets live in `./.env.noodle` (never commit it). A required `secret(...)` or `variable(...)` that cannot resolve fails boot closed. `noodle tools call` / `noodle test` / `noodle dev` / `noodle devtools` stop before exposing an empty endpoint and print the exact effective target plus recovery command.
 
 ### Prove real output

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

@@ -91,9 +91,9 @@ Give every business action a portable `tool(..., { title: "Complete task", descr
 Local MCP authoring and tests need no account, but an external browser embed needs an active assistant-enabled deployment before a backend client can be created. Set the model values on the target org/app/env, then deploy:
 
 ```sh
-noodle variables set ASSISTANT_MODEL_BASE_URL --scope env --org <org> --app <app> --env <env> --value <https-model-base-url>
-noodle variables set ASSISTANT_MODEL --scope env --org <org> --app <app> --env <env> --value <model>
-noodle secrets set ASSISTANT_MODEL_API_KEY --scope env --org <org> --app <app> --env <env> --from-env ASSISTANT_MODEL_API_KEY
+noodle variables set ASSISTANT_MODEL_BASE_URL --scope env --runtime cloud --org <org> --app <app> --env <env> --value <https-model-base-url>
+noodle variables set ASSISTANT_MODEL --scope env --runtime cloud --org <org> --app <app> --env <env> --value <model>
+noodle secrets set ASSISTANT_MODEL_API_KEY --scope env --runtime cloud --org <org> --app <app> --env <env> --from-env ASSISTANT_MODEL_API_KEY
 noodle deploy --org <org> --app <app> --env <env>
 ```
 

package/skills/codex/references/feedback.md

@@ -1,6 +1,6 @@
 # Send product feedback
 
-When you — the coding agent — discover a way Noodle Seed could be better, prepare one sanitized feedback proposal. Feedback crosses the customer project boundary and lands in Noodle Seed’s private tracker, so the user must make an informed choice. Show the user the exact command and ask for explicit user approval. Do not run or submit it until approval is given.
+When you — the coding agent — discover a way Noodle Seed could be better, prepare one sanitized feedback proposal. Feedback crosses the customer project boundary and lands in the Noodle Seed private feedback tracker, so the user must make an informed choice. Preview the exact normalized submission locally, show it with the exact live command, and ask for explicit user approval. Do not submit it until approval is given.
 
 ## Contents
 
@@ -26,20 +26,22 @@ Do not batch several findings into one proposal, and do not re-propose the same
 
 ## Approval workflow
 
-1. Draft and sanitize the title, message, labels, and exact shell command.
-2. Show the user the exact command and explain that it sends the shown content plus CLI version, OS/platform, and Node version to Noodle Seed’s private tracker.
-3. Ask for explicit user approval. Do not run, submit, or send anything until the user clearly approves that exact proposal.
-4. After approval, run it once. If authentication is missing, report that feedback was not sent and offer the normal `noodle login` path; never sign in or retry without direction.
+1. Discover the current positional arguments, flags, choices, defaults, and limits from `noodle commands --json`; `noodle feedback --help` is the human-readable view. Do not guess or rely on a remembered catalog.
+2. Draft one finding, then sanitize its title and message using the rules below.
+3. Run the proposal with `--dry-run --json`. This local preview needs no login and sends nothing. Parse `{"ok":true,"data":{"mode":"preview","willSubmit":false,"destination":"Noodle Seed private feedback tracker","submission":{...}}}`.
+4. Inspect the complete `submission`, including its normalized defaults and automatically attached diagnostics. Show the user the exact previewed proposal, its `destination`, and a POSIX-safely quoted live command containing the same fields but without `--dry-run`.
+5. Ask for explicit approval of that exact previewed proposal. If the user changes any field, preview the changed proposal again before asking.
+6. Only after approval, submit it once by running the disclosed live command without `--dry-run`. Never auto-login and never retry-loop. If authentication fails before the request or a rate limit denies it, report that nothing was sent. For `feedback_recording_failed`, report that no reference was returned and the outcome may be unknown; do not retry because the private issue might already exist.
 
 ## The command
 
 ```sh
-noodle feedback "resources list --json omits the truncated flag the docs promise" \
-  --title "resources list --json missing truncated flag" \
-  --type fix --severity P2 --area cli --json
+noodle feedback 'resources list --json omits the truncated flag the docs promise' \
+  --title 'resources list --json missing truncated flag' \
+  --type fix --severity P2 --area cli --dry-run --json
 ```
 
-This is an example only; build the exact command for the finding and show it before execution. Read `noodle feedback --help` for human-readable constraints or inspect `noodle commands --json` for the same machine-readable usage, enum, and length metadata instead of guessing accepted values. The message is required (1–4000 chars). Pass `--json` and parse the envelope: success is `{ok:true,data:{reference,labels}}`; a `429` means the per-user hourly budget (5) is spent — report that it was not sent and never retry-loop. The CLI attaches only the disclosed light diagnostics automatically: CLI version, OS/platform, Node version. Nothing else is collected.
+This is a preview example only. Build the exact command for the finding using current `noodle commands --json` metadata, POSIX-quote every user-controlled value, and inspect the returned submission instead of reconstructing it. The message is required (1–4000 chars). The CLI attaches only the disclosed light diagnostics automatically: CLI version, OS/platform, Node version. Nothing else is collected. After approval, the live success envelope is `{ok:true,data:{reference,labels}}`; a `429` means the per-user hourly budget (5) is spent — report that it was not sent and never retry-loop.
 
 ## Choose the structured fields
 

package/skills/codex/references/tool-design.md

@@ -0,0 +1,103 @@
+# Tool design
+
+## Contents
+
+- Design tools for the model
+- Title and annotations
+- Bound every output
+- Keep the tool surface small
+- Provision context deliberately
+- Errors an agent can act on
+- What `noodle check` reports
+
+## Design tools for the model
+
+Design tools around what a user says, not 1:1 around API endpoints. A raw wrapper per endpoint (`get_task`, `list_tasks`, `close_task`) forces the model to orchestrate low-level calls and to know identifiers the user never sees — an MCP connector, but not a usable product. Instead:
+
+- **Shape by intent.** Name and scope tools for the job to be done — "find my overdue tasks", "complete the task matching this text" — combining multiple backing calls in one recorded flow (`when(...)`) where it helps.
+- **Prefer names/text over raw IDs.** When an action needs an id the user does not know, pair the id-taking operation with a find/search operation that returns model-friendly summaries (id + a human label), so the model resolves text → id itself. Write descriptions that tell the model when to use each tool and how they chain.
+- **Return only what the model needs.** Map the response to a small, typed `output` (a few labelled fields), not the raw API payload.
+
+This example pairs a name resolver with an id-taking action: the model calls `find_tasks` to turn the user’s words into an id, then `complete_task`. It is compile-verified on every `pnpm test`.
+
+```ts
+import { connector, secret, server, tool, z } from '@noodleseed/one';
+
+const tasks = connector('tasks').version('1.0.0').http({
+  baseUrl: 'https://api.tasks.example',
+  allowedOrigins: ['https://api.tasks.example'],
+  auth: { kind: 'bearer', secret: secret('TASKS_TOKEN') },
+  operations: {
+    search_tasks: {
+      type: 'read',
+      method: 'GET',
+      path: '/tasks',
+      query: ['query'],
+      input: z.object({ query: z.string() }),
+      output: z.object({ matches: z.array(z.unknown()) }),
+      response: { matches: '${response.results}' },
+    },
+    close_task: {
+      type: 'action',
+      method: 'POST',
+      path: '/tasks/{id}/close',
+      input: z.object({ id: z.string() }),
+      output: z.object({ ok: z.boolean() }),
+      response: { ok: '${response.ok}' },
+    },
+  },
+});
+
+export default server('todo', { title: 'Tasks', version: '1.0.0', use: { tasks } }, [
+  tool('find_tasks', {
+    description: 'Find tasks whose text matches a query — call this first to resolve a task the user names by text into its id, then pass that id to complete_task.',
+    input: z.object({ query: z.string() }),
+    output: z.object({ matches: z.array(z.object({ id: z.string(), title: z.string() })) }),
+    fulfil: ({ input, connectors }) => {
+      const found = connectors.tasks.search_tasks({ query: input.query });
+      return { matches: found.matches };
+    },
+  }),
+  tool('complete_task', {
+    description: 'Mark a task complete by its id (get the id from find_tasks).',
+    input: z.object({ id: z.string() }),
+    output: z.object({ ok: z.boolean() }),
+    fulfil: ({ input, connectors }) => {
+      const result = connectors.tasks.close_task({ id: input.id });
+      return { ok: result.ok };
+    },
+  }),
+]);
+```
+
+The model never sees a task id from the user; `find_tasks` returns `{ id, title }` summaries it can pick from, then `complete_task` acts by id. Keep write actions (`complete_task`) separate and explicitly described so the host can gate them.
+
+## Title and annotations
+
+Every model-visible tool needs a `title` — the action name hosts show in tool pickers and confirmation prompts — and `annotations`. `annotations.readOnly()` is a closed-world safe read; `annotations.action()` affects the world; `annotations.localAction()` affects only this app's data; `annotations.openAction()` reaches the open internet. Keep reads and writes in separate tools: one tool that both lists and mutates cannot be annotated honestly, so no host can gate it correctly. Missing titles and hints are also the most common consumer-directory rejection.
+
+## Bound every output
+
+Always declare `output`. Without it the model has to parse prose and hosts have no structured result to render. Then bound any list: cap the array with `z.array(item).max(50)`, or take a bounded pagination input (`limit`, `cursor`). An unbounded list either exhausts the context window or is truncated somewhere you do not control. Map the response to the few labelled fields the model needs, never the raw upstream payload — every field you pass through is context paid for on every later turn.
+
+## Keep the tool surface small
+
+`noodle check` warns above 20 model-visible tools. That is a documented heuristic, not a host limit: no host publishes a hard number, and the real threshold depends on how distinct your descriptions are. Collapse variants that differ only by a filter into one intent-shaped tool with a typed enum, and mark widget-only helpers `visibility: ['app']` so they stay callable from the app surface without entering the model's list.
+
+## Provision context deliberately
+
+Most “the model guessed wrong” bugs are missing context, not a missing tool. Every invocation already carries a server-authoritative instant plus locale and time zone, so never ask the model for today's date. Set `server(..., { context: { defaults: { locale, timeZone } } })` for ambient defaults, and mark one zero-input tool `contextProvider: true` when the model needs portable application context such as workspace, plan, or permissions. `references/authoring-workflow.md` owns the full invocation-context contract.
+
+## Errors an agent can act on
+
+An agent cannot recover from “Request failed”. Say which argument was wrong, which tool resolves it, and whether retrying helps. Error text is part of the tool interface and is read far more often by a model than by a human.
+
+## What `noodle check` reports
+
+- `tool_design_titles` — a model-visible tool has no `title`.
+- `tool_design_output_shape` — a model-visible tool has no `output` schema.
+- `tool_design_output_bounds` — an output array has no `maxItems` and the tool takes no pagination input.
+- `tool_design_surface_budget` — more than 20 model-visible tools.
+- `tool_design_context` — which tool provides application context (informational).
+
+All five are warnings, never failures, so they never change the exit code. Use `noodle check --min-severity warn` to see only what needs fixing and `noodle check --json` to consume them programmatically.

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

@@ -3,11 +3,11 @@ 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 -->
+<!-- noodle-skill version:0.43.0 hash:0f404109f4845683 -->
 
 # reporting-noodle-feedback
 
-Offer one sanitized feedback command and submit it only after informed explicit approval.
+Preview one sanitized feedback proposal and submit it once only after informed explicit approval.
 
 ## Use when
 
@@ -23,7 +23,7 @@ Offer one sanitized feedback command and submit it only after informed explicit
 
 - One distinct finding.
 - Sanitized observed and expected behavior.
-- User approval for the exact command.
+- User approval for the exact dry-run preview and live command.
 
 ## Workflow
 
@@ -31,15 +31,15 @@ Read and follow the canonical playbook `references/feedback.md` at `../noodle-se
 
 ## Verification evidence
 
-The user saw the exact sanitized command; only a returned reference proves submission.
+The user saw the exact sanitized preview, diagnostics, destination, and live 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.
+If login or rate limits block the one live submission, report that nothing was sent. A recording failure has an unknown outcome: report no reference and never auto-login or retry-loop.
 
 ## Stop conditions
 
-Stop before running the command until the user explicitly approves it.
+Stop after the local dry-run and before the live command until the user explicitly approves it.
 
 ## Handoff contract
 

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.41.0 hash:6ef6ef551e26b78e -->
+<!-- noodle-skill version:0.43.0 hash:6ef6ef551e26b78e -->
 
 # verifying-mcp-delivery