@noodleseed/agent-kit 0.34.0 → 0.36.0

package/skills/codex/examples/gmail-multi-account/test/server.test.ts

@@ -0,0 +1,271 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import {
+  compileManifest,
+  InMemoryCatalog,
+  validateJsonSchemaWithDefaults,
+} from '../../../packages/compiler/src/index.js';
+import { compileConnectors } from '../../../packages/connector-defs/src/index.js';
+import {
+  type CredentialBroker,
+  type CredentialRequest,
+  type DownstreamCredential,
+  executePreparedTool,
+  executeTool,
+  InMemoryConnectorRegistry,
+  isConfirmationRequired,
+  prepareToolForConfirmation,
+} from '../../../packages/runtime/src/index.js';
+import app, { PERSONAL_ACCOUNT, WORK_ACCOUNT } from '../src/server.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+async function compiledFixture() {
+  const catalog = structuredClone(app.toConnectorCatalog());
+  if (catalog === undefined) throw new Error('expected connector catalog');
+  for (const connector of catalog.connectors) {
+    if ('http' in connector) {
+      for (const [name, operation] of Object.entries(connector.operations)) {
+        operation.fake = {
+          response: {
+            id: `${name}-fixture`,
+            messages: [{ id: `${name}-message` }],
+            drafts: [{ id: `${name}-draft` }],
+          },
+        };
+      }
+    }
+  }
+  const connectors = compileConnectors(JSON.stringify(catalog), { mode: 'fake' });
+  if (!connectors.ok) throw new Error(JSON.stringify(connectors.errors));
+  const manifest = await app.toManifest();
+  const compiled = compileManifest(manifest, {
+    catalog: new InMemoryCatalog(connectors.catalog),
+  });
+  if (!compiled.ok) throw new Error(JSON.stringify(compiled.errors));
+  const requests: CredentialRequest[] = [];
+  const broker: CredentialBroker = {
+    getCredential(request): Promise<DownstreamCredential> {
+      requests.push(request);
+      return Promise.resolve({ token: `${request.bindingId}-fixture-token` });
+    },
+  };
+  return {
+    artifact: compiled.artifact,
+    deps: { connectors: new InMemoryConnectorRegistry(connectors.connectors), broker },
+    requests,
+  };
+}
+
+describe('multi-account Gmail flagship', () => {
+  it('binds the same curated connector twice without provider ids, credentials, or real labels', async () => {
+    const manifest = await app.toManifest();
+    expect(manifest.connectors).toMatchObject({
+      personal_gmail: {
+        id: 'gmail',
+        binding: {
+          profile: 'user_oauth',
+          connection: { id: 'personal_gmail', source: { kind: 'externalExchange' } },
+        },
+      },
+      work_gmail: {
+        id: 'gmail',
+        binding: {
+          profile: 'user_oauth',
+          connection: { id: 'work_gmail', source: { kind: 'externalExchange' } },
+        },
+      },
+    });
+    const wire = JSON.stringify({ manifest, catalog: app.toConnectorCatalog() });
+    expect(wire).not.toMatch(/access[_-]?token|client[_-]?secret/i);
+  });
+
+  it('emits enforceable canonical account arrays on every tool', async () => {
+    const manifest = await app.toManifest();
+    for (const tool of manifest.tools) {
+      expect(tool.inputSchema.properties).toHaveProperty('accounts');
+      expect(JSON.stringify(tool.inputSchema.properties.accounts)).toContain(PERSONAL_ACCOUNT);
+      expect(JSON.stringify(tool.inputSchema.properties.accounts)).toContain(WORK_ACCOUNT);
+    }
+    const read = manifest.tools.find((tool) => tool.name === 'search_messages');
+    const write = manifest.tools.find((tool) => tool.name === 'trash_message');
+    const readAccountsSchema = JSON.stringify(read?.inputSchema.properties.accounts);
+    const writeAccountsSchema = JSON.stringify(write?.inputSchema.properties.accounts);
+    expect(readAccountsSchema).toContain(PERSONAL_ACCOUNT);
+    expect(readAccountsSchema).toContain(WORK_ACCOUNT);
+    expect(readAccountsSchema).toContain('"maxItems":2');
+    expect(writeAccountsSchema).not.toContain('"maxItems":2');
+  });
+
+  it('allows subject-only or plain-body-only vacation replies but rejects an empty enabled reply', async () => {
+    const manifest = await app.toManifest();
+    const schema = manifest.tools.find((tool) => tool.name === 'update_vacation')?.inputSchema;
+    if (schema === undefined) throw new Error('expected update_vacation schema');
+    const base = { accounts: [PERSONAL_ACCOUNT], settings: { enable_auto_reply: true } };
+
+    expect(
+      validateJsonSchemaWithDefaults(schema, {
+        ...base,
+        settings: { ...base.settings, response_subject: 'Away' },
+      }).issues,
+    ).toHaveLength(0);
+    expect(
+      validateJsonSchemaWithDefaults(schema, {
+        ...base,
+        settings: { ...base.settings, response_body_plain_text: 'Back soon' },
+      }).issues,
+    ).toHaveLength(0);
+    expect(validateJsonSchemaWithDefaults(schema, base).issues).not.toHaveLength(0);
+  });
+
+  it.each([
+    [],
+    ['unknown@example.com'],
+    [PERSONAL_ACCOUNT, PERSONAL_ACCOUNT],
+    [WORK_ACCOUNT, PERSONAL_ACCOUNT],
+  ])('rejects invalid read accounts %j before connector dispatch', async (accounts) => {
+    const setup = await compiledFixture();
+    const schema = setup.artifact.tools.find(
+      (candidate) => candidate.name === 'search_messages',
+    )?.inputSchema;
+    if (!schema) throw new Error('expected search schema');
+    const result = validateJsonSchemaWithDefaults(schema, { accounts, query: '' });
+    expect(result.issues).not.toHaveLength(0);
+    expect(setup.requests).toHaveLength(0);
+  });
+
+  it('rejects multi-account mutations at the write schema boundary', async () => {
+    const setup = await compiledFixture();
+    const schema = setup.artifact.tools.find(
+      (candidate) => candidate.name === 'trash_message',
+    )?.inputSchema;
+    if (!schema) throw new Error('expected trash schema');
+
+    const result = validateJsonSchemaWithDefaults(schema, {
+      accounts: [PERSONAL_ACCOUNT, WORK_ACCOUNT],
+      message_id: 'fixture-message',
+    });
+
+    expect(result.issues).not.toHaveLength(0);
+    expect(setup.requests).toHaveLength(0);
+  });
+
+  it('rejects a no-op label mutation before confirmation or credential lookup', async () => {
+    const setup = await compiledFixture();
+
+    await expect(
+      prepareToolForConfirmation(
+        setup.artifact,
+        'modify_message_labels',
+        { accounts: [PERSONAL_ACCOUNT], message_id: 'fixture-message' },
+        setup.deps,
+      ),
+    ).resolves.toMatchObject({ status: 'failed', error: { code: 'arg_invalid' } });
+    expect(setup.requests).toHaveLength(0);
+  });
+
+  it('routes personal, work, and combined reads to isolated bindings and preserves account labels', async () => {
+    const personal = await compiledFixture();
+    const personalResult = await executeTool(
+      personal.artifact,
+      'search_messages',
+      { accounts: [PERSONAL_ACCOUNT], query: 'is:unread' },
+      personal.deps,
+    );
+    expect(personal.requests.flatMap((request) => request.bindingId ?? [])).toEqual([
+      'personal_gmail',
+    ]);
+    expect(personalResult).toMatchObject({
+      ok: true,
+      output: { results: [{ account: PERSONAL_ACCOUNT }] },
+    });
+
+    const work = await compiledFixture();
+    const workResult = await executeTool(
+      work.artifact,
+      'search_messages',
+      { accounts: [WORK_ACCOUNT], query: 'is:unread' },
+      work.deps,
+    );
+    expect(work.requests.flatMap((request) => request.bindingId ?? [])).toEqual(['work_gmail']);
+    expect(workResult).toMatchObject({
+      ok: true,
+      output: { results: [{ account: WORK_ACCOUNT }] },
+    });
+
+    const both = await compiledFixture();
+    const bothResult = await executeTool(
+      both.artifact,
+      'search_messages',
+      { accounts: [PERSONAL_ACCOUNT, WORK_ACCOUNT], query: 'is:unread' },
+      both.deps,
+    );
+    expect(both.requests.flatMap((request) => request.bindingId ?? [])).toEqual([
+      'personal_gmail',
+      'work_gmail',
+    ]);
+    expect(bothResult).toMatchObject({
+      ok: true,
+      output: {
+        results: [{ account: PERSONAL_ACCOUNT }, { account: WORK_ACCOUNT }],
+      },
+    });
+  });
+
+  it('prepares the exact selected write binding, dispatches only after confirmation, and rejects replay drift', async () => {
+    const setup = await compiledFixture();
+    const prepared = await prepareToolForConfirmation(
+      setup.artifact,
+      'trash_message',
+      { accounts: [WORK_ACCOUNT], message_id: 'fixture-message' },
+      setup.deps,
+    );
+    expect(isConfirmationRequired(prepared)).toBe(true);
+    if (!isConfirmationRequired(prepared)) throw new Error('expected confirmation');
+    expect(setup.requests).toHaveLength(0);
+    expect(prepared.review.action).toMatchObject({
+      bindingId: 'work_gmail',
+      connectionId: 'work_gmail',
+      operation: 'trash_message',
+    });
+
+    await expect(
+      executePreparedTool(setup.artifact, prepared.continuation, setup.deps),
+    ).resolves.toMatchObject({ status: 'completed' });
+    expect(setup.requests.flatMap((request) => request.bindingId ?? [])).toEqual(['work_gmail']);
+
+    const personalPrepared = structuredClone(prepared.continuation);
+    if (personalPrepared.reviewedAction) {
+      (personalPrepared.reviewedAction as { bindingId?: string }).bindingId = 'personal_gmail';
+    }
+    await expect(
+      executePreparedTool(setup.artifact, personalPrepared, setup.deps),
+    ).resolves.toMatchObject({ status: 'failed' });
+  });
+
+  it('makes every mutation confirmable and keeps the personal-email skill concise and safe', async () => {
+    const manifest = await app.toManifest();
+    const catalog = app.toConnectorCatalog();
+    const actionNames = new Set(
+      catalog?.connectors.flatMap((connector) =>
+        Object.entries(connector.operations)
+          .filter(([, operation]) => operation.type === 'action')
+          .map(([name]) => name),
+      ),
+    );
+    for (const tool of manifest.tools.filter((candidate) => actionNames.has(candidate.name))) {
+      expect(tool.annotations?.confirm, tool.name).toBe(true);
+    }
+
+    const skill = readFileSync(join(here, '../skills/personal-email-automation/SKILL.md'), 'utf8');
+    expect(skill).toMatch(/^---\nname: personal-email-automation\ndescription:/);
+    expect(skill.split('\n').length).toBeLessThan(140);
+    expect(skill).toContain('accounts');
+    expect(skill).toMatch(/draft/i);
+    expect(skill).toMatch(/confirm/i);
+    expect(skill).toMatch(/permanent delete/i);
+    expect(skill).not.toMatch(/client[_-]?secret|access[_-]?token/i);
+  });
+});

package/skills/codex/examples/gmail-multi-account/vitest.config.ts

@@ -0,0 +1,28 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@noodleseed/one': new URL('../../packages/authoring/src/index.ts', import.meta.url).pathname,
+      '@noodle-borg/capabilities': new URL(
+        '../../packages/capabilities/src/index.ts',
+        import.meta.url,
+      ).pathname,
+      '@noodle-borg/compiler': new URL('../../packages/compiler/src/index.ts', import.meta.url)
+        .pathname,
+      '@noodle-borg/compute': new URL('../../packages/compute/src/index.ts', import.meta.url)
+        .pathname,
+      '@noodle-borg/connector-defs': new URL(
+        '../../packages/connector-defs/src/index.ts',
+        import.meta.url,
+      ).pathname,
+      '@noodle-borg/connector-http': new URL(
+        '../../packages/connector-http/src/index.ts',
+        import.meta.url,
+      ).pathname,
+      '@noodle-borg/runtime': new URL('../../packages/runtime/src/index.ts', import.meta.url)
+        .pathname,
+    },
+  },
+  test: { include: ['test/**/*.test.ts'] },
+});

package/skills/codex/references/app-directory-compliance.md

@@ -0,0 +1,59 @@
+# App directory compliance (pre-submission)
+
+Use this shared checklist against the built integration before preparing a directory submission. It
+covers evidence common to app and connector directories without assuming a particular host, review
+portal, client framework, or vendor policy.
+
+## Contents
+
+- Validation evidence
+- Capability and interaction quality
+- Safety, privacy, and data handling
+- Reliability and accessibility
+- Directory-specific delta
+
+## Validation evidence
+
+A clean local validation result proves only the checks that actually ran. Record server validation,
+behavior tests, protocol conformance, production reachability, and interactive rendering as separate
+evidence levels. Never treat metadata readiness as proof of host rendering or directory acceptance.
+
+## Capability and interaction quality
+
+1. **User value** — each exposed capability solves a concrete user job and cites built behavior rather
+   than an aspiration.
+2. **Grounded capability** — knowledge, actions, and presentation come from authoritative application
+   data or bounded operations instead of invented state.
+3. **Atomic interfaces** — every action has a focused purpose, explicit input and output schemas, honest
+   effect annotations, and useful failure output.
+4. **Helpful UI only** — every interactive surface earns its place and preserves a useful text or
+   structured fallback when rendering is unavailable.
+5. **Meaningful completion** — the user can complete the promised task within the declared boundary,
+   with any external handoff clearly identified.
+
+## Safety, privacy, and data handling
+
+- Minimize model-visible and UI-visible data; remove secrets, internal identifiers, unnecessary personal
+  data, and continuation credentials from results and logs.
+- Document authentication, authorization scopes, retention, deletion, subprocessors, and external
+  handoffs accurately in the public privacy and support material.
+- Make mutations explicit, bounded, and confirmation-aware. Never imply that a read or preparation
+  request authorizes a write.
+- For regulated or consequential workflows, show source provenance, uncertainty, cautions, and the
+  boundary between information and a professional decision.
+
+## Reliability and accessibility
+
+- Exercise representative positive, negative, empty, loading, error, and recovery cases against the
+  production-shaped endpoint.
+- Preserve keyboard access, readable contrast, responsive layout, concise status feedback, and graceful
+  degradation when an interactive surface is unsupported.
+- State latency, availability, rate-limit, and support expectations using observed evidence rather than
+  unverified claims.
+
+## Directory-specific delta
+
+After the shared checklist passes, read the selected directory’s current official documentation and add
+only its verified requirements. Keep directory-specific metadata, screenshots, test accounts, policy
+statements, and review procedures in that submission evidence—not in this shared skill reference. Mark
+unknown or untested requirements explicitly, and never reuse another directory’s checklist as a proxy.

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

@@ -41,6 +41,8 @@ Tools record connector calls into a flow; recording is not execution. Do not bra
 
 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. `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.
+
 ## HTTP connector example (full server)
 
 Declare the API as data, bind it with `use`, then record calls in tools. The operation mapping in detail: `request` builds the JSON request body, `query: [...]` names the input args sent as URL query parameters, and `response` maps the parsed HTTP body (bound to `${response}`) into your typed `output`. `auth` reads a managed `secret(...)` — never inline a key. This whole example is compile-verified on every `pnpm test`.
@@ -273,7 +275,7 @@ tool('prepare_time_off', {
 });
 ```
 
-Use a stable lowercase/number/underscore id and a flat form of string/number/integer/boolean, string choices or multi-select, with optional `email`, `uri`, `date`, or `date-time` formats. Nested objects and credential-shaped fields fail with `invalid_elicitation_schema`. Every interactive flow must place all `ctx.elicit` calls before its first connector operation or compilation fails with `invalid_elicitation_flow`. Embedded/headless clients receive `input_requested`; bidirectional MCP transports map the primitive to standard form `elicitation/create`. On stateless hosts, the adapter returns a structured non-executing `interaction_unavailable` result; linked Apps render its business-user form and retry in request `_meta`, while models can use the advertised reserved retry field. Accept validates and replays only the operation-free input prefix; invalid content returns `arg_invalid`, and decline/cancel stop. Elicitation gathers missing input and does not replace confirmation. In a flow marked `confirm: true`, every eligible `input_requested` precedes `tool_proposed`; the final proposal reviews the original input, elicited values, and sole exact connector action. Accept is bound to that action and only then may execution start. A confirmable flow may contain at most one connector operation; additional operations fail with `invalid_confirmation_flow`. MCP uses final standard form confirmation on capable bidirectional transports and fails closed otherwise. Setting `interactions: { confirmationFallback: "host" }` in the server options explicitly trusts native host approval only when confirmation transport is unavailable and after every elicited field is collected; it is never inferred from client name and does not replace authorization. Omitted or `false` annotations execute directly; hints alone never gate. `annotations.action({ confirm: true })` explicitly enables confirmation; `annotations.action({ confirm: false })` explicitly preserves direct execution.
+Use a stable lowercase/number/underscore id and a flat form of string/number/integer/boolean, string choices or multi-select, with optional `email`, `uri`, `date`, or `date-time` formats. Nested objects and credential-shaped fields fail with `invalid_elicitation_schema`. Every interactive flow must place all `ctx.elicit` calls before its first connector operation or compilation fails with `invalid_elicitation_flow`. Embedded/headless clients receive `input_requested`; bidirectional MCP transports map the primitive to standard form `elicitation/create`. On stateless hosts, the adapter returns a structured non-executing `interaction_unavailable` result; linked Apps render its business-user form and retry in request `_meta`, while models can use the advertised reserved retry field. Accept validates and replays only the operation-free input prefix; invalid content returns `arg_invalid`, and decline/cancel stop. Elicitation gathers missing input and does not replace confirmation. In a flow marked `confirm: true`, every eligible `input_requested` precedes `tool_proposed`; the final proposal reviews the original input, elicited values, and sole exact eligible connector action. Conditional branches may declare multiple candidate actions only when preparation resolves exactly one eligible action from input/context or completed pure steps; zero or multiple actions fail with `invalid_confirmation_flow` before I/O. Acceptance is bound to that exact action. Later read-only operations and pure compute may assemble output, but a second eligible action fails closed. Use `ref.at(index)` for array access in recorded expressions. MCP uses final standard form confirmation on capable bidirectional transports and fails closed otherwise. Setting `interactions: { confirmationFallback: "host" }` in the server options explicitly trusts native host approval only when confirmation transport is unavailable and after every elicited field is collected; it still uses preparation and prepared execution, is never inferred from client name, and does not replace authorization. Omitted or `false` annotations execute directly; hints alone never gate. `annotations.action({ confirm: true })` explicitly enables confirmation; `annotations.action({ confirm: false })` explicitly preserves direct execution.
 
 ## Compute connector example
 

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

@@ -0,0 +1,52 @@
+# Outcome
+
+Deliver an MCP App whose visual interaction gives the user a concrete benefit beyond a good text response, while preserving useful model-visible output when the widget is unavailable.
+
+## Use when
+
+- The user asks for an MCP App, widget, interactive card, visual workflow, or host-visible UI.
+- Comparison, selection, progress, editing, confirmation, or another visual interaction materially improves the conversational job.
+
+## Do not use when
+
+- A concise text or structured tool result fully serves the user. UI must earn its place.
+- The requested task is a headless server, API connector, diagnosis, deployment, or publication with no UI change; select that route.
+- The agent lacks the product inputs needed to explain who benefits, what action the UI enables, and what happens without it.
+
+## Required inputs
+
+Before implementation, capture a short design spec: target user, conversational job, explicit user benefit, information hierarchy, primary interaction, states (loading/empty/error/success), model-visible result, widget-only data, and useful text fallback. Use `references/experience-design.md` for the deeper product-design questions only when needed.
+
+## Workflow
+
+1. **Pass the UI fit check.** State why a visual interaction is better than text for this request. If there is no defensible user benefit, keep the capability headless and stop the App route.
+2. **Agree on the design spec.** Describe the smallest complete experience and its states before writing the component. Avoid recreating a full dashboard or website inside the conversation.
+3. **Define the output boundary.** Keep concise facts and action results model-visible. Put presentation-heavy or interactive widget data in the widget-only channel. The model must not depend on opaque UI state to continue the conversation.
+4. **Preserve fallback.** Every tool that launches a widget must still return useful text without the widget, so unsupported hosts and failed rendering remain usable.
+5. **Author and wire the App contract.** Follow `references/widgets-and-apps.md` for the canonical component guidance, view registration, hooks, state, CSP, tool visibility, and output shaping. Keep tool effects and confirmation semantics correct independently of the UI.
+6. **Validate the local artifact.** Run `noodle validate --json`, `noodle test --json`, and `noodle check --json`. Repair failures at the layer that produced them.
+7. **Inspect the experience.** Run `noodle devtools` and verify loading, empty, error, success, responsive layout, focus/keyboard behavior, and the text fallback.
+8. **Escalate evidence only on request.** Run a host test only when the user requested host verification. Run host-specific compliance only when preparing that host submission; select the exact host-testing or compliance entry from the router lookup catalog only after that evidence level is explicitly requested.
+
+## Verification evidence
+
+- **Product:** the design spec states the user benefit and the UI fit decision.
+- **Server:** `noodle validate --json` and `noodle test --json` succeeded.
+- **App contract:** `noodle check --json` succeeded.
+- **Local UX:** `noodle devtools` exercised the relevant states and the useful text fallback without the widget.
+- **Host/compliance:** report each requested host or compliance check with its evidence; report every unperformed higher level as not run.
+
+## Recovery paths
+
+- Weak UI fit: remove the widget and ship the stronger headless result, or narrow the visual interaction to the one decision it improves.
+- App check failure: repair the cited view, metadata, output, CSP, or accessibility issue and rerun `noodle check --json` before reopening devtools.
+- Blank or stale widget: verify the tool returns the intended widget data, the view is registered, and state derives from supported hooks rather than hidden global state.
+- Model cannot continue without UI: move the essential facts into model-visible output and keep only presentation data widget-only.
+- Host-only mismatch: record local checks as passed, isolate the host symptom, and select the host-testing lookup only for that observed host; do not rewrite a working local contract without host evidence.
+
+## Stop conditions
+
+- Stop complete at the locally requested boundary when product fit, server tests, App checks, devtools states, and text fallback are evidenced.
+- Stop before host connection, deployment, or submission unless the user requested that next evidence level.
+- Stop blocked when the required design decision, external data, credentials, or host access is unavailable; name the missing input and the exact next action.
+- Never claim host compatibility, directory compliance, or production behavior from local devtools evidence alone.

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

@@ -0,0 +1,54 @@
+# Outcome
+
+Deliver the smallest useful Noodle Seed MCP server that turns a real user intent into a safe, typed result. Author only the configured TypeScript entrypoint, normally `src/server.ts`; keep the public authoring surface TypeScript-only and never hand-author generated manifests or connector IR.
+
+## Use when
+
+- The user asks to create or extend a headless MCP server, tools, resources, prompts, or connector-backed behavior.
+- The requested result is primarily model-facing and does not require a widget or host-visible UI.
+
+## Do not use when
+
+- The primary outcome is an MCP App, widget, or visual interaction; select the App route.
+- The task is only to diagnose existing failures, deploy, publish, embed, or report feedback; select that dedicated route.
+- The idea has no conversational fit: static content, a dashboard, deep navigation, or a full existing app port should be narrowed to the few actions that are better said than clicked.
+
+## Required inputs
+
+Establish only the inputs needed for the requested stopping point. Follow `references/authoring-workflow.md` for the canonical discovery paths. Do not guess or invent a private schema, endpoint, authentication model, eligibility rule, or approval flow. If a required input is unavailable, state exactly what evidence is missing and stop before fabricating behavior.
+
+## Workflow
+
+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.
+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.
+8. **Stop at the requested boundary.** Do not add an App, host test, hosted environment, publication work, or deployment unless the user requested that outcome. Deploy only when the selected route or the user explicitly requires it.
+
+## Verification evidence
+
+Report evidence as a ladder and claim only levels actually exercised:
+
+- **Authoring:** the requested TypeScript behavior exists with typed inputs and outputs.
+- **Compilation:** `noodle validate --json` returned success.
+- **Local smoke:** `noodle test --json` returned success.
+- **Connector reality:** a representative safe read via `noodle tools call` returned populated mapped fields. This is required for connector-backed work.
+- **Higher levels:** explicitly report host, deployment, and production checks as not run unless they were separately requested and evidenced.
+
+## Recovery paths
+
+- Validation failure: fix each structured error at its reported path, rerun validation, then resume at the next unproven layer.
+- Tool registers but returns empty or `undefined` fields: inspect one sanitized real response, correct `${response...}` mappings, and rerun the same read.
+- Credential unavailable: verify `secret(...)` naming and the effective local target; never inline or print the secret.
+- Missing product input: ask for the smallest concrete example, schema, or rule that unblocks the selected job. Do not widen the build to compensate.
+- Repeated failure at the same layer: stop after two evidence-backed repair attempts with the same failure signature and report the command, sanitized error, evidence already proven, and exact next action.
+
+## Stop conditions
+
+- Stop complete when the requested behavior passes validation and local smoke, and every connector-backed read has real-output evidence.
+- Stop at the user's requested boundary; do not deploy unless the user requested deployment.
+- Stop blocked when progress requires unavailable credentials, private schemas, external approval, or a live write the user has not approved.
+- In the handoff, name what changed, what passed, what was not run, and any remaining risk without upgrading local evidence into a hosted or production claim.

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

@@ -59,5 +59,9 @@ Run `noodle validate` (add `--json` for the machine-readable envelope, `--fix-pr
 | `unknown_connector_alias` | The tool calls a connector alias not declared in `use`/`provides`; add it or fix the alias (see `suggestions`). |
 | `connector_not_in_catalog` | The referenced connector is not in the resolved catalog; add it to the project connectors or correct the reference. |
 | `unknown_operation` | The connector has no such operation; use an operation declared on that connector (see `didYouMean`/`suggestions`). |
+| `connector_binding_required` | Bind the connector alias with `bind(connector, { profile, connection })`; credential-requiring operations cannot use an unbound alias. |
+| `unsupported_credential_profile` | Select a credential profile declared by the connector and accepted by the operation; use the reported suggestions instead of inventing a profile name. |
+| `credential_scope_mismatch` | Declare a connection source whose scopes include every operation-required scope, or select an external exchange provider that can mint them. |
+| `credential_audience_mismatch` | Set the connection source audience to the operation-required audience exactly, or use an external exchange provider that can mint it. |
 | `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`. |