@jaypie/mcp 0.8.57 → 0.8.59

package/dist/suites/docs/index.js

@@ -9,7 +9,7 @@ import { gt } from 'semver';
 /**
  * Docs Suite - Documentation services (skill, version, release_notes)
  */
-const BUILD_VERSION_STRING = "@jaypie/mcp@0.8.57#b4f7b221"
+const BUILD_VERSION_STRING = "@jaypie/mcp@0.8.59#659b659d"
     ;
 const __filename$1 = fileURLToPath(import.meta.url);
 const __dirname$1 = path.dirname(__filename$1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/mcp",
-  "version": "0.8.57",
+  "version": "0.8.59",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",

package/release-notes/constructs/1.2.55.md

@@ -0,0 +1,45 @@
+---
+version: 1.2.55
+date: 2026-05-10
+summary: JaypieMigration `timeout` prop default 15m (#341); JaypieDistribution `waf.allow` path-scoped relaxations (#342)
+---
+
+## Changes
+
+### `JaypieMigration` — `timeout` prop, default 15 minutes (#341)
+
+- `JaypieMigrationProps` accepts an optional `timeout?: cdk.Duration` that is forwarded to the inner `JaypieLambda`.
+- The default migration Lambda timeout is now **15 minutes** (Lambda's maximum), up from 5 minutes.
+
+### `JaypieDistribution` — `waf.allow` (#342)
+
+- New `waf.allow` field accepts an entry (or array of entries) shaped `{ path, AWSManagedRulesCommonRuleSet: [...], AWSManagedRulesKnownBadInputsRuleSet: [...], ... }`. Each entry flips the named sub-rules from `block` to `count` **only** on requests matching its path set; strict default action is preserved everywhere else.
+- `path` accepts a string or string[]. Trailing `*` becomes WAFv2 `STARTS_WITH`; no trailing `*` becomes `EXACTLY`. Multiple paths in one entry are OR'd.
+- Each managed-rule-group key accepts a string or string[] of sub-rule names.
+- `waf.allow` composes with `waf.managedRuleOverrides`: the baseline override list applies to both the relaxed and strict emissions of a group; `allow` further relaxes specific (path × sub-rule) intersections. Groups not named in `allow` keep their existing single-rule emission.
+
+```ts
+waf: {
+  allow: [
+    {
+      path: "/hooks/*",
+      AWSManagedRulesCommonRuleSet: ["ExploitablePaths_URIPATH"],
+      AWSManagedRulesKnownBadInputsRuleSet: ["CrossSiteScripting_BODY"],
+    },
+  ],
+}
+```
+
+## Motivation
+
+### `JaypieMigration` timeout
+
+Real-world DynamoDB migrations the construct exists to support routinely exceed five minutes: first-time GSI creation commonly takes 3–10 minutes to reach `ACTIVE`, and a backfill that scans and rewrites entities after the GSI is ready adds more. The previous 5-minute hard cap left no headroom; CloudFormation rolled back even when the underlying operation would have completed.
+
+### `waf.allow`
+
+Webhook ingress paths (Datadog, GitHub, Slack, Jira) legitimately trip body- and URI-inspection rules in `AWSManagedRulesCommonRuleSet` / `AWSManagedRulesKnownBadInputsRuleSet`, while the rest of the API should keep full blocking. The previous escape hatch — distribution-wide `managedRuleOverrides` — weakened protection on every path on the host. `waf.allow` confines the relaxation to the listed paths.
+
+## Migration
+
+No action required. `JaypieMigration` callers that previously relied on the 5-minute default still complete in well under 15 minutes; callers that want to keep 5 minutes can pass `timeout: Duration.minutes(5)` explicitly. `waf.allow` is opt-in — distributions that don't pass it keep their previous WebACL exactly.

package/release-notes/constructs/1.2.56.md

@@ -0,0 +1,58 @@
+---
+version: 1.2.56
+date: 2026-05-10
+summary: JaypieMigration waiter pattern (#346); fix JaypieEnvSecret cross-stack export name regression (#347)
+---
+
+## Changes
+
+### `JaypieEnvSecret` — fix cross-stack export name regression (#347)
+
+Two bugs introduced by the shorthand detection feature (1.2.44+) that broke cross-stack `JaypieEnvSecret` wiring:
+
+1. **Export name drift** — when using shorthand (`new JaypieEnvSecret(scope, "SECRET_KEY")`), the CDK construct id was prefixed to `EnvSecret_SECRET_KEY`, causing the auto-generated `Export.Name` to change from `env-<env>-<project>-SECRETKEY` to `env-<env>-<project>-EnvSecretSECRETKEY`. CloudFormation refused to delete the old export while any consumer still imported it.
+
+2. **Consumer `undefined` env vars** — `exportEnvName` ignored the explicit `consumer: true` prop and fell through to an else branch when `PROJECT_ENV` was not `"personal"`, producing `env-undefined-undefined-...` in `Fn::ImportValue`.
+
+**Fixes:**
+- `exportEnvName` now accepts `consumer` and uses it alongside `checkEnvIsConsumer(env)`, so explicit `{ consumer: true }` always resolves to the sandbox-scoped import name regardless of `PROJECT_ENV`.
+- The `exportEnvName` call site now passes `envKey || id` instead of `id`, restoring the original key as the name component and eliminating the `EnvSecret` prefix from the export name.
+
+### `JaypieMigration` — waiter pattern with `queryInterval` and `totalTimeout` (#346)
+
+- `JaypieMigrationProps` accepts two new optional props:
+  - `queryInterval?: cdk.Duration` — polling interval between `isCompleteHandler` invocations. Default: **60 seconds**.
+  - `totalTimeout?: cdk.Duration` — maximum wall time across all invocations. Default: **2 hours**.
+- `cr.Provider` is now wired with `isCompleteHandler: this.lambda` in addition to `onEventHandler`, activating Step Functions-backed polling. Each invocation of `isCompleteHandler` lives under the per-Lambda timeout cap, but the orchestration can run for `totalTimeout` (up to 2 h by default).
+- `onEventHandler` now returns `PhysicalResourceId` immediately; the migration Lambda runs exclusively in `isCompleteHandler` invocations.
+
+```ts
+new JaypieMigration(this, "Migration", {
+  code: "dist/migration",
+  handler: "index.handler",
+  tables: [table],
+  queryInterval: Duration.seconds(60),   // optional, this is the default
+  totalTimeout: Duration.hours(2),       // optional, this is the default
+});
+```
+
+## Motivation
+
+`JaypieMigration` previously ran all migrations synchronously inside a single Lambda invocation, bounded by Lambda's 15-minute hard cap. Multi-step migrations whose cumulative wall time exceeds 15 minutes — three back-to-back GSI creations being the canonical example — would be killed mid-flight, causing CloudFormation rollback and repeated partial teardown cycles.
+
+AWS's canonical answer for this shape is `cr.Provider`'s waiter pattern: an `isCompleteHandler` Lambda is invoked repeatedly on a `queryInterval` until it returns `IsComplete: true`. Step Functions orchestrates the polling loop; each invocation is independently time-bounded by the Lambda timeout, while the total can span hours.
+
+## Migration
+
+No action required for existing single-shot migrations. `migrationHandler` maps a handler that returns no `pending` flag to `IsComplete: true`, so `cr.Provider` calls `isCompleteHandler` exactly once and the deploy completes as before. The only observable difference is an extra `onEventHandler` invocation (which returns immediately) before the migration runs.
+
+To enable multi-step migrations, return `{ pending: true }` from `migrationHandler` until all steps are complete:
+
+```typescript
+import { migrationHandler } from "jaypie";
+
+export const handler = migrationHandler(async (event) => {
+  const remaining = await runNextPendingMigration();
+  return { pending: remaining > 0 };
+});
+```

package/release-notes/jaypie/1.2.47.md

@@ -0,0 +1,9 @@
+---
+version: 1.2.47
+date: 2026-05-10
+summary: Bump @jaypie/llm to 1.2.34 for retry-executor sibling-rejection fix (issue #336)
+---
+
+## Changes
+
+- Bumps the `@jaypie/llm` peer dependency to `^1.2.34` so the retry executor no longer crashes the host when an upstream SDK surfaces twin rejections of an already-handled error.

package/release-notes/lambda/1.2.7.md

@@ -0,0 +1,29 @@
+---
+version: 1.2.7
+date: 2026-05-10
+summary: migrationHandler waiter protocol — onEventHandler/isCompleteHandler mode detection and pending flag (#346)
+---
+
+## Changes
+
+- `migrationHandler` now detects whether the Lambda is being invoked as `onEventHandler` or `isCompleteHandler` (by `cr.Provider`'s Step Functions waiter) and branches accordingly:
+  - **`onEventHandler` mode** (event has no `Data` field): returns `{ PhysicalResourceId }` immediately without running the user's handler. This is the fast-return that lets CFN start the polling loop.
+  - **`isCompleteHandler` mode** (event has a top-level `Data` field): runs the user's handler and wraps the result in CFN's `IsComplete` protocol: `{ IsComplete: !pending, Data: result }`.
+- The user handler may return `{ pending: true }` to signal more work remains; the waiter will re-invoke after `queryInterval`. Omitting `pending` (or `pending: false`) maps to `IsComplete: true`.
+
+```typescript
+import { migrationHandler } from "jaypie";
+
+export const handler = migrationHandler(async (event) => {
+  const remaining = await runNextPendingMigration();
+  return { pending: remaining > 0 };
+});
+```
+
+## Motivation
+
+`cr.Provider` uses a Step Functions state machine to poll `isCompleteHandler` independently from `onEventHandler`. When both handlers point to the same Lambda ARN, the Lambda must distinguish its role from the event shape. `isCompleteHandler` events always carry a top-level `Data` field (whatever `onEventHandler` returned); `onEventHandler` events do not. This is the discriminator.
+
+## Migration
+
+Existing `migrationHandler` users are upgraded automatically when they deploy with `@jaypie/constructs@1.2.56` (which now always wires `isCompleteHandler`). The migration runs in `isCompleteHandler` instead of `onEventHandler`; CloudFormation behavior is identical for single-shot migrations that complete in one call.

package/release-notes/llm/1.2.34.md

@@ -0,0 +1,18 @@
+---
+version: 1.2.34
+date: 2026-05-10
+summary: Retry executor swallows sibling rejections of already-handled upstream errors (issue #336)
+---
+
+## Changes
+
+- New shared `createStaleRejectionGuard` helper records errors that the retry layer has caught and recognizes sibling unhandled rejections by reference *or* by `name + message`. When a sibling fires, the guard attaches a `.catch()` to the dangling promise so it is no longer treated as unhandled.
+- `RetryExecutor` and `StreamLoop` both consume the shared guard. Transient socket teardown errors (`TypeError: terminated`, `ECONNRESET`, etc.) continue to be suppressed exactly as before.
+
+## Motivation
+
+Provider SDKs occasionally surface a single upstream failure as twin promise rejections. The retry layer catches and handles the first; the second arrives on a later microtask and escaped the previous guard because that guard only matched a fixed set of transient-network patterns. A real example: OpenRouter's `matchers.js` does `JSON.parse("")` and throws `SyntaxError: Unexpected end of JSON input`. The retry executor caught it and was sleeping before the next attempt when the sibling rejection killed the host process — many hours into a long evaluation run.
+
+## Migration
+
+No action required. The new guard is strictly more permissive than the old one — it swallows the same transient-network rejections plus any rejection whose error matches one the retry loop has already caught. Unrelated rejections are unaffected.

package/release-notes/llm/1.2.35.md

@@ -0,0 +1,9 @@
+---
+version: 1.2.35
+date: 2026-05-10
+summary: Downgrade tool-throw log level from error to warn
+---
+
+## Bug Fixes
+
+- **Tool throw log level** — When a tool registered with the operate loop throws, the error is now logged at `log.warn` instead of `log.error` in both the streaming and non-streaming paths. Tool throws are a normal operating mode; the loop already feeds the error back to the model as a `tool_result`. Elevating every tool throw to `error` caused monitoring noise for routine outcomes like authorization refusals and allowlist misses. The existing `log.warn("Stopped after N consecutive tool errors")` continues to fire at warn for the terminal threshold case.

package/release-notes/mcp/0.8.58.md

@@ -0,0 +1,9 @@
+---
+version: 0.8.58
+date: 2026-05-10
+summary: Release notes for @jaypie/constructs 1.2.55 and @jaypie/llm 1.2.34
+---
+
+## Changes
+
+- Adds release notes for `@jaypie/constructs` 1.2.55 (`JaypieMigration` `timeout` prop default 15 minutes — issue #341; `JaypieDistribution` `waf.allow` path-scoped relaxations — issue #342) and `@jaypie/llm` 1.2.34 (retry executor swallows sibling rejections — issue #336), plus the corresponding `jaypie` 1.2.47 dependency bump.

package/release-notes/mcp/0.8.59.md

@@ -0,0 +1,13 @@
+---
+version: 0.8.59
+date: 2026-05-10
+summary: Update migrations skill for waiter pattern — pending flag, queryInterval, totalTimeout (#346)
+---
+
+## Changes
+
+- Updated `skills/migrations.md` to document the `cr.Provider` waiter pattern introduced in `@jaypie/constructs@1.2.56` and `@jaypie/lambda@1.2.7`:
+  - New `queryInterval` and `totalTimeout` props in the Props table
+  - Updated Behavior section to describe the `onEventHandler` / `isCompleteHandler` two-phase execution model
+  - New "Multi-step migrations" section explaining the `pending` flag and waiter protocol
+  - Updated Construct Internals to mention the Step Functions state machine

package/skills/migrations.md

@@ -35,20 +35,23 @@ new JaypieMigration(this, "SeedData", {
 | `dependencies` | `Construct[]` | `[]` | Constructs that must be created before the migration runs |
 | `environment` | `Record<string, string> \| (Record<string, string> \| string)[]` | - | Environment variables for the migration Lambda |
 | `handler` | `string` | `"index.handler"` | Lambda entry point |
+| `queryInterval` | `cdk.Duration` | `Duration.seconds(60)` | Polling interval between `isCompleteHandler` invocations |
 | `secrets` | `SecretsArrayItem[]` | `[]` | Secrets to make available to the Lambda |
 | `tables` | `dynamodb.ITable[]` | `[]` | DynamoDB tables to grant read/write access |
+| `timeout` | `cdk.Duration` | `Duration.minutes(15)` | Per-invocation Lambda timeout |
+| `totalTimeout` | `cdk.Duration` | `Duration.hours(2)` | Maximum wall time across all `isCompleteHandler` invocations |
 
 ## Behavior
 
-- **Timeout**: 5 minutes (vs 30s for API Lambdas) to accommodate long-running migrations
+- **Timeout**: 15 minutes per invocation (Lambda max); `totalTimeout` controls the end-to-end ceiling across all polling invocations (default 2 hours)
 - **Role**: Tagged as `CDK.ROLE.PROCESSING`
-- **Execution**: Runs on every deploy via CloudFormation custom resource (uses a deploy nonce to force re-invocation even when only Lambda code changes)
+- **Execution**: Uses `cr.Provider` with both `onEventHandler` and `isCompleteHandler` pointing to the same Lambda. The `onEventHandler` returns `PhysicalResourceId` immediately; the migration code runs in `isCompleteHandler` invocations, which are polled by Step Functions until `IsComplete: true`.
 - **Dependencies**: Use `dependencies` to ensure tables and other resources exist before the migration executes
 - **Permissions**: Tables passed via `tables` get data-plane (`grantReadWriteData`) plus control-plane access (`DescribeTable`, `UpdateTable`, `UpdateTimeToLive`, `UpdateContinuousBackups`) scoped to the table ARN and its indexes — migrations that add GSIs, toggle TTL, or change backups work without extra IAM
 
 ## Migration Lambda Handler
 
-The migration Lambda receives a CloudFormation custom resource event. Use `migrationHandler` so a thrown error fails the CFN custom resource (and the deploy) — `lambdaHandler`'s default `throw: false` returns a success-shaped response on error and CFN reports `CREATE_COMPLETE` even when the migration failed.
+Use `migrationHandler` from `jaypie` so errors propagate as CFN failures and the waiter protocol is handled automatically.
 
 ```typescript
 // src/migrations/seed/index.ts
@@ -69,6 +72,21 @@ export const handler = migrationHandler(async (event) => {
 
 `migrationHandler` is `lambdaHandler` with `throw: true` defaulted. Pass `{ throw: false }` to opt back into soft-fail behavior.
 
+### Multi-step migrations (waiter pattern)
+
+Return `{ pending: true }` to request another invocation after `queryInterval`. The handler runs repeatedly until `pending` is omitted or `false`.
+
+```typescript
+export const handler = migrationHandler(async (event) => {
+  const remaining = await runNextPendingMigration();
+  return { pending: remaining > 0 };
+});
+```
+
+`migrationHandler` maps the `pending` flag onto CFN's `IsComplete` protocol:
+- `pending: true` → `{ IsComplete: false }` — waiter re-invokes after `queryInterval`
+- `pending: false` or omitted → `{ IsComplete: true }` — deploy proceeds
+
 ## Building Migration Code
 
 Bundle migrations separately using esbuild, then reference the output directory:
@@ -110,11 +128,11 @@ new JaypieMigration(this, "DataMigration", {
 
 ## Construct Internals
 
-`JaypieMigration` creates three resources:
+`JaypieMigration` creates:
 
 1. **`JaypieLambda`** - The migration function (exposed as `migration.lambda`)
-2. **`cr.Provider`** - CloudFormation custom resource provider wrapping the Lambda
-3. **`cdk.CustomResource`** - The custom resource that triggers on every deploy
+2. **`cr.Provider`** - Custom resource provider with `onEventHandler` and `isCompleteHandler` both pointing to the migration Lambda; backed by a Step Functions state machine for the waiter loop
+3. **`cdk.CustomResource`** - Triggers on every deploy via a `deployNonce` property
 
 Dependencies are attached to the custom resource so the migration waits for prerequisite resources.