feat: 로그 출력 개선 - Tool Args 상세 정보 및 토큰 사용량/비용 정보 추가

[dohapark81]

요청 배경

API 기반 에이전트 실행 시 디버깅 및 비용 추적을 위한 로그 정보가 부족합니다.

요청 사항

1. Tool Call 상세 정보 누락

현재:

[INFO] Tool called: run_shell_command
[INFO] Tool result preview: STDOUT: ...

요청:

[INFO] Tool called: run_shell_command
[INFO] Tool args: { "command": "node skills/lineagem-classchange/simulator.js simulate '{...}'" }
[INFO] Tool result preview: STDOUT: ...

문제점:

• 어떤 tool을 호출했는지는 나오지만, 어떤 인자로 실행했는지 안 남음
• run_shell_command가 5번 찍히면 어떤 명령어를 실행한 건지 구분 불가
• read_file도 어떤 파일을 읽었는지 안 보임
• tool args (인자) 를 같이 로깅해야 디버깅 가능

2. 토큰 사용량 / 비용 정보 누락

현재:

[INFO] Total tool calls across 6 step(s): 5
[INFO] Task completed successfully in 60737ms

요청:

[INFO] Step 1: input_tokens=4406, output_tokens=132, cost=$0.00118
[INFO] Step 2: input_tokens=6337, output_tokens=115, cost=$0.00161
...
[INFO] Total: input_tokens=41431, output_tokens=1192, total_cost=$0.00725
[INFO] Task completed successfully in 60737ms

문제점:

• OpenRouter API 응답에 usage.prompt_tokens, usage.completion_tokens 포함되어 있음
• 현재는 이 정보를 버리고 있어서, 비용 확인하려면 Chrome으로 https://openrouter.ai/logs 직접 접속해야 함
• step별 토큰 수 + 총 비용을 로그에 찍어주면 CLI에서 바로 확인 가능

기술 구현 방향 (초안)

1. Tool Args 로깅

파일: packages/sdk/src/core/providers/MastraAPIProvider.ts:400-408

현재 로깅 코드에 tool args 추가:

// Before
console.log(`[INFO] Tool called: ${toolName}`);

// After
console.log(`[INFO] Tool called: ${toolName}`);
if (toolArgs && Object.keys(toolArgs).length > 0) {
  const argsPreview = JSON.stringify(toolArgs).substring(0, 200);
  console.log(`[INFO] Tool args: ${argsPreview}${JSON.stringify(toolArgs).length > 200 ? '...' : ''}`);
}

2. Token Usage 및 Cost 로깅

관련 파일:

• packages/sdk/src/core/providers/MastraAPIProvider.ts:371-456 - convertResponse()
• packages/sdk/src/config/pricing.ts - calculateCost() 이미 구현됨
• packages/sdk/src/core/providers/ai-provider.interface.ts:69-73 - AIResponse.usage 이미 정의됨

구현 방향:

1. Vercel AI SDK / Mastra의 fullOutput 객체에서 usage 정보 추출

   • fullOutput.usage 또는 fullOutput.response.usage 확인
   • steps[].usage 가 있는지 확인 (multi-step)

2. convertResponse()에서 usage 정보 수집:

   // Collect usage from all steps
   let totalInputTokens = 0;
   let totalOutputTokens = 0;
   
   for (const step of steps) {
     if (step.usage) {
       totalInputTokens += step.usage.promptTokens || 0;
       totalOutputTokens += step.usage.completionTokens || 0;
       console.log(`[INFO] Step ${i}: input_tokens=${step.usage.promptTokens}, output_tokens=${step.usage.completionTokens}, cost=$${calculateCost(...)}`);
     }
   }
   
   // Add to response
   response.usage = {
     inputTokens: totalInputTokens,
     outputTokens: totalOutputTokens,
   };
   
   // Final summary
   const totalCost = calculateCost(totalInputTokens, totalOutputTokens, this.config.model);
   console.log(`[INFO] Total: input_tokens=${totalInputTokens}, output_tokens=${totalOutputTokens}, total_cost=$${totalCost.toFixed(5)}`);

논의 필요 사항

1. Vercel AI SDK usage 데이터 구조 확인

   • fullOutput.usage 필드 존재 여부
   • Multi-step의 경우 step별 usage 추적 방법
   • OpenRouter vs 다른 provider의 차이

2. 로그 출력 형식

   • Tool args 최대 길이 (현재 200자 제안)
   • Cost 소수점 자리수 (현재 5자리 제안)
   • Step별 로그 vs 최종 요약만

3. 환경변수 설정

   • CREWX_LOG_TOOL_ARGS_MAX_LENGTH 추가?
   • CREWX_LOG_SHOW_COST=true/false 추가?

4. CLI Provider 호환성

   • Claude/Gemini/Copilot도 같은 방식으로 토큰 정보 제공?
   • CLI에서 usage 정보 추출 방법?

다음 단계

1. 내부 회의: Dev Lead가 팀원들과 기술 구현 방향 논의
2. Spike: Vercel AI SDK usage 데이터 구조 확인 (실험)
3. 구현: 합의된 방향으로 구현
4. 테스트: 실제 OpenRouter API로 검증
5. 문서화: README 및 가이드 업데이트

참고

• 요청자: @U08LSF2KNVD (Doha)
• 관련 파일: MastraAPIProvider.ts, ai-provider.interface.ts, pricing.ts
• 기존 인프라: AIResponse.usage, calculateCost() 이미 구현됨

[dohapark81]

🤖 Dev Lead 분석 및 구현 방안

기술 검토 완료 사항

1. 기존 인프라 확인 ✅

이미 구현된 기능:

• AIResponse.usage 필드 (ai-provider.interface.ts:69-73)
• calculateCost() 함수 (pricing.ts:86-97)
• getPricing() 함수 - 모델별 가격 테이블
• LogConfig - 로그 길이 제한 설정

결론: 토큰 비용 계산 인프라는 이미 준비되어 있음. usage 정보만 추출하면 됨.

2. Vercel AI SDK Usage 데이터 구조

Vercel AI SDK의 generateText() / Mastra Agent의 generate() 응답 구조:

{
  text: string,
  steps: [
    {
      text: string,
      toolCalls: [...],
      toolResults: [...],
      usage: {
        promptTokens: number,
        completionTokens: number,
        totalTokens: number
      }
    }
  ],
  usage: {
    promptTokens: number,
    completionTokens: number,
    totalTokens: number
  }
}

키 포인트:

• fullOutput.usage - 전체 요청의 누적 토큰 (OpenRouter, Anthropic 모두 지원)
• fullOutput.steps[].usage - step별 토큰 (multi-step agent loop)
• OpenRouter는 usage.prompt_tokens, usage.completion_tokens 필드 제공 확인됨

3. 구현 우선순위 및 복잡도

항목	우선순위	복잡도	예상 작업 시간
Tool args 로깅	P0 (High)	Low	30분
Token usage 로깅 (전체 합계)	P0 (High)	Low	30분
Step별 usage 로깅	P1 (Medium)	Medium	1시간
민감 정보 마스킹	P2 (Low)	High	2-3시간
환경변수 설정	P1 (Medium)	Low	30분

제안: P0 항목 먼저 구현 → 0.8.0 릴리스에 포함

---

최종 구현 방안

Phase 1: Tool Args 로깅 (P0)

파일: packages/sdk/src/core/providers/MastraAPIProvider.ts:400

// Before (line 400)
console.log(`[INFO] Tool called: ${toolName}`);

// After
console.log(`[INFO] Tool called: ${toolName}`);
if (toolArgs && Object.keys(toolArgs).length > 0) {
  const argsStr = JSON.stringify(toolArgs);
  const maxLen = this.logConfig.toolArgsMaxLength || 200;
  const preview = argsStr.substring(0, maxLen);
  console.log(`[INFO] Tool args: ${preview}${argsStr.length > maxLen ? '...' : ''}`);
}

환경변수 추가:

// log.config.ts
export interface LogConfig {
  promptMaxLength: number;
  toolResultMaxLength: number;
  conversationMaxLength: number;
  toolArgsMaxLength: number; // 추가
}

const DEFAULT_LOG_CONFIG: LogConfig = {
  // ...
  toolArgsMaxLength: 200, // 추가
};

Phase 2: Token Usage 로깅 (P0)

파일: packages/sdk/src/core/providers/MastraAPIProvider.ts:371-456

private convertResponse(fullOutput: any, taskId: string): AIResponse {
  // ... 기존 코드 ...
  
  // Extract usage information
  let totalInputTokens = 0;
  let totalOutputTokens = 0;
  
  if (fullOutput.usage) {
    totalInputTokens = fullOutput.usage.promptTokens || 0;
    totalOutputTokens = fullOutput.usage.completionTokens || 0;
    
    // Add usage to response
    response.usage = {
      inputTokens: totalInputTokens,
      outputTokens: totalOutputTokens,
    };
    
    // Calculate cost
    const cost = calculateCost(totalInputTokens, totalOutputTokens, this.config.model);
    
    // Log summary
    console.log(`[INFO] Total: input_tokens=${totalInputTokens}, output_tokens=${totalOutputTokens}, total_cost=\$${cost.toFixed(5)}`);
  }
  
  return response;
}

import 추가:

import { calculateCost } from '../../config/pricing';

Phase 3: Step별 Usage 로깅 (P1 - Optional)

// Step별 usage 로깅 (선택적)
for (let i = 0; i < steps.length; i++) {
  const step = steps[i];
  if (step.usage) {
    const stepCost = calculateCost(
      step.usage.promptTokens || 0,
      step.usage.completionTokens || 0,
      this.config.model
    );
    console.log(
      `[INFO] Step ${i + 1}: input_tokens=${step.usage.promptTokens}, " +
      "output_tokens=${step.usage.completionTokens}, cost=\$${stepCost.toFixed(5)}`
    );
  }
}

---

보안 고려사항

민감 정보 마스킹 (Phase 4 - Future)

Tool args에 포함될 수 있는 민감 정보:

• API Keys (OPENAI_API_KEY, etc.)
• 패스워드, 토큰
• 개인정보 (이메일, 전화번호)

제안 방안:

1. 키워드 기반 마스킹: password, apiKey, token, secret 필드 자동 마스킹
2. 환경변수: CREWX_LOG_MASK_SENSITIVE=true (기본값: false)

function maskSensitiveData(obj: any): any {
  const sensitiveKeys = ['password', 'apikey', 'token', 'secret', 'key'];
  // ... recursive masking logic
  return masked;
}

우선순위: P2 (나중에 구현) - 현재 CrewX는 내부 개발팀 전용이므로 급하지 않음.

---

테스트 계획

1. Unit Test: MastraAPIProvider.test.ts에 usage 추출 테스트 추가
2. Integration Test: tool-calling-live.test.ts에 usage 로깅 검증 추가
3. Manual Test: OpenRouter API로 실제 실행 후 로그 확인

---

다음 단계

✅ 결정 완료 - 구현 착수 가능

@crewx_claude_dev에게 구현 위임:

crewx x "@crewx_claude_dev Issue #120 구현해줘. Phase 1 (Tool Args) + Phase 2 (Token Usage)만 구현하고 PR 생성해줘."

예상 작업 시간: 1-2시간
타겟 릴리스: 0.8.0

[dohapark81]

📝 요구사항 업데이트 (Dev Lead)

사용자 피드백을 반영하여 요구사항을 다음과 같이 조정합니다:

✅ P0 (최우선 구현)

1. Tool Args 로깅 (기본 출력)

• 모든 tool call에 대해 args 정보 출력
• 민감정보 마스킹은 P2로 후순위 처리
• 다른 CLI provider와 동일하게 처리

2. 토큰 사용량 로깅 (기본 출력)

• 기본 로그에 토큰 수 정보 포함

[INFO] Total: input_tokens=1250, output_tokens=340, total_cost=$0.00725

3. --verbose 옵션 구현

• Ollama 스타일로 상세 토큰 정보 출력
• Step별 토큰 사용량 + 비용 표시

[VERBOSE] Step 1: input_tokens=450, output_tokens=120, cost=$0.00118
[VERBOSE] Step 2: input_tokens=520, output_tokens=140, cost=$0.00161
...
[INFO] Total: input_tokens=1250, output_tokens=340, total_cost=$0.00725

📋 P2 (후순위)

마스킹 기능

• Tool args에서 API key, password 등 민감정보 자동 마스킹
• 현재는 내부 개발팀 전용이므로 급하지 않음

---

구현 우선순위:

1. Phase 1 (P0): Tool Args 로깅
2. Phase 2 (P0): 기본 토큰 사용량 로깅
3. Phase 3 (P0): --verbose 옵션 구현
4. Phase 4 (P2): 민감정보 마스킹

@crewx_claude_dev P0 항목 우선 구현 부탁드립니다!

[dohapark81]

🔍 추가 요구사항 확인: traces.db 저장

요청:

• 로그 파일(traces.db)에도 tool args 및 토큰 사용량 정보 저장

✅ 현황 확인:

1. traces.db 스키마 (이미 구현됨)

CREATE TABLE tasks (
  ...
  input_tokens INTEGER,
  output_tokens INTEGER,
  cost_usd REAL,
  ...
);

CREATE TABLE tool_calls (
  id TEXT PRIMARY KEY,
  task_id TEXT NOT NULL,
  tool_name TEXT NOT NULL,
  input TEXT,           -- JSON으로 tool args 저장 가능
  output TEXT,          -- JSON으로 tool result 저장 가능
  duration_ms INTEGER,
  timestamp TEXT NOT NULL,
  ...
);

2. 구현 계획

Phase 1: Tool Args 로깅 → traces.db 저장

• 콘솔 로그: [INFO] Tool args: {...}
• traces.db 저장: 이미 tool_calls 테이블에 input 컬럼 존재 ✅
• 구현 위치: MastraAPIProvider → TracingService.logToolCall()

Phase 2: 토큰 사용량 → traces.db 저장

• 콘솔 로그: [INFO] Total: input_tokens=X, output_tokens=Y, total_cost=
• traces.db 저장: 이미 tasks 테이블에 input_tokens, output_tokens, cost_usd 컬럼 존재 ✅
• 구현 위치: MastraAPIProvider → TracingService.completeTask()

3. 구현 방향

A. Tool Args 저장 (traces.db)

// MastraAPIProvider.ts - Tool call 실행 시
const toolCallId = this.tracingService.logToolCall({
  task_id: this.currentTaskId,
  tool_name: toolName,
  input: toolArgs,  // ← 이미 존재하는 필드 활용
  output: toolResult,
  duration_ms: toolDuration,
});

B. 토큰 사용량 저장 (traces.db)

// MastraAPIProvider.ts - Task 완료 시
this.tracingService.completeTask(taskId, result, exitCode, {
  inputTokens: totalInputTokens,   // ← 이미 구현됨
  outputTokens: totalOutputTokens, // ← 이미 구현됨
});
// calculateCost()는 TracingService 내부에서 자동 계산됨

4. 결론

✅ traces.db 스키마는 이미 준비되어 있습니다!

• Tool args 저장: tool_calls.input 컬럼 활용
• 토큰 사용량 저장: tasks.input_tokens, output_tokens, cost_usd 컬럼 활용

✅ 구현 필요 작업:

1. MastraAPIProvider에서 tool args를 logToolCall() input 파라미터로 전달
2. MastraAPIProvider에서 usage 정보를 completeTask()로 전달

우선순위:

• P0 (최우선): 콘솔 로그 출력 + traces.db 저장 동시 진행
• traces.db는 이미 인프라가 준비되어 있어서 추가 작업 없음

---

다음 단계:
@crewx_claude_dev가 구현 시 TracingService API를 활용하여 traces.db에도 자동 저장되도록 구현합니다.