@jaypie/mcp 0.8.58 → 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.58#340296a3"
+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.58",
+  "version": "0.8.59",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",

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/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.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.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.