@jaypie/mcp 0.8.73 → 0.8.75

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.73#8addc2dd"
+const BUILD_VERSION_STRING = "@jaypie/mcp@0.8.75#7dfeb98d"
     ;
 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.73",
+  "version": "0.8.75",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",

package/release-notes/constructs/1.2.65.md

@@ -0,0 +1,14 @@
+---
+version: 1.2.65
+date: 2026-06-18
+summary: Stabilize JaypieEnvSecret cross-stack export name across both call forms
+---
+
+## Changes
+
+- `JaypieEnvSecret` now always derives its CloudFormation cross-stack export name from the construct id, for both the shorthand and explicit `(id, { envKey })` call forms.
+- Previously the explicit form derived the export name from `envKey`, silently renaming the export across a version bump and breaking existing `Fn::ImportValue` consumers (e.g. `env-sandbox-agents-AgentsInternalKey` became `env-sandbox-agents-AGENTSINTERNALKEY`).
+
+## Migration
+
+No changes required. Unchanged explicit-form call sites now keep their original id-based export name, restoring compatibility with previously published exports (issues #347, #365).

package/release-notes/datadog/1.2.3.md

@@ -0,0 +1,18 @@
+---
+version: 1.2.3
+date: 2026-06-17
+summary: add loadDatadogApiKey to populate DD_API_KEY from DD_API_KEY_SECRET_ARN when LLM Observability is enabled
+---
+
+## Changes
+
+- New `loadDatadogApiKey()` export. When `DD_LLMOBS_ENABLED` is truthy (anything but `false`/`0`), `DD_API_KEY_SECRET_ARN` is set, and neither `DD_API_KEY` nor `DATADOG_API_KEY` is present, it fetches the secret at the ARN and sets `process.env.DD_API_KEY`. Otherwise it is a no-op.
+- `DATADOG.ENV` gains `DD_API_KEY` and `DD_LLMOBS_ENABLED` constants.
+
+## Motivation
+
+dd-trace LLM Observability authenticates with `DD_API_KEY`. On Lambda the key is typically only available as a Secrets Manager ARN (`DD_API_KEY_SECRET_ARN`). This helper resolves the secret into the environment so LLM Observability spans can be submitted without manual wiring.
+
+## Migration
+
+No changes required. `loadDatadogApiKey()` is invoked automatically by `@jaypie/lambda` (`lambdaHandler`, `lambdaStreamHandler`) and `@jaypie/express` (`expressHandler`) before the handler runs.

package/release-notes/datadog/1.2.4.md

@@ -0,0 +1,19 @@
+---
+version: 1.2.4
+date: 2026-06-18
+summary: Add bundler-safe flushLlmObs(), getLlmObs(), and isLlmObsEnabled()
+---
+
+## Changes
+
+- `flushLlmObs()` — flush buffered LLM Observability spans via the runtime `dd-trace` singleton. No-op unless `DD_LLMOBS_ENABLED` is truthy or when `dd-trace` is absent; wrapped so it never throws.
+- `getLlmObs()` — lazy, bundler-safe accessor for the runtime `tracer.llmobs` SDK, or `null` when `dd-trace` cannot be resolved. For manual enclosing spans, annotations, and `submitEvaluation`.
+- `isLlmObsEnabled()` — `true` when `DD_LLMOBS_ENABLED` is truthy (anything but `false`/`0`).
+
+## Notes
+
+`dd-trace` is resolved at runtime via a computed module specifier, so bundlers (esbuild/rollup) leave it external and the layer-initialized singleton is used — never a bundled copy whose buffer would never ship.
+
+## Migration
+
+No changes required. New exports are additive.

package/release-notes/express/1.2.24.md

@@ -0,0 +1,17 @@
+---
+version: 1.2.24
+date: 2026-06-17
+summary: load Datadog LLM Observability API key into the environment before the handler runs
+---
+
+## Changes
+
+- `expressHandler` now calls `loadDatadogApiKey()` (from `@jaypie/datadog`) as the first request setup step.
+
+## Motivation
+
+When `DD_LLMOBS_ENABLED` is set but only `DD_API_KEY_SECRET_ARN` is available, dd-trace LLM Observability cannot authenticate. Resolving the secret into `DD_API_KEY` before the handler runs lets LLM Observability spans emit without per-handler wiring.
+
+## Migration
+
+No changes required. The step is a no-op unless `DD_LLMOBS_ENABLED` is truthy, `DD_API_KEY_SECRET_ARN` is set, and neither `DD_API_KEY` nor `DATADOG_API_KEY` is already present.

package/release-notes/express/1.2.25.md

@@ -0,0 +1,18 @@
+---
+version: 1.2.25
+date: 2026-06-18
+summary: Auto-flush LLM Observability spans in the Lambda adapters
+---
+
+## Changes
+
+- `createLambdaHandler` and `createLambdaStreamHandler` call `flushLlmObs()` from `@jaypie/datadog` in their `finally` block.
+- Buffered Datadog LLM Obs spans flush before the Lambda freezes — even when the Express app errors.
+
+## Notes
+
+No-op unless `DD_LLMOBS_ENABLED` is truthy; never affects the response. No per-handler flush code is required.
+
+## Migration
+
+No changes required.

package/release-notes/jaypie/1.2.53.md

@@ -0,0 +1,14 @@
+---
+version: 1.2.53
+date: 2026-06-18
+summary: pull in @jaypie/datadog, @jaypie/express, and @jaypie/lambda with Datadog LLM Observability API key loading
+---
+
+## Changes
+
+- Bumps `@jaypie/datadog` (1.2.3), `@jaypie/express` (1.2.24), and `@jaypie/lambda` (1.2.9).
+- Handlers now resolve `DD_API_KEY` from `DD_API_KEY_SECRET_ARN` before running when LLM Observability is enabled.
+
+## Migration
+
+No changes required. The new step is a no-op unless `DD_LLMOBS_ENABLED` is truthy, `DD_API_KEY_SECRET_ARN` is set, and neither `DD_API_KEY` nor `DATADOG_API_KEY` is already present.

package/release-notes/jaypie/1.2.54.md

@@ -0,0 +1,14 @@
+---
+version: 1.2.54
+date: 2026-06-18
+summary: Pull updated datadog, express, lambda, and logger subpackages
+---
+
+## Changes
+
+- Bumps `@jaypie/datadog` (`^1.2.4`), `@jaypie/express` (`^1.2.25`), `@jaypie/lambda` (`^1.2.10`), and `@jaypie/logger` (`^1.2.17`).
+- Surfaces the new `flushLlmObs`, `getLlmObs`, and `isLlmObsEnabled` exports (re-exported from `@jaypie/datadog`) and LLM Observability auto-flush in the Lambda/Express handlers.
+
+## Migration
+
+No changes required.

package/release-notes/lambda/1.2.10.md

@@ -0,0 +1,18 @@
+---
+version: 1.2.10
+date: 2026-06-18
+summary: Auto-flush LLM Observability spans in handler teardown
+---
+
+## Changes
+
+- `lambdaHandler` and `lambdaStreamHandler` append a final teardown step that calls `flushLlmObs()` from `@jaypie/datadog`.
+- Runs after user teardown and always (jaypieHandler runs teardown in a `finally`), so buffered LLM Obs spans flush before the Lambda freezes — even when the handler throws.
+
+## Notes
+
+No-op unless `DD_LLMOBS_ENABLED` is truthy; a flush failure never affects the handler response. No per-handler flush code is required.
+
+## Migration
+
+No changes required.

package/release-notes/lambda/1.2.9.md

@@ -0,0 +1,18 @@
+---
+version: 1.2.9
+date: 2026-06-17
+summary: load Datadog LLM Observability API key into the environment before the handler runs
+---
+
+## Changes
+
+- `lambdaHandler` and `lambdaStreamHandler` now call `loadDatadogApiKey()` (from `@jaypie/datadog`) as the first setup step.
+- Adds `@jaypie/datadog` as a peer dependency.
+
+## Motivation
+
+When `DD_LLMOBS_ENABLED` is set but only `DD_API_KEY_SECRET_ARN` is available, dd-trace LLM Observability cannot authenticate. Resolving the secret into `DD_API_KEY` before the handler runs lets LLM Observability spans emit without per-handler wiring.
+
+## Migration
+
+No changes required. The step is a no-op unless `DD_LLMOBS_ENABLED` is truthy, `DD_API_KEY_SECRET_ARN` is set, and neither `DD_API_KEY` nor `DATADOG_API_KEY` is already present.

package/release-notes/llm/1.2.41.md

@@ -0,0 +1,18 @@
+---
+version: 1.2.41
+date: 2026-06-18
+summary: operate() backfills declared array fields in structured output
+---
+
+## Changes
+
+- A declared `format` is treated as a schema contract: every array field declared in `format` is now present in `content` as an array. An empty list surfaces as `[]` rather than being dropped (`undefined`/absent), so `content.someArray.length` is safe across all providers.
+- New util `fillFormatArrays` walks the schema (NaturalSchema, Zod, or JSON Schema) and recurses into nested objects and arrays of objects.
+
+## Notes
+
+The shipped npm `1.3.0` predates the Datadog LLM Observability emission feature and contains no `dd-trace` code — a `^1.2` range resolves to `1.3.0` and silently loses emission. Pin to a feature-bearing `latest` 1.2.x until a release above `1.3.0` ships.
+
+## Migration
+
+No changes required. Consumers that defensively normalized missing array fields to `[]` can drop that workaround.

package/release-notes/llm/1.3.1.md

@@ -0,0 +1,13 @@
+---
+version: 1.3.1
+date: 2026-06-18
+summary: Version step to 1.3.1 to avoid conflict with an accidental 1.3.0
+---
+
+## Changes
+
+- No functional changes. Version advances directly from `1.2.41` to `1.3.1` to step over an accidental `1.3.0` and prevent ongoing version conflicts.
+
+## Migration
+
+No changes required.

package/release-notes/logger/1.2.17.md

@@ -0,0 +1,18 @@
+---
+version: 1.2.17
+date: 2026-06-18
+summary: Add log.flag() for conditional child loggers tagged with a flag
+---
+
+## Changes
+
+- Added `log.flag(flag?)` to `JaypieLogger`
+  - For a non-empty string, returns a child logger tagged `{ flag }` (via `with`)
+  - For `undefined`, a non-string, or an empty string, returns the same logger unchanged
+
+## Usage
+
+```typescript
+log.flag("beta").info("Behind a flag"); // tags { flag: "beta" }
+log.flag(maybeFlag).info("Always logs"); // no-op tag when maybeFlag is falsy/non-string
+```

package/release-notes/mcp/0.8.74.md

@@ -0,0 +1,15 @@
+---
+version: 0.8.74
+date: 2026-06-18
+summary: Document LLM Observability flush primitives and handler auto-flush
+---
+
+## Changes
+
+- `datadog` skill: document `flushLlmObs()`, `getLlmObs()`, and `isLlmObsEnabled()`.
+- `lambda` and `express` skills: document automatic LLM Obs flush in handler teardown.
+- `llm` skill: add an Availability note (npm `1.3.0` predates LLM Obs emission) and Lambda flush guidance.
+
+## Migration
+
+No changes required.

package/release-notes/mcp/0.8.75.md

@@ -0,0 +1,13 @@
+---
+version: 0.8.75
+date: 2026-06-18
+summary: Document JaypieMigration in the cdk skill
+---
+
+## Changes
+
+- `cdk` skill: add a Database Migrations section covering `JaypieMigration` and link to `skill("migrations")`.
+
+## Migration
+
+No changes required.

package/release-notes/testkit/1.2.43.md

@@ -0,0 +1,17 @@
+---
+version: 1.2.43
+date: 2026-06-17
+summary: mock loadDatadogApiKey from @jaypie/datadog
+---
+
+## Changes
+
+- Adds a mock for `loadDatadogApiKey` (resolves to `false`) to the Datadog mock module.
+
+## Motivation
+
+Keeps testkit's mock surface in sync with the new `@jaypie/datadog` export so tests that mock `jaypie`/`@jaypie/datadog` resolve `loadDatadogApiKey`.
+
+## Migration
+
+No changes required.

package/release-notes/testkit/1.2.44.md

@@ -0,0 +1,18 @@
+---
+version: 1.2.44
+date: 2026-06-18
+summary: Add flag to the log mock surface
+---
+
+## Changes
+
+- Adds `flag` to the log mock (`mockLogFactory`), returning the mock for chaining like `with`/`lib`.
+- Adds `flag` to the spy/restore method list and the `LogMock` type.
+
+## Motivation
+
+Keeps testkit's log mock in sync with the new `log.flag()` method in `@jaypie/logger`.
+
+## Migration
+
+No changes required.

package/skills/cdk.md

@@ -237,6 +237,27 @@ new JaypieLambda(this, "Handler", {
 
 See `skill("dynamodb")` for table key conventions and query patterns.
 
+## Database Migrations
+
+`JaypieMigration` runs DynamoDB migrations as a CloudFormation custom resource on every `cdk deploy`. It wraps a `JaypieLambda` in a `cr.Provider` and re-fires on the deploy nonce, so newly added migrations run on code-only deploys instead of being skipped:
+
+```typescript
+import { JaypieDynamoDb, JaypieMigration } from "@jaypie/constructs";
+
+const table = new JaypieDynamoDb(this, "myApp");
+
+new JaypieMigration(this, "SeedData", {
+  code: "dist/migrations/seed",
+  handler: "index.handler",
+  tables: [table],
+  dependencies: [table], // Ensures the table exists first
+});
+```
+
+Use `migrationHandler` from `jaypie` in the migration Lambda so errors propagate as CloudFormation failures. Prefer this construct over a hand-rolled `cr.Provider` + `cdk.CustomResource`, which is easy to key on the table name alone and thereby skip the deploy-nonce re-fire.
+
+See `skill("migrations")` for the full props table, behavior, and handler pattern.
+
 ## Lambda with Secrets
 
 Pass secrets as strings (auto-creates `JaypieEnvSecret`) or as construct instances:
@@ -390,6 +411,7 @@ new JaypieOrganizationTrail(this, "OrgTrail", {
 - **`skill("dynamodb")`** - DynamoDB key design and query patterns
 - **`skill("express")`** - Express handler and Lambda adapter
 - **`skill("lambda")`** - Lambda handler wrappers and lifecycle
+- **`skill("migrations")`** - JaypieMigration DynamoDB migration custom resources
 - **`skill("secrets")`** - Secret management with JaypieEnvSecret
 - **`skill("streaming")`** - JaypieDistribution and JaypieNextJs streaming configuration
 - **`skill("variables")`** - Environment variables reference

package/skills/datadog.md

@@ -101,6 +101,30 @@ await datadogEvent({
 });
 ```
 
+### LLM Observability primitives
+
+Bundler-safe access to the runtime `dd-trace` LLM Obs singleton. `dd-trace` is resolved at runtime via a computed module specifier (never bundled), so on Lambda these reach the layer-initialized singleton — a bundled copy would be a different instance whose buffer never ships.
+
+```typescript
+import { flushLlmObs, getLlmObs, isLlmObsEnabled } from "@jaypie/datadog";
+
+isLlmObsEnabled(); // true when DD_LLMOBS_ENABLED is truthy (not "false"/"0")
+
+// Manual span / annotation / submitEvaluation against the runtime SDK
+getLlmObs()?.trace({ kind: "workflow", name: "my-job" }, async () => {
+  /* ... */
+});
+
+// Flush before the Lambda freezes — no-op unless enabled; never throws
+flushLlmObs();
+```
+
+| Export | Description |
+|--------|-------------|
+| `flushLlmObs()` | Flush buffered LLM Obs spans. No-op when `DD_LLMOBS_ENABLED` is falsy or `dd-trace` is absent; wrapped so it never throws. Called automatically in `@jaypie/lambda`/`@jaypie/express` handler teardown. |
+| `getLlmObs()` | Lazy accessor for the runtime `tracer.llmobs` SDK, or `null` when `dd-trace` cannot be resolved. For manual enclosing spans, annotations, and `submitEvaluation`. |
+| `isLlmObsEnabled()` | `true` when `DD_LLMOBS_ENABLED` is truthy. |
+
 ## Unified Service Tagging
 
 Use consistent tags across services:

package/skills/express.md

@@ -104,6 +104,10 @@ import { createLambdaStreamHandler } from "@jaypie/express";
 export const handler = createLambdaStreamHandler(app);
 ```
 
+### LLM Observability auto-flush
+
+`createLambdaHandler` and `createLambdaStreamHandler` call `flushLlmObs()` from `@jaypie/datadog` in their `finally` block, so buffered Datadog LLM Obs spans flush before the Lambda freezes — even when the Express app errors. No-op unless `DD_LLMOBS_ENABLED` is truthy; never affects the response. No per-handler flush code is required.
+
 ## Event Format Support
 
 The adapter supports both API Gateway formats:

package/skills/lambda.md

@@ -93,12 +93,17 @@ lambdaHandler({ name: "test" }, myFunction);
 ## Lifecycle Flow
 
 1. **Logger initialization** - Re-init logger, tag with `invoke` and `handler`
-2. **Secrets loading** - If `secrets` provided, load via `loadEnvSecrets`
-3. **Validate** - Run validation functions
-4. **Setup** - Run setup functions
-5. **Handler** - Execute main handler logic
-6. **Teardown** - Run teardown functions (always runs)
-7. **Response** - Return result or error body
+2. **Datadog LLM Observability** - `loadDatadogApiKey()` resolves `DD_API_KEY` from the secret ARN when LLM Obs is enabled (no-op otherwise)
+3. **Secrets loading** - If `secrets` provided, load via `loadEnvSecrets`
+4. **Validate** - Run validation functions
+5. **Setup** - Run setup functions
+6. **Handler** - Execute main handler logic
+7. **Teardown** - Run teardown functions, then auto-flush LLM Obs spans (always runs)
+8. **Response** - Return result or error body
+
+### LLM Observability auto-flush
+
+`lambdaHandler` and `lambdaStreamHandler` append a final teardown step that calls `flushLlmObs()` from `@jaypie/datadog`. It runs **after** user teardown and **always** (jaypieHandler runs teardown in a `finally`), so buffered LLM Obs spans flush before the Lambda freezes even when the handler throws. No-op unless `DD_LLMOBS_ENABLED` is truthy; never affects the response. No per-handler flush code is required.
 
 ## Error Handling
 

package/skills/llm.md

@@ -182,6 +182,22 @@ const result = await Llm.operate("Extract contact info from: John Doe, john@exam
 // result.content = { name: "John Doe", email: "john@example.com", phone: "555-1234" }
 ```
 
+#### Declared arrays always present
+
+A declared `format` is a schema contract. `operate()` guarantees every array field declared in `format` is present in `content` as an array — an empty list surfaces as `[]`, never `undefined` or a dropped key. This holds across providers/models, including those that omit empty array fields, so `content.someArray.length` is always safe without defensive normalization. The backfill recurses into nested objects and arrays of objects.
+
+```typescript
+const res = await Llm.operate(message, {
+  format: {
+    "Merchant Request": String,
+    "Merchant Attachments": [String],
+    "Recommended Actions": [String],
+  },
+});
+// Even when the model returns no recommendations:
+// res.content["Recommended Actions"] === []  (never undefined)
+```
+
 ### Zod Schema
 
 ```typescript
@@ -358,6 +374,28 @@ Behavior:
 
 For esbuild-bundled Lambda handlers that also want dd-trace auto-instrumentation, wire the `dd-trace/esbuild` plugin with `keepNames: true`; the spans above do not require it.
 
+### Availability
+
+Span emission ships in the **`@jaypie/llm` 1.2.x line** (current `latest`). Note that the `1.3.0` build published to npm predates this feature and contains **no** LLM Obs code — a `^1.2` range resolves to `1.3.0` and silently loses emission. Until a release **above** `1.3.0` ships with the feature, pin to a `latest` 1.2.x that includes it (grep the installed dist for `llmobs` to confirm).
+
+### Flushing on Lambda
+
+On Lambda the runtime freezes the instant the handler resolves, so buffered LLM Obs spans are dropped unless flushed first. Jaypie handler wrappers flush automatically in teardown — no per-handler code:
+
+- `@jaypie/lambda` — `lambdaHandler`, `lambdaStreamHandler`
+- `@jaypie/express` — `createLambdaHandler`, `createLambdaStreamHandler`
+
+Outside those wrappers, flush manually before returning with the bundler-safe `flushLlmObs()` from `@jaypie/datadog`; reach the runtime SDK singleton for manual spans/annotations/`submitEvaluation` via `getLlmObs()`.
+
+```typescript
+import { flushLlmObs, getLlmObs } from "@jaypie/datadog";
+
+getLlmObs()?.trace({ kind: "workflow", name: "my-job" }, async () => {
+  await Llm.operate(input);
+});
+flushLlmObs(); // no-op unless DD_LLMOBS_ENABLED; never throws
+```
+
 ## Error Handling
 
 The package auto-retries rate limits and transient errors: