feat(skills): Agent Skills

.github/workflows/ci.yml

@@ -118,6 +118,12 @@ jobs:
       - name: Type check all packages
         run: yarn typecheck
 
+      # Fails when a public name changes in either entry point of
+      # @launchdarkly/ai-server without the checked-in report under
+      # packages/client/etc/ being updated (yarn workspace @launchdarkly/ai-server api:update).
+      - name: Check client API reports
+        run: yarn workspace @launchdarkly/ai-server api:check
+
   # ─── Test ───────────────────────────────────────────────────────────────────
   test:
     name: Tests

.gitignore

@@ -28,4 +28,6 @@ spec.md
 tmp/
 integration-tests/**/.staging/
 
-.claude/
+.claude/
+# API Extractor working files
+packages/client/temp/

AGENTS.md

@@ -164,11 +164,11 @@ The client manages a singleton connection to LaunchDarkly and the associated tel
 | Export | Description |
 |---|---|
 | `initClient(options?)` | Auto-discovers and initializes `@launchdarkly/node-server-sdk` (optional peer dep, loaded via dynamic import). Optional — the first AI API call triggers lazy init when `LD_SDK_KEY` is set. Accepts optional overrides for SDK key, base URIs, service name, environment, and OTLP endpoint. Returns `Promise<LDClientInterface>`. On every successful path, including the already-initialized path, flushes `$ld:ai:sdk:info` for any LaunchDarkly AI packages that have not yet reported. |
-| `initClient(client)` | **BYOC overload** — accepts a pre-initialized `LDClientInterface` (e.g. from `@launchdarkly/vercel-server-sdk`). Stores it directly without calling the node SDK. Flushes pending `$ld:ai:sdk:info` events. |
+| `initClient(client, options?)` | **BYOC overload** — accepts a pre-initialized `LDClientInterface` (e.g. from `@launchdarkly/vercel-server-sdk`). Stores it directly without calling the node SDK. Flushes pending `$ld:ai:sdk:info` events. The optional second argument is the same options bag as the other overload. Idempotent like that overload: once a client is set, a second call returns it and ignores both a different client and the new telemetry options — `shutdown()` first to swap clients. |
 | `getClient()` | Returns the initialized `LDClientInterface`. Throws if initialization has not completed. |
 | `shutdown()` | Flushes all pending events and telemetry, then closes the client. Must be called before the process exits. Clears sdk-info reporting so a later client reports again. |
 | `waitForTelemetry()` | Waits for the OTel provider to be ready. Useful when spans must not be dropped at startup. |
-| `shutdownTelemetry()` | Flushes and stops the OTel exporter independently of the LD client. |
+| `shutdownTelemetry()` | Flushes and stops the OTel exporter independently of the LD client, and releases the OTel globals the SDK registered. |
 | `registerAiSdkPackage(name, version)` | Records a LaunchDarkly AI package identity. Handler and convenience packages call this at import time. |
 
 ### Core Data Types

integration-tests/commonjs-webpack/commonjs-webpack.test.ts

@@ -1,7 +1,18 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { beforeAll, describe, expect, it } from 'vitest';
-import { bundle, createConsumer, invoke, packedFiles, repoRoot, runEntrypoint } from './harness.js';
+import {
+  bundle,
+  consumerDir,
+  createConsumer,
+  invoke,
+  packedFiles,
+  RESOLUTION_MODES,
+  type ResolutionMode,
+  repoRoot,
+  runEntrypoint,
+  typecheck,
+} from './harness.js';
 
 const SETUP_TIMEOUT_MS = 15 * 60 * 1000;
 const CASE_TIMEOUT_MS = 5 * 60 * 1000;
@@ -37,7 +48,12 @@ const OPTIONAL_DEPS: Record<string, string[]> = {
 const RESOLVED_SYMBOLS = {
   aiNodeConfig: 'function',
   aiNodeInitClient: 'function',
+  aiNodeExperimentalGetSkill: 'function',
+  aiNodeRootGetSkill: 'undefined',
   aiServerConfig: 'function',
+  // The experimental subpath resolves, and its names stay off the root.
+  aiServerExperimentalGetSkill: 'function',
+  aiServerRootGetSkill: 'undefined',
   openaiMessages: 'function',
   langchainMessages: 'function',
 };
@@ -109,6 +125,31 @@ describe('CommonJS consumer bundled with Webpack + webpack-node-externals', () =
     CASE_TIMEOUT_MS,
   );
 
+  // `node10` ignores `exports`, so the experimental subpath's types resolve only through
+  // `typesVersions`; without it the import fails with TS2307.
+  it.each(Object.keys(RESOLUTION_MODES) as ResolutionMode[])(
+    'type-checks root and experimental imports under moduleResolution %s',
+    (mode) => {
+      const result = typecheck(mode);
+
+      expect(result.stderr).toBe('');
+      expect(result.status, result.stdout).toBe(0);
+      // A module tsc cannot resolve in the consumer is looked up again in every ancestor
+      // `node_modules`, and the consumer sits inside this repo, so a failed lookup would land on
+      // the workspace copy and pass. Every file loaded from the repo must be the consumer's own.
+      const loaded = result.stdout.split('\n').filter((file) => file.startsWith(repoRoot));
+      expect(loaded.filter((file) => !file.startsWith(`${consumerDir}/`))).toEqual([]);
+      for (const pkg of ['ai-server', 'ai-node']) {
+        const experimental = join(consumerDir, 'node_modules', '@launchdarkly', pkg, 'dist', 'experimental.d.');
+        expect(
+          loaded.some((file) => file.startsWith(experimental)),
+          pkg,
+        ).toBe(true);
+      }
+    },
+    CASE_TIMEOUT_MS,
+  );
+
   it.each([...Object.keys(OPTIONAL_DEPS)])('keeps %s optional dependencies behind a dynamic import in CJS', (pkg) => {
     const cjs = readFileSync(join(repoRoot, 'packages', pkg, 'dist', 'index.cjs'), 'utf8');
 
@@ -129,6 +170,20 @@ describe('CommonJS consumer bundled with Webpack + webpack-node-externals', () =
       expect.arrayContaining(['dist/index.js', 'dist/index.cjs', 'dist/index.d.ts', 'dist/index.d.cts']),
     );
   });
+
+  it.each([
+    'client',
+    'ai-node',
+  ])('packs the experimental entry point in both runtime and declaration formats for %s', (workspace) => {
+    expect(packedFiles.get(workspace)).toEqual(
+      expect.arrayContaining([
+        'dist/experimental.js',
+        'dist/experimental.cjs',
+        'dist/experimental.d.ts',
+        'dist/experimental.d.cts',
+      ]),
+    );
+  });
 });
 
 describe('package manifests', () => {
@@ -143,4 +198,13 @@ describe('package manifests', () => {
     expect(manifest.module).toBe('dist/index.js');
     expect(manifest.types).toBe('dist/index.d.ts');
   });
+
+  it.each(['client', 'ai-node'])('%s declares the experimental subpath with both conditions', (pkg) => {
+    const manifest = JSON.parse(readFileSync(join(repoRoot, 'packages', pkg, 'package.json'), 'utf8'));
+
+    expect(manifest.exports['./experimental']).toEqual({
+      import: { types: './dist/experimental.d.ts', default: './dist/experimental.js' },
+      require: { types: './dist/experimental.d.cts', default: './dist/experimental.cjs' },
+    });
+  });
 });

integration-tests/commonjs-webpack/fixture/entrypoints.cjs

@@ -2,7 +2,9 @@
 
 // Loads every installed package root through `require` and reports what resolved.
 const aiNode = require('@launchdarkly/ai-node');
+const aiNodeExperimental = require('@launchdarkly/ai-node/experimental');
 const aiServer = require('@launchdarkly/ai-server');
+const aiServerExperimental = require('@launchdarkly/ai-server/experimental');
 const openaiMessages = require('@launchdarkly/ai-openai-messages');
 const langchainMessages = require('@launchdarkly/ai-langchain-messages');
 
@@ -12,7 +14,11 @@ process.stdout.write(
   JSON.stringify({
     aiNodeConfig: typeof aiNode.config,
     aiNodeInitClient: typeof aiNode.initClient,
+    aiNodeExperimentalGetSkill: typeof aiNodeExperimental.getSkill,
+    aiNodeRootGetSkill: typeof aiNode.getSkill,
     aiServerConfig: typeof aiServer.config,
+    aiServerExperimentalGetSkill: typeof aiServerExperimental.getSkill,
+    aiServerRootGetSkill: typeof aiServer.getSkill,
     openaiMessages: typeof openaiMessages.openaiMessages,
     langchainMessages: typeof langchainMessages.langchainMessages,
   }),

integration-tests/commonjs-webpack/fixture/entrypoints.mjs

@@ -1,16 +1,22 @@
 // ESM twin of entrypoints.cjs — same package roots, resolved through the `import` condition.
 import * as aiNode from '@launchdarkly/ai-node';
+import * as aiNodeExperimental from '@launchdarkly/ai-node/experimental';
 import * as langchainMessages from '@launchdarkly/ai-langchain-messages';
 import * as openaiMessages from '@launchdarkly/ai-openai-messages';
 import * as aiServer from '@launchdarkly/ai-server';
+import * as aiServerExperimental from '@launchdarkly/ai-server/experimental';
 
 await import('@launchdarkly/ai-otel');
 
 process.stdout.write(
   JSON.stringify({
     aiNodeConfig: typeof aiNode.config,
     aiNodeInitClient: typeof aiNode.initClient,
+    aiNodeExperimentalGetSkill: typeof aiNodeExperimental.getSkill,
+    aiNodeRootGetSkill: typeof aiNode.getSkill,
     aiServerConfig: typeof aiServer.config,
+    aiServerExperimentalGetSkill: typeof aiServerExperimental.getSkill,
+    aiServerRootGetSkill: typeof aiServer.getSkill,
     openaiMessages: typeof openaiMessages.openaiMessages,
     langchainMessages: typeof langchainMessages.langchainMessages,
   }),

integration-tests/commonjs-webpack/fixture/types.ts

@@ -0,0 +1,15 @@
+// Type-checked by the integration test under each `moduleResolution` a consumer may use,
+// including `node` (node10), which ignores `exports` and needs `typesVersions` for a subpath.
+import { config, initClient } from '@launchdarkly/ai-node';
+import { setSkillStore as setNodeSkillStore } from '@launchdarkly/ai-node/experimental';
+import * as server from '@launchdarkly/ai-server';
+import { InMemorySkillStore, type SkillStore, setSkillStore } from '@launchdarkly/ai-server/experimental';
+
+const store: SkillStore = new InMemorySkillStore();
+setSkillStore(store);
+setNodeSkillStore(store);
+
+// @ts-expect-error Agent Skills is not exported from the package root.
+export const rootGetSkill = server.getSkill;
+
+export const used = [config, initClient, server.config];

integration-tests/commonjs-webpack/harness.ts

@@ -17,6 +17,9 @@ const WORKSPACES = ['client', 'ai-node', 'ai-otel', 'openai-messages', 'langchai
 /** Pinned to the versions reported in AIC-3370. */
 const BUNDLER_DEPS = ['webpack@5.104.1', 'webpack-cli@6.0.1', 'webpack-node-externals@3.0.0'];
 
+/** Type-checks the consumer's imports (see `typecheck`). */
+const TYPESCRIPT_DEP = 'typescript@5.9.3';
+
 export type Variant = 'externalized' | 'allowlisted';
 
 /** Workspace name -> paths inside the tarball `npm publish` would upload. */
@@ -92,7 +95,7 @@ export function createConsumer(): string {
   );
   cpSync(join(here, 'fixture'), consumerDir, { recursive: true });
 
-  runOrThrow('npm', ['install', '--no-audit', '--no-fund', ...tarballs, ...BUNDLER_DEPS], consumerDir);
+  runOrThrow('npm', ['install', '--no-audit', '--no-fund', ...tarballs, ...BUNDLER_DEPS, TYPESCRIPT_DEP], consumerDir);
 
   return consumerDir;
 }
@@ -107,6 +110,42 @@ export function invoke(variant: Variant): RunResult {
   return run('node', ['invoke.cjs', `./dist-${variant}/handler.js`], consumerDir);
 }
 
+/** `moduleResolution` modes paired with the `module` setting each requires. */
+export const RESOLUTION_MODES = {
+  node10: 'commonjs',
+  node16: 'node16',
+  bundler: 'esnext',
+} as const;
+
+export type ResolutionMode = keyof typeof RESOLUTION_MODES;
+
+/**
+ * Type-checks `types.ts` against the installed tarballs' declarations. Runs the consumer's own
+ * `tsc` rather than `npx`, whose npm config warnings would land in stderr. `--listFiles` prints
+ * every file the program loaded, so a caller can check where each declaration came from.
+ */
+export function typecheck(mode: ResolutionMode): RunResult {
+  return run(
+    'node',
+    [
+      join('node_modules', 'typescript', 'bin', 'tsc'),
+      '--noEmit',
+      '--listFiles',
+      // Only the consumer's own `@types`, not those of every ancestor `node_modules`.
+      '--typeRoots',
+      join('node_modules', '@types'),
+      '--strict',
+      '--skipLibCheck',
+      '--module',
+      RESOLUTION_MODES[mode],
+      '--moduleResolution',
+      mode,
+      'types.ts',
+    ],
+    consumerDir,
+  );
+}
+
 /** Runs an unbundled entry point against the installed tarballs. */
 export function runEntrypoint(file: string): RunResult {
   return run('node', [file], consumerDir);

packages/ai-node/README.md

@@ -111,6 +111,19 @@ module.exports = {
 };
 ```
 
+## Experimental features
+
+Experimental features are not exported from the package root. Import them from
+`@launchdarkly/ai-node/experimental`, which re-exports `@launchdarkly/ai-server/experimental`, so
+you need no direct dependency on `@launchdarkly/ai-server`. For example:
+
+```ts
+import { InMemorySkillStore, setSkillStore } from '@launchdarkly/ai-node/experimental';
+```
+
+Names there may change in a minor release. See the
+[Agent Skills guide](../client/README.md#agent-skills-experimental).
+
 ## Full API reference
 
 See [`@launchdarkly/ai-server`](../client/README.md) — all exports are re-exported unchanged from this package.

packages/ai-node/agents.md

@@ -21,6 +21,7 @@ For edge runtimes (Vercel, Cloudflare Workers, Deno, etc.) use `@launchdarkly/ai
 | File | Responsibility |
 |---|---|
 | `src/index.ts` | Single `export * from '@launchdarkly/ai-server'` — the entire public barrel |
+| `src/experimental.ts` | Single `export * from '@launchdarkly/ai-server/experimental'` — published as `@launchdarkly/ai-node/experimental`, so Node.js users reach experimental features (Agent Skills) without a direct `@launchdarkly/ai-server` dependency |
 
 ---
 
@@ -32,7 +33,7 @@ This package re-exports everything from `@launchdarkly/ai-server` and nothing el
 export * from '@launchdarkly/ai-server';
 ```
 
-Every symbol available from `@launchdarkly/ai-server` is available from `@launchdarkly/ai-node` under the same name. No additional symbols are added. When `@launchdarkly/ai-server` gains a new export, this package automatically picks it up.
+Every symbol available from `@launchdarkly/ai-server` is available from `@launchdarkly/ai-node` under the same name, and every symbol from `@launchdarkly/ai-server/experimental` is available from `@launchdarkly/ai-node/experimental`. No additional symbols are added. When `@launchdarkly/ai-server` gains a new export, this package automatically picks it up.
 
 ---
 

packages/ai-node/package.json

@@ -27,6 +27,13 @@
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "experimental": [
+        "dist/experimental.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "import": {
@@ -37,6 +44,16 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
+    },
+    "./experimental": {
+      "import": {
+        "types": "./dist/experimental.d.ts",
+        "default": "./dist/experimental.js"
+      },
+      "require": {
+        "types": "./dist/experimental.d.cts",
+        "default": "./dist/experimental.cjs"
+      }
     }
   },
   "files": [

packages/ai-node/src/__tests__/reexports.test.ts

@@ -29,3 +29,21 @@ describe('@launchdarkly/ai-node re-exports', () => {
     }
   });
 });
+
+describe('@launchdarkly/ai-node/experimental re-exports', () => {
+  it('exports every named export from @launchdarkly/ai-server/experimental, as the same references', async () => {
+    const serverExperimental = await import('@launchdarkly/ai-server/experimental');
+    const nodeExperimental = await import('../experimental.js');
+
+    const serverKeys = Object.keys(serverExperimental);
+    expect(serverKeys.length).toBeGreaterThan(0);
+    for (const key of serverKeys) {
+      expect((nodeExperimental as any)[key], key).toBe((serverExperimental as any)[key]);
+    }
+  });
+
+  it('keeps experimental names off the package root', () => {
+    expect('getSkill' in node).toBe(false);
+    expect('setSkillStore' in node).toBe(false);
+  });
+});

packages/ai-node/src/experimental.ts

@@ -0,0 +1,17 @@
+/**
+ * Experimental features of the LaunchDarkly AI SDK for Node.js.
+ *
+ * @launchdarkly/ai-node/experimental
+ *
+ * Re-exports `@launchdarkly/ai-server/experimental`, so a Node.js application
+ * that installs only this package can reach experimental features without a
+ * direct dependency on `@launchdarkly/ai-server` (required under strict
+ * package managers such as pnpm and Yarn PnP). Every name here may change in a
+ * minor release, and none is exported from the package root.
+ */
+import { registerAiSdkPackage } from '@launchdarkly/ai-server';
+import { LD_AI_PACKAGE_NAME, LD_AI_PACKAGE_VERSION } from './version.js';
+
+registerAiSdkPackage(LD_AI_PACKAGE_NAME, LD_AI_PACKAGE_VERSION);
+
+export * from '@launchdarkly/ai-server/experimental';

packages/ai-node/tsup.config.ts

@@ -1 +1,10 @@
-export { default } from '../../tsup.config.base';
+import { defineConfig } from 'tsup';
+import base from '../../tsup.config.base';
+
+// Two entry points, mirroring @launchdarkly/ai-server: the package root and
+// `@launchdarkly/ai-node/experimental`. Both re-export from external packages,
+// so there is nothing to share between them.
+export default defineConfig({
+  ...base,
+  entry: { index: 'src/index.ts', experimental: 'src/experimental.ts' },
+});