@ductape/mcp 0.2.37 → 0.3.1

package/dist/action-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-contract.d.ts","sourceRoot":"","sources":["../src/action-contract.ts"],"names":[],"mappings":"AAiFA,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAYnE"}
+{"version":3,"file":"action-contract.d.ts","sourceRoot":"","sources":["../src/action-contract.ts"],"names":[],"mappings":"AAoFA,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAYnE"}

package/dist/action-contract.js

@@ -61,8 +61,11 @@ function schemaFromLocation(value) {
             property.description = String(item.description);
         if (item.sampleValue !== undefined && item.sampleValue !== '')
             property.example = item.sampleValue;
+        const defaultValue = item.defaultValue ?? item.default_value ?? item.default ?? item.value;
+        if (defaultValue !== undefined && defaultValue !== '')
+            property.default = defaultValue;
         properties[key] = property;
-        if (item.required === true)
+        if (item.required === true || String(item.required).toLowerCase() === 'true')
             required.push(key);
     }
     for (const row of legacyRows) {
@@ -77,6 +80,7 @@ function schemaFromLocation(value) {
             type: 'string',
             ...(description ? { description } : {}),
             ...(item.value !== undefined ? { example: item.value } : {}),
+            ...(item.value !== undefined && item.value !== '' ? { default: item.value } : {}),
         };
         if (/\(required\)|^required\b/i.test(description))
             required.push(key);

package/dist/index.js

@@ -16,6 +16,7 @@ import { homedir } from 'os';
 import { delimiter, join } from 'path';
 import { z } from 'zod';
 import { normalizeLiveActionContract } from './action-contract.js';
+import { runtimeInputRecovery } from './runtime-recovery.js';
 import { executeViaProxy, generateExecutablePayload, getAssetSchemas, } from './proxy-client.js';
 import { EVENTS_DELIVERY_SEMANTICS, EVENTS_IMPLEMENTATION_WARNING, eventsCapabilityOverview, inspectEventsComponent, searchEventsCapabilities, } from './events-capabilities.js';
 const MODULES = [
@@ -1355,7 +1356,7 @@ const ductape = new Ductape({
   product: String(payload.product),
   env: String(payload.env),
   redis_url: process.env.DUCTAPE_REDIS_URL,
-  runtime_sync: { interval_ms: 30_000, jitter: 0.2 },
+  runtime_sync: { interval_ms: 30_000, jitter: 0.2, warm_connections: true },
 });
 
 async function run() {
@@ -2564,7 +2565,7 @@ and env, then await ready() before accepting work:
     accessKey: process.env.DUCTAPE_ACCESS_KEY!,
     product: "payments",
     env: "prd",
-    runtime_sync: { interval_ms: 30_000, jitter: 0.2, max_backoff_ms: 300_000 },
+  runtime_sync: { interval_ms: 30_000, jitter: 0.2, max_backoff_ms: 300_000, warm_connections: true },
   });
   await ductape.ready();
 
@@ -2579,7 +2580,10 @@ Runtime synchronization is automatic when product + env are supplied:
     assetRevision are narrower change hints. Any databaseRevision change also changes runtimeRevision.
   - A changed snapshot is loaded off-path and atomically replaces cache entries. Deleted assets are removed.
   - Refresh failure retains the last-known-good snapshot and retries with jittered exponential backoff.
-  - Use runtimeSnapshotStatus() for revision/error telemetry and refreshRuntime() for an explicit pull.
+  - await ready() before accepting traffic. It now waits for the initial snapshot and database pool
+    warm-up, so first Feature/Database execution does not absorb MongoDB TLS/pool establishment.
+  - runtime_sync.warm_connections defaults to true; disable it only when lazy connections are intentional.
+  - Use runtimeSnapshotStatus() for revision/error/warm-up phase telemetry and refreshRuntime() for an explicit pull.
   - Call close() during process shutdown. Do not create one Ductape instance per request.
 
 For NestJS, use DuctapeModule.forIntegration({ accessKey, product, env, runtimeSync }) instead of
@@ -3224,6 +3228,22 @@ Action input — flat input format:
     input: { "headers:X-Idempotency-Key": "..." } → request header
   Always use ductape_generate_payload or actions.fetch to know the exact field names — never guess.
 
+UNIVERSAL HTTP 400 / MISSING-INPUT SELF-HEALING:
+  This applies equally to actions.run, a Feature API step, a Quota option, and every Fallback provider.
+  The outer component does not hide or replace the referenced App Action contract.
+  1. Do not retry an unchanged payload and never invent the missing value.
+  2. Read the deepest provider error and identify app, action, field, and body/query/params/headers location.
+  3. MUST call ductape_schema({ product_tag, env_slug, app_tag, action_tag }) for each failing action.
+     For Feature/Quota/Fallback, fetch the outer component too, follow its step/option mapping, and
+     schema-check the referenced action that actually returned 400.
+  4. Compare every location separately. Restore schema defaults and required constant query values.
+     Use explicit input keys such as "query:type" when location is ambiguous.
+  5. If the action definition lost the required/default metadata, repair the canonical
+     ductape/actions/<app-tag>/<action-tag>.action.json and update the App Action via ductape_cli.
+     Do not hardcode a provider-specific workaround into one Feature, Quota, or Fallback.
+  6. Call ductape_generate_payload, validate it against the looked-up contract, and retry once.
+     If it still returns 400, stop and report the remaining provider/schema mismatch.
+
 Run an action at runtime:
   → CALL ductape_generate_payload FIRST (operation_family="action", method="run", targets={app, action})
   ductape_execute("actions.run", [{ product, env, app, action, input: { "body:field": value } }])
@@ -3333,7 +3353,9 @@ Product structure (IProduct fields):
 
 Bootstrap (single API call returning product context + component config + private key):
   Initialize @ductape/sdk with product + env and await ductape.ready(). It fetches the full
-  environment-scoped product runtime snapshot and primes BootstrapCache for connected App actions
+  runtime snapshot and warms its database connection pools before the process is marked ready. Do
+  not start the HTTP server or worker consumer before ready() resolves. The environment-scoped
+  snapshot primes BootstrapCache for connected App actions
   and product components. A service falls back to its targeted bootstrap endpoint only when the
   requested asset is absent. Polling uses ETag/304 and atomically refreshes changed state.
   See ductape_docs({ topic: "runtime-sync" }).
@@ -3687,7 +3709,7 @@ QUOTAS — weighted/provider-capacity routing pools (NOT request rate limiting):
     input: { to: { type: "string", required: true }, message: { type: "string" } },
     options: [
       { provider: "twilio", app: "twilio-app", type: "action", event: "send-sms",
-        quota: 1000, uses: 0, retries: 2,
+        quota: 1000, uses: 0, retries: 2, health: "twilio-health",
         input: { "body:to": "$Input{to}", "body:message": "$Input{message}" },
         output: {} },
       { provider: "nexmo", app: "nexmo-app", type: "action", event: "send-sms",
@@ -3709,13 +3731,54 @@ FALLBACKS — automatic provider switching on failure:
   fallback.run      [{ product, env, tag, input }]  ← CALL ductape_generate_payload FIRST
   fallback.dispatch [{ product, env, tag, input, schedule? }]
 
+HEALTH-GATED PROVIDERS — REQUIRED BEHAVIOR:
+  Provider options may declare health: "<healthcheck-tag>". healthcheck is a deprecated input alias;
+  generate health in new JSON and code. Before creating a quota/fallback, list the product's existing
+  healthchecks and reuse one whose probe targets the same app/resource and operation. Create a new
+  healthcheck only when no equivalent check exists. Verify the referenced tag exists in the same
+  product and covers every environment used by the quota/fallback.
+
+  This is an active prerequisite, not optional advice. When creating or updating a quota/fallback:
+  1. List existing healthchecks and connected product providers.
+  2. Match each provider to an existing check by probe type + provider asset/app + safe probe event.
+  3. For every unmatched provider, inspect its live action/resource schema, choose a repeat-safe probe,
+     write ductape/healthchecks/<tag>.json, and run: ductape resources health create --tag <product>
+     -f ductape/healthchecks/<tag>.json --json.
+  4. Fetch and explicitly run each newly-created check in every target environment. Do not create the
+     quota/fallback until the probe schema and status lookup both succeed.
+  5. Put health: "<verified-healthcheck-tag>" on every provider option, then create/update and refetch
+     the quota/fallback. A provider without a verified health tag is an incomplete resilience asset.
+  If no safe repeatable probe exists, stop and explain the blocker; never invent an endpoint or omit
+  health silently.
+
+  Runtime contract:
+  - Read the linked health status before provider selection.
+  - Never select a provider whose linked status is unavailable, even when every provider is down.
+    Return NO_HEALTHY_PROVIDERS/NO_PROVIDERS_AVAILABLE instead of forcing traffic through it.
+  - When a selected provider exhausts its bounded retries, immediately mark the linked healthcheck
+    unavailable. The current fallback or quota invocation must immediately continue/reselect from
+    the remaining healthy options; subsequent invocations must also skip it. Never wait for the
+    health poll before performing local failover.
+  - Runtime success does not close the circuit. Only a successful scheduled or explicit health probe
+    restores available, preventing one opportunistic request from bypassing recovery validation.
+  - One global Tickets-hosted scheduler is the fallback runner when no fresh local SDK monitor result
+    exists. Do not require application code to call monitor() for platform healthchecks to run.
+  - Remote and local runtimes share health through the product's centrally persisted health state,
+    not through a common Redis instance. SDK runtime-manifest polling compares healthRevision and
+    atomically refreshes an in-process health snapshot in the background. Quota/fallback routing uses
+    synchronous snapshot reads; never add a bootstrap, Redis, or backend lookup to the invocation path.
+    A local provider failure trips the in-process state immediately and persists it asynchronously so
+    other instances receive it on their next lightweight poll.
+  - A transition from available to unavailable sends one alert to accepted workspace participants;
+    repeated unhealthy probe results must not generate duplicate transition emails.
+
 HEALTHCHECKS — continuous probe with failure notifications:
-  Scheduled probes have a platform-owned fallback runner in the Ductape proxy. A local SDK monitor
-  may also run them: while it consistently persists a fresh lastChecked record, the proxy defers
-  that product/env/check. The proxy freshness window accounts for the SDK's batched backend status
+  Scheduled probes have a platform-owned global fallback runner in the Ductape Tickets service. A local SDK monitor
+  may also run them: while it consistently persists a fresh lastChecked record, the global worker defers
+  that product/env/check. The server freshness window accounts for the SDK's batched backend status
   flush (currently five minutes), not only the shorter probe interval. If records stop arriving and
-  the freshness window expires, the proxy automatically takes over. Do not instruct users to
-  disable the proxy fallback when using a local monitor.
+  the freshness window expires, the global worker automatically takes over. Do not instruct users to
+  disable the server fallback when using a local monitor.
 
   Workbench definition shape:
   {
@@ -4673,7 +4736,7 @@ Import (register an EXISTING cloud resource):
       product: "my-product",
       env: "prd",
       redis_url: process.env.DUCTAPE_REDIS_URL,  // required for any dispatch(); omit only if never dispatching
-      runtime_sync: { interval_ms: 30_000, jitter: 0.2 },
+      runtime_sync: { interval_ms: 30_000, jitter: 0.2, warm_connections: true },
     });
     await ductape.ready();
     await ductape.events.produce({
@@ -6329,7 +6392,15 @@ async function main() {
                     'Enable it in Workbench → Tokens → Publishable Key. ' +
                     'If write access cannot be granted to the publishable key, perform this operation server-side using a full Ductape SDK instance initialized with an access key.';
             }
-            return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+            const recovery = runtimeInputRecovery(message, {
+                module: args.module,
+                method: args.method,
+                params: args.params,
+            });
+            const text = recovery
+                ? JSON.stringify({ error: message, recovery }, null, 2)
+                : `Error: ${message}`;
+            return { content: [{ type: 'text', text }], isError: true };
         }
     };
     const payloadGenerateHandler = async (args) => {

package/dist/runtime-recovery.d.ts

@@ -0,0 +1,9 @@
+type RuntimeContext = {
+    module: string;
+    method: string;
+    params: unknown[];
+};
+export declare function isRepairableClientInputError(message: string): boolean;
+export declare function runtimeInputRecovery(message: string, context: RuntimeContext): Record<string, unknown> | null;
+export {};
+//# sourceMappingURL=runtime-recovery.d.ts.map

package/dist/runtime-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-recovery.d.ts","sourceRoot":"","sources":["../src/runtime-recovery.ts"],"names":[],"mappings":"AAAA,KAAK,cAAc,GAAG;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB,CAAC;AAeF,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAErE;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAkC7G"}

package/dist/runtime-recovery.js

@@ -0,0 +1,53 @@
+function visit(value, found) {
+    if (!value || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        value.forEach((item) => visit(item, found));
+        return;
+    }
+    const record = value;
+    const app = String(record.app ?? record.provider ?? '').trim();
+    const action = String(record.action ?? record.event ?? '').trim();
+    if (app && action)
+        found.set(`${app}:${action}`, { app, action });
+    Object.values(record).forEach((item) => visit(item, found));
+}
+export function isRepairableClientInputError(message) {
+    return /(?:status(?: code)?\s*400|http\s*400|err_bad_request|bad request|\bis required\b|required field|missing (?:input|field|parameter|value)|invalid (?:input|payload|parameter|payment type)|validation (?:error|failed))/i.test(message);
+}
+export function runtimeInputRecovery(message, context) {
+    if (!isRepairableClientInputError(message))
+        return null;
+    const actions = new Map();
+    visit(context.params, actions);
+    const appMatches = [...message.matchAll(/(?:app|provider)["'\s:=]+([\w:.-]+)/gi)].map((match) => match[1]);
+    const actionMatches = [...message.matchAll(/(?:action|event)["'\s:=]+([\w.-]+)/gi)].map((match) => match[1]);
+    for (const app of appMatches)
+        for (const action of actionMatches)
+            actions.set(`${app}:${action}`, { app, action });
+    return {
+        classification: 'repairable_client_input_error',
+        failed_operation: `${context.module}.${context.method}`,
+        implicated_actions: [...actions.values()],
+        rules: [
+            'Do not retry the unchanged payload and do not guess a missing value.',
+            'Treat the deepest provider/API 400 envelope as authoritative, even when wrapped by a Feature, Quota, or Fallback error.',
+            'Redact credentials and never move authentication values into ordinary Feature or runtime input.',
+        ],
+        repair_steps: [
+            'Read the complete nested error envelope and identify the failing provider, action, HTTP status, field, and input location.',
+            'Call ductape_schema for the exact implicated app action using product_tag, env_slug, app_tag, and action_tag. This lookup is mandatory before changing input.',
+            'For Feature, Quota, or Fallback execution, also fetch that component definition and follow its selected option/step to every referenced app action. Schema-check each failing action, not only the outer component.',
+            'Compare supplied input against body, query, params, and headers separately. Restore schema-declared defaults and required constant query values; preserve explicit location prefixes when a name is ambiguous.',
+            'If the live action contract itself omitted a required/default value, update its canonical ductape/actions/<app-tag>/<action-tag>.action.json and update the action through ductape_cli. Do not patch only generated Feature code.',
+            'Call ductape_generate_payload for the repaired operation, validate the generated payload against the looked-up schema, then retry once.',
+            'If the corrected call still returns 400, stop automatic retries and report the provider response plus the schema/payload mismatch that remains.',
+        ],
+        scope_notes: {
+            actions: 'Repair the direct app-action input.',
+            features: 'Repair the failing Feature step mapping or referenced action contract; do not special-case one Feature tag.',
+            fallback: 'Repair the input mapping/action contract for the failing provider option while retaining bounded failover.',
+            quotas: 'Repair the selected Quota option/action mapping; a Quota wrapper does not make a provider 400 retryable.',
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.2.37",
+  "version": "0.3.1",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node scripts/check-cli-command-security.mjs && node scripts/check-frontend-analytics-guidance.mjs && node scripts/check-events-discovery.mjs && node scripts/check-schema-fallback.mjs && node scripts/check-paystack-action-schema.mjs && node scripts/check-portable-functions.mjs && node scripts/check-feature-control-flow.mjs && node scripts/check-project-link-guidance.mjs && node scripts/check-graph-vector-projection-guidance.mjs && node scripts/check-asset-file-guidance.mjs && node scripts/check-database-action-contract-guidance.mjs && node scripts/check-runtime-sync-guidance.mjs",
+    "test": "npm run build && node scripts/check-cli-command-security.mjs && node scripts/check-frontend-analytics-guidance.mjs && node scripts/check-events-discovery.mjs && node scripts/check-schema-fallback.mjs && node scripts/check-paystack-action-schema.mjs && node scripts/check-portable-functions.mjs && node scripts/check-feature-control-flow.mjs && node scripts/check-project-link-guidance.mjs && node scripts/check-graph-vector-projection-guidance.mjs && node scripts/check-asset-file-guidance.mjs && node scripts/check-database-action-contract-guidance.mjs && node scripts/check-runtime-sync-guidance.mjs && node scripts/check-runtime-input-recovery.mjs && node scripts/check-resilience-health-guidance.mjs",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"
   },