@gracker/smartperfetto 1.0.13

package/dist/agentv3/claudeAgentDefinitions.js

@@ -0,0 +1,209 @@
+"use strict";
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2024-2026 Gracker (Chris)
+// This file is part of SmartPerfetto. See LICENSE for details.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAgentDefinitions = buildAgentDefinitions;
+const claudeMcpServer_1 = require("./claudeMcpServer");
+/** Tools that are orchestrator-only — sub-agents collect evidence, not plan/hypothesize.
+ * These are excluded when deriving sub-agent tools from the full allowedTools list. */
+const ORCHESTRATOR_ONLY_TOOLS = new Set([
+    'submit_plan',
+    'update_plan_phase',
+    'revise_plan',
+    'submit_hypothesis',
+    'resolve_hypothesis',
+    'flag_uncertainty',
+    'recall_patterns',
+    // Comparison tools — orchestrator-only to prevent sub-agents from breaking comparison protocol
+    'compare_skill',
+    'execute_sql_on',
+    'get_comparison_context',
+]);
+/**
+ * Derive sub-agent tools from the orchestrator's allowedTools.
+ * This ensures adding a new MCP tool automatically propagates to sub-agents
+ * unless it is explicitly listed in ORCHESTRATOR_ONLY_TOOLS.
+ */
+function deriveSubAgentTools(allowedTools) {
+    return allowedTools.filter(t => {
+        const shortName = t.replace(claudeMcpServer_1.MCP_NAME_PREFIX, '');
+        return !ORCHESTRATOR_ONLY_TOOLS.has(shortName);
+    });
+}
+/**
+ * Build architecture-specific guidance lines for sub-agent prompts.
+ * Keeps sub-agents aware of the rendering pipeline they are analyzing.
+ */
+function buildArchitectureGuidance(ctx) {
+    const lines = [];
+    if (ctx?.packageName) {
+        lines.push(`- **目标包名**: \`${ctx.packageName}\`，调用 invoke_skill 时使用 process_name="${ctx.packageName}"`);
+    }
+    if (!ctx?.architecture)
+        return lines.length > 0 ? `\n## 当前 Trace 信息\n${lines.join('\n')}` : '';
+    const arch = ctx.architecture;
+    lines.push(`- **渲染架构**: ${arch.type} (置信度 ${(arch.confidence * 100).toFixed(0)}%)`);
+    if (arch.type === 'FLUTTER') {
+        lines.push(`- **Flutter 引擎**: ${arch.flutter?.engine || 'unknown'}`);
+        lines.push(`- **线程模型**: 使用 \`N.ui\` (Dart UI) 和 \`N.raster\` (GPU raster) 线程，不是标准的 MainThread/RenderThread`);
+        lines.push(`- **关键 Slice**: 看 \`GPURasterizer::Draw\` (帧 GPU 耗时)，Skia 看 \`SkCanvas*\`，Impeller 看 \`Impeller*\``);
+        if (arch.flutter?.newThreadModel) {
+            lines.push(`- **新线程模型**: 已启用`);
+        }
+    }
+    else if (arch.type === 'COMPOSE') {
+        lines.push(`- **Compose**: 关注 \`Recomposer:recompose\` slice 频率和耗时`);
+        if (arch.compose?.isHybridView) {
+            lines.push(`- **混合模式**: View + Compose 混合渲染`);
+        }
+    }
+    else if (arch.type === 'WEBVIEW') {
+        lines.push(`- **WebView**: 引擎=${arch.webview?.engine || 'Chromium'}，有独立 Compositor/Renderer 线程`);
+    }
+    return `\n## 当前 Trace 架构\n${lines.join('\n')}`;
+}
+function buildFrameExpert(subAgentTools, ctx) {
+    const archGuidance = buildArchitectureGuidance(ctx);
+    return {
+        description: 'Frame rendering and jank diagnosis expert. Delegate to this agent for scrolling/jank analysis, ' +
+            'frame timeline investigation, and rendering pipeline diagnosis. Use when analyzing dropped frames, ' +
+            'jank root causes, or frame-level performance.',
+        prompt: `你是帧渲染与掉帧诊断专家。你的任务是收集帧级别的证据数据。
+${archGuidance}
+
+## 职责范围
+- 帧渲染管线分析（MainThread → RenderThread → SurfaceFlinger）
+- 掉帧/卡顿检测与根因分类
+- 四象限线程状态分析
+- VSync 对齐与 Buffer Stuffing 检测
+- 消费端真实掉帧 vs 框架标记掉帧的区分
+- GPU 渲染分析（gpu_analysis, gpu_metrics, gpu_freq_in_range, gpu_render_in_range）
+- SurfaceFlinger 合成分析（surfaceflinger_analysis, sf_composition_in_range）
+
+## 工具使用
+- 优先使用 invoke_skill：scrolling_analysis, jank_frame_detail, consumer_jank_detection
+- GPU 相关：gpu_analysis, gpu_metrics
+- SF 相关：surfaceflinger_analysis, sf_frame_consumption
+- 需要自定义查询时，先调 lookup_sql_schema 确认表/列名再写 SQL
+- 调用 invoke_skill 时使用 process_name 参数
+
+## 输出要求
+- **只收集证据，不做最终诊断**
+- 返回结构化数据：帧列表、根因分类、关键指标
+- 使用中文输出
+- 每个发现标注严重程度 [CRITICAL]/[HIGH]/[MEDIUM]/[LOW]/[INFO]`,
+        tools: subAgentTools,
+        model: ctx?.subAgentModel ?? 'sonnet',
+        maxTurns: 8,
+    };
+}
+function buildSystemExpert(subAgentTools, ctx) {
+    const archGuidance = buildArchitectureGuidance(ctx);
+    return {
+        description: 'System-level performance expert. Delegate to this agent for CPU scheduling, memory/GC analysis, ' +
+            'Binder IPC investigation, thermal throttling, and kernel-level diagnosis. Use when the orchestrator ' +
+            'needs system context beyond frame rendering.',
+        prompt: `你是系统级性能分析专家。你的任务是收集系统层面的证据数据。
+${archGuidance}
+
+## 职责范围
+- CPU 调度与频率分析（大小核分布、频率升降、调度延迟）
+- 内存分析（GC、LMK、页面错误、dmabuf）
+- Binder IPC 分析（阻塞事务、跨进程延迟）
+- 内核调度（锁竞争、IRQ、IO 阻塞）
+- 热管理与降频检测
+
+## 工具使用
+- 优先使用 invoke_skill：cpu_analysis, memory_analysis, binder_analysis, scheduling_analysis
+- Range-based skills：cpu_load_in_range, sched_latency_in_range, lock_contention_in_range
+- 热降频：thermal_throttling, cpu_throttling_in_range
+- 需要自定义查询时，先调 lookup_sql_schema 确认表/列名再写 SQL
+- 调用 invoke_skill 时使用 process_name 参数
+
+## 输出要求
+- **只收集证据，不做最终诊断**
+- 返回结构化数据：CPU 频率时序、内存波动、Binder 延迟分布
+- 使用中文输出
+- 每个发现标注严重程度 [CRITICAL]/[HIGH]/[MEDIUM]/[LOW]/[INFO]`,
+        tools: subAgentTools,
+        model: ctx?.subAgentModel ?? 'sonnet',
+        maxTurns: 8,
+    };
+}
+function buildStartupExpert(subAgentTools, ctx) {
+    const archGuidance = buildArchitectureGuidance(ctx);
+    return {
+        description: 'App startup analysis expert. Delegate to this agent for cold/warm/hot start analysis, ' +
+            'TTID/TTFD measurement, and startup phase breakdown.',
+        prompt: `你是应用启动分析专家。你的任务是收集启动过程的证据数据。
+${archGuidance}
+
+## 职责范围
+- 冷启动/温启动/热启动阶段分解
+- TTID (Time To Initial Display) 和 TTFD (Time To Full Display) 测量
+- 启动过程中的阻塞因素定位（ClassLoader、ContentProvider、主线程阻塞）
+- 启动期间的资源竞争（CPU、IO、Binder）
+
+## 工具使用
+- 优先使用 invoke_skill：startup_analysis, startup_detail
+- **不要** 调用 cpu_analysis, binder_analysis, memory_analysis, scheduling_analysis
+  这些由 system-expert 负责，避免重复
+- 需要自定义查询时使用 execute_sql
+
+## 输出要求
+- **只收集证据，不做最终诊断**
+- 返回：各阶段耗时、阻塞因素、关键 Slice 列表
+- 使用中文输出
+- 每个发现标注严重程度 [CRITICAL]/[HIGH]/[MEDIUM]/[LOW]/[INFO]`,
+        tools: subAgentTools,
+        model: ctx?.subAgentModel ?? 'sonnet',
+        maxTurns: 8,
+    };
+}
+/**
+ * Build agent definitions based on scene type and runtime context.
+ * Injects architecture/packageName into sub-agent prompts dynamically.
+ *
+ * **Parallelism note**: The SDK `agents` option accepts multiple definitions,
+ * but whether they run in parallel or serially depends on the SDK's internal
+ * orchestration. As of claude-agent-sdk 0.x, the SDK decides execution order
+ * based on the orchestrator model's tool calls. We design prompts assuming
+ * parallel evidence collection, but actual behavior should be verified via
+ * SDK logs when CLAUDE_ENABLE_SUB_AGENTS=true is enabled.
+ *
+ * Scene-based gating:
+ * - scrolling: frame-expert + system-expert (parallel evidence collection)
+ * - startup: startup-expert + system-expert (CPU freq/thermal/binder context for startup)
+ * - anr: no sub-agents (2-skill pipeline, sub-agents add latency without benefit)
+ * - general: frame-expert + system-expert
+ */
+function buildAgentDefinitions(sceneType, ctx) {
+    // Auto-derive sub-agent tools from orchestrator's allowedTools, excluding orchestrator-only tools.
+    // Falls back to empty array if allowedTools not provided (sub-agents will have no tools — safe failure).
+    const subAgentTools = ctx?.allowedTools ? deriveSubAgentTools(ctx.allowedTools) : [];
+    const agents = {};
+    switch (sceneType) {
+        case 'scrolling':
+            agents['frame-expert'] = buildFrameExpert(subAgentTools, ctx);
+            agents['system-expert'] = buildSystemExpert(subAgentTools, ctx);
+            break;
+        case 'startup':
+            agents['startup-expert'] = buildStartupExpert(subAgentTools, ctx);
+            agents['system-expert'] = buildSystemExpert(subAgentTools, ctx);
+            break;
+        case 'anr':
+            // ANR is a 2-skill pipeline — sub-agents add latency without benefit
+            break;
+        case 'general':
+        default:
+            // For general queries, frame-expert + system-expert provide broad coverage.
+            // startup-expert is omitted to avoid duplicating system-expert's CPU/Binder/Memory skills.
+            // The orchestrator can still call startup_analysis directly if needed.
+            agents['frame-expert'] = buildFrameExpert(subAgentTools, ctx);
+            agents['system-expert'] = buildSystemExpert(subAgentTools, ctx);
+            break;
+    }
+    return agents;
+}
+//# sourceMappingURL=claudeAgentDefinitions.js.map

package/dist/agentv3/claudeAgentDefinitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claudeAgentDefinitions.js","sourceRoot":"","sources":["../../src/agentv3/claudeAgentDefinitions.ts"],"names":[],"mappings":"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"}

package/dist/agentv3/claudeConfig.d.ts

@@ -0,0 +1,156 @@
+import type { SceneType } from './sceneClassifier';
+import { type OutputLanguage } from './outputLanguage';
+import type { ProviderScope } from '../services/providerManager';
+export type EffortLevel = 'low' | 'medium' | 'high' | 'max';
+export interface ClaudeAgentConfig {
+    model: string;
+    /** Lightweight model for auxiliary single-turn calls (verifier, classifier, summarizer).
+     *  When using a third-party proxy that maps only one model, set CLAUDE_LIGHT_MODEL
+     *  to the same value as CLAUDE_MODEL so all SDK calls route to the same endpoint. */
+    lightModel: string;
+    maxTurns: number;
+    maxBudgetUsd?: number;
+    cwd: string;
+    effort: EffortLevel;
+    /** Enable sub-agent delegation (frame-expert, system-expert, startup-expert). Default: false */
+    enableSubAgents: boolean;
+    /** Enable conclusion verification (heuristic + LLM). Default: false */
+    enableVerification: boolean;
+    /** Per sub-agent timeout in ms. Sub-agents exceeding this are stopped via stopTask(). Default: 120000 (2min) */
+    subAgentTimeoutMs: number;
+    /** Sub-agent model shorthand. Defaults to 'sonnet'.
+     *  Accepted values: 'haiku' | 'sonnet' | 'opus' | 'inherit' (inherit orchestrator model). */
+    subAgentModel?: 'inherit' | 'haiku' | 'sonnet' | 'opus';
+    /** Per-turn timeout (ms) for the full analysis pipeline. Default: 60_000 (60s/turn).
+     *  Raise via CLAUDE_FULL_PER_TURN_MS for slower LLMs (DeepSeek / Ollama / GLM). */
+    fullPathPerTurnMs: number;
+    /** Per-turn timeout (ms) for the quick analysis pipeline. Default: 40_000 (40s/turn).
+     *  Override via CLAUDE_QUICK_PER_TURN_MS. */
+    quickPathPerTurnMs: number;
+    /** Timeout (ms) for the single-turn verifier LLM call. Default: 60_000.
+     *  Override via CLAUDE_VERIFIER_TIMEOUT_MS (raise when CLAUDE_LIGHT_MODEL is not Haiku). */
+    verifierTimeoutMs: number;
+    /** Timeout (ms) for the single-turn query complexity classifier. Default: 30_000.
+     *  Override via CLAUDE_CLASSIFIER_TIMEOUT_MS. */
+    classifierTimeoutMs: number;
+    /** User-facing output language. Default: zh-CN. Override via SMARTPERFETTO_OUTPUT_LANGUAGE=en. */
+    outputLanguage: OutputLanguage;
+}
+export declare function loadClaudeConfig(overrides?: Partial<ClaudeAgentConfig>): ClaudeAgentConfig;
+/**
+ * Resolve effort level by scene type.
+ * Deterministic pipelines (scrolling/startup/anr) use 'medium' since the workflow is prescriptive.
+ * Open-ended queries ('general') use the configured default (typically 'high').
+ */
+export declare function resolveEffort(config: ClaudeAgentConfig, sceneType?: SceneType): EffortLevel;
+export interface BedrockStatus {
+    enabled: boolean;
+    hasAuth: boolean;
+    authMethod?: 'bearer_token' | 'iam_credentials' | 'profile_or_chain';
+    region: string;
+    baseUrl?: string;
+    missing?: string[];
+}
+export interface VertexStatus {
+    enabled: boolean;
+    configured: boolean;
+    projectId?: string;
+    region?: string;
+    missing?: string[];
+}
+/**
+ * Detects whether AWS Bedrock is configured and whether its authentication
+ * credentials are complete. Supports three auth paths:
+ *   1. Bearer token: AWS_BEARER_TOKEN_BEDROCK
+ *   2. IAM credentials: AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (+ optional AWS_SESSION_TOKEN)
+ *   3. AWS profile / default credential chain: AWS_PROFILE or implicit chain resolution
+ */
+export declare function detectBedrock(env?: Record<string, string | undefined>): BedrockStatus;
+export declare function detectVertex(env?: Record<string, string | undefined>): VertexStatus;
+/**
+ * Returns true when any supported Claude credential source is present:
+ * direct API key, proxy base URL, or AWS Bedrock.
+ */
+export declare function hasClaudeCredentials(env?: Record<string, string | undefined>): boolean;
+export declare function getClaudeRuntimeDiagnostics(providerId?: string | null, providerScope?: ProviderScope): {
+    runtime: string;
+    providerMode: string;
+    model: string;
+    lightModel: string;
+    baseUrl: string | undefined;
+    outputLanguage: {
+        value: OutputLanguage;
+        displayName: string;
+        env: string;
+        default: OutputLanguage;
+    };
+    configured: boolean;
+    credentialSources: string[];
+    baseUrlConfigured: boolean;
+    bedrock: {
+        enabled: boolean;
+        authMethod: "bearer_token" | "iam_credentials" | "profile_or_chain" | undefined;
+        region: string;
+        baseUrlConfigured: boolean;
+    };
+    vertex: VertexStatus;
+    configHint: string;
+    sdkBinary: ClaudeSdkBinaryDiagnostics;
+};
+export declare function isClaudeQuotaError(message: string): boolean;
+export interface CredentialSourceHint {
+    source: 'provider-manager' | 'env-or-default';
+    providerName?: string;
+    providerType?: string;
+    providerRuntime?: string;
+    envCredentialSources: string[];
+    providerOverridesEnv: boolean;
+}
+export declare function getCredentialSourceHint(providerId?: string | null, providerScope?: ProviderScope): CredentialSourceHint;
+export declare function explainClaudeRuntimeError(message: string, outputLanguage?: OutputLanguage, credentialSourceHint?: CredentialSourceHint): string;
+/**
+ * Check if ClaudeRuntime (agentv3) is the active orchestrator.
+ * Defaults to true unless the explicit runtime is OpenAI Agents SDK.
+ */
+export declare function isClaudeCodeEnabled(): boolean;
+/**
+ * Create a lightweight config for quick (factual) queries.
+ * Reduces maxTurns, effort, and disables verification/sub-agents
+ * to optimize for fast response on simple questions.
+ */
+export declare function createQuickConfig(baseConfig: ClaudeAgentConfig): ClaudeAgentConfig;
+/** Diagnostics describing how the Claude Agent SDK native binary was resolved. */
+export interface ClaudeSdkBinaryDiagnostics {
+    detectedPlatformKey: string | null;
+    chosenPath: string | null;
+    fallbackUsed: boolean;
+    source: 'env-override' | 'sdk-default' | 'fallback' | 'none';
+    error?: string;
+}
+/** Test-only: reset the auto-detection memo. */
+export declare function resetSdkBinaryOptionCache(): void;
+/**
+ * Resolve `pathToClaudeCodeExecutable`. Explicit CLAUDE_BINARY_PATH is read
+ * per-call so Provider Manager env overlays take effect; auto-detection is
+ * memoized.
+ */
+export declare function getSdkBinaryOption(env?: Record<string, string | undefined>): {
+    pathToClaudeCodeExecutable?: string;
+};
+export declare function getClaudeSdkBinaryDiagnostics(env?: Record<string, string | undefined>): ClaudeSdkBinaryDiagnostics;
+/**
+ * Create a sanitized copy of process.env for SDK subprocess spawning.
+ * When a providerId is given, overlays that provider's env vars.
+ * When no providerId is given, overlays the active provider only when it is
+ * configured for the Claude Agent SDK runtime.
+ * Falls back to raw process.env when no provider is configured.
+ */
+export declare function createSdkEnv(sessionOverrideProviderId?: string | null, providerScope?: ProviderScope): Record<string, string | undefined>;
+/**
+ * Resolve the effective ClaudeAgentConfig based on the active provider or session override.
+ * Unlike loadClaudeConfig() which only reads process.env at construction time,
+ * this reads providerManager env vars at call time when the provider matches
+ * the Claude Agent SDK runtime.
+ */
+export declare function resolveRuntimeConfig(baseConfig: ClaudeAgentConfig, providerId?: string | null, providerScope?: ProviderScope): ClaudeAgentConfig;
+//# sourceMappingURL=claudeConfig.d.ts.map

package/dist/agentv3/claudeConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claudeConfig.d.ts","sourceRoot":"","sources":["../../src/agentv3/claudeConfig.ts"],"names":[],"mappings":"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"}