@moda-ai/cli 1.11.0 → 1.12.0

package/skills/integration/index.json

@@ -0,0 +1,123 @@
+{
+  "schema_version": "moda.skill_index.v1",
+  "bundled_at": "2026-07-06T02:25:00.333Z",
+  "cli_version": "1.12.0",
+  "skills": [
+    {
+      "id": "integration-node-anthropic",
+      "version": "1.0.0",
+      "summary": "Auto-instrument @anthropic-ai/sdk client calls with Moda in a Node.js or TypeScript app; no per-call changes required.",
+      "targets": {
+        "language": "node",
+        "frameworks": [],
+        "providers": [
+          "anthropic"
+        ]
+      }
+    },
+    {
+      "id": "integration-node-generic",
+      "version": "1.0.0",
+      "summary": "General Moda SDK integration for a Node.js or TypeScript app when no specific framework or provider skill matches.",
+      "targets": {
+        "language": "node",
+        "frameworks": [],
+        "providers": []
+      }
+    },
+    {
+      "id": "integration-node-langchain",
+      "version": "1.0.0",
+      "summary": "Instrument a Node.js LangChain or LangGraph app with Moda: init before the framework, explicit conversation ids around every run.",
+      "targets": {
+        "language": "node",
+        "frameworks": [
+          "langchain"
+        ],
+        "providers": []
+      }
+    },
+    {
+      "id": "integration-node-openai",
+      "version": "1.0.0",
+      "summary": "Auto-instrument direct openai client calls with Moda in a Node.js or TypeScript app; no per-call changes required.",
+      "targets": {
+        "language": "node",
+        "frameworks": [],
+        "providers": [
+          "openai"
+        ]
+      }
+    },
+    {
+      "id": "integration-node-vercel-ai-sdk",
+      "version": "1.0.0",
+      "summary": "Instrument Vercel AI SDK calls (generateText, streamText, generateObject) with Moda telemetry in a Node.js or TypeScript app.",
+      "targets": {
+        "language": "node",
+        "frameworks": [
+          "vercel-ai-sdk"
+        ],
+        "providers": []
+      }
+    },
+    {
+      "id": "integration-python-anthropic",
+      "version": "1.0.0",
+      "summary": "Auto-instrument anthropic client calls with Moda in a Python app; no per-call changes required.",
+      "targets": {
+        "language": "python",
+        "frameworks": [],
+        "providers": [
+          "anthropic"
+        ]
+      }
+    },
+    {
+      "id": "integration-python-claude-agent-sdk",
+      "version": "1.0.0",
+      "summary": "Instrument Claude Agent SDK sessions (ClaudeSDKClient) with Moda via the dedicated moda-claude-agent-sdk instrumentor.",
+      "targets": {
+        "language": "python",
+        "frameworks": [
+          "claude-agent-sdk"
+        ],
+        "providers": []
+      }
+    },
+    {
+      "id": "integration-python-generic",
+      "version": "1.0.0",
+      "summary": "General Moda SDK integration for a Python app when no specific framework or provider skill matches.",
+      "targets": {
+        "language": "python",
+        "frameworks": [],
+        "providers": []
+      }
+    },
+    {
+      "id": "integration-python-langchain",
+      "version": "1.0.0",
+      "summary": "Instrument a Python LangChain or LangGraph app with Moda: init before the framework, explicit conversation ids around every run.",
+      "targets": {
+        "language": "python",
+        "frameworks": [
+          "langchain"
+        ],
+        "providers": []
+      }
+    },
+    {
+      "id": "integration-python-openai",
+      "version": "1.0.0",
+      "summary": "Auto-instrument openai client calls with Moda in a Python app; no per-call changes required.",
+      "targets": {
+        "language": "python",
+        "frameworks": [],
+        "providers": [
+          "openai"
+        ]
+      }
+    }
+  ]
+}

package/skills/integration/integration-node-anthropic/EXAMPLE.md

@@ -0,0 +1,59 @@
+# Golden reference: Express + Anthropic SDK + Moda
+
+The complete finished integration for a minimal Express chat server that
+calls the Anthropic SDK directly. Match this structure; adapt names to the
+target repository.
+
+## src/server.ts
+
+```typescript
+import express from 'express';
+import { Moda, withContext } from 'moda-ai';
+import Anthropic from '@anthropic-ai/sdk';
+
+// Initialize Moda once, before the Anthropic client is created. After this,
+// every messages.create / messages.stream call is captured automatically.
+await Moda.init(process.env.MODA_API_KEY!);
+
+const client = new Anthropic();
+const app = express();
+app.use(express.json());
+
+app.post('/chat', async (req, res) => {
+  const { sessionId, userId, message } = req.body;
+
+  // Scoped context: safe under concurrent requests.
+  const response = await withContext(`session_${sessionId}`, userId, async () =>
+    client.messages.create({
+      model: 'claude-sonnet-4-20250514',
+      max_tokens: 1024,
+      messages: [{ role: 'user', content: message }],
+    }),
+  );
+
+  const reply = response.content
+    .filter((block) => block.type === 'text')
+    .map((block) => block.text)
+    .join('');
+  res.json({ reply });
+});
+
+// Flush pending telemetry on shutdown.
+process.on('SIGTERM', async () => {
+  await Moda.flush();
+  await Moda.shutdown();
+  process.exit(0);
+});
+
+app.listen(3000);
+```
+
+## What changed, and what did not
+
+- `moda-ai` added to `package.json` dependencies.
+- One `Moda.init` call added at startup, before `new Anthropic()`.
+- The handler wraps its existing Anthropic call in `withContext`; the
+  `messages.create` call itself is unchanged — instrumentation is automatic.
+- A `SIGTERM` handler flushes telemetry on shutdown.
+- No `.env` file was created or edited; `MODA_API_KEY` is read from the
+  runtime environment.

package/skills/integration/integration-node-anthropic/SKILL.md

@@ -0,0 +1,150 @@
+---
+id: integration-node-anthropic
+name: "Integrate Moda with the Anthropic SDK (Node.js / TypeScript)"
+version: 1.0.0
+category: integration
+targets:
+  language: node
+  frameworks: []
+  providers:
+    - anthropic
+sdk_package: moda-ai
+summary: "Auto-instrument @anthropic-ai/sdk client calls with Moda in a Node.js or TypeScript app; no per-call changes required."
+---
+
+# Integrate Moda with the Anthropic SDK (Node.js / TypeScript)
+
+Follow the steps below in order. Each step has a stop condition; when you hit
+one, stop and report instead of guessing. `EXAMPLE.md` in this directory shows
+the complete finished integration; match its structure. For API details beyond
+this skill, read https://docs.moda.dev/ingestion/providers/anthropic and
+https://docs.moda.dev/ingestion/moda-sdk-node (if the installed `moda-ai`
+package ships docs under `node_modules/moda-ai/docs/`, prefer those; they
+match the installed SDK version).
+
+## Safety rules (apply to every step)
+
+- Only touch the repository you were launched in.
+- Never write the `MODA_API_KEY` value (or any secret) into source files, and
+  never create or edit `.env` files. The key belongs in the runtime
+  environment or a secret manager.
+- Make the smallest correct change. Match the existing code style and imports.
+- Do not commit unless the user asks.
+- If a step is ambiguous in this repository, stop and report rather than
+  guessing.
+
+## Step 1: Confirm the raw Anthropic client is the integration surface
+
+Find the real LLM call sites: `client.messages.create(...)` or
+`client.messages.stream(...)` on a client constructed with `new Anthropic()`
+from the `@anthropic-ai/sdk` package.
+
+- If the Anthropic calls go through a wrapper framework instead — the `ai`
+  package (Vercel AI SDK) or LangChain — stop: instrument the wrapper layer
+  with its dedicated skill, never the underlying provider client.
+- If the repo wraps its Anthropic client in a helper module (for example
+  `lib/anthropic.ts` exporting a shared client), plan to instrument at that
+  one place; do not edit every call site.
+- If there are no Anthropic call sites at all, stop and report.
+
+## Step 2: Install the SDK
+
+Install `moda-ai` with the package manager this repository already uses
+(check the lockfile: `bun.lock`/`bun.lockb` means bun, `pnpm-lock.yaml` means
+pnpm, `yarn.lock` means yarn, otherwise npm):
+
+```bash
+npm install moda-ai
+```
+
+If `moda-ai` is already in `package.json`, skip the install.
+
+## Step 3: Initialize Moda once at startup, before the client is created
+
+Instrumentation is automatic: once `Moda.init` has run, every
+`messages.create` / `messages.stream` call (including extended thinking and
+tool use) is captured with no per-call changes.
+
+`Moda.init` must run before the Anthropic client is constructed. If a
+`Moda.init` call already exists, verify it runs at startup before client
+creation and skip this step; never add a second call.
+
+```typescript
+import { Moda } from 'moda-ai';
+import Anthropic from '@anthropic-ai/sdk';
+
+await Moda.init(process.env.MODA_API_KEY!);
+
+const client = new Anthropic();
+```
+
+If the client lives in a shared helper module, initialize Moda at the top of
+the application entry point (before that module is imported), or at the top
+of the helper module itself — whichever the existing structure makes
+smallest.
+
+## Step 4: Set conversation and user context
+
+Set a stable conversation id before each LLM call so multi-turn
+conversations group together, and a user id when one user can be identified.
+
+For sequential code, use the global properties:
+
+```typescript
+Moda.conversationId = `session_${sessionId}`;
+Moda.userId = userId;
+```
+
+For concurrent request handlers (any web server), use the scoped helper so
+overlapping requests do not leak context into each other:
+
+```typescript
+import { withContext } from 'moda-ai';
+
+const response = await withContext(`session_${sessionId}`, userId, async () =>
+  client.messages.create({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 1024,
+    messages: [{ role: 'user', content: userMessage }],
+  }),
+);
+```
+
+Reuse the session/thread identifier the app already has. If no session
+identifier exists anywhere, the SDK falls back to hashing the first user
+message plus the system prompt — acceptable only for simple chatbots that
+pass full message history on every call. If this repo is an agent framework
+or does not pass full history, an explicit conversation id is required; stop
+and report if you cannot find a session identifier to use.
+
+## Step 5: Flush before exit
+
+For short-lived scripts and CLIs, flush before the process exits:
+
+```typescript
+await Moda.flush();
+```
+
+For long-running servers, flush on shutdown:
+
+```typescript
+process.on('SIGTERM', async () => {
+  await Moda.flush();
+  await Moda.shutdown();
+  process.exit(0);
+});
+```
+
+## Step 6: Validate
+
+Report the packages installed, files edited, and any step a human still needs
+to do (for example setting `MODA_API_KEY` in the deploy environment). Then
+verify telemetry reaches Moda:
+
+```bash
+moda doctor --online --json
+```
+
+The report should show recent traces. If it does not, confirm `MODA_API_KEY`
+is available in the runtime environment and that `Moda.init()` runs before
+the Anthropic client is created.

package/skills/integration/integration-node-generic/EXAMPLE.md

@@ -0,0 +1,77 @@
+# Golden reference: generic Node.js app + Moda
+
+The complete finished integration for a small Node.js chat script whose LLM
+calls go through the `openai` client (automatically instrumented), plus the
+manual-tracing pattern for a provider Moda does not instrument. Match this
+structure; adapt names to the target repository.
+
+## src/main.ts
+
+```typescript
+import { Moda, withContext } from 'moda-ai';
+import OpenAI from 'openai';
+
+// Initialize Moda once, before any LLM client is created.
+await Moda.init(process.env.MODA_API_KEY!);
+
+const client = new OpenAI();
+
+export async function answer(sessionId: string, userId: string, message: string) {
+  // Scoped context: safe under concurrent callers.
+  return withContext(`session_${sessionId}`, userId, async () =>
+    client.chat.completions.create({
+      model: 'gpt-4o',
+      messages: [{ role: 'user', content: message }],
+    }),
+  );
+}
+
+const response = await answer('demo-session', 'user-123', 'Hello!');
+console.log(response.choices[0].message.content);
+
+// Flush pending telemetry before exit.
+await Moda.flush();
+```
+
+## Manual tracing for a non-instrumented provider
+
+Only needed when a call site does not go through an automatically
+instrumented client:
+
+```typescript
+import { Moda } from 'moda-ai';
+
+const messages = [{ role: 'user', content: 'Hello!' }];
+
+const data = await Moda.withLLMCall(
+  { vendor: 'my-provider', type: 'chat' },
+  async ({ span }) => {
+    span.reportRequest({ model: 'my-model', messages });
+
+    const response = await fetch('https://api.my-provider.example/v1/chat', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ model: 'my-model', messages }),
+    });
+    const body = await response.json();
+
+    span.reportResponse({
+      model: body.model,
+      usage: body.usage,
+      completions: body.choices,
+    });
+
+    return body;
+  },
+);
+```
+
+## What changed, and what did not
+
+- `moda-ai` added to `package.json` dependencies.
+- One `Moda.init` call added at startup, before any LLM client is created.
+- Call sites through instrumented clients are unchanged; only context
+  scoping was added around them.
+- Non-instrumented provider calls are wrapped in `Moda.withLLMCall`.
+- No `.env` file was created or edited; `MODA_API_KEY` is read from the
+  runtime environment.

package/skills/integration/integration-node-generic/SKILL.md

@@ -0,0 +1,170 @@
+---
+id: integration-node-generic
+name: "Integrate the Moda SDK (Node.js / TypeScript, any provider)"
+version: 1.0.0
+category: integration
+targets:
+  language: node
+  frameworks: []
+  providers: []
+sdk_package: moda-ai
+summary: "General Moda SDK integration for a Node.js or TypeScript app when no specific framework or provider skill matches."
+---
+
+# Integrate the Moda SDK (Node.js / TypeScript, any provider)
+
+This is the general Node.js integration path, used when no framework- or
+provider-specific skill matches. Follow the steps below in order. Each step
+has a stop condition; when you hit one, stop and report instead of guessing.
+`EXAMPLE.md` in this directory shows a complete finished integration; match
+its structure. For API details beyond this skill, read
+https://docs.moda.dev/ingestion/moda-sdk-node (if the installed `moda-ai`
+package ships docs under `node_modules/moda-ai/docs/`, prefer those; they
+match the installed SDK version).
+
+## Safety rules (apply to every step)
+
+- Only touch the repository you were launched in.
+- Never write the `MODA_API_KEY` value (or any secret) into source files, and
+  never create or edit `.env` files. The key belongs in the runtime
+  environment or a secret manager.
+- Make the smallest correct change. Match the existing code style and imports.
+- Do not commit unless the user asks.
+- If a step is ambiguous in this repository, stop and report rather than
+  guessing.
+
+## Step 1: Find the real LLM call sites and pick the right surface
+
+Search the repository for LLM calls and classify them:
+
+- Calls through the `openai` or `@anthropic-ai/sdk` client: automatically
+  instrumented once Moda is initialized (Step 3); no per-call changes.
+  OpenAI-compatible gateways (for example OpenRouter used through the
+  `openai` client with a custom `baseURL`) count as `openai` here.
+- Calls through the Vercel AI SDK (`ai` package) or LangChain: stop — use
+  the dedicated wrapper-framework skill instead; never instrument the
+  underlying provider client when a wrapper framework is in use.
+- Direct HTTP calls to some other LLM provider: plan to trace them manually
+  with `Moda.withLLMCall` (Step 5).
+
+If the repository has no LLM call sites at all, stop and report.
+
+## Step 2: Install the SDK
+
+Install `moda-ai` with the package manager this repository already uses
+(check the lockfile: `bun.lock`/`bun.lockb` means bun, `pnpm-lock.yaml` means
+pnpm, `yarn.lock` means yarn, otherwise npm):
+
+```bash
+npm install moda-ai
+```
+
+If `moda-ai` is already in `package.json`, skip the install.
+
+## Step 3: Initialize Moda once at startup
+
+`Moda.init` must run once, at startup, before any LLM client is created. If
+a `Moda.init` call already exists, verify it runs at startup and skip this
+step; never add a second call.
+
+```typescript
+import { Moda } from 'moda-ai';
+
+await Moda.init(process.env.MODA_API_KEY!);
+```
+
+`Moda.init` is async; await it so instrumentation is active before the first
+call.
+
+## Step 4: Set conversation and user context
+
+Set a stable conversation id before each LLM call so multi-turn
+conversations group together, and a user id when one user can be identified.
+If one user reaches the same agent through several channels, use the same
+user id across channels.
+
+For sequential code, use the global properties:
+
+```typescript
+Moda.conversationId = `session_${sessionId}`;
+Moda.userId = userId;
+```
+
+For concurrent request handlers (any web server), use the scoped helper so
+overlapping requests do not leak context into each other:
+
+```typescript
+import { withContext } from 'moda-ai';
+
+const response = await withContext(`session_${sessionId}`, userId, async () =>
+  makeLlmCall(userMessage),
+);
+```
+
+Reuse the session/thread identifier the app already has. If no session
+identifier exists anywhere, the SDK falls back to hashing the first user
+message plus the system prompt — acceptable only for simple chatbots that
+pass full message history on every call. If this repo is an agent framework
+or does not pass full history, an explicit conversation id is required; stop
+and report if you cannot find a session identifier to use.
+
+## Step 5: Manually trace non-instrumented providers (only if found in Step 1)
+
+For providers that are not automatically instrumented (direct HTTP calls,
+custom providers), wrap the call with `Moda.withLLMCall`:
+
+```typescript
+import { Moda } from 'moda-ai';
+
+const result = await Moda.withLLMCall(
+  { vendor: 'my-provider', type: 'chat' },
+  async ({ span }) => {
+    span.reportRequest({ model: 'my-model', messages });
+
+    const response = await callProviderHttpApi(messages);
+
+    span.reportResponse({
+      model: response.model,
+      usage: response.usage,
+      completions: response.choices,
+    });
+
+    return response;
+  },
+);
+```
+
+Skip this step entirely when every call site goes through an automatically
+instrumented client.
+
+## Step 6: Flush before exit
+
+For short-lived scripts and CLIs, flush before the process exits:
+
+```typescript
+await Moda.flush();
+```
+
+For long-running servers, flush on shutdown:
+
+```typescript
+process.on('SIGTERM', async () => {
+  await Moda.flush();
+  await Moda.shutdown();
+  process.exit(0);
+});
+```
+
+## Step 7: Validate
+
+Report the packages installed, files edited, and any step a human still needs
+to do (for example setting `MODA_API_KEY` in the deploy environment). Then
+verify telemetry reaches Moda:
+
+```bash
+moda doctor --online --json
+```
+
+The report should show recent traces. If it does not, confirm `MODA_API_KEY`
+is available in the runtime environment and that `Moda.init()` runs before
+the first LLM client is created.

package/skills/integration/integration-node-langchain/EXAMPLE.md

@@ -0,0 +1,59 @@
+# Golden reference: Node.js LangChain agent + Moda
+
+The complete finished integration for a minimal LangChain app. Match this
+structure; adapt names to the target repository. Note what is absent: no
+LangChain callbacks or tracer classes for Moda — instrumentation happens at
+the Moda SDK level, and the only per-run change is the explicit conversation
+id wrapper.
+
+## src/agent.ts
+
+```typescript
+import { Moda, withContext } from 'moda-ai';
+import { ChatOpenAI } from '@langchain/openai';
+import { ChatPromptTemplate } from '@langchain/core/prompts';
+
+// Initialize Moda once, before LangChain constructs any provider client,
+// so instrumentation is active for everything the agent does.
+await Moda.init(process.env.MODA_API_KEY!);
+
+const model = new ChatOpenAI({ model: 'gpt-4o' });
+const prompt = ChatPromptTemplate.fromMessages([
+  ['system', 'You are a helpful assistant.'],
+  ['human', '{input}'],
+]);
+const chain = prompt.pipe(model);
+
+export async function runAgent(sessionId: string, userId: string, input: string) {
+  // Explicit conversation id around the whole run: every internal LLM call
+  // made during this invocation shares it. Automatic detection does NOT
+  // work for agent frameworks.
+  return withContext(`agent_session_${sessionId}`, userId, async () =>
+    chain.invoke({ input }),
+  );
+}
+```
+
+## src/main.ts
+
+```typescript
+import { Moda } from 'moda-ai';
+import { runAgent } from './agent.js';
+
+const result = await runAgent('demo-session', 'user-123', 'What is TypeScript?');
+console.log(result.content);
+
+// Flush pending telemetry before exit.
+await Moda.flush();
+```
+
+## What changed, and what did not
+
+- `moda-ai` added to `package.json` dependencies.
+- One `Moda.init` call added at startup, before any LangChain model is
+  constructed.
+- Each agent/chain entry point is wrapped in `withContext` with an explicit
+  conversation id; the LangChain code itself is unchanged.
+- No LangChain callbacks, handlers, or tracers were added for Moda.
+- No `.env` file was created or edited; `MODA_API_KEY` is read from the
+  runtime environment.