Debug LoggingSAFE

🤖 Type-safe, provider-agnostic TypeScript AI SDK for streaming chat, tool calling, agents, and multimodal apps across OpenAI, Anthropic, Gemini, React, Vue, Svelte, and Solid.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: ai-core/debug-logging
description: >
  Pluggable, category-toggleable debug logging for TanStack AI activities.
  Toggle with `debug: true | false | DebugConfig` on chat(), summarize(),
  generateImage(), generateSpeech(), generateTranscription(), generateVideo().
  Categories: request, provider, output, middleware, tools, agentLoop,
  config, errors. Pipe into pino/winston/etc via `debug: { logger }`. Errors
  log by default even when `debug` is omitted; silence with `debug: false`.
type: sub-skill
library: tanstack-ai
library_version: '0.42.0'
sources:
  - 'TanStack/ai:docs/advanced/debug-logging.md'
---

# Debug Logging

> **Dependency note:** This skill builds on ai-core. Read it first for critical rules.

Use this skill when you need to turn debug logging on or off, narrow what's
printed, or pipe logs into a custom logger (pino, winston, etc.). The same
`debug` option works on every activity — `chat()`, `summarize()`,
`generateImage()`, `generateSpeech()`, `generateTranscription()`,
`generateVideo()`.

## Turn it on

```typescript
import { chat } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'

const messages = [{ role: 'user' as const, content: 'Hello' }]

const stream = chat({
  adapter: openaiText('gpt-5.5'),
  messages,
  debug: true, // all categories on, prints to console
})
```

Each log line is prefixed with an emoji and `[tanstack-ai:<category>]`:

```
📤 [tanstack-ai:request] 📤 activity=chat provider=openai model=gpt-5.2 messages=1 tools=0 stream=true
🔁 [tanstack-ai:agentLoop] 🔁 run started
📥 [tanstack-ai:provider] 📥 provider=openai type=response.output_text.delta
📨 [tanstack-ai:output] 📨 type=TEXT_MESSAGE_CONTENT
```

## Turn it off

```typescript
import { chat } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'

const messages = [{ role: 'user' as const, content: 'Hello' }]

chat({
  adapter: openaiText('gpt-5.5'),
  messages,
  debug: false, // silence everything, including errors
})
```

Omitting `debug` is **not** the same as `debug: false`. When omitted, the
`errors` category is still on (errors are cheap and important). Use
`debug: false` or `debug: { errors: false }` for true silence.

## `DebugOption` — the accepted shapes

```typescript
import type { Logger } from '@tanstack/ai'

// As exported by '@tanstack/ai'
type DebugOption = boolean | DebugConfig

interface DebugConfig {
  // Per-category flags. Any flag omitted from a DebugConfig defaults to true.
  request?: boolean
  provider?: boolean
  output?: boolean
  middleware?: boolean
  tools?: boolean
  agentLoop?: boolean
  config?: boolean
  errors?: boolean
  // Optional custom logger. Defaults to ConsoleLogger.
  logger?: Logger
}
```

Resolution rules for the `debug?: DebugOption` field on every activity:

| `debug` value         | Effect                                                                       |
| --------------------- | ---------------------------------------------------------------------------- |
| omitted (`undefined`) | Only `errors` is active; default `ConsoleLogger`.                            |
| `true`                | All categories on; default `ConsoleLogger`.                                  |
| `false`               | All categories off (including `errors`); default `ConsoleLogger`.            |
| `DebugConfig` object  | Each unspecified flag defaults to `true`; `logger` replaces `ConsoleLogger`. |

## Narrow what's printed

Pass a `DebugConfig` object. Unspecified categories default to `true`, so it's
easiest to toggle by setting specific flags to `false`:

```typescript
import { chat } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'

const messages = [{ role: 'user' as const, content: 'Hello' }]

chat({
  adapter: openaiText('gpt-5.5'),
  messages,
  debug: { middleware: false }, // everything except middleware
})
```

To print only a specific set, set the rest to `false` explicitly:

```typescript
import { chat } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'

const messages = [{ role: 'user' as const, content: 'Hello' }]

chat({
  adapter: openaiText('gpt-5.5'),
  messages,
  debug: {
    provider: true,
    output: true,
    middleware: false,
    tools: false,
    agentLoop: false,
    config: false,
    errors: true, // keep errors on — they're cheap and important
    request: false,
  },
})
```

## Pipe into your own logger

```typescript
import { chat, type Logger } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
import pino from 'pino'

const pinoLogger = pino()
const logger: Logger = {
  debug: (msg, meta) => pinoLogger.debug(meta, msg),
  info: (msg, meta) => pinoLogger.info(meta, msg),
  warn: (msg, meta) => pinoLogger.warn(meta, msg),
  error: (msg, meta) => pinoLogger.error(meta, msg),
}

const messages = [{ role: 'user' as const, content: 'Hello' }]

chat({
  adapter: openaiText('gpt-5.5'),
  messages,
  debug: { logger }, // all categories on, piped to pino
})
```

The default console logger is exported as `ConsoleLogger` if you want to wrap
it:

```typescript
import { ConsoleLogger } from '@tanstack/ai'
```

## Categories

| Category     | Logs                                                           | Applies to                            |
| ------------ | -------------------------------------------------------------- | ------------------------------------- |
| `request`    | Outgoing call to a provider (model, message count, tool count) | All activities                        |
| `provider`   | Every raw chunk/frame received from a provider SDK             | Streaming activities (chat, realtime) |
| `output`     | Every chunk or result yielded to the caller                    | All activities                        |
| `middleware` | Inputs and outputs around every middleware hook                | `chat()` only                         |
| `tools`      | Before/after tool call execution                               | `chat()` only                  

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.