lukasa1993/tanstack-skills-extracted/tanstack-ai-core-debug-logging

Name: tanstack-ai-core-debug-logging
Author: lukasa1993

Claude Code and agent skill by lukasa1993/tanstack-skills-extracted

Trust tier 2

community

LLM review pending

By lukasa1993
AI/ML
lukasa1993/tanstack-skills-extracted
skills/tanstack-ai-core-debug-logging/SKILL.md
Updated 29 Oct 2026
Version 1.0.01 version recorded

Source check pending

Checking that the SKILL.md file is still in the repository.

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

Install

npx vskill@latest install lukasa1993/tanstack-skills-extracted/tanstack-ai-core-debug-logging

SKILL.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,
  threadId: 'thread-1',
  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,
  threadId: 'thread-1',
  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,
  threadId: 'thread-1',
  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,
  threadId: 'thread-1',
  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,
  threadId: 'thread-1',
  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'

Non-chat activities

Same debug option everywhere:

typescript

import {
  summarize,
  generateImage,
  generateSpeech,
  generateTranscription,
  generateVideo,
} from '@tanstack/ai'
import {
  openaiSummarize,
  openaiImage,
  openaiSpeech,
  openaiTranscription,
  openaiVideo,
} from '@tanstack/ai-openai'
import { logger } from './logger'
import { audio } from './recording'
summarize({
  adapter: openaiSummarize('gpt-5.5'),
  threadId: 'thread-1',
  text: 'Long article…',
  debug: true,
})
generateImage({
  adapter: openaiImage('gpt-image-2'),
  threadId: 'thread-1',
  prompt: 'a cat',
  debug: { logger },
})
generateSpeech({
  adapter: openaiSpeech('tts-1-hd'),
  threadId: 'thread-1',
  text: 'Hello',
  debug: { request: true },
})
generateTranscription({
  adapter: openaiTranscription('gpt-4o-transcribe'),
  threadId: 'thread-1',
  audio,
  debug: false,
})
generateVideo({
  adapter: openaiVideo('sora-2'),
  threadId: 'thread-1',
  prompt: 'a wave',
  debug: { output: true },
})

Realtime session adapters in provider packages (e.g. openaiRealtime, elevenlabsRealtime) accept the same debug?: DebugOption on their session options. They emit request, provider, and errors lines; the chat-only categories don't apply.

Common Mistakes

a. HIGH: Treating omitted `debug` as silent

typescript

import { chat } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
const adapter = openaiText('gpt-5.5')
const messages = [{ role: 'user' as const, content: 'Hello' }]
// WRONG — expecting this to be completely silent
chat({ adapter, messages, threadId: 'thread-1' })
// Errors still print via [tanstack-ai:errors] ... on failure.
// CORRECT — explicit silence
chat({ adapter, messages, threadId: 'thread-1', debug: false })
chat({ adapter, messages, threadId: 'thread-1', debug: { errors: false } })

debug undefined means "only errors"; debug: false means "nothing at all".

Source: docs/advanced/debug-logging.md

b. MEDIUM: Reaching for middleware when `debug` would do

typescript

import { chat, type ChatMiddleware } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
const adapter = openaiText('gpt-5.5')
const messages = [{ role: 'user' as const, content: 'Hello' }]
// WRONG — writing logging middleware to see chunks flow
const chunkLogger: ChatMiddleware = {
  name: 'chunk-logger',
  onChunk: (ctx, chunk) => {
    console.log(chunk.type, chunk)
  },
}
chat({ adapter, messages, threadId: 'thread-1', middleware: [chunkLogger] })
// CORRECT — just turn on the relevant categories
chat({
  adapter,
  messages,
  threadId: 'thread-1',
  debug: { provider: true, output: true },
})

For observing the built-in pipeline, the debug option is strictly faster than writing logging middleware. Reach for middleware when you need to _transform_ chunks, not just see them.

Source: docs/advanced/debug-logging.md

c. LOW: Logger implementation that can throw

A user-supplied Logger that throws will have its exception swallowed by the SDK so it never masks the real error that triggered the log call. Still, prefer implementations that don't throw — silenced exceptions are harder to debug than loud ones.

typescript

import type { Logger } from '@tanstack/ai'
// WRONG — a logger that can throw on serialization
const fragile: Logger = {
  debug: (msg, meta) => console.debug(msg, JSON.stringify(meta)), // cyclic meta → throws
  info: (msg, meta) => console.info(msg, JSON.stringify(meta)),
  warn: (msg, meta) => console.warn(msg, JSON.stringify(meta)),
  error: (msg, meta) => console.error(msg, JSON.stringify(meta)),
}
// CORRECT — guard serialization in the logger itself
const guarded =
  (log: (...args: Array<unknown>) => void): Logger['debug'] =>
  (msg, meta) => {
    try {
      log(msg, JSON.stringify(meta))
    } catch {
      log(msg) // fall back to the bare message rather than throw
    }
  }
const safe: Logger = {
  debug: guarded(console.debug),
  info: guarded(console.info),
  warn: guarded(console.warn),
  error: guarded(console.error),
}

Source: packages/ai/src/logger/internal-logger.ts

Cross-References

See also: ../tanstack-ai-core-middleware/SKILL.md — if you need to transform

chunks/config, not just observe them.

See also: Observability (docs/advanced/observability.md) — the

programmatic event client for a richer, structured feed beyond log lines.

Security

Security scanPassed, 100 of 100Pattern checks on the skill's files.
Model reviewNot runA model review is scheduled for the next rescan.

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryCheckingskills/tanstack-ai-core-debug-logging/SKILL.md

Popularity

7-day trend score: 0

Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/lukasa1993/tanstack-skills-extracted/tanstack-ai-core-debug-logging/badge)](https://verified-skill.com/skills/lukasa1993/tanstack-skills-extracted/tanstack-ai-core-debug-logging)

Something wrong with this skill or its page? Tell us.

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
`agentLoop`	Agent-loop iterations and phase transitions	`chat()` only
`config`	Config transforms returned by middleware `onConfig` hooks	`chat()` only
`errors`	Every caught error anywhere in the pipeline	All activities

Install

SKILL.md

Debug Logging

Turn it on

Turn it off

DebugOption — the accepted shapes

Narrow what's printed

Pipe into your own logger

Categories

Non-chat activities

Common Mistakes

a. HIGH: Treating omitted debug as silent

b. MEDIUM: Reaching for middleware when debug would do

c. LOW: Logger implementation that can throw

Cross-References

Security

Quality evaluation

Source

Popularity

Works with

`DebugOption` — the accepted shapes

a. HIGH: Treating omitted `debug` as silent

b. MEDIUM: Reaching for middleware when `debug` would do